<info@openflowswitch.org>
+Contents
+========
+
+The OpenFlow reference implementation includes two OpenFlow switch
+implementations:
+
+ - The "kernel-based switch": This divides the switch into a
+ "datapath" Linux kernel module (openflow_mod.o for Linux 2.4
+ or openflow_mod.ko for Linux 2.6) and a userspace program
+ (secchan). The kernel-based switch is faster than either of
+ the other two implementations but requires building and
+ installing a kernel module, which can sometimes be
+ challenging.
+
+ - The "userspace datapath-based switch": This divides the
+ switch into a userspace "datapath" (built as
+ udatapath/udatapath) and the same userspace program used by
+ the kernel-based switch (secchan). The userspace
+ datapath-based switch does not require building a kernel
+ module, but it is not as fast as the kernel-based switch.
+
+The reference implementation also contains a simple OpenFlow
+controller (built as controller/controller) and a number of related
+utilities.
+
Build Methods
=============
- 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
+ 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).
+ - Autoconf version 2.60 or later (http://www.gnu.org/software/autoconf).
- Automake version 1.10 or later (http://www.gnu.org/software/automake).
"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:
The following binaries will be built:
- - 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.
+ - Userspace datapath: udatapath/udatapath.
- Secure channel executable: secchan/secchan.
- 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.
+
If you passed --with-l26 to configure, "make" will also build the
following kernel modules:
openflow-pki (see below).
- openflow-switch: Install this package on a machine that acts
- as an OpenFlow userspace or kernel switch.
+ as an OpenFlow kernel switch.
- openflow-datapath-source: Source code for OpenFlow's Linux
kernel module.
- Completely by hand, as described under the Testing section
below.
- For the userspace switch, this is the only supported form of
- configuration.
+ 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
% /etc/init.d/openflow-switch restart
This form of configuration is not supported for the userspace
- switch.
+ datapath-based switch.
- By running the ofp-switch-setup program. This interactive
program will walk you through all the steps of configuring an
% ofp-switch-setup
This form of configuration is not supported for the userspace
- switch.
+ datapath-based switch.
Testing
=======
-Testing Userspace Programs
---------------------------
+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.
-0. The commands below must run as root, so log in as root, or use a
- program such as "su" to become root temporarily.
+Userspace Datapath
+------------------
+
+These instructions use the OpenFlow userspace datapath ("udatapath").
1. Start the OpenFlow controller running in the background, by running
the "controller" program with a command like the following:
- # controller ptcp: &
+ # controller punix:/var/run/controller.sock &
- This command causes the controller to bind to port 975 (the
- default) awaiting connections from OpenFlow switches. See
+ 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. 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:
+2. The commands below must run as root, so log in as root, or use a
+ program such as "su" to become root temporarily.
- # switch tcp:127.0.0.1 -i eth1,eth2
+3. Create a datapath instance running in the background. The command
+ below creates a datapath that listens for connections from secchan
+ on a Unix domain socket located in /var/run and services physical
+ ports eth1 and eth2:
+
+ # udatapath punix:/var/run/dp0.sock -i eth1,eth2 &
+
+4. Run secchan to start the secure channel connecting the datapath and
+ the controller:
+
+ # secchan unix:/var/run/controller.sock unix:/var/run/dp0.sock &
- 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.)
+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.
-Testing the Kernel-Based Implementation
----------------------------------------
+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 secchan(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:
-The OpenFlow kernel module must be loaded, as described in the
-previous section, before it may be tested.
+(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. The command below creates a datapath with
- ID 0 (see dpctl(8) for more detailed usage information).
+1. Create a datapath instance running in the background. The command
+ below creates a datapath that listens for connections from secchan
+ 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:
- # dpctl adddp 0
-
- In principle, openflow_mod supports multiple datapaths within the
- same host, but this is rarely useful in practice.
+ # udatapath punix:/var/run/dp0.sock -i eth1,eth2 --local-port=tap:tap0 &
- 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".
+ (See udatapath(8) for details.)
-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:
+ 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.
- # dpctl addif 0 eth1
- # dpctl addif 0 eth2
+3. Arrange so that the switch can reach the controller over the
+ network.
- You can verify that the interfaces were successfully added by asking
- dpctl to print the current status of datapath 0:
+ - If you are using out-of-band control, at this point make sure
+ that the switch machine can reach the controller over the
+ network.
- # dpctl show 0
+ - 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:
-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.
+ * If the switch has a static IP address, you may configure
+ its IP address now, e.g.:
-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:
+ # ifconfig tap0 192.168.1.1
- # controller -v nl:0
+ * 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.
- 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.
+ - If you are using in-band control with controller discovery, no
+ configuration is required at this point. You may proceed to
+ step 4.
-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:
+4. Run secchan 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 secchan invocation
+ would look like this:
-1. Start the datapath and attach it to two or more physical ports as
- described in the previous section.
+ # secchan unix:/var/run/dp0.sock tcp:192.168.1.2
-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.
+ - If you are using in-band control with controller discovery, omit
+ the second argument to the secchan command.
- # controller -v ptcp:
+ - If you are using out-of-band control, add --out-of-band to the
+ command line.
- (See controller(8) for more details)
-
- Make sure the machine hosting the controller is reachable by the switch.
+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.
-3. Arrange so that the switch can reach the controller over the
- network. There are two ways to do this:
+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.
- - 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.
+Testing the Kernel-Based Implementation
+---------------------------------------
- - 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.
+The OpenFlow kernel module must be loaded, as described under
+"Building Conventionally", before it may be used.
- When in-band control is used, the location of the controller
- may be configured manually or discovered automatically:
+0. The commands below must run as root, so log in as root, or use a
+ program such as "su" to become root temporarily.
- * Manual configuration: Start by bringing up of0 before
- you start the secure channel:
+1. Create a datapath instance. The command below creates a datapath
+ identified as nl:0 (see dpctl(8) for more detailed usage
+ information).
- # ifconfig of0 up
+ # dpctl adddp nl:0
+
+ (nl:0 is the first datapath within a host. openflow_mod supports
+ multiple datapaths within the same host, which would be identified
+ as nl:1, nl:2, etc.)
+
+ Creating datapath nl:0 also creates a new network device named of0.
+ This network device, called the datapath's "local port", will be
+ bridged to the physical switch ports by the secchan, for use in
+ in-band control.
+
+ 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 nl:0 eth1
+ # dpctl addif nl:0 eth2
- 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:
+ You can verify that the interfaces were successfully added by asking
+ dpctl to print the current status of datapath nl:0:
+
+ # dpctl show nl:0
- . If the switch has a static IP address, you may
- configure its IP address now, e.g.:
+3. Arrange so that the switch can reach the controller over the
+ network.
- # ifconfig of0 192.168.1.1
+ - 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 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, then at this point you must
+ configure the of0 network device created in step 1. This
+ device is not yet bridged to any physical network (because
+ secchan does that, and it is not yet running), so the next
+ step depends on whether connectivity is required to configure
+ the device's IP address:
- * 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.
+ * If the switch has a static IP address, you may configure
+ its IP address now, e.g.:
-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 details depend on how you configured the
- network in step 3:
+ # ifconfig of0 192.168.1.1
- - If you are using in-band control and controller discovery,
- invoke secchan something like this:
+ * 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.
- # secchan -v nl:0
+ - If you are using in-band control with controller discovery, no
+ configuration is required at this point. You may proceed to
+ step 4.
- 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.
+4. Run secchan 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 secchan invocation
+ would look like this:
- - 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 nl:0 tcp:192.168.1.2
- # secchan -v nl:0 tcp:192.168.1.2
+ - If you are using in-band control with controller discovery, omit
+ the second argument to the secchan command.
- 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.
+ - If you are using out-of-band control, add --out-of-band to the
+ command line.
-5. If you are using the same network for control and data, and the
+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
=============
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
+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 \
# 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:
+To configure a switch to connect to a controller running on port 6633
+(the default) on host 192.168.1.2 over SSL, invoke secchan as follows:
- # switch -v ssl:192.168.1.2 -i INTERFACES --private-key=PRIVKEY \
+ # secchan -v DATAPATH ssl:192.168.1.2 --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:
+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:
- # secchan -v -i INTERFACES ssl:192.168.1.2 --private-key=sc-privkey.pem \
+ # secchan -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
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 switch or secchan
- program with the --ca-cert option to enable it to authenticate
- valid controllers.
+ authority. This file must be provided to secchan 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
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.
+respectively, of secchan would point to these files.
Bug Reporting
-------------
git://git.onelab.eu / sliver-openvswitch.git / blobdiff