- Installation Instructions for OpenFlow Reference Release v0.1.5
+ Installation Instructions for OpenFlow Reference Release
-This document describes how to build, install, and execute the v0.1.5
+This document describes how to build, install, and execute the
reference implementation of OpenFlow. Please send any comments to:
<info@openflowswitch.org>
-Setting up the Kernel Build Environment
----------------------------------------
+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.1 or 4.2.
+
+ - 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 compile the datapath kernel module, you will additionally need:
+
+ - 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 datapath kernel module must be compiled against a kernel build
-directory for the Linux version the module is to run on. The datapath
-module has been mainly tested on Linux 2.6.23. Support for Linux 2.4
-is also in place, although it has only been lightly tested under 2.4.35.
+ - The correct version of GCC for the kernel that you are building
+ the module against:
-For example, if compiling on Debian or Ubuntu, the Linux headers
-and image packages must be installed (apt-get install
-linux-headers-<version> linux-image-<version>).
+ * 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).
-Note: the OpenFlow datapath requires that bridging support has been
-configured in the kernel, but not enabled 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 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 the Code
-----------------
-1. In the top source directory, configure the package, passing the
- location of the kernel build directory as an argument. Use
- --with-l26 for Linux 2.6, --with-l24 for Linux 2.4:
+1. In the top source directory, configure the package by running the
+ configure script. To compile without building a kernel module, you
+ can usually invoke configure without any arguments:
+ % ./configure
- For example, if compiling for a running instance of Linux 2.6:
+ To build a kernel module as well as the rest of the distribution,
+ pass the location of the kernel build directory as an argument.
+ Use --with-l26 for Linux 2.6, --with-l24 for Linux 2.4. For
+ example, to build for a running instance of Linux 2.6:
% ./configure --with-l26=/lib/modules/`uname -r`/build
- Or if compiling for a running instance of Linux 2.4:
+ To build for a running instance of Linux 2.4:
% ./configure --with-l24=/lib/modules/`uname -r`/build
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
+ The configure script accepts a number of other options and honors a
+ additional environment variables. For a full list, invoke
+ configure with the --help option.
+
2. Run make in the top source directory:
+ % make
- % make
+ The following binaries will be built:
- The following binaries will be built:
+ Datapath kernel module:
+ datapath/linux-2.6/openflow_mod.ko (if --with-l26 was specified)
+ datapath/linux-2.4/openflow_mod.o (if --with-l24 was specified)
- Datapath kernel module:
- ./datapath/linux-2.6/openflow_mod.ko (If compiling for Linux 2.6)
- ./datapath/linux-2.4/openflow_mod.o (If compiling for Linux 2.4)
+ Secure channel executable:
+ secchan/secchan
- Secure channel executable:
- ./secchan/secchan
+ Controller executable:
+ controller/controller
- Controller executable:
- ./controller/controller
+ Datapath administration utility:
+ utilities/dpctl
- Datapath administration utility:
- ./utilities/dpctl
+ 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.
To run the module, simply insmod it:
- (Linux 2.6)
- % insmod datapath/linux-2.6/openflow_mod.ko
+ (Linux 2.6)
+ % insmod datapath/linux-2.6/openflow_mod.ko
- (Linux 2.4)
- % insmod datapath/linux-2.4/compat24_mod.o
- % insmod datapath/linux-2.4/openflow_mod.o
+ (Linux 2.4)
+ % insmod datapath/linux-2.4/compat24_mod.o
+ % insmod datapath/linux-2.4/openflow_mod.o
Testing the datapath
1. Create a datapath instance. The command below creates a datapath with
ID 0 (see dpctl(8) for more detailed usage information).
-
- % dpctl adddp 0
+ % dpctl adddp 0
(note, while in principle openflow_mod supports multiple datapaths
within the same host, this is rarely useful in practice)
machine. Say, for example, you want to create a trivial 2-port
switch using interfaces eth1 and eth2, you would issue the following
commands:
-
- % dpctl addif 0 eth1
- % dpctl addif 0 eth2
+ % dpctl addif 0 eth1
+ % dpctl addif 0 eth2
You can verify that the interfaces were successfully added by asking
dpctl to print the current status of datapath 0:
-
- % dpctl show 0
+ % dpctl show 0
3. (Optional) You can manually add flows to the datapath to test using
dpctl add-flows and view them using dpctl dump-flows. See dpctl(8)
4. The simplest way to test the datapath is to run the provided sample
controller on the host machine to manage the datapath directly using
- netlink.
-
- % controller -v nl:0
+ netlink:
+ % controller -v nl:0
Once the controller is running, the datapath should operate like a
learning Ethernet switch. You may monitor the flows in the datapath
2. Run the controller in passive tcp mode on the host which will act as
the controller. In the example below, the controller will bind to
port 975 (the default) awaiting connections from secure channels.
-
- % controller -v ptcp:
+ % controller -v ptcp:
(See controller(8) for more details)
If the controller is running on host 192.168.1.2 port 975 (the
default port) and the datapath ID is 0, the secchan invocation
would look like:
-
- % secchan -v nl:0 tcp:192.168.1.2
+ % secchan -v nl:0 tcp:192.168.1.2
+
+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.
+
+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 the
+default port, 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 the
+default port on host 192.168.1.2 over SSL, invoke it as follows:
+ % secchan -v nl:0 ssl:192.168.1.2 --private-key=PRIVKEY \
+ --certificate=CERT --ca-cert=CACERT
+where 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 nl:0 ssl:192.168.1.2 --private-key=sc-privkey.pem \
+ --certificate=sc-cert.pem --ca-cert=pki/controllerca/cacert.pem
+
+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 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 of secchan,
+respectively, would point to these files.
Bug Reporting
-------------
projects / openvswitch / blobdiff