git://git.onelab.eu / sliver-openvswitch.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Make it possible to open more than one vlog client socket at a time.
[sliver-openvswitch.git] / INSTALL
diff --git a/INSTALL b/INSTALL
index 618affd..c201b14 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -5,6 +5,39 @@ reference implementation of OpenFlow.  Please send any comments to:
 
                       <info@openflowswitch.org>
 
 
                       <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
 =============
 
 Build Methods
 =============
 
@@ -77,6 +110,11 @@ software listed in the "Base Prerequisites" section above:
       "lsmod | grep bridge"), you must remove it ("rmmod bridge")
       before starting the datapath.
 
       "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 correct version of GCC for the kernel that you are building
       the module against:
 
@@ -130,10 +168,7 @@ distribution in the ordinary way using "configure" and "make".
 
    The following binaries will be built:
 
 
    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.
 
 
       - Secure channel executable: secchan/secchan.
 
@@ -143,6 +178,22 @@ distribution in the ordinary way using "configure" and "make".
 
       - Runtime logging configuration utility: utilities/vlogconf.
 
 
       - 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:
 
    If you passed --with-l26 to configure, "make" will also build the
    following kernel modules:
 
@@ -310,8 +361,16 @@ Follow these instructions to build Debian packages for OpenFlow.
 Testing
 =======
 
 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.
 
 0. The commands below must run as root, so log in as root, or use a
    program such as "su" to become root temporarily.
@@ -321,7 +380,7 @@ Testing Userspace Programs
 
       # controller ptcp: &
 
 
       # controller ptcp: &
 
-   This command causes the controller to bind to port 975 (the
+   This command causes the controller to bind to port 6633 (the
    default) awaiting connections from OpenFlow switches.  See
    controller(8) for details.
    
    default) awaiting connections from OpenFlow switches.  See
    controller(8) for details.
    
@@ -343,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.
 
 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.
 
 
 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:
+
+      # 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.
 
 
-      # dpctl addif 0 eth1
-      # dpctl addif 0 eth2
+Installation
+============
 
 
-   You can verify that the interfaces were successfully added by asking
-   dpctl to print the current status of datapath 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:
+
+      - 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.
 
 
-      # dpctl show 0
+Controller Setup
+----------------
 
 
-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.
+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.  (Because it listens on a
+low-numbered port, this command must run as root.)
 
 
-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 ptcp:
 
 
-      # controller -v nl:0
+(See controller(8) for more details)
 
 
-   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.
+Make sure the machine hosting the controller is reachable by the
+switch.
 
 
-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:
+Userspace Switch-Based Setup
+----------------------------
 
 
-1. Start the datapath and attach it to two or more physical ports as
-   described in the previous section.
+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.)
 
 
-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. 
+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 6633 (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
 
 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:
 
 
-        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 tap0 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 6633 (the default port), the secchan invocation
+   would look like this:
 
 
-                      # ifconfig of0 192.168.1.1
+      # secchan unix:/var/run/dp0.sock 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:
+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.
 
 
-      - If you are using in-band control and controller discovery,
-        invoke secchan something like 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.
 
 
-           # secchan -v nl:0
+Testing the Kernel-Based Implementation
+---------------------------------------
 
 
-        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.
+The OpenFlow kernel module must be loaded, as described under
+"Building Conventionally", before it may be used.
 
 
-      - 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:
+0. The commands below must run as root, so log in as root, or use a
+   program such as "su" to become root temporarily.
 
 
-           # secchan -v nl:0 tcp:192.168.1.2
+1. Create a datapath instance.  The command below creates a datapath
+   identified as nl:0 (see dpctl(8) for more detailed usage
+   information).
 
 
-        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.
+      # 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".
 
 
-5. If you are using the same network for control and data, and the
+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
+
+   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
+
+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, 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:
+
+           * If the switch has a static IP address, you may configure
+             its IP address now, e.g.:
+
+                # ifconfig of0 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 6633 (the default port), the secchan invocation
+   would look like this:
+
+      # secchan 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, 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.
 
    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
 =============
 
 Configuration
 =============
 
@@ -516,7 +697,7 @@ 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.
 
 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 \
 (the default), invoke it as follows:
 
       # controller -v pssl: --private-key=PRIVKEY --certificate=CERT \
@@ -531,20 +712,21 @@ 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
 
       # 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
 
             --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
             --certificate=sc-cert.pem --ca-cert=pki/controllerca/cacert.pem
 
 [*] To be specific, OpenFlow uses TLS version 1.0 or later (TLSv1), as
@@ -557,9 +739,11 @@ 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:
 
 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
 
 The pki directory contains two important subdirectories.  The
 controllerca subdirectory contains controller certificate authority
sliver-openvswitch