X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=INSTALL;fp=INSTALL;h=618affdfc6f461fe3a22b582b16017732c2b04d5;hb=91c3455d0dd693fb33854f86d6fc7a47c52cf85a;hp=742a18de4dae47c853e0559e02e61692a7e754a1;hpb=5990f0423c7bd551d6159baa0f3596110865775b;p=sliver-openvswitch.git diff --git a/INSTALL b/INSTALL index 742a18de4..618affdfc 100644 --- a/INSTALL +++ b/INSTALL @@ -5,11 +5,23 @@ reference implementation of OpenFlow. Please send any comments to: -Prerequisites -------------- +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. -To compile the userspace programs in the OpenFlow reference -distribution, you will need the following software: + - As a set of Debian packages. Refer to Building Debian + Packages, below, for instructions. + +Base Prerequisites +------------------ + +Regardless of how it is built, OpenFlow 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. @@ -20,7 +32,7 @@ distribution, you will need the following software: - libssl, from OpenSSL (http://www.openssl.org/), is optional but recommended. libssl is required to establish confidentiality and authenticity in the connections among OpenFlow switches and - controllers. To enable, compile with --enable-ssl=yes + controllers. To enable, configure with --enable-ssl=yes If you are working from a Git tree or snapshot (instead of from a distribution tarball), or if you modify the OpenFlow build system, you @@ -33,21 +45,64 @@ will also need the following software: - pkg-config (http://pkg-config.freedesktop.org/wiki/). We test with version 0.22. -The optional Linux module has additional prerequisites, described -later in the section "Building and Testing the Linux Kernel-Based -Switch". +Debian Prerequisites +-------------------- + +To build Debian packages from the OpenFlow 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. -Building Userspace Programs ---------------------------- +To build Debian packages without being root, also install the +"fakeroot" package. -The OpenFlow distribution includes two implementations of the switch: -one entirely in userspace, for portability and ease of installation, -and another with a Linux kernel module component that is more -difficult to install but should also yield better performance. These -instructions describe how to build the userspace components of the -OpenFlow distribution. Refer to "Building and Testing the Linux -Kernel-Based Switch", below, for additional instructions on how to -build the optional Linux kernel module. +Kernel-Based Switch Prerequisites +--------------------------------- + +The OpenFlow distribution also includes a Linux kernel module that can +be used to achieve higher switching performance. To compile the +kernel module, you must install the following in addition to the +software listed in the "Base Prerequisites" section above: + + - 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. + + - The correct version of GCC for the kernel that you are building + the module against: + + * To build a kernel module for a Linux 2.6 kernel, you need + the same version of GCC that was used to build that kernel + (usually version 4.0 or later). + + * To build a kernel module for a Linux 2.4 kernel, you need an + earlier version of GCC, typically GCC 2.95, 3.3, or 3.4. + + - 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. + +Building Conventionally +======================= + +This section explains how to build and install the OpenFlow +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. If you want to compile the Linux + kernel module, also check that the prequisites listed under + Kernel-Based Switch Prequisites are installed. 1. In the top source directory, configure the package by running the configure script. You can usually invoke configure without any @@ -60,6 +115,11 @@ build the optional Linux kernel module. % ./configure CC=gcc-4.2 + To build the Linux kernel module, so that you can run the + kernel-based switch, add --with-l26 or --with-l24 option, or both, + to the configure script's command line. Refer to Building the + Linux Kernel-Based Switch, below, for more information. + The configure script accepts a number of other options and honors additional environment variables. For a full list, invoke configure with the --help option. @@ -83,253 +143,216 @@ build the optional Linux kernel module. - Runtime logging configuration utility: utilities/vlogconf. -3. (Optional) Run "make install" to install the executables and - manpages into the running system, by default under /usr/local. + If you passed --with-l26 to configure, "make" will also build the + following kernel modules: -Testing Userspace Programs --------------------------- + - datapath/linux-2.6/openflow_mod.ko -0. The commands below must run as root, so log in as root, or use a - program such as "su" to become root temporarily. + - datapath/linux-2.6/hwtable__mod.ko for each
+ specified on --enable-hw-tables (if any). -1. Start the OpenFlow controller running in the background, by running - the "controller" program with a command like the following: + If you passed --with-l24 to configure, "make" will also build the + following kernel modules: - # controller ptcp: & + - datapath/linux-2.4/openflow_mod.o - This command causes the controller to bind to port 975 (the - default) awaiting connections from OpenFlow switches. See - controller(8) for details. - -2. On the same machine, use the "switch" program to start an OpenFlow - switch, specifying network devices to use as switch ports on the -i - option as a comma-separated list, like so: + - datapath/linux-2.6/hwtable_
_mod.o for each
+ specified on --enable-hw-tables (if any). - # switch tcp:127.0.0.1 -i eth1,eth2 - - The network devices that you specify should not have configured IP - addresses. +3. Run "make install" to install the executables and manpages into the + running system, by default under /usr/local. -3. The controller causes each switch that connects to it to act like a - learning Ethernet switch. Thus, devices plugged into the specified - network ports should now be able to send packets to each other, as - if they were plugged into ports on a conventional Ethernet switch. +4. If you built kernel modules, you may load them with "insmod", e.g.: -Troubleshooting: if the commands above do not work, try using the -v -or --verbose option on the controller or switch commands, which will -cause a large amount of debug output from each program. + (Linux 2.6) + % insmod datapath/linux-2.6/openflow_mod.ko -Remote switches: These instructions assume that the controller and the -switch are running on the same machine. This is an easy configuration -for testing, but a more conventional setup would run a controller on -one machine and one or more switches on different machines. To do so, -simply specify the IP address of the controller as the first argument -to the switch program (in place of 127.0.0.1). (Note: The userspace -switch must be connected to the controller over a "control network" -that is physically separate from the one that the switch and -controller are controlling. The kernel-based switch does not have -this limitation.) + (Linux 2.4) + % insmod datapath/linux-2.4/compat24_mod.o + % insmod datapath/linux-2.4/openflow_mod.o -Secure operation over SSL -------------------------- + After you load the openflow module, you may load one hardware switch + table module (if any were built) to enable support for that hardware + switching table. -The instructions above set up OpenFlow for operation over a plaintext -TCP connection. Production use of OpenFlow 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. + 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. -To use SSL with OpenFlow, 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, -OpenFlow can use it directly. Otherwise, refer to "Establishing a -Public Key Infrastructure" below. +4. Test the userspace programs, as described under Testing Userspace + Programs below. -To configure the controller to listen for SSL connections on port 976 -(the default), invoke it as follows: +5. If you built the kernel module, test the kernel-based switch, as + described under Testing the Kernel-Based Implementation below. - # controller -v pssl: --private-key=PRIVKEY --certificate=CERT \ - --ca-cert=CACERT +Building the Linux Kernel-Based Switch +-------------------------------------- -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: +To build the kernel module, follow the build process described above, +but pass the location of the kernel build directory as an additional +argument to the configure script, as described under step 1 in that +section. Specify the location on --with-l26 for Linux 2.6, --with-l24 +for Linux 2.4. For example, to build for a running instance of Linux +2.6: - # controller -v pssl: --private-key=ctl-privkey.pem \ - --certificate=ctl-cert.pem --ca-cert=pki/switchca/cacert.pem + % ./configure --with-l26=/lib/modules/`uname -r`/build -To configure a switch to connect to a controller running on port 976 -(the default) on host 192.168.1.2 over SSL, invoke it as follows: +To build for a running instance of Linux 2.4: - # switch -v ssl:192.168.1.2 -i INTERFACES --private-key=PRIVKEY \ - --certificate=CERT --ca-cert=CACERT + % ./configure --with-l24=/lib/modules/`uname -r`/build -where INTERFACES is the command-separated list of network device -interfaces, 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: +If you wish to build OpenFlow for an architecture other than the +architecture used for compilation, you may specify the kernel +architecture string using the KARCH variable when invoking the +configure script. For example, to build OpenFlow for MIPS with Linux +2.4: - # secchan -v -i INTERFACES ssl:192.168.1.2 --private-key=sc-privkey.pem \ - --certificate=sc-cert.pem --ca-cert=pki/controllerca/cacert.pem + % ./configure --with-l24=/path/to/linux-2.4 KARCH=mips -[*] To be specific, OpenFlow 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. +If you have hardware that supports accelerated OpenFlow switching, and +you have obtained a hardware table module for your hardware and +extracted it into the OpenFlow reference distribution source tree, +then you may also enable building support for the hardware switching +table with --enable-hw-tables. For example, if your hardware +switching table is in a directory named datapath/hwtable-foomatic, you +could compile support for it with the running Linux 2.6 kernel like +so: -Establishing a Public Key Infrastructure ----------------------------------------- + % ./configure --with-l26=/lib/modules/`uname -r`/build \ + --enable-hw-tables=foomatic -If you do not have a PKI, the ofp-pki script included with OpenFlow -can help. To create an initial PKI structure, invoke it as: - % ofp-pki new-pki -which will create and populate a new directory named "pki" under the -current directory. +For more information about hardware table modules, please read +README.hwtables at the root of the OpenFlow distribution tree. -The pki directory contains two important subdirectories. The -controllerca subdirectory contains controller certificate authority -related files, including the following: +Building Debian Packages +======================== - - cacert.pem: Root certificate for the controller certificate - authority. This file must be provided to the switch or secchan - program with the --ca-cert option to enable it to authenticate - valid controllers. +Follow these instructions to build Debian packages for OpenFlow. - - 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. +0. Check that you have installed all the prerequisites listed above in + the Base Prerequisites and Debian Prerequisites sections above. -The switchca subdirectory contains switch certificate authority -related files, analogous to those in the controllerca subdirectory: +1. In the top source directory, run the following command, as root: - - 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. + % dpkg-buildpackage - - 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. + Alternatively, if you installed the "fakeroot" package, you may run + dpkg-buildpackage as an ordinary user with the following syntax: -After you create the initial structure, you can create keys and -certificates for switches and controllers with ofp-pki. To create a -controller private key and certificate in files named ctl-privkey.pem -and ctl-cert.pem, for example, you could run: - % ofp-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 controller, respectively, would point to these files. + % dpkg-buildpackage -rfakeroot -Analogously, to create a switch private key and certificate in files -named sc-privkey.pem and sc-cert.pem, for example, you could run: - % ofp-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 switch and secchan would point to these files. + The following packages will be built in the directory above the + source tree: -Building and Testing the Linux Kernel-Based Switch --------------------------------------------------- + - openflow-controller: The OpenFlow controller. Depends on + openflow-pki (see below). -The OpenFlow distribution also includes a Linux kernel module that can -be used to achieve higher switching performance at a cost in -portability and ease of installation. Compiling the kernel module has -the following prerequisites in addition to those listed in the -"Prerequisites" section above: + - openflow-switch: Install this package on a machine that acts + as an OpenFlow userspace or kernel switch. - - A supported Linux kernel version. Please refer to README for a - list of supported versions. + - openflow-datapath-source: Source code for OpenFlow's Linux + kernel module. - 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. + - 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). - - The correct version of GCC for the kernel that you are building - the module against: + - openflow-common: Files and utilities required by more than one + of the above packages. - * To build a kernel module for a Linux 2.6 kernel, you need - the same version of GCC that was used to build that kernel - (usually version 4.0 or later). +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: - * To build a kernel module for a Linux 2.4 kernel, you need an - earlier version of GCC, typically GCC 2.95, 3.3, or 3.4. + % /etc/init.d/openflow-controller restart - - 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. +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. -To build the kernel module, follow the build process described under -"Building Userspace Programs" above, but pass the location of the -kernel build directory as an additional argument to the configure -script, as described under step 1 in that section. Specify the -location on --with-l26 for Linux 2.6, --with-l24 for Linux 2.4. For -example, to build for a running instance of Linux 2.6: + You may configure the switch one of the following ways: - % ./configure --with-l26=/lib/modules/`uname -r`/build + - Completely by hand, as described under the Testing section + below. -To build for a running instance of Linux 2.4: + For the userspace switch, this is the only supported form of + configuration. - % ./configure --with-l24=/lib/modules/`uname -r`/build + - 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". -If you wish to build OpenFlow for an architecture other than the architecture -used for compilation, you may specify the kernel architecture string using the -KARCH variable when invoking the configure script. For example, to build -OpenFlow for MIPS with Linux 2.4: + After you edit this file, you will need to start the switch by + running: - % ./configure --with-l24=/path/to/linux-2.4 KARCH=mips + % /etc/init.d/openflow-switch restart -If you have hardware that supports accelerated OpenFlow switching, and -you have obtained a hardware table module for your hardware and -extracted it into the OpenFlow reference distribution source tree, -then you may also enable building support for the hardware switching -table with --enable-hw-tables. For example, if your hardware -switching table is in a directory named datapath/hwtable-foomatic, you -could compile support for it with the running Linux 2.6 kernel like -so: + This form of configuration is not supported for the userspace + switch. - % ./configure --with-l26=/lib/modules/`uname -r`/build \ - --enable-hw-tables=foomatic + - By running the ofp-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: -For more information about hardware table modules, please read -README.hwtables at the root of the OpenFlow distribution tree. + % ofp-switch-setup -In addition to the binaries listed under step 2 in "Building Userspace -Programs" above, "make" will build the following kernel modules: + This form of configuration is not supported for the userspace + switch. - datapath/linux-2.6/openflow_mod.ko (if --with-l26 was specified) - datapath/linux-2.4/openflow_mod.o (if --with-l24 was specified) +Testing +======= + +Testing Userspace Programs +-------------------------- -"make" will also build a kernel module for each hardware switch table -enabled with --enable-hw-tables. +0. The commands below must run as root, so log in as root, or use a + program such as "su" to become root temporarily. -Once you have built the kernel modules, activating them requires only -running "insmod", e.g.: +1. Start the OpenFlow controller running in the background, by running + the "controller" program with a command like the following: - (Linux 2.6) - % insmod datapath/linux-2.6/openflow_mod.ko + # controller ptcp: & - (Linux 2.4) - % insmod datapath/linux-2.4/compat24_mod.o - % insmod datapath/linux-2.4/openflow_mod.o + This command causes the controller to bind to port 975 (the + default) awaiting connections from OpenFlow switches. See + controller(8) for details. + +2. On the same machine, use the "switch" program to start an OpenFlow + switch, specifying network devices to use as switch ports on the -i + option as a comma-separated list, like so: -After you load the openflow module, you may load one hardware switch -table module (if any were built) to enable support for that hardware -switching table. + # switch tcp:127.0.0.1 -i eth1,eth2 + + The network devices that you specify should not have configured IP + addresses. -The insmod program must be run as root. You may need to specify a -full path to insmod, which is usually in the /sbin directory. To -verify that the modules have been loaded, run "lsmod" (also in /sbin) -and check that openflow_mod appears in the result. +3. The controller causes each switch that connects to it to act like a + learning Ethernet switch. Thus, devices plugged into the specified + network ports should now be able to send packets to each other, as + if they were plugged into ports on a conventional Ethernet switch. + +Troubleshooting: if the commands above do not work, try using the -v +or --verbose option on the controller or switch commands, which will +cause a large amount of debug output from each program. + +Remote switches: These instructions assume that the controller and the +switch are running on the same machine. This is an easy configuration +for testing, but a more conventional setup would run a controller on +one machine and one or more switches on different machines. To do so, +simply specify the IP address of the controller as the first argument +to the switch program (in place of 127.0.0.1). (Note: The userspace +switch must be connected to the controller over a "control network" +that is physically separate from the one that the switch and +controller are controlling. The kernel-based switch does not have +this limitation.) Testing the Kernel-Based Implementation --------------------------------------- @@ -475,6 +498,112 @@ following instructions to set up remote switches: secure channel will only be able to connect to the controller after an IP address has been obtained. +Configuration +============= + +Secure operation over SSL +------------------------- + +The instructions above set up OpenFlow for operation over a plaintext +TCP connection. Production use of OpenFlow 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 OpenFlow, 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, +OpenFlow can use it directly. Otherwise, refer to "Establishing a +Public Key Infrastructure" below. + +To configure the controller to listen for SSL connections on port 976 +(the default), invoke it as follows: + + # 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: + + # 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 976 +(the default) on host 192.168.1.2 over SSL, invoke it as follows: + + # switch -v ssl:192.168.1.2 -i INTERFACES --private-key=PRIVKEY \ + --certificate=CERT --ca-cert=CACERT + +where INTERFACES is the command-separated list of network device +interfaces, 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 -i INTERFACES ssl:192.168.1.2 --private-key=sc-privkey.pem \ + --certificate=sc-cert.pem --ca-cert=pki/controllerca/cacert.pem + +[*] To be specific, OpenFlow 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 ofp-pki script included with OpenFlow +can help. To create an initial PKI structure, invoke it as: + % ofp-pki new-pki +which will create and populate a new directory named "pki" under the +current directory. + +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 the switch or secchan + program 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 ofp-pki. To create a +controller private key and certificate in files named ctl-privkey.pem +and ctl-cert.pem, for example, you could run: + % ofp-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 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: + % ofp-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 switch and secchan would point to these files. + Bug Reporting -------------