From: Ben Pfaff Date: Tue, 9 Jun 2009 20:09:08 +0000 (-0700) Subject: Update documentation. X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4b11d5e8d34655977d716cbdba504528aa866997;p=openvswitch Update documentation. --- diff --git a/INSTALL b/INSTALL deleted file mode 100644 index 994e8d32..00000000 --- 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 index 00000000..26839409 --- /dev/null +++ b/INSTALL.Linux @@ -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 -e vswitchd/reload + +where 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 index 00000000..d672d627 --- /dev/null +++ b/INSTALL.SSL @@ -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 index 00000000..bdfc26a9 --- /dev/null +++ b/INSTALL.XenServer @@ -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= + XENKERNEL= + 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: + + is the version number that appears in the + name of the Open vSwitch tarball, e.g. 0.90.0. + + 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@: +(At this point you will have to enter 's root password.) + ssh root@ +(At this point you will have to enter 's root password again.) + rpm -U vswitch-$VERSION-1.i386.rpm + +To uninstall Open vSwitch from a XenServer host, remove the package: + + ssh root@ +(At this point you will have to enter '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. diff --git a/Makefile.am b/Makefile.am index 18108cf0..44addf02 100644 --- a/Makefile.am +++ b/Makefile.am @@ -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 8991e4c8..7311292b 100644 --- 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 -------