From 8cfc2d6f69f9c8b03cd81c0cee32285e69282f44 Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Thu, 9 Oct 2008 15:52:17 -0700 Subject: [PATCH] Update documentation to talk about userspace datapath. --- INSTALL | 425 +++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 301 insertions(+), 124 deletions(-) diff --git a/INSTALL b/INSTALL index 91635269..58b6cbf1 100644 --- a/INSTALL +++ b/INSTALL @@ -5,6 +5,39 @@ reference implementation of OpenFlow. Please send any comments to: +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,161 +402,283 @@ 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 ---------------------------------------- +Userspace Datapath +------------------ -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: + + # controller punix:/var/run/controller.sock & - # dpctl adddp 0 + 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: - 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". + # udatapath punix:/var/run/dp0.sock -i eth1,eth2 & -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: +3. Run secchan to start the secure channel connecting the datapath and + the controller: - # dpctl addif 0 eth1 - # dpctl addif 0 eth2 + # 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. - You can verify that the interfaces were successfully added by asking - dpctl to print the current status of datapath 0: +Installation +============ - # dpctl show 0 +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: -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. + - 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. -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: + - 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 -v nl:0 + The userspace datapath-based and kernel-based switch + implementations support in-band control. The userspace switch + does not. - 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. +Controller Setup +---------------- -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: +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.) -1. Start the datapath and attach it to two or more physical ports as - described in the previous section. + # controller -v ptcp: -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. +(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. - # controller -v ptcp: +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: - (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. + 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. 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 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. - When in-band control is used, the location of the controller - may be configured manually or discovered automatically: +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 + the datapath with "dpctl adddp". - * Manual configuration: Start by bringing up of0 before - you start the secure channel: +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: - # ifconfig of0 up + # 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: - . If the switch has a static IP address, you may - configure its IP address now, e.g.: + # dpctl show nl:0 - # ifconfig of0 192.168.1.1 +3. Arrange so that the switch 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 out-of-band control, at this point make sure + that the switch machine can reach the controller over the + network. - * 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 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: -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 the switch has a static IP address, you may configure + its IP address now, e.g.: - - If you are using in-band control and controller discovery, - invoke secchan something like this: + # ifconfig of0 192.168.1.1 - # secchan -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. - 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. + - If you are using in-band control with controller discovery, no + configuration is required at this point. You may proceed to + step 4. - - 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: +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 -v nl:0 tcp:192.168.1.2 + # secchan 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. + - If you are using in-band control with controller discovery, omit + the second argument to the secchan command. -5. If you are using the same network for control and data, and the + - 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. + 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"). -- 2.30.2