X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=INSTALL;h=8f558b4152d99a4fa585e1e7d66c26fe9a229370;hb=62093bae13aa604a6e542ce327a3954d45760883;hp=c201b14999c92fd089472964adf0d43b4b01591b;hpb=f1126f43ad62618cf1b6f6ab48d9635fc5cbcad6;p=sliver-openvswitch.git diff --git a/INSTALL b/INSTALL index c201b1499..8f558b415 100644 --- a/INSTALL +++ b/INSTALL @@ -11,11 +11,6 @@ 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 @@ -28,11 +23,17 @@ 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 - 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 "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 userspace switch is deprecated in favor of the userspace + datapath-based switch. It will likely be removed in a + future OpenFlow release. The reference implementation also contains a simple OpenFlow controller (built as controller/controller) and a number of related @@ -65,13 +66,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 - 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: - - 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). @@ -168,7 +169,7 @@ distribution in the ordinary way using "configure" and "make". The following binaries will be built: - - Switch executable: switch/switch. + - Userspace datapath: udatapath/udatapath. - Secure channel executable: secchan/secchan. @@ -183,16 +184,16 @@ distribution in the ordinary way using "configure" and "make". - Tests: various binaries in tests/. + - Switch executable: switch/switch. + 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. + ext/ezio/ofp-switchui. If you passed --with-l26 to configure, "make" will also build the following kernel modules: @@ -300,7 +301,7 @@ Follow these instructions to build Debian packages for OpenFlow. 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. @@ -366,51 +367,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. -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 6633 (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"). -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: @@ -420,23 +380,65 @@ 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. + + 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 & -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 & -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. +Userspace Switch +---------------- + +These instructions use the OpenFlow userspace switch that runs as an +integrated userspace program. Keep in mind that the userspace switch +is deprecated: you should use the userspace datapath instead. + +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 6633 (the + default) 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. The "switch" program must run as root, so log in as root, or use a + program such as "su" to become root temporarily. + +3. 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. + +4. 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. + Installation ============ @@ -450,9 +452,6 @@ each switch to reach the controller over the network: 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 @@ -460,17 +459,15 @@ each switch to reach the controller over the network: 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. + The (deprecated) userspace switch does not support in-band + control. Controller Setup ---------------- 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.) +port 6633 (the default), as shown below. # controller -v ptcp: @@ -479,44 +476,11 @@ low-numbered port, this command must run as root.) 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 6633 (the default port), and eth1 - and eth2 are to be the switch ports, the switch invocation would - look like this: - - # switch tcp:127.0.0.1 -i eth1,eth2 - - The network devices that you specify should not have configured IP - addresses. - -2. The controller causes each switch that connects to it to act like a - learning Ethernet switch. Thus, devices plugged into the specified - network ports should now be able to send packets to each other, as - if they were plugged into ports on a conventional Ethernet switch. - Userspace Datapath-Based Setup ------------------------------ On a machine that is to host an OpenFlow userspace datapath-based -switch, follow the procedure below. These instructions require the -OpenFlow userspace datapath ("udatapath"). The udatapath program is -part of the OpenFlow extensions repository, which is not included in -every OpenFlow distribution. +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. @@ -601,9 +565,9 @@ The OpenFlow kernel module must be loaded, as described under # 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 @@ -679,6 +643,36 @@ The OpenFlow kernel module must be loaded, as described under use, because the switch must then also obtain its own IP address and the controller's location via DHCP. +Userspace Switch-Based Setup +---------------------------- + +To set up an OpenFlow switch using the (deprecated) 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 other +switch implementations 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 6633 (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. + Configuration =============