Installation Instructions for OpenFlow Reference Release This document describes how to build, install, and execute the reference implementation of OpenFlow. Please send any comments to: Contents ======== The OpenFlow reference implementation includes one OpenFlow switch implementations: - The "userspace datapath-based switch": This divides the switch into a userspace "datapath" (built as udatapath/ofdatapath) and a userspace program that implements the secure channel component (ofprotocol). The userspace datapath-based switch does not require building a kernel module, but it is not as fast as a kernel-based switch. The reference implementation also contains a simple OpenFlow controller (built as controller/controller) and 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, 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. - 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 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 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 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. To build Debian packages without being root, also install the "fakeroot" package. Userspace Switch Prerequisites --------------------------------- - To enable slicing support, "tc" frontend should be installed (from iproute2, part of all major distributions, http://www.linux-foundation.org/en/Net:Iproute2). You also need to enable the following kernel configuration options under the QoS and/or Fair queueing section : CONFIG_NET_SCHED,CONFIG_NET_SCH_HTB (already configured that way in most distributions). (NOTE: You can disable slicing (and these dependencies) at runtime using the --no-slicing option) 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. Run `boot.sh` if necessary to create the configure script. % ./boot.sh 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 If you have hardware that supports accelerated OpenFlow switching and you have obtained a hardware table library for your hardware and extracted it into the OpenFlow reference distribution source tree, then you may also enable building support for the hardware switch table with --enable-hw-lib. For more information, read README.hwtables at the root of the OpenFlow distribution tree. 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 binaries will be built: - Userspace datapath: udatapath/ofdatapath. - Secure channel executable: secchan/ofprotocol. - Controller executable: controller/controller. - Datapath administration utility: utilities/dpctl. - Runtime logging configuration utility: utilities/vlogconf. - Miscellaneous utilities: utilities/ofp-discover, utilities/ofp-kill. - Tests: various binaries in tests/. If your distribution includes the OpenFlow extensions, the following additional binaries will be built: - ANSI terminal support for EZIO 16x2 LCD panel: ext/ezio/ezio-term. - Switch monitoring UI for small text displays: ext/ezio/ofp-switchui. 3. Run "make install" to install the executables and manpages into the running system, by default under /usr/local. 4. Test the userspace programs, as described under Testing Userspace Programs 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 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: % ofp-switch-setup This form of configuration is not supported for the userspace datapath-based switch. Testing ======= The following sets of instructions show how to use the OpenFlow reference implementation as a switch on a single machine. This can be used to verify that the distribution built properly. For full installation instructions, refer to the Installation section below. Userspace Datapath ------------------ These instructions use the OpenFlow userspace datapath ("ofdatapath"). 1. Start the OpenFlow controller running in the background, by running the "controller" program with a command like the following: # controller punix:/var/run/controller.sock & This command causes the controller to bind to the specified Unix domain socket, awaiting connections from OpenFlow switches. See controller(8) for details. The "controller" program does not require any special privilege, so you do not need to run it as root. 2. The commands below must run as root, so log in as root, or use a program such as "su" to become root temporarily. 3. Create a datapath instance running in the background. The command below creates a datapath that listens for connections from ofprotocol on a Unix domain socket located in /var/run and services physical ports eth1 and eth2: # ofdatapath punix:/var/run/dp0.sock -i eth1,eth2 & 4. Run ofprotocol to start the secure channel connecting the datapath and the controller: # ofprotocol unix:/var/run/controller.sock unix:/var/run/dp0.sock & 5. Devices plugged into the network ports specified in step 2 should now be able to send packets to each other, as if they were plugged into ports on a conventional Ethernet switch. Installation ============ This section explains how to install OpenFlow 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 ofprotocol(8) for instructions on setting up controller discovery. Controller Setup ---------------- On the machine that is to be the OpenFlow controller, start the "controller" program listening for connections from switches on TCP port 6633 (the default), as shown below. # controller -v ptcp: (See controller(8) for more details) Make sure the machine hosting the controller is reachable by the switch. Userspace Datapath-Based Setup ------------------------------ On a machine that is to host an OpenFlow userspace datapath-based switch, follow the procedure below. 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 running in the background. The command below creates a datapath that listens for connections from ofprotocol on a Unix domain socket located in /var/run, services physical ports eth1 and eth2, and creates a TAP network device named "tap0" for use in in-band control: # ofdatapath punix:/var/run/dp0.sock -i eth1,eth2 --local-port=tap:tap0 & (See ofdatapath(8) for details.) If the switch will connect to the controller out-of-band, then the --local-port option may be omitted, or --no-local-port may be substituted. 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 with manual configuration, at this point the TAP network device created in step 1 is not bridged to any physical network, 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 tap0 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 ofprotocol 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 ofprotocol invocation would look like this: # ofprotocol unix:/var/run/dp0.sock tcp:192.168.1.2 - If you are using in-band control with controller discovery, omit the second argument to the ofprotocol 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 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 6633 (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 6633 (the default) on host 192.168.1.2 over SSL, invoke ofprotocol as follows: # ofprotocol -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. nl:0 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: # ofprotocol -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, 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 init which will create and populate a new PKI directory. The default location for the PKI directory depends on how the OpenFlow tree was configured (to see the configured default, look for the --dir option description in the output of "ofp-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 ofprotocol 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 ofprotocol would point to these files. Bug Reporting ------------- Please report problems to: openflow-discuss@openflowswitch.org or post them to our online bug tracking system at: http://www.openflowswitch.org/bugs/openflow