- 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 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.
+ controllers. To enable, compile 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
- pkg-config (http://pkg-config.freedesktop.org/wiki/). We test
with version 0.22.
-Building the Code
------------------
+The optional Linux module has additional prerequisites, described
+later in the section "Building and Testing the Linux Kernel-Based
+Switch".
-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
+Building Userspace Programs
+---------------------------
- 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
+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.
- 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
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
+ - 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
+ - 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.
-Installing the datapath
------------------------
-
-To run the module, simply insmod it:
-
- (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
+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.
-Testing the datapath
---------------------
+1. Start the OpenFlow controller running in the background, by running
+ the "controller" program with a command like the following:
-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.
+ # controller ptcp: &
-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
+ This command causes the controller to bind to port 975 (the
+ default) awaiting connections from OpenFlow switches. See
+ controller(8) for details.
- (note, while in principle openflow_mod supports multiple datapaths
- within the same host, this is rarely useful in practice)
-
-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
-
- You can verify that the interfaces were successfully added by asking
- dpctl to print the current status of datapath 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)
- for more details.
-
-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
-
- 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
----------------------------------------------
-
-1. Start the datapath and attach it to two or more physical ports as
- described in the previous section.
+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:
- 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
- the controller. In the example below, the controller will bind to
- port 975 (the default) awaiting connections from secure channels.
- % controller -v ptcp:
-
- (See controller(8) for more details)
+ # switch tcp:127.0.0.1 -i eth1,eth2
- Make sure the machine hosting the controller is reachable by the switch.
-
-3. 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.
-
- 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
+ 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.)
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.
+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
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.
+
+Building and Testing the Linux Kernel-Based Switch
+--------------------------------------------------
+
+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:
+
+ - 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.
+
+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:
+
+ % ./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 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.
+
+In addition to the binaries listed under step 2 in "Building Userspace
+Programs" above, "make" will build the following kernel modules:
+
+ datapath/linux-2.6/openflow_mod.ko (if --with-l26 was specified)
+ datapath/linux-2.4/openflow_mod.o (if --with-l24 was specified)
+
+"make" will also build a kernel module for each hardware switch table
+enabled with --enable-hw-tables.
+
+Once you have built the kernel modules, activating them requires only
+running "insmod", e.g.:
+
+ (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
+
+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 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.
+
+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
+
+ 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
+
+ You can verify that the interfaces were successfully added by asking
+ dpctl to print the current status of datapath 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)
+ for more details.
+
+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
+
+ 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.
+
+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.
+
+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:
+
+ (See controller(8) for more details)
+
+ Make sure the machine hosting the controller is reachable by the switch.
+
+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. 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. For this
+ purpose, each datapath nl:K has a corresponding virtual
+ network device named ofK. 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.
+
+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.
+
+ 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 separate control and data networks, or if the
+ networks are combined 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.
Bug Reporting
-------------
git://git.onelab.eu / sliver-openvswitch.git / blobdiff