diff options
Diffstat (limited to 'INSTALL')
| -rw-r--r-- | INSTALL | 514 |
1 files changed, 514 insertions, 0 deletions
diff --git a/INSTALL b/INSTALL new file mode 100644 index 000000000..994e8d320 --- /dev/null +++ b/INSTALL @@ -0,0 +1,514 @@ + 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. |