Update documentation.
authorBen Pfaff <blp@nicira.com>
Tue, 9 Jun 2009 20:09:08 +0000 (13:09 -0700)
committerBen Pfaff <blp@nicira.com>
Tue, 9 Jun 2009 20:09:08 +0000 (13:09 -0700)
INSTALL [deleted file]
INSTALL.Linux [new file with mode: 0644]
INSTALL.SSL [new file with mode: 0644]
INSTALL.XenServer [new file with mode: 0644]
Makefile.am
README

diff --git a/INSTALL b/INSTALL
deleted file mode 100644 (file)
index 994e8d3..0000000
--- a/INSTALL
+++ /dev/null
@@ -1,514 +0,0 @@
-               Open vSwitch Installation Instructions
-
-This document describes how to build, install, and execute
-Open vSwitch.
-
-Open vSwitch implements an Ethernet switch with MAC learning that may
-be configured with any of the following features:
-
-       * NIC bonding with automatic fail-over and source MAC-based TX
-         load balancing ("SLB").
-
-       * 802.1Q VLAN support.
-
-       * Port mirroring, with optional VLAN tagging.
-
-       * NetFlow v5 flow logging.
-
-       * Connectivity to an external OpenFlow controller, such as
-          NOX.
-
-The current version of this distribution requires a kernel module to
-be built and loaded.  An (optional) entirely userspace switch is on
-the roadmap for future versions.
-
-The distribution also contains a number of related utilities.
-
-Build Methods
-=============
-
-There are two principal ways to build and install this distribution:
-
-       - Using "configure" and "make" in the ordinary way.  See
-          Building Conventionally below for detailed instructions.
-
-       - As a set of Debian packages.  Refer to Building Debian
-          Packages, below, for instructions.
-
-Base Prerequisites
-------------------
-
-Regardless of how it is built, Open vSwitch has a common set of
-prerequisites.  To compile the userspace programs in the OpenFlow
-reference distribution, you will need the following software:
-
-    - A make program, e.g. GNU make
-      (http://www.gnu.org/software/make/).  BSD make should also work.
-
-    - The GNU C compiler (http://gcc.gnu.org/).  We generally test
-      with version 4.2 or 4.3.
-
-    - libssl, from OpenSSL (http://www.openssl.org/), is optional but
-      recommended if you plan to connect the Open vSwitch to an
-      OpenFlow controller.  libssl is required to establish
-      confidentiality and authenticity in the connections from an
-      Open vSwitch to an OpenFlow controller.  To enable, configure
-      with --enable-ssl=yes.
-
-To compile the kernel module, you must also install the following:
-
-    - A supported Linux kernel version.  Please refer to README for a
-      list of supported versions.
-
-      The OpenFlow datapath requires bridging support (CONFIG_BRIDGE)
-      to be built as a kernel module.  (This is common in kernels
-      provided by Linux distributions.)  The bridge module must not be
-      loaded or in use.  If the bridge module is running (check with
-      "lsmod | grep bridge"), you must remove it ("rmmod bridge")
-      before starting the datapath.
-
-    - To build a kernel module, you need the same version of GCC that
-      was used to build that kernel (usually version 4.0 or later).
-
-    - A kernel build directory corresponding to the Linux kernel image
-      the module is to run on.  Under Debian and Ubuntu, for example,
-      each linux-image package containing a kernel binary has a
-      corresponding linux-headers package with the required build
-      infrastructure.
-
-If you are working from a Git tree or snapshot (instead of from a
-distribution tarball), or if you modify the Open vSwitch build system,
-you will also need the following software:
-
-    - Autoconf version 2.60 or later (http://www.gnu.org/software/autoconf).
-
-    - Automake version 1.10 or later (http://www.gnu.org/software/automake).
-
-    - pkg-config (http://pkg-config.freedesktop.org/wiki/).  We test
-      with version 0.22.
-
-Debian Prerequisites
---------------------
-
-To build Debian packages from the Open vSwitch distribution, you will
-need to install a number of Debian packages in addition to the base
-prerequisites listed above.  These additional prerequisites may be
-found listed as "Build-Depends" in debian/control in the source tree.
-To check that they are installed, first install the dpkg-dev package,
-then run dpkg-checkbuilddeps from the top level of the OpenFlow source
-tree.
-
-To build Debian packages without being root, also install the
-"fakeroot" package.
-
-Building Conventionally
-=======================
-
-This section explains how to build and install the Open vSwitch
-distribution in the ordinary way using "configure" and "make".
-
-0. Check that you have installed all the prerequisites listed above in
-   the Base Prerequisites section.
-
-1. In the top source directory, configure the package by running the
-   configure script.  You can usually invoke configure without any
-   arguments:
-
-      % ./configure
-
-   To use a specific C compiler for compiling OpenFlow user programs,
-   also specify it on the configure command line, like so:
-
-      % ./configure CC=gcc-4.2
-
-   To build the Linux kernel module, so that you can run the
-   kernel-based switch, pass the location of the kernel build
-   directory on --with-l26.  For example, to build for a running
-   instance of Linux 2.6:
-
-      % ./configure --with-l26=/lib/modules/`uname -r`/build
-
-   If you wish to build the kernel module for an architecture other
-   than the architecture of the machine used for the build, you may
-   specify the kernel architecture string using the KARCH variable
-   when invoking the configure script.  For example, to build for MIPS
-   with Linux 2.6:
-
-        % ./configure --with-l26=/path/to/linux-2.6 KARCH=mips
-
-   The configure script accepts a number of other options and honors
-   additional environment variables.  For a full list, invoke
-   configure with the --help option.
-
-2. Run make in the top source directory: 
-
-      % make
-
-   The following main binaries will be built:
-
-      - Virtual switch daemon: vswitchd/ovs-vswitchd
-
-      - Bridge compatibility daemon: vswitchd/ovs-brcompatd
-
-      - Datapath administration utility: utilities/ovs-dpctl.
-
-   Some less important binaries will be built also:
-
-      - Runtime configuration utility: utilities/ovs-appctl.
-
-      - Simple OpenFlow controller: utilities/ovs-controller.
-
-      - Secure channel executable: secchan/secchan.
-
-      - Miscellaneous utilities: utilities/ovs-discover,
-        utilities/ovs-kill.
-
-      - ANSI terminal support for EZIO 16x2 LCD panel:
-        extras/ezio/ezio-term (only if the proper libraries are
-        installed).
-
-      - Switch monitoring UI for small text displays:
-        extras/ezio/ovs-switchui (only if the proper libraries are
-        installed).
-
-      - Tests: various binaries in tests/.
-
-   If you passed --with-l26 to configure, "make" will also build the
-   following kernel modules:
-
-      - datapath/linux-2.6/brcompat_mod.ko
-
-      - datapath/linux-2.6/openflow_mod.ko
-
-3. Run "make install" to install the executables and manpages into the
-   running system, by default under /usr/local.
-
-4. If you built kernel modules, you may load them with "insmod", e.g.:
-
-      % insmod datapath/linux-2.6/openflow_mod.ko
-
-   The insmod program must be run as root.  You may need to specify a
-   full path to insmod, e.g. /sbin/insmod.  To verify that the modules
-   have been loaded, run "/sbin/lsmod" and check that openflow_mod is
-   listed.
-
-5. Test the virtuaal switch, as described under Testing the Virtual
-Switch below.
-
-Building Debian Packages
-========================
-
-Follow these instructions to build Debian packages for OpenFlow.
-
-0. Check that you have installed all the prerequisites listed above in
-   the Base Prerequisites and Debian Prerequisites sections above.
-
-1. In the top source directory, run the following command, as root:
-
-      % dpkg-buildpackage
-
-   Alternatively, if you installed the "fakeroot" package, you may run
-   dpkg-buildpackage as an ordinary user with the following syntax:
-
-      % dpkg-buildpackage -rfakeroot
-
-   The following packages will be built in the directory above the
-   source tree:
-
-      - openflow-controller: The OpenFlow controller.  Depends on
-        openflow-pki (see below).
-
-      - openflow-switch: Install this package on a machine that acts
-        as an OpenFlow kernel switch.
-
-      - openflow-datapath-source: Source code for OpenFlow's Linux
-        kernel module.
-
-      - openflow-pki: Public-key infrastructure for OpenFlow.  Install
-        this package on a machine that acts as an OpenFlow PKI server
-        (see "Establishing a Public Key Infrastructure" below).
-
-      - openflow-common: Files and utilities required by more than one
-        of the above packages.
-
-2. To set up an OpenFlow controller, install the openflow-controller
-   package and its dependencies.  You may configure it by editing
-   /etc/default/openflow-controller, e.g. to enable non-SSL
-   connections, which are disabled by default.  If you change the
-   default settings, you will need to restart the controller by
-   running:
-
-      % /etc/init.d/openflow-controller restart
-
-3. To set up an OpenFlow switch, install the openflow-switch package
-   and its dependencies.  If it is to be a kernel-based switch, also
-   install openflow-datapath-source, then follow the instructions in
-   /usr/share/doc/openflow-datapath-source/README.Debian to build and
-   install the kernel module.
-
-   You may configure the switch one of the following ways:
-
-      - Completely by hand, as described under the Testing section
-        below.
-
-        For the userspace datapath-based switch, this is the only
-        supported form of configuration.
-
-      - By editing /etc/default/openflow-switch.  You must at least
-        configure some network devices, by uncommenting NETDEVS and
-        adding the appropriate devices to the list, e.g. NETDEVS="eth0
-        eth1".
-
-        After you edit this file, you will need to start the switch by
-        running:
-
-           % /etc/init.d/openflow-switch restart
-
-        This form of configuration is not supported for the userspace
-        datapath-based switch.
-
-      - By running the ovs-switch-setup program.  This interactive
-        program will walk you through all the steps of configuring an
-        OpenFlow switch, including configuration of SSL certificates.
-        Run it without arguments, as root:
-
-           % ovs-switch-setup
-
-        This form of configuration is not supported for the userspace
-        datapath-based switch.
-
-Installation
-============
-
-This section explains how to install Open vSwitch in a network with one
-controller and one or more switches, each of which runs on a separate
-machine.  Before you begin, you must decide on one of two ways for
-each switch to reach the controller over the network:
-
-      - Use a "control network" that is completely separate from the
-        "data network" to be controlled ("out-of-band control").  The
-        location of the controller must be configured manually in this
-        case.
-
-      - Use the same network for control and for data ("in-band
-        control").  When in-band control is used, the location of the
-        controller may be configured manually or discovered
-        automatically.  We will assume manual configuration here;
-        please refer to secchan(8) for instructions on setting up
-        controller discovery.  
-
-Controller Setup
-----------------
-
-On the machine that is to be the OpenFlow controller, start the
-"ovs-controller" program listening for connections from switches on
-TCP port 6633 (the default), as shown below.
-
-   # ovs-controller -v ptcp:
-
-(See ovs-controller(8) for more details)
-
-Make sure the machine hosting the controller is reachable by the
-switch.
-
-Testing the Virtual Switch
---------------------------
-
-The Open vSwitch kernel module must be loaded, as described under
-"Building Conventionally", before it may be used.
-
-0. The commands below must run as root, so log in as root, or use a
-   program such as "su" to become root temporarily.
-
-1. Create a datapath instance.  The command below creates a datapath
-   identified as dp0 (see ovs-dpctl(8) for more detailed usage
-   information).
-
-      # ovs-dpctl add-dp dp0
-   
-   (dp0 is the first datapath within a host.  openvswitch_mod supports
-   multiple datapaths within the same host, which would be identified
-   as dp1, dp2, etc.)
-
-   Creating datapath dp0 creates a new network device, also named dp0.
-   This network device, called the datapath's "local port", will be
-   bridged to the physical switch ports by the secchan, for use in
-   in-band control.
-
-2. Use ovs-dpctl to attach the datapath to physical interfaces on the
-   machine.  Say, for example, you want to create a trivial 2-port
-   switch using interfaces eth1 and eth2, you would issue the
-   following commands:
-
-      # ovs-dpctl add-if dp0 eth1
-      # ovs-dpctl add-if dp0 eth2
-
-   You can verify that the interfaces were successfully added by asking
-   ovs-dpctl to print the current status of datapath dp0:
-
-      # ovs-dpctl show dp0
-
-3. Arrange so that the switch can reach the controller over the
-   network.
-
-      - If you are using out-of-band control, at this point make sure
-        that the switch machine can reach the controller over the
-        network.
-
-      - If you are using in-band control, then at this point you must
-        configure the dp0 network device created in step 1.  This
-        device is not yet bridged to any physical network (because
-        secchan does that, and it is not yet running), so the next
-        step depends on whether connectivity is required to configure
-        the device's IP address:
-
-           * If the switch has a static IP address, you may configure
-             its IP address now, e.g.:
-
-                # ifconfig dp0 192.168.1.1
-
-           * If the switch does not have a static IP address, e.g. its
-             IP address is obtained dynamically via DHCP, then proceed
-             to step 4.  The DHCP client will not be able to contact
-             the DHCP server until the secure channel has started up.
-
-      - If you are using in-band control with controller discovery, no
-        configuration is required at this point.  You may proceed to
-        step 4.
-
-4. Run secchan to start the secure channel connecting the datapath to
-   a remote controller.  If the controller is running on host
-   192.168.1.2 port 6633 (the default port), the secchan invocation
-   would look like this:
-
-      # secchan dp0 tcp:192.168.1.2
-
-   - If you are using in-band control with controller discovery, omit
-     the second argument to the secchan command.
-
-   - If you are using out-of-band control, add --out-of-band to the
-     command line.
-
-5. If you are using in-band control with manual configuration, and the
-   switch obtains its IP address dynamically, then you may now obtain
-   the switch's IP address, e.g. by invoking a DHCP client.  The
-   secure channel will only be able to connect to the controller after
-   an IP address has been obtained.
-
-6. The secure channel should connect to the controller within a few
-   seconds.  It may take a little longer if controller discovery is in
-   use, because the switch must then also obtain its own IP address
-   and the controller's location via DHCP.
-
-Configuration
-=============
-
-Secure operation over SSL
--------------------------
-
-The instructions above set up Open vSwitch for operation over a
-plaintext TCP connection.  Production use of Open vSwitch should use
-SSL[*] to ensure confidentiality and authenticity of traffic among
-switches and controllers.  The source must be configured with
---enable-ssl=yes to build with SSL support.
-
-To use SSL with Open vSwitch, you must set up a public-key infrastructure
-(PKI) including a pair of certificate authorities (CAs), one for
-controllers and one for switches.  If you have an established PKI,
-Open vSwitch can use it directly.  Otherwise, refer to "Establishing a
-Public Key Infrastructure" below.
-
-To configure the controller to listen for SSL connections on port 6633
-(the default), invoke it as follows:
-
-      # ovs-controller -v pssl: --private-key=PRIVKEY --certificate=CERT \
-            --ca-cert=CACERT
-
-where PRIVKEY is a file containing the controller's private key, CERT
-is a file containing the controller CA's certificate for the
-controller's public key, and CACERT is a file containing the root
-certificate for the switch CA.  If, for example, your PKI was created
-with the instructions below, then the invocation would look like:
-
-      # ovs-controller -v pssl: --private-key=ctl-privkey.pem \
-            --certificate=ctl-cert.pem --ca-cert=pki/switchca/cacert.pem
-
-To configure a switch to connect to a controller running on port 6633
-(the default) on host 192.168.1.2 over SSL, invoke secchan as follows:
-
-      # secchan -v DATAPATH ssl:192.168.1.2 --private-key=PRIVKEY \
-            --certificate=CERT --ca-cert=CACERT
-
-where DATAPATH is the datapath to connect to (e.g. dp0 or
-unix:/var/run/dp0.sock), PRIVKEY is a file containing the switch's
-private key, CERT is a file containing the switch CA's certificate for
-the switch's public key, and CACERT is a file containing the root
-certificate for the controller CA.  If, for example, your PKI was
-created with the instructions below, then the invocation would look
-like:
-
-      # secchan -v DATAPATH ssl:192.168.1.2 --private-key=sc-privkey.pem \
-            --certificate=sc-cert.pem --ca-cert=pki/controllerca/cacert.pem
-
-[*] To be specific, Open vSwitch uses TLS version 1.0 or later (TLSv1), as
-    specified by RFC 2246, which is very similar to SSL version 3.0.
-    TLSv1 was released in January 1999, so all current software and
-    hardware should implement it.
-
-Establishing a Public Key Infrastructure
-----------------------------------------
-
-If you do not have a PKI, the ovs-pki script included with Open vSwitch
-can help.  To create an initial PKI structure, invoke it as:
-      % ovs-pki init
-which will create and populate a new PKI directory.  The default
-location for the PKI directory depends on how the Open vSwitch tree was
-configured (to see the configured default, look for the --dir option
-description in the output of "ovs-pki --help").
-
-The pki directory contains two important subdirectories.  The
-controllerca subdirectory contains controller certificate authority
-related files, including the following:
-
-    - cacert.pem: Root certificate for the controller certificate
-      authority.  This file must be provided to secchan with the
-      --ca-cert option to enable it to authenticate valid controllers.
-
-    - private/cakey.pem: Private signing key for the controller
-      certificate authority.  This file must be kept secret.  There is
-      no need for switches or controllers to have a copy of it.
-
-The switchca subdirectory contains switch certificate authority
-related files, analogous to those in the controllerca subdirectory:
-
-    - cacert.pem: Root certificate for the switch certificate
-      authority.  This file must be provided to the controller program
-      with the --ca-cert option to enable it to authenticate valid
-      switches.
-
-    - private/cakey.pem: Private signing key for the switch
-      certificate authority.  This file must be kept secret.  There is
-      no need for switches or controllers to have a copy of it.
-
-After you create the initial structure, you can create keys and
-certificates for switches and controllers with ovs-pki.  To create a
-controller private key and certificate in files named ctl-privkey.pem
-and ctl-cert.pem, for example, you could run:
-      % ovs-pki req+sign ctl controller
-ctl-privkey.pem and ctl-cert.pem would need to be copied to the
-controller for its use at runtime (they could then be deleted from
-their original locations).  The --private-key and --certificate
-options of ovs-controller, respectively, would point to these files.
-
-Analogously, to create a switch private key and certificate in files
-named sc-privkey.pem and sc-cert.pem, for example, you could run: 
-      % ovs-pki req+sign sc switch
-sc-privkey.pem and sc-cert.pem would need to be copied to the switch
-for its use at runtime (they could then be deleted from their original
-locations).  The --private-key and --certificate options,
-respectively, of secchan would point to these files.
-
-Bug Reporting
--------------
-
-Please report problems to ovs-bugs@openvswitch.org.
diff --git a/INSTALL.Linux b/INSTALL.Linux
new file mode 100644 (file)
index 0000000..2683940
--- /dev/null
@@ -0,0 +1,171 @@
+                 How to Install Open vSwitch on Linux
+                 ====================================
+
+This document describes how to build and install Open vSwitch on a
+generic Linux host host.  If you want to install Open vSwitch on a
+Citrix XenServer 5.5.0, see INSTALL.XenServer instead.
+
+This version of Open vSwitch should be built manually with "configure"
+and "make".  Debian packaging for Open vSwitch is also included, but
+they have not been recently tested, and so Debian packages are not a
+recommended way to use this version of Open vSwitch.
+
+Build Requirements
+------------------
+
+To compile the userspace programs in the Open vSwitch distribution,
+you will need the following software:
+
+    - A make program, e.g. GNU make.  BSD make should also work.
+
+    - The GNU C compiler.  We generally test with version 4.1, 4.2, or
+      4.3.
+
+    - libssl, from OpenSSL, is optional but recommended if you plan to
+      connect the Open vSwitch to an OpenFlow controller.  libssl is
+      required to establish confidentiality and authenticity in the
+      connections from an Open vSwitch to an OpenFlow controller.  To
+      enable, configure with --enable-ssl=yes.
+
+To compile the kernel module (which is required for operation), you
+must also install the following:
+
+    - A supported Linux kernel version.  Please refer to README for a
+      list of supported versions.
+
+      The Open vSwitch datapath requires bridging support
+      (CONFIG_BRIDGE) to be built as a kernel module.  (This is common
+      in kernels provided by Linux distributions.)  The bridge module
+      must not be loaded or in use.  If the bridge module is running
+      (check with "lsmod | grep bridge"), you must remove it ("rmmod
+      bridge") before starting the datapath.
+
+      For optional support of ingress policing, you must enable kernel
+      configuration options NET_CLS_ACT, NET_CLS_U32, NET_SCH_INGRESS,
+      and NET_ACT_POLICE, either built-in or as modules.
+      (NET_CLS_POLICE is obsolete and not needed.)
+
+    - To build a kernel module, you need the same version of GCC that
+      was used to build that kernel.
+
+    - A kernel build directory corresponding to the Linux kernel image
+      the module is to run on.  Under Debian and Ubuntu, for example,
+      each linux-image package containing a kernel binary has a
+      corresponding linux-headers package with the required build
+      infrastructure.
+
+If you are working from a Git tree or snapshot (instead of from a
+distribution tarball), or if you modify the Open vSwitch build system,
+you will also need the following software:
+
+    - Autoconf version 2.60 or later.
+
+    - Automake version 1.10 or later.
+
+    - pkg-config.  We test with version 0.22.
+
+Installation Requirements
+-------------------------
+
+The machine on which Open vSwitch is to be installed must have the
+following software:
+
+    - libc compatible with the libc used for build.
+
+    - libssl compatible with the libssl used for build, if OpenSSL was
+      used for the build.
+
+    - The Linux kernel version configured as part of the build.
+
+    - For optional support of ingress policing, the "tc" program from
+      iproute2 (part of all major distributions and available at
+      http://www.linux-foundation.org/en/Net:Iproute2).
+
+    - For debugging purposes, Open vSwitch expects that "tcpdump" is
+      installed as /usr/sbin/tcpdump.  If tcpdump is not installed, or
+      if it is installed in a different location, then some Open
+      vSwitch log messages will not be as detailed.
+
+Building and Installing Open vSwitch for Linux
+==============================================
+
+Once you have installed all the prerequisites listed above in the Base
+Prerequisites section, follow the procedure below to build.
+
+1. In the top source directory, configure the package by running the
+   configure script.  You can usually invoke configure without any
+   arguments:
+
+      % ./configure
+
+   By default all files are installed under /usr/local.  If you want
+   to install into, e.g., /usr and /var instead of /usr/local and
+   /usr/local/var, add options as shown here:
+
+      % ./configure --prefix=/usr --localstatedir=/var
+
+   To use a specific C compiler for compiling Open vSwitch user
+   programs, also specify it on the configure command line, like so:
+
+      % ./configure CC=gcc-4.2
+
+   To build the Linux kernel module, so that you can run the
+   kernel-based switch, pass the location of the kernel build
+   directory on --with-l26.  For example, to build for a running
+   instance of Linux 2.6:
+
+      % ./configure --with-l26=/lib/modules/`uname -r`/build
+
+   If you wish to build the kernel module for an architecture other
+   than the architecture of the machine used for the build, you may
+   specify the kernel architecture string using the KARCH variable
+   when invoking the configure script.  For example, to build for MIPS
+   with Linux 2.6:
+
+      % ./configure --with-l26=/path/to/linux-2.6 KARCH=mips
+
+   The configure script accepts a number of other options and honors
+   additional environment variables.  For a full list, invoke
+   configure with the --help option.
+
+2. Run make in the top source directory: 
+
+      % make
+
+3. Become root by running "su" or another program.
+
+4. Run "make install" to install the executables and manpages into the
+   running system, by default under /usr/local.
+
+5. If you built kernel modules, you may load them with "insmod", e.g.:
+
+      % insmod datapath/linux-2.6/openvswitch_mod.ko
+
+   You may need to specify a full path to insmod, e.g. /sbin/insmod.
+   To verify that the modules have been loaded, run "/sbin/lsmod" and
+   check that openvswitch_mod is listed.
+
+Configuration
+=============
+
+Open vSwitch is configured primarily through a configuration file,
+whose name is specified on the ovs-vswitchd command line.  Please
+refer to ovs-vswitchd(8) and ovs-vswitchd.conf(5) for information on
+how to start ovs-vswitchd and the syntax of its configuration file,
+respectively.
+
+At runtime, you may make ovs-vswitchd reload its configuration file
+and update its configuration accordingly by sending it a SIGHUP
+signal.  The ovs-appctl utility can also be used to do this with a
+command such as:
+
+    % ovs-appctl -t <pid> -e vswitchd/reload
+
+where <pid> is ovs-vswitchd's process ID.  In the latter case,
+ovs-appctl will not exit until the reload and reconfiguration is
+complete.
+
+Bug Reporting
+-------------
+
+Please report problems to ovs-bugs@openvswitch.org.
diff --git a/INSTALL.SSL b/INSTALL.SSL
new file mode 100644 (file)
index 0000000..d672d62
--- /dev/null
@@ -0,0 +1,317 @@
+                   Configuring Open vSwitch for SSL
+                   ================================
+
+If you plan to configure Open vSwitch to connect across the network to
+an OpenFlow controller, then we recommend that you configure and
+enable SSL support in Open vSwitch.  SSL support ensures integrity and
+confidentiality of the OpenFlow connections, increasing network
+security.
+
+This file explains how to configure an Open vSwitch to connect to an
+OpenFlow controller over SSL.  Refer to INSTALL.Linux for instructions
+on building Open vSwitch with SSL support.  (In particular, you must
+pass --enable-ssl to the "configure" script to use SSL.)
+
+Open vSwitch uses TLS version 1.0 or later (TLSv1), as specified by
+RFC 2246, which is very similar to SSL version 3.0.  TLSv1 was
+released in January 1999, so all current software and hardware should
+implement it.
+
+This document assumes basic familiarity with public-key cryptography
+and public-key infrastructure.
+
+SSL Concepts for OpenFlow
+-------------------------
+
+This section is an introduction to the public-key infrastructure
+architectures that Open vSwitch supports for SSL authentication.
+
+To connect over SSL, every Open vSwitch must have a unique
+private/public key pair and a certificate that signs that public key.
+Typically, the Open vSwitch generates its own public/private key pair.
+There are two common ways to obtain a certificate for a switch:
+
+    * Self-signed certificates: The Open vSwitch signs its certificate
+      with its own private key.  In this case, each switch must be
+      individually approved by the OpenFlow controller(s), since there
+      is no central authority.
+
+      This is the only switch PKI model currently supported by NOX
+      (http://noxrepo.org).
+
+    * Switch certificate authority: A certificate authority (the
+      "switch CA") signs each Open vSwitch's public key.  The OpenFlow
+      controllers then check that any connecting switches'
+      certificates are signed by that certificate authority.
+
+      This is the only switch PKI model supported by the simple
+      OpenFlow controller included with Open vSwitch.
+
+Each Open vSwitch must also have a copy of the CA certificate for the
+certificate authority that signs OpenFlow controllers' keys (the
+"controller CA" certificate).  Typically, the same controller CA
+certificate is installed on all of the switches within a given
+administrative unit.  There are two common ways for a switch to obtain
+the controller CA certificate:
+
+    * Manually copy the certificate to the switch through some secure
+      means, e.g. using a USB flash drive, or over the network with
+      "scp", or even FTP or HTTP followed by manual verification.
+
+    * Open vSwitch "bootstrap" mode, in which Open vSwitch accepts and
+      saves the controller CA certificate that it obtains from the
+      OpenFlow controller on its first connection.  Thereafter the
+      switch will only connect to controllers signed by the same CA
+      certificate.
+
+Establishing a Public Key Infrastructure
+----------------------------------------
+
+Open vSwitch can make use of your existing public key infrastructure.
+If you already have a PKI, you may skip forward to the next section.
+Otherwise, if you do not have a PKI, the ovs-pki script included with
+Open vSwitch can help.  To create an initial PKI structure, invoke it
+as:
+
+    % ovs-pki init
+
+to create and populate a new PKI directory.  The default location for
+the PKI directory depends on how the Open vSwitch tree was configured
+(to see the configured default, look for the --dir option description
+in the output of "ovs-pki --help").
+
+The pki directory contains two important subdirectories.  The
+controllerca subdirectory contains controller CA files, including the
+following:
+
+    - cacert.pem: Root certificate for the controller certificate
+      authority.  Each Open vSwitch must have a copy of this file to
+      allow it to authenticate valid controllers.
+
+    - private/cakey.pem: Private signing key for the controller
+      certificate authority.  This file must be kept secret.  There is
+      no need for switches or controllers to have a copy of it.
+
+The switchca subdirectory contains switch CA files, analogous to those
+in the controllerca subdirectory:
+
+    - cacert.pem: Root certificate for the switch certificate
+      authority.  The OpenFlow controller must have this file to
+      enable it to authenticate valid switches.
+
+    - private/cakey.pem: Private signing key for the switch
+      certificate authority.  This file must be kept secret.  There is
+      no need for switches or controllers to have a copy of it.
+
+After you create the initial structure, you can create keys and
+certificates for switches and controllers with ovs-pki.  Refer to the
+ovs-pki(8) manage for complete details.  A few examples of its use
+follow:
+
+CONTROLLER KEY GENERATION
+
+To create a controller private key and certificate in files named
+ctl-privkey.pem and ctl-cert.pem, run the following on the machine
+that contains the PKI structure:
+
+      % ovs-pki req+sign ctl controller
+
+ctl-privkey.pem and ctl-cert.pem would need to be copied to the
+controller for its use at runtime.  If you were to use ovs-controller,
+the simple OpenFlow controller included with Open vSwitch, then the
+--private-key and --certificate options, respectively, would point to
+these files.
+
+It is very important to make sure that no stray copies of
+ctl-privkey.pem are created, because they could be used to impersonate
+the controller.
+
+SWITCH KEY GENERATION WITH SELF-SIGNED CERTIFICATES
+
+If you are using self-signed certificates (see "SSL Concepts for
+OpenFlow"), this is one way to create an acceptable certificate for
+your controller to approve.
+
+1. Run the following command on the Open vSwitch itself:
+
+       % ovs-pki self-sign sc
+
+   (This command does not require a copy of any of the PKI files
+   generated by "ovs-pki init", and you should not copy them to the
+   switch because some of them have contents that must remain secret
+   for security.)
+
+   The "ovs-pki self-sign" command has the following output:
+
+       * sc-privkey.pem, the switch private key file.  For security,
+         the contents of this file must remain secret.  There is
+         ordinarily no need to copy this file off the Open vSwitch.
+
+       * sc-cert.pem, the switch certificate, signed by the switch's
+         own private key.  Its contents are not a secret.
+
+2. Optionally, copy controllerca/cacert.pem from the machine that has
+   the OpenFlow PKI structure and verify that it is correct.
+   (Otherwise, you will have to use CA certificate bootstrapping when
+   you configure Open vSwitch in the next step.)
+
+3. Configure Open vSwitch to use the keys and certificates (see
+   "Configuring SSL Support", below).
+
+SWITCH KEY GENERATION WITH A SWITCH PKI (EASY METHOD)
+
+If you are using a switch PKI (see "SSL Concepts for OpenFlow",
+above), this method of switch key generation is a little easier than
+the alternate method described below, but it is also a little less
+secure because it requires copying a sensitive private key from file
+from the machine hosting the PKI to the switch.
+
+1. Run the following on the machine that contains the PKI structure:
+
+       % ovs-pki req+sign sc switch
+
+   This command has the following output:
+
+       * sc-privkey.pem, the switch private key file.  For
+         security, the contents of this file must remain secret.
+
+       * sc-cert.pem, the switch certificate.  Its contents are
+         not a secret.
+
+2. Copy sc-privkey.pem and sc-cert.pem, plus controllerca/cacert.pem,
+   to the Open vSwitch.
+
+3. Delete the copies of sc-privkey.pem and sc-cert.pem on the PKI
+   machine and any other copies that may have been made in transit.
+   It is very important to make sure that there are no stray copies of
+   sc-privkey.pem, because they could be used to impersonate the
+   switch.
+
+   (Don't delete controllerca/cacert.pem!  It is not
+   security-sensitive and you will need it to configure additional
+   switches.)
+
+4. Configure Open vSwitch to use the keys and certificates (see
+   "Configuring SSL Support", below).
+
+SWITCH KEY GENERATION WITH A SWITCH PKI (MORE SECURE)
+
+If you are using a switch PKI (see "SSL Concepts for OpenFlow",
+above), then, compared to the previous method, the method described
+here takes a little more work, but it does not involve copying the
+private key from one machine to another, so it may also be a little
+more secure.
+
+1. Run the following command on the Open vSwitch itself:
+
+       % ovs-pki req sc switch
+
+   (This command does not require a copy of any of the PKI files
+   generated by "ovs-pki init", and you should not copy them to the
+   switch because some of them have contents that must remain secret
+   for security.)
+
+   The "ovs-pki req" command has the following output:
+
+       * sc-privkey.pem, the switch private key file.  For security,
+         the contents of this file must remain secret.  There is
+         ordinarily no need to copy this file off the Open vSwitch.
+
+       * sc-req.pem, the switch "certificate request", which is
+         essentially the switch's public key.  Its contents are not a
+         secret.
+
+       * A fingerprint, on stdout.
+
+2. Write the fingerprint down on a slip of paper and copy sc-req.pem
+   to the machine that contains the PKI structure.
+
+3. On the machine that contains the PKI structure, run:
+
+       % ovs-pki sign sc switch
+
+   This command will output a fingerprint to stdout and request that
+   you verify it.  Check that it is the same as the fingerprint that
+   you wrote down on the slip of paper before you answer "yes".
+
+   "ovs-pki sign" creates a file named sc-cert.pem, which is the
+   switch certificate.  Its contents are not a secret.
+
+4. Copy the generated sc-cert.pem, plus controllerca/cacert.pem from
+   the PKI structure, to the Open vSwitch, and verify that they were
+   copied correctly.
+
+   You may delete sc-cert.pem from the machine that hosts the PKI
+   structure now, although it is not important that you do so.  (Don't
+   delete controllerca/cacert.pem!  It is not security-sensitive and
+   you will need it to configure additional switches.)
+
+5. Configure Open vSwitch to use the keys and certificates (see
+   "Configuring SSL Support", below).
+
+Configuring SSL Support
+-----------------------
+
+SSL configuration requires three additional configuration files.  The
+first two of these are unique to each Open vSwitch.  If you used the
+instructions above to build your PKI, then these files will be named
+sc-privkey.pem and sc-cert.pem, respectively:
+
+    - A private key file, which contains the private half of an RSA or
+      DSA key.
+
+      This file can be generated on the Open vSwitch itself, for the
+      greatest security, or it can be generated elsewhere and copied
+      to the Open vSwitch.
+
+      The contents of the private key file are secret and must not be
+      exposed.
+
+    - A certificate file, which certifies that the private key is that
+      of a trustworthy Open vSwitch.
+
+      This file has to be generated on a machine that has the private
+      key for the switch certification authority, which should not be
+      an Open vSwitch; ideally, it should be a machine that is not
+      networked at all.
+
+      The certificate file itself is not a secret.
+
+The third configuration file is typically the same across all the
+switches in a given administrative unit.  If you used the
+instructions above to build your PKI, then this file will be named
+cacert.pem:
+
+    - The root certificate for the controller certificate authority.
+      The Open vSwitch verifies it that is authorized to connect to an
+      OpenFlow controller by verifying a signature against this CA
+      certificate.
+
+Once you have these files, configure ovs-vswitchd to use them by
+adding the following keys to your ovs-vswitchd.conf file:
+
+    ssl.private-key=/etc/vswitch/sc-privkey.pem
+    ssl.certificate=/etc/vswitch/sc-cert.pem
+    ssl.ca-cert=/etc/vswitch/cacert.pem
+
+Substitute the correct file names, of course, if they differ from the
+ones used above.
+
+If you are using self-signed certificates (see "SSL Concepts for
+OpenFlow") and you did not copy controllerca/cacert.pem from the PKI
+machine to the Open vSwitch, then also add the following key:
+
+    ssl.bootstrap-ca-cert=true
+
+After you have added all of these configuration keys, you may specify
+"ssl:" connection methods elsewhere in ovs-vswitchd.conf, e.g.:
+
+    mgmt.controller=ssl:192.168.0.1
+
+"tcp:" connection methods are still allowed even after SSL has been
+configured, so for security you should use only "ssl:" connections.
+
+Reporting Bugs
+--------------
+
+Please report problems to ovs-bugs@openvswitch.org.
diff --git a/INSTALL.XenServer b/INSTALL.XenServer
new file mode 100644 (file)
index 0000000..bdfc26a
--- /dev/null
@@ -0,0 +1,70 @@
+           How to Install Open vSwitch on Citrix XenServer
+           ===============================================
+
+This document describes how to build and install Open vSwitch on a
+Citrix XenServer 5.5.0 host.  If you want to install Open vSwitch on a
+generic Linux host, see INSTALL.Linux instead.
+
+Building Open vSwitch for XenServer
+-----------------------------------
+
+The recommended build environment to build RPMs for Citrix XenServer
+is the DDK VM available from Citrix.  If you are building from an Open
+vSwitch distribution tarball, this VM has all the tools that you will
+need.  If you are building from an Open vSwitch Git tree, then you
+will need to first create a distribution tarball elsewhere, by running
+"./boot.sh; ./configure; make dist" in the Git tree, because the DDK
+VM does not include Autoconf or Automake that are required to
+bootstrap the Open vSwitch distribution.
+
+Once you have a distribution tarball, copy it into
+/usr/src/redhat/SOURCES inside the VM.  Then execute the following:
+
+   VERSION=<Open vSwitch version>
+   XENKERNEL=<Xen kernel version>
+   cd /tmp
+   tar xfz /usr/src/redhat/SOURCES/openvswitch-$VERSION.tar.gz
+   rpmbuild \
+        -D "vswitch_version $VERSION" \
+        -D "xen_version $XENKERNEL" \
+        -bb openvswitch-$VERSION/xenserver/vswitch-xen.spec
+
+where:
+
+    <openvswitch version> is the version number that appears in the
+    name of the Open vSwitch tarball, e.g. 0.90.0.
+
+    <Xen kernel version> is the version number of the Xen kernel,
+    e.g. 2.6.18-128.1.1.el5.xs5.5.0.487.1006xen.  This version number
+    appears as the name of a directory in /lib/modules inside the VM.
+    It always ends in "xen".
+
+Two RPMs will be output into /usr/src/redhat/RPMS, whose names begin
+with "vswitch" and "vswitch-debuginfo".
+
+Installing Open vSwitch for XenServer
+-------------------------------------
+
+To install Open vSwitch on a XenServer host, or to upgrade to a newer
+version, copy the "vswitch" RPM to that host with "scp", then install
+it with "rpm -U", e.g.:
+
+     scp vswitch-$VERSION-1.i386.rpm root@<host>:
+(At this point you will have to enter <host>'s root password.) 
+     ssh root@<host>
+(At this point you will have to enter <host>'s root password again.) 
+     rpm -U vswitch-$VERSION-1.i386.rpm
+
+To uninstall Open vSwitch from a XenServer host, remove the package:
+
+     ssh root@<host>
+(At this point you will have to enter <host>'s root password again.) 
+     rpm -e vswitch
+
+After installing or uninstalling Open vSwitch, the XenServer should be
+rebooted as soon as possible.
+
+Reporting Bugs
+--------------
+
+Please report problems to ovs-bugs@openvswitch.org.
index 18108cf020b4c264e04eb2a8bf92dfaf934de68e..44addf025551dc4430afea5848f340dd0ee1c084 100644 (file)
@@ -28,7 +28,7 @@ endif
 
 CLEANFILES =
 DISTCLEANFILES =
-EXTRA_DIST =
+EXTRA_DIST = INSTALL.Linux INSTALL.XenServer INSTALL.SSL
 TESTS =
 TESTS_ENVIRONMENT =
 bin_PROGRAMS =
diff --git a/README b/README
index 8991e4c81276b1a769731fffe4a6de650f57225d..7311292b6b9cfc6e9548cb244c8df929cb64e8c3 100644 (file)
--- a/README
+++ b/README
@@ -18,54 +18,67 @@ following features:
        * Connectivity to an external OpenFlow controller, such as
           NOX.
 
+Open vSwitch supports Linux 2.6.15 and up, with testing focused on
+2.6.18 with Centos and Xen patches and version 2.6.26 from kernel.org.
+Open vSwitch also has special support for Citrix XenServer hosts.
+
 What's here?
 ------------
 
-The most important components of this distribution are:
+The main components of this distribution are:
+
+        - ovs-vswitchd, a daemon that implements the virtual switch,
+          along with a companion Linux kernel module for flow-based
+          switching.
 
-       - A Linux kernel module for flow-based switching, in the
-          datapath directory.
+        - ovs-brcompatd, a daemon that allows ovs-vswitchd to act as a
+          drop-in replacement for the Linux bridge in many
+          environments, along with a companion Linux kernel module to
+          intercept bridge ioctls.
 
-        - ovs-vswitchd, a daemon that implements the virtual switch.
+       - ovs-dpctl, a tool for configuring the virtual switch kernel
+          module.
 
-       - ovs-dpctl, a tool for configuring the kernel module and
-          controlling OpenFlow switches.
+        - Scripts and specs for building RPMs that allow Open vSwitch
+          to be installed on a Citrix XenServer host as a drop-in
+          replacement for its virtual switch, with additional
+          functionality.
+
+       - vlog-appctl, a utility that can control Open vSwitch daemons,
+          adjusting their logging levels among other uses.
 
-This distribution includes some additional software as well:
+Open vSwitch also provides an OpenFlow implementation and tools for
+those interested in OpenFlow but not additional Open vSwitch features:
 
        - secchan, a program that implements a simple OpenFlow switch
           (without the special features provided by ovs-vswitchd) using
           the same kernel module as ovs-vswitchd.
 
-       - ovs-controller, a simple OpenFlow switch
+       - ovs-controller, a simple OpenFlow controller.
 
        - ovs-ofctl, a utility for querying and controlling OpenFlow
           switches and controllers.
 
-       - vlog-appctl, a utility that can control Open vSwitch daemons,
-          adjusting their logging levels among other uses.
-
        - ovs-pki, a utility for creating and managing the public-key
           infrastructure for OpenFlow switches.
 
        - A patch to tcpdump that enables it to parse OpenFlow
           messages.
 
-For installation instructions, read INSTALL.  Each userspace program
-is also accompanied by a manpage.
+What other documentation is available?
+--------------------------------------
 
-Platform support
-----------------
+To install Open vSwitch on a regular Linux machine, read INSTALL.Linux.
 
-Our primary test environment is Debian GNU/Linux.  Ports to other
-platforms are welcome.  Please contact us with portability-related bug
-reports or patches.
+To build RPMs for installing Open vSwitch on a Citrix XenServer host
+or resource pool, read INSTALL.XenServer.
 
-The testing of the kernel module has focused on version 2.6.18 from
-Xen and version 2.6.26 from kernel.org.  Linux 2.6 releases from
-2.6.15 onward should also work.
+To learn set up SSL support for Open vSwitch, read INSTALL.SSL.
 
-GCC is the expected compiler.
+Each Open vSwitch userspace program is accompanied by a manpage.  Many
+of the manpages are customized to your configuration as part of the
+build process, so we recommend building Open vSwitch before reading
+the manpages.
 
 Contact 
 -------