git://git.onelab.eu / sliver-openvswitch.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
New function svec_join().
[sliver-openvswitch.git] / INSTALL
diff --git a/INSTALL b/INSTALL
index 58b6cbf..fc7d3f7 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -8,13 +8,8 @@ reference implementation of OpenFlow.  Please send any comments to:
 Contents
 ========
 
 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 OpenFlow reference implementation includes two OpenFlow switch
+implementations:
 
         - The "kernel-based switch": This divides the switch into a
           "datapath" Linux kernel module (openflow_mod.o for Linux 2.4
 
         - The "kernel-based switch": This divides the switch into a
           "datapath" Linux kernel module (openflow_mod.o for Linux 2.4
@@ -28,11 +23,8 @@ OpenFlow switch implementations:
           switch into a userspace "datapath" (built as
           udatapath/udatapath) and the same userspace program used by
           the kernel-based switch (secchan).  The userspace
           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.
+          datapath-based switch does not require building a kernel
+          module, but it is not as fast as the kernel-based switch.
 
 The reference implementation also contains a simple OpenFlow
 controller (built as controller/controller) and a number of related
 
 The reference implementation also contains a simple OpenFlow
 controller (built as controller/controller) and a number of related
@@ -65,13 +57,13 @@ reference distribution, you will need the following software:
     - libssl, from OpenSSL (http://www.openssl.org/), is optional but
       recommended.  libssl is required to establish confidentiality
       and authenticity in the connections among OpenFlow switches and
     - libssl, from OpenSSL (http://www.openssl.org/), is optional but
       recommended.  libssl is required to establish confidentiality
       and authenticity in the connections among OpenFlow switches and
-      controllers.  To enable, configure with --enable-ssl=yes
+      controllers.  To enable, configure with --enable-ssl=yes.
 
 If you are working from a Git tree or snapshot (instead of from a
 distribution tarball), or if you modify the OpenFlow build system, you
 will also need the following software:
 
 
 If you are working from a Git tree or snapshot (instead of from a
 distribution tarball), or if you modify the OpenFlow build system, you
 will also need the following software:
 
-    - Autoconf version 2.59 or later (http://www.gnu.org/software/autoconf).
+    - Autoconf version 2.60 or later (http://www.gnu.org/software/autoconf).
 
     - Automake version 1.10 or later (http://www.gnu.org/software/automake).  
 
 
     - Automake version 1.10 or later (http://www.gnu.org/software/automake).  
 
@@ -168,7 +160,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.
+      - Userspace datapath: udatapath/udatapath.
 
       - Secure channel executable: secchan/secchan.
 
 
       - Secure channel executable: secchan/secchan.
 
@@ -186,13 +178,11 @@ distribution in the ordinary way using "configure" and "make".
    If your distribution includes the OpenFlow extensions, the
    following additional binaries will be built:
 
    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:
       - ANSI terminal support for EZIO 16x2 LCD panel:
         ext/ezio/ezio-term.
 
       - Switch monitoring UI for small text displays:
-        ext/ezio/ofp-switchmon.
+        ext/ezio/ofp-switchui.
 
    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:
@@ -300,7 +290,7 @@ Follow these instructions to build Debian packages for OpenFlow.
         openflow-pki (see below).
 
       - openflow-switch: Install this package on a machine that acts
         openflow-pki (see below).
 
       - openflow-switch: Install this package on a machine that acts
-        as an OpenFlow userspace or kernel switch.
+        as an OpenFlow kernel switch.
 
       - openflow-datapath-source: Source code for OpenFlow's Linux
         kernel module.
 
       - openflow-datapath-source: Source code for OpenFlow's Linux
         kernel module.
@@ -332,8 +322,8 @@ Follow these instructions to build Debian packages for OpenFlow.
       - Completely by hand, as described under the Testing section
         below.
 
       - Completely by hand, as described under the Testing section
         below.
 
-        For the userspace switch, this is the only supported form of
-        configuration.
+        For the userspace datapath-based switch, this is the only
+        supported form of configuration.
 
       - By editing /etc/default/openflow-switch.  You must at least
         configure some network devices, by uncommenting NETDEVS and
 
       - By editing /etc/default/openflow-switch.  You must at least
         configure some network devices, by uncommenting NETDEVS and
@@ -346,7 +336,7 @@ Follow these instructions to build Debian packages for OpenFlow.
            % /etc/init.d/openflow-switch restart
 
         This form of configuration is not supported for the userspace
            % /etc/init.d/openflow-switch restart
 
         This form of configuration is not supported for the userspace
-        switch.
+        datapath-based switch.
 
       - By running the ofp-switch-setup program.  This interactive
         program will walk you through all the steps of configuring an
 
       - By running the ofp-switch-setup program.  This interactive
         program will walk you through all the steps of configuring an
@@ -356,7 +346,7 @@ Follow these instructions to build Debian packages for OpenFlow.
            % ofp-switch-setup
 
         This form of configuration is not supported for the userspace
            % ofp-switch-setup
 
         This form of configuration is not supported for the userspace
-        switch.
+        datapath-based switch.
 
 Testing
 =======
 
 Testing
 =======
@@ -366,51 +356,10 @@ 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.
 
 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.
-
-1. Start the OpenFlow controller running in the background, by running
-   the "controller" program with a command like the following:
-
-      # controller ptcp: &
-
-   This command causes the controller to bind to port 975 (the
-   default) awaiting connections from OpenFlow switches.  See
-   controller(8) for details.
-   
-2. On the same machine, use the "switch" program to start an OpenFlow
-   switch, specifying network devices to use as switch ports on the -i
-   option as a comma-separated list, like so:
-
-      # switch tcp:127.0.0.1 -i eth1,eth2
-   
-   The network devices that you specify should not have configured IP
-   addresses.
-
-3. 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.
-
-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.
-
 Userspace Datapath
 ------------------
 
 These instructions use the OpenFlow userspace datapath ("udatapath").
 Userspace Datapath
 ------------------
 
 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. Start the OpenFlow controller running in the background, by running
    the "controller" program with a command like the following:
 
 1. Start the OpenFlow controller running in the background, by running
    the "controller" program with a command like the following:
@@ -420,20 +369,26 @@ which is not included in every OpenFlow distribution.
    This command causes the controller to bind to the specified Unix
    domain socket, awaiting connections from OpenFlow switches.  See
    controller(8) for details.
    This command causes the controller to bind to the specified Unix
    domain socket, awaiting connections from OpenFlow switches.  See
    controller(8) for details.
+
+   The "controller" program does not require any special privilege, so
+   you do not need to run it as root.
    
    
-2. Create a datapath instance running in the background.  The command
+2. The commands below must run as root, so log in as root, or use a
+   program such as "su" to become root temporarily.
+
+3. 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 &
 
    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
+4. Run secchan to start the secure channel connecting the datapath and
    the controller:
 
       # secchan unix:/var/run/controller.sock unix:/var/run/dp0.sock &
    
    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
+5. 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.
 
    now be able to send packets to each other, as if they were plugged
    into ports on a conventional Ethernet switch.
 
@@ -450,9 +405,6 @@ each switch to reach the controller over the network:
         location of the controller must be configured manually in this
         case.
 
         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
       - 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
@@ -460,17 +412,12 @@ each switch to reach the controller over the network:
         please refer to secchan(8) for instructions on setting up
         controller discovery.  
 
         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
 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.)
+port 6633 (the default), as shown below.
 
    # controller -v ptcp:
 
 
    # controller -v ptcp:
 
@@ -479,44 +426,11 @@ low-numbered port, this command must run as root.)
 Make sure the machine hosting the controller is reachable by the
 switch.
 
 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
 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.
+switch, follow the procedure below.
 
 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.
@@ -564,7 +478,7 @@ every OpenFlow distribution.
 
 4. Run secchan to start the secure channel connecting the datapath to
    a remote controller.  If the controller is running on host
 
 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
+   192.168.1.2 port 6633 (the default port), the secchan invocation
    would look like this:
 
       # secchan unix:/var/run/dp0.sock tcp:192.168.1.2
    would look like this:
 
       # secchan unix:/var/run/dp0.sock tcp:192.168.1.2
@@ -601,9 +515,9 @@ The OpenFlow kernel module must be loaded, as described under
 
       # dpctl adddp nl:0
    
 
       # 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.)
+   (nl:0 is the first datapath within a host.  openflow_mod supports
+   multiple datapaths within the same host, which would be identified
+   as nl:1, nl:2, etc.)
 
    Creating datapath nl:0 also creates a new network device named of0.
    This network device, called the datapath's "local port", will be
 
    Creating datapath nl:0 also creates a new network device named of0.
    This network device, called the datapath's "local port", will be
@@ -657,7 +571,7 @@ The OpenFlow kernel module must be loaded, as described under
 
 4. Run secchan to start the secure channel connecting the datapath to
    a remote controller.  If the controller is running on host
 
 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
+   192.168.1.2 port 6633 (the default port), the secchan invocation
    would look like this:
 
       # secchan nl:0 tcp:192.168.1.2
    would look like this:
 
       # secchan nl:0 tcp:192.168.1.2
@@ -697,7 +611,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 \
@@ -712,7 +626,7 @@ 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
+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:
 
       # secchan -v DATAPATH ssl:192.168.1.2 --private-key=PRIVKEY \
 (the default) on host 192.168.1.2 over SSL, invoke secchan as follows:
 
       # secchan -v DATAPATH ssl:192.168.1.2 --private-key=PRIVKEY \
@@ -750,9 +664,8 @@ controllerca subdirectory contains controller certificate authority
 related files, including the following:
 
     - cacert.pem: Root certificate for the controller certificate
 related files, including the following:
 
     - cacert.pem: Root certificate for the controller certificate
-      authority.  This file must be provided to the switch or secchan
-      program with the --ca-cert option to enable it to authenticate
-      valid controllers.
+      authority.  This file must be provided to secchan with the
+      --ca-cert option to enable it to authenticate valid controllers.
 
     - private/cakey.pem: Private signing key for the controller
       certificate authority.  This file must be kept secret.  There is
 
     - private/cakey.pem: Private signing key for the controller
       certificate authority.  This file must be kept secret.  There is
@@ -786,7 +699,7 @@ named sc-privkey.pem and sc-cert.pem, for example, you could run:
 sc-privkey.pem and sc-cert.pem would need to be copied to the switch
 for its use at runtime (they could then be deleted from their original
 locations).  The --private-key and --certificate options,
 sc-privkey.pem and sc-cert.pem would need to be copied to the switch
 for its use at runtime (they could then be deleted from their original
 locations).  The --private-key and --certificate options,
-respectively, of switch and secchan would point to these files.
+respectively, of secchan would point to these files.
 
 Bug Reporting
 -------------
 
 Bug Reporting
 -------------
sliver-openvswitch