Update documentation to talk about userspace datapath.
authorBen Pfaff <blp@nicira.com>
Thu, 9 Oct 2008 22:52:17 +0000 (15:52 -0700)
committerBen Pfaff <blp@nicira.com>
Thu, 9 Oct 2008 22:53:05 +0000 (15:53 -0700)
INSTALL

diff --git a/INSTALL b/INSTALL
index 91635269c4363119184b6565bc0dc90b2426ea78..58b6cbf1dde0f16dff4376847fea5416166492e2 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -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,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").