SunnyQjm/openflow
1
0 Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Update documentation to talk about userspace datapath.

Browse Source
This commit is contained in:
Ben Pfaff committed 2008-10-09 15:53:05 -07:00
1 parent a6a94c514f
commit 8cfc2d6f69
1 file changed
+310 -133
Download Patch File Download Diff File Expand all files Collapse all files
INSTALL
+310 -133
View File
@@ -5,6 +5,39 @@ reference implementation of OpenFlow. Please send any comments to:
<info@openflowswitch.org>
Contents
========
The OpenFlow reference implementation includes three separate
OpenFlow switch implementations:
- The "userspace switch": This implements an OpenFlow switch
as a single user program (built as switch/switch). The
userspace switch is the easiest to build and use but it is
much less featureful than the other 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 is as featureful as the kernel-based
switch and it does not require building a kernel module, but
it is not as fast as the kernel-based switch and it is part
of the OpenFlow extensions distribution, not the main
OpenFlow distribution.
The reference implementation also contains a simple OpenFlow
controller (built as controller/controller) and a number of related
utilities.
Build Methods
=============
@@ -135,10 +168,7 @@ distribution in the ordinary way using "configure" and "make".
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.
- Switch executable: switch/switch.
- Secure channel executable: secchan/secchan.
@@ -148,6 +178,22 @@ distribution in the ordinary way using "configure" and "make".
- 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:
- Userspace datapath: ext/udatapath/udatapath.
- ANSI terminal support for EZIO 16x2 LCD panel:
ext/ezio/ezio-term.
- Switch monitoring UI for small text displays:
ext/ezio/ofp-switchmon.
If you passed --with-l26 to configure, "make" will also build the
following kernel modules:
@@ -315,8 +361,16 @@ Follow these instructions to build Debian packages for OpenFlow.
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.
Userspace Switch
----------------
These instructions use the OpenFlow userspace switch that runs as an
integrated userspace program.
0. The commands below must run as root, so log in as root, or use a
program such as "su" to become root temporarily.
@@ -348,33 +402,213 @@ 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.)
Userspace Datapath
------------------
Testing the Kernel-Based Implementation
---------------------------------------
The OpenFlow kernel module must be loaded, as described in the
previous section, before it may be tested.
These instructions use the OpenFlow userspace datapath ("udatapath").
The udatapath program is part of the OpenFlow extensions repository,
which is not included in every OpenFlow distribution.
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. Start the OpenFlow controller running in the background, by running
the "controller" program with a command like the following:
# dpctl adddp 0
# 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.
In principle, openflow_mod supports multiple datapaths within the
same host, but this is rarely useful in practice.
2. 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 &
3. Run secchan to start the secure channel connecting the datapath and
the controller:
# secchan unix:/var/run/controller.sock unix:/var/run/dp0.sock &
4. 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.
All three switch implementations support only out-of-band
control.
- 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.
The userspace datapath-based and kernel-based switch
implementations support in-band control. The userspace switch
does not.
Controller Setup
----------------
On the machine that is to be the OpenFlow controller, start the
"controller" program listening for connections from switches on TCP
port 975 (the default), as shown below. (Because it listens on a
low-numbered port, this command must run as root.)
# controller -v ptcp:
(See controller(8) for more details)
Make sure the machine hosting the controller is reachable by the
switch.
Userspace Switch-Based Setup
----------------------------
To set up an OpenFlow switch using the userspace switch, follow this
procedure. 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 and
userspace datapath-based switches do not have this limitation.)
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. Use the "switch" program to start an OpenFlow switch, specifying
the IP address of the controller as the first argument to the
switch program, and the network devices to include in the switch as
arguments to the -i option. For example, if the controller is
running on host 192.168.1.2 port 975 (the default port), and eth1
and eth2 are to be the switch ports, the switch invocation would
look like this:
# switch tcp:127.0.0.1 -i eth1,eth2
The network devices that you specify should not have configured IP
addresses.
2. 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.
Userspace Datapath-Based Setup
------------------------------
On a machine that is to host an OpenFlow userspace datapath-based
switch, follow the procedure below. These instructions require the
OpenFlow userspace datapath ("udatapath"). The udatapath program is
part of the OpenFlow extensions repository, which is not included in
every OpenFlow distribution.
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 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:
# udatapath punix:/var/run/dp0.sock -i eth1,eth2 --local-port=tap:tap0 &
(See udatapath(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 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 975 (the default port), the secchan invocation
would look like this:
# secchan 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 secchan 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.
Testing the Kernel-Based Implementation
---------------------------------------
The OpenFlow kernel module must be loaded, as described under
"Building Conventionally", before it may be used.
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
identified as nl:0 (see dpctl(8) for more detailed usage
information).
# dpctl adddp nl:0
(In principle, openflow_mod supports multiple datapaths within the
same host which would be identified as nl:1, nl:2, etc., but this
is rarely useful in practice.)
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
@@ -385,124 +619,66 @@ previous section, before it may be tested.
switch using interfaces eth1 and eth2, you would issue the following
commands:
# dpctl addif 0 eth1
# dpctl addif 0 eth2
# dpctl addif nl:0 eth1
# dpctl addif nl:0 eth2
You can verify that the interfaces were successfully added by asking
dpctl to print the current status of datapath 0:
dpctl to print the current status of datapath nl: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.
# dpctl show nl:0
3. Arrange so that the switch can reach the controller over the
network. There are two ways to do this:
network.
- 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.
- If you are using out-of-band control, at this point make sure
that the switch machine can reach the controller over the
network.
- 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.
- 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:
When in-band control is used, the location of the controller
may be configured manually or discovered automatically:
* If the switch has a static IP address, you may configure
its IP address now, e.g.:
* Manual configuration: Start by bringing up of0 before
you start the secure channel:
# ifconfig of0 192.168.1.1
# ifconfig of0 up
* 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.
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 you are using in-band control with controller discovery, no
configuration is required at this point. You may proceed to
step 4.
. If the switch has a static IP address, you may
configure its IP address now, e.g.:
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 975 (the default port), the secchan invocation
would look like this:
# ifconfig of0 192.168.1.1
# secchan nl:0 tcp:192.168.1.2
. 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, omit
the second argument to the secchan command.
* 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 you are using out-of-band control, add --out-of-band to the
command line.
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:
- If you are using in-band control and controller discovery,
invoke secchan something like this:
# 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
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
=============
@@ -537,19 +713,20 @@ with the instructions below, then the invocation would look like:
--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:
(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
@@ -564,7 +741,7 @@ 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
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").