284 lines
11 KiB
Plaintext
284 lines
11 KiB
Plaintext
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:
|
|
|
|
<info@openflowswitch.org>
|
|
|
|
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 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.
|
|
|
|
Building the Code
|
|
-----------------
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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)
|
|
|
|
Secure channel executable:
|
|
secchan/secchan
|
|
|
|
Controller executable:
|
|
controller/controller
|
|
|
|
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.
|
|
|
|
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 the datapath
|
|
--------------------
|
|
|
|
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.
|
|
|
|
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
|
|
|
|
(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.
|
|
|
|
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)
|
|
|
|
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
|
|
|
|
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
|
|
|
|
[*] 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.
|
|
|
|
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
|
|
-------------
|
|
|
|
Please report problems to:
|
|
info@openflowswitch.org
|