<info@openflowswitch.org>
-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.
+
+ - As a set of Debian packages. Refer to Building Debian
+ Packages, below, for instructions.
-To compile the userspace programs in the OpenFlow reference
-distribution, you will need the following software:
+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.
- 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.
+ 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.59 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.
+
+Kernel-Based Switch Prerequisites
+---------------------------------
-To compile the datapath kernel module, you will additionally need:
+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.
"lsmod | grep bridge"), you must remove it ("rmmod bridge")
before starting the datapath.
+ In kernels prior to 2.6.9, VLAN support (CONFIG_VLAN_8021Q) must
+ be compiled either directly or as a module. Failure to do this
+ will cause an error on module insertion due to the
+ "dev_change_flags" symbol being undefined.
+
- The correct version of GCC for the kernel that you are building
the module against:
corresponding linux-headers package with the required build
infrastructure.
-Building the Code
------------------
+Building Conventionally
+=======================
-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
+This section explains how to build and install the OpenFlow
+distribution in the ordinary way using "configure" and "make".
- 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
+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.
- To build for a running instance of Linux 2.4:
- % ./configure --with-l24=/lib/modules/`uname -r`/build
+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
- The configure script accepts a number of other options and honors a
+ 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.
2. Run make in the top source directory:
+
% make
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)
+ - Switch executable: switch/switch. This executable is built
+ only if the configure script detects a supported interface to
+ network devices. Refer to README for a list of OSes whose
+ network device interfaces are supported.
+
+ - Secure channel executable: secchan/secchan.
+
+ - Controller executable: controller/controller.
+
+ - Datapath administration utility: utilities/dpctl.
- Secure channel executable:
- secchan/secchan
+ - Runtime logging configuration utility: utilities/vlogconf.
- Controller executable:
- controller/controller
+ If you passed --with-l26 to configure, "make" will also build the
+ following kernel modules:
- Datapath administration utility:
- utilities/dpctl
+ - datapath/linux-2.6/openflow_mod.ko
- Runtime logging configuration utility:
- utilities/vlogconf
+ - datapath/linux-2.6/hwtable_<table>_mod.ko for each <table>
+ specified on --enable-hw-tables (if any).
-3. (Optional) Run "make install" to install the executables and
- manpages into the running system, by default under /usr/local.
+ If you passed --with-l24 to configure, "make" will also build the
+ following kernel modules:
-Installing the datapath
------------------------
+ - datapath/linux-2.4/openflow_mod.o
-To run the module, simply insmod it:
+ - datapath/linux-2.6/hwtable_<table>_mod.o for each <table>
+ specified on --enable-hw-tables (if any).
+
+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.:
(Linux 2.6)
% insmod datapath/linux-2.6/openflow_mod.ko
% insmod datapath/linux-2.4/compat24_mod.o
% insmod datapath/linux-2.4/openflow_mod.o
+ 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.
-Testing the datapath
---------------------
+ 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.
+
+4. Test the userspace programs, as described under Testing Userspace
+ Programs below.
+
+5. If you built the kernel module, test the kernel-based switch, as
+ described under Testing the Kernel-Based Implementation below.
+
+Building the Linux Kernel-Based Switch
+--------------------------------------
+
+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:
+
+ % ./configure --with-l26=/lib/modules/`uname -r`/build
+
+To build for a running instance of Linux 2.4:
+
+ % ./configure --with-l24=/lib/modules/`uname -r`/build
+
+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:
+
+ % ./configure --with-l24=/path/to/linux-2.4 KARCH=mips
+
+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:
+
+ % ./configure --with-l26=/lib/modules/`uname -r`/build \
+ --enable-hw-tables=foomatic
+
+For more information about hardware table modules, please read
+README.hwtables at the root of the OpenFlow distribution tree.
+
+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 userspace or kernel switch.
+
+ - openflow-datapath-source: Source code for OpenFlow's Linux
+ kernel module.
-Once the OpenFlow datapath has been installed (you can verify that it is
-running if it appears in lsmod's listing), you can configure it using
-the dpctl command line utility.
+ - 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 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
+ 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
+ switch.
+
+Testing
+=======
+
+Testing Userspace Programs
+--------------------------
+
+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. Start the OpenFlow controller running in the background, by running
+ the "controller" program with a command like the following:
+
+ # controller ptcp: &
+
+ 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:
+
+ # switch tcp:127.0.0.1 -i eth1,eth2
+
+ The network devices that you specify should not have configured IP
+ addresses.
+
+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
+---------------------------------------
+
+The OpenFlow kernel module must be loaded, as described in the
+previous section, before it may be tested.
+
+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 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)
+ In principle, openflow_mod supports multiple datapaths within the
+ same host, but this is rarely useful in practice.
+
+ If you built a support module for hardware accelerated OpenFlow
+ switching and you want to use it, you must load it before creating
+ the datapath with "dpctl adddp".
2. Use 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:
- % 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
+
+ # 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
flow table using "dpctl dump-flows" command.
-Running the datapath with a remote controller
----------------------------------------------
+The preceding 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. Use the
+following instructions to set up remote switches:
1. Start the datapath and attach it to two or more physical ports as
described in the previous section.
- Note: The current version of the secure channel and controller
- require at least one interface not be connected to the datapath
- to be functional. This interface will be used for communication
- between the secure channel and the controller. Future releases will
- support in-band control communication.
-
-2. Run the controller in passive tcp mode on the host which will act as
+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)
Make sure the machine hosting the controller is reachable by the switch.
-3. Run secchan on the datapath host to start the secure channel
+3. Arrange so that the switch can reach the controller over the
+ network. There are two ways to do this:
+
+ - Use a "control network" that is completely separate from the
+ "data network" to be controlled ("out-of-band control"). To
+ do so, configure a network device (one that has not been added
+ to the datapath with "dpctl addif") to access the control
+ network in the usual way.
+
+ - Use the same network for control and for data ("in-band
+ control"). For this purpose, each datapath nl:K has a
+ corresponding virtual network device named ofK.
+
+ When in-band control is used, the location of the controller
+ may be configured manually or discovered automatically:
+
+ * Manual configuration: Start by bringing up of0 before
+ you start the secure channel:
+
+ # ifconfig of0 up
+
+ Before the secure channel starts up, the of0 device
+ cannot send or receive any packets, 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 of0 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.
+
+ * Controller discovery: No special setup is required at
+ the switch, but you must specially configure a DHCP
+ server to give out the switch's IP address and to tell
+ it the location of the controller. See secchan(8) for
+ details.
+
+4. Run secchan on the datapath host to start the secure channel
connecting the datapath to a remote controller. (See secchan(8)
- for usage details). The channel should be configured to connect to
- the controller's IP address on the port configured in step 2.
+ for usage details). The details depend on how you configured the
+ network in step 3:
+
+ - If you are using in-band control and controller discovery,
+ invoke secchan something like this:
- 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
+
+ The secure channel should connect to the controller after it
+ obtains its own IP address and the controller's location via
+ DHCP. This can take a few seconds. Switch setup is now
+ complete.
+
+ - Otherwise, the secure channel should be configured to connect
+ to the controller's IP address on the port configured in step
+ 2. 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
+
+ If you are using out-of-band control, or if you are using
+ in-band control and the switch has a static IP address, the
+ secure channel should quickly connect to the controller.
+ Setup is now complete. Otherwise, proceed to step 5.
+
+5. If you are using the same network for control and data, 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.
+
+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.
+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
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 \
+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 \
+
+ # 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 \
+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 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
+
+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 nl:0 ssl:192.168.1.2 --private-key=sc-privkey.pem \
+
+ # 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.
+ % 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 the secchan
- program with the --ca-cert option to enable it to
- authenticate valid controllers.
+ 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
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:
+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.
+locations). The --private-key and --certificate options,
+respectively, of switch and secchan would point to these files.
Bug Reporting
-------------
git://git.onelab.eu / sliver-openvswitch.git / blobdiff