- Installation Instructions for OpenFlow Reference Release v0.1.5
+ Installation Instructions for OpenFlow Reference Release
-This document describes how to build, install, and execute the v0.1.5
+This document describes how to build, install, and execute the
reference implementation of OpenFlow. Please send any comments to:
<info@openflowswitch.org>
-Setting up the Kernel Build Environment
----------------------------------------
+Contents
+========
-The datapath kernel module must be compiled against a kernel build
-directory for the Linux version the module is to run on. The datapath
-module has been mainly tested on Linux 2.6.23. Support for Linux 2.4
-is also in place, although it has only been lightly tested under 2.4.35.
+The OpenFlow reference implementation includes two OpenFlow switch
+implementations:
-For example, if compiling on Debian or Ubuntu, the Linux headers
-and image packages must be installed (apt-get install
-linux-headers-<version> linux-image-<version>).
+ - 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.
-Note: the OpenFlow datapath requires that bridging support has been
-configured in the kernel, but not enabled or in use. If the bridge
-module is running (check with "lsmod | grep bridge"), you must remove
-it ("rmmod bridge") before starting the datapath.
+ - 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 does not require building a kernel
+ module, but it is not as fast as the kernel-based switch.
-Building the Code
------------------
+The reference implementation also contains a simple OpenFlow
+controller (built as controller/controller) and a number of related
+utilities.
-1. In the top source directory, configure the package, passing the
- location of the kernel build directory as an argument. Use
- --with-l26 for Linux 2.6, --with-l24 for Linux 2.4:
+Build Methods
+=============
- For example, if compiling for a running instance of Linux 2.6:
- % ./configure --with-l26=/lib/modules/`uname -r`/build
+There are two principal ways to build and install this distribution:
- Or if compiling for a running instance of Linux 2.4:
- % ./configure --with-l24=/lib/modules/`uname -r`/build
+ - Using "configure" and "make" in the ordinary way. See
+ Building Conventionally below for detailed instructions.
+
+ - As a set of Debian packages. Refer to Building Debian
+ Packages, below, for instructions.
+
+Base Prerequisites
+------------------
+
+Regardless of how it is built, OpenFlow has a common set of
+prerequisites. To compile the userspace programs in the OpenFlow
+reference distribution, you will need the following software:
+
+ - A make program, e.g. GNU make
+ (http://www.gnu.org/software/make/). BSD make should also work.
+
+ - The GNU C compiler (http://gcc.gnu.org/). We generally test
+ with version 4.1 or 4.2.
+
+ - 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.
+
+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.60 or later (http://www.gnu.org/software/autoconf).
+
+ - Automake version 1.10 or later (http://www.gnu.org/software/automake).
+
+ - pkg-config (http://pkg-config.freedesktop.org/wiki/). We test
+ with version 0.22.
+
+Debian Prerequisites
+--------------------
+
+To build Debian packages from the OpenFlow distribution, you will need
+to install a number of Debian packages in addition to the base
+prerequisites listed above. These additional prerequisites may be
+found listed as "Build-Depends" in debian/control in the source tree.
+To check that they are installed, first install the dpkg-dev package,
+then run dpkg-checkbuilddeps from the top level of the OpenFlow source
+tree.
+
+To build Debian packages without being root, also install the
+"fakeroot" package.
+
+Kernel-Based Switch Prerequisites
+---------------------------------
+
+The OpenFlow distribution also includes a Linux kernel module that can
+be used to achieve higher switching performance. To compile the
+kernel module, you must install the following in addition to the
+software listed in the "Base Prerequisites" section above:
+
+ - A supported Linux kernel version. Please refer to README for a
+ list of supported versions.
+
+ The OpenFlow datapath requires bridging support (CONFIG_BRIDGE)
+ to be built as a kernel module. (This is common in kernels
+ provided by Linux distributions.) The bridge module must not be
+ loaded or in use. If the bridge module is running (check with
+ "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:
+
+ * To build a kernel module for a Linux 2.6 kernel, you need
+ the same version of GCC that was used to build that kernel
+ (usually version 4.0 or later).
+
+ * To build a kernel module for a Linux 2.4 kernel, you need an
+ earlier version of GCC, typically GCC 2.95, 3.3, or 3.4.
+
+ - A kernel build directory corresponding to the Linux kernel image
+ the module is to run on. Under Debian and Ubuntu, for example,
+ each linux-image package containing a kernel binary has a
+ corresponding linux-headers package with the required build
+ infrastructure.
+
+Building Conventionally
+=======================
+
+This section explains how to build and install the OpenFlow
+distribution in the ordinary way using "configure" and "make".
+
+0. Check that you have installed all the prerequisites listed above in
+ the Base Prerequisites section. If you want to compile the Linux
+ kernel module, also check that the prequisites listed under
+ Kernel-Based Switch Prequisites are installed.
+
+1. In the top source directory, configure the package by running the
+ configure script. You can usually invoke configure without any
+ arguments:
+
+ % ./configure
To use a specific C compiler for compiling OpenFlow user programs,
also specify it on the configure command line, like so:
+
% ./configure CC=gcc-4.2
+ To build the Linux kernel module, so that you can run the
+ kernel-based switch, add --with-l26 or --with-l24 option, or both,
+ to the configure script's command line. Refer to Building the
+ Linux Kernel-Based Switch, below, for more information.
+
+ The configure script accepts a number of other options and honors
+ additional environment variables. For a full list, invoke
+ configure with the --help option.
+
2. Run make in the top source directory:
- % make
+ % make
- The following binaries will be built:
+ The following binaries will be built:
- Datapath kernel module:
- ./datapath/linux-2.6/openflow_mod.ko (If compiling for Linux 2.6)
- ./datapath/linux-2.4/openflow_mod.o (If compiling for Linux 2.4)
+ - Userspace datapath: udatapath/udatapath.
- Secure channel executable:
- ./secchan/secchan
+ - Secure channel executable: secchan/secchan.
- Controller executable:
- ./controller/controller
+ - Controller executable: controller/controller.
- Datapath administration utility:
- ./utilities/dpctl
+ - Datapath administration utility: utilities/dpctl.
-3. (Optional) Run "make install" to install the executables and
- manpages into the running system, by default under /usr/local.
+ - Runtime logging configuration utility: utilities/vlogconf.
-Installing the datapath
------------------------
+ - Miscellaneous utilities: utilities/ofp-discover,
+ utilities/ofp-kill.
-To run the module, simply insmod it:
+ - Tests: various binaries in tests/.
- (Linux 2.6)
- % insmod datapath/linux-2.6/openflow_mod.ko
+ If your distribution includes the OpenFlow extensions, the
+ following additional binaries will be built:
- (Linux 2.4)
- % insmod datapath/linux-2.4/compat24_mod.o
- % insmod datapath/linux-2.4/openflow_mod.o
+ - ANSI terminal support for EZIO 16x2 LCD panel:
+ ext/ezio/ezio-term.
+ - Switch monitoring UI for small text displays:
+ ext/ezio/ofp-switchui.
-Testing the datapath
---------------------
+ If you passed --with-l26 to configure, "make" will also build the
+ following kernel modules:
-Once the OpenFlow datapath has been installed (you can verify that it is
-running if it appears in lsmod's listing), you can configure it using
-the dpctl command line utility.
+ - datapath/linux-2.6/openflow_mod.ko
-1. Create a datapath instance. The command below creates a datapath with
- ID 0 (see dpctl(8) for more detailed usage information).
+ - datapath/linux-2.6/hwtable_<table>_mod.ko for each <table>
+ specified on --enable-hw-tables (if any).
- % dpctl adddp 0
-
- (note, while in principle openflow_mod supports multiple datapaths
- within the same host, this is rarely useful in practice)
+ If you passed --with-l24 to configure, "make" will also build the
+ following kernel modules:
-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:
+ - datapath/linux-2.4/openflow_mod.o
- % dpctl addif 0 eth1
- % dpctl addif 0 eth2
+ - datapath/linux-2.6/hwtable_<table>_mod.o for each <table>
+ specified on --enable-hw-tables (if any).
- You can verify that the interfaces were successfully added by asking
- dpctl to print the current status of datapath 0:
+3. Run "make install" to install the executables and manpages into the
+ running system, by default under /usr/local.
+
+4. If you built kernel modules, you may load them with "insmod", e.g.:
+
+ (Linux 2.6)
+ % insmod datapath/linux-2.6/openflow_mod.ko
+
+ (Linux 2.4)
+ % insmod datapath/linux-2.4/compat24_mod.o
+ % insmod datapath/linux-2.4/openflow_mod.o
+
+ After you load the openflow module, you may load one hardware switch
+ table module (if any were built) to enable support for that hardware
+ switching table.
+
+ The insmod program must be run as root. You may need to specify a
+ full path to insmod, e.g. /sbin/insmod. To verify that the modules
+ have been loaded, run "/sbin/lsmod" and check that openflow_mod is
+ listed.
+
+4. Test the userspace programs, as described under Testing Userspace
+ Programs below.
+
+5. If you built the kernel module, test the kernel-based switch, as
+ described under Testing the Kernel-Based Implementation below.
+
+Building the Linux Kernel-Based Switch
+--------------------------------------
+
+To build the kernel module, follow the build process described above,
+but pass the location of the kernel build directory as an additional
+argument to the configure script, as described under step 1 in that
+section. Specify the location on --with-l26 for Linux 2.6, --with-l24
+for Linux 2.4. For example, to build for a running instance of Linux
+2.6:
+
+ % ./configure --with-l26=/lib/modules/`uname -r`/build
+
+To build for a running instance of Linux 2.4:
+
+ % ./configure --with-l24=/lib/modules/`uname -r`/build
+
+If you wish to build OpenFlow for an architecture other than the
+architecture used for compilation, you may specify the kernel
+architecture string using the KARCH variable when invoking the
+configure script. For example, to build OpenFlow for MIPS with Linux
+2.4:
+
+ % ./configure --with-l24=/path/to/linux-2.4 KARCH=mips
+
+If you have hardware that supports accelerated OpenFlow switching, and
+you have obtained a hardware table module for your hardware and
+extracted it into the OpenFlow reference distribution source tree,
+then you may also enable building support for the hardware switching
+table with --enable-hw-tables. For example, if your hardware
+switching table is in a directory named datapath/hwtable-foomatic, you
+could compile support for it with the running Linux 2.6 kernel like
+so:
+
+ % ./configure --with-l26=/lib/modules/`uname -r`/build \
+ --enable-hw-tables=foomatic
+
+For more information about hardware table modules, please read
+README.hwtables at the root of the OpenFlow distribution tree.
+
+Building Debian Packages
+========================
+
+Follow these instructions to build Debian packages for OpenFlow.
+
+0. Check that you have installed all the prerequisites listed above in
+ the Base Prerequisites and Debian Prerequisites sections above.
+
+1. In the top source directory, run the following command, as root:
+
+ % dpkg-buildpackage
+
+ Alternatively, if you installed the "fakeroot" package, you may run
+ dpkg-buildpackage as an ordinary user with the following syntax:
+
+ % dpkg-buildpackage -rfakeroot
+
+ The following packages will be built in the directory above the
+ source tree:
+
+ - openflow-controller: The OpenFlow controller. Depends on
+ openflow-pki (see below).
+
+ - openflow-switch: Install this package on a machine that acts
+ as an OpenFlow kernel switch.
- % dpctl show 0
+ - openflow-datapath-source: Source code for OpenFlow's Linux
+ kernel module.
-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.
+ - openflow-pki: Public-key infrastructure for OpenFlow. Install
+ this package on a machine that acts as an OpenFlow PKI server
+ (see "Establishing a Public Key Infrastructure" below).
-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.
+ - openflow-common: Files and utilities required by more than one
+ of the above packages.
- % controller -v nl:0
+2. To set up an OpenFlow controller, install the openflow-controller
+ package and its dependencies. You may configure it by editing
+ /etc/default/openflow-controller, e.g. to enable non-SSL
+ connections, which are disabled by default. If you change the
+ default settings, you will need to restart the controller by
+ running:
- 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.
+ % /etc/init.d/openflow-controller restart
-Running the datapath with a remote controller
----------------------------------------------
+3. To set up an OpenFlow switch, install the openflow-switch package
+ and its dependencies. If it is to be a kernel-based switch, also
+ install openflow-datapath-source, then follow the instructions in
+ /usr/share/doc/openflow-datapath-source/README.Debian to build and
+ install the kernel module.
-1. Start the datapath and attach it to two or more physical ports as
- described in the previous section.
+ You may configure the switch one of the following ways:
- Note: The current version of the secure channel and controller
- require at least one interface not be connected to the datapath
- to be functional. This interface will be used for communication
- between the secure channel and the controller. Future releases will
- support in-band control communication.
+ - Completely by hand, as described under the Testing section
+ below.
-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.
+ 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
+ adding the appropriate devices to the list, e.g. NETDEVS="eth0
+ eth1".
+
+ After you edit this file, you will need to start the switch by
+ running:
+
+ % /etc/init.d/openflow-switch restart
+
+ This form of configuration is not supported for the userspace
+ datapath-based switch.
+
+ - By running the ofp-switch-setup program. This interactive
+ program will walk you through all the steps of configuring an
+ OpenFlow switch, including configuration of SSL certificates.
+ Run it without arguments, as root:
+
+ % ofp-switch-setup
+
+ This form of configuration is not supported for the userspace
+ datapath-based switch.
+
+Testing
+=======
+
+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 Datapath
+------------------
+
+These instructions use the OpenFlow userspace datapath ("udatapath").
+
+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 &
+
+ 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.
- % controller -v ptcp:
+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 &
+
+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 &
+
+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.
+
+Installation
+============
+
+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.
+
+ - 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 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.
+
+ # controller -v ptcp:
+
+(See controller(8) for more details)
+
+Make sure the machine hosting the controller is reachable by the
+switch.
+
+Userspace Datapath-Based Setup
+------------------------------
+
+On a machine that is to host an OpenFlow userspace datapath-based
+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.
+
+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.)
- (See controller(8) for more 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.
+
+ - 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 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 6633 (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.
+
+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
- Make sure the machine hosting the controller is reachable by the switch.
+ (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
+ 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".
+
+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:
-3. 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 channel should be configured to connect to
- the controller's IP address on the port configured in step 2.
+ # secchan nl:0 tcp:192.168.1.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:
+ - If you are using in-band control with controller discovery, omit
+ the second argument to the secchan command.
- % secchan -v nl:0 tcp:192.168.1.2
+ - 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
+=============
+
+Secure operation over SSL
+-------------------------
+
+The instructions above set up OpenFlow for operation over a plaintext
+TCP connection. Production use of OpenFlow should use SSL[*] to
+ensure confidentiality and authenticity of traffic among switches and
+controllers. The source must be configured with --enable-ssl=yes to
+build with SSL support.
+
+To use SSL with OpenFlow, you must set up a public-key infrastructure
+(PKI) including a pair of certificate authorities (CAs), one for
+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.
+
+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 \
+ --ca-cert=CACERT
+
+where PRIVKEY is a file containing the controller's private key, CERT
+is a file containing the controller CA's certificate for the
+controller's public key, and CACERT is a file containing the root
+certificate for the switch CA. If, for example, your PKI was created
+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
+
+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 \
+ --certificate=CERT --ca-cert=CACERT
+
+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 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
+ specified by RFC 2246, which is very similar to SSL version 3.0.
+ TLSv1 was released in January 1999, so all current software and
+ hardware should implement it.
+
+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:
+ % 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
+related files, including the following:
+
+ - cacert.pem: Root certificate for the controller certificate
+ 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
+ no need for switches or controllers to have a copy of it.
+
+The switchca subdirectory contains switch certificate authority
+related files, analogous to those in the controllerca subdirectory:
+
+ - cacert.pem: Root certificate for the switch certificate
+ authority. This file must be provided to the controller program
+ with the --ca-cert option to enable it to authenticate valid
+ switches.
+
+ - private/cakey.pem: Private signing key for the switch
+ certificate authority. This file must be kept secret. There is
+ no need for switches or controllers to have a copy of it.
+
+After you create the initial structure, you can create keys and
+certificates for switches and controllers with ofp-pki. To create a
+controller private key and certificate in files named ctl-privkey.pem
+and ctl-cert.pem, for example, you could run:
+ % ofp-pki req+sign ctl controller
+ctl-privkey.pem and ctl-cert.pem would need to be copied to the
+controller for its use at runtime (they could then be deleted from
+their original locations). The --private-key and --certificate
+options of controller, respectively, would point to these files.
+
+Analogously, to create a switch private key and certificate in files
+named sc-privkey.pem and sc-cert.pem, for example, you could run:
+ % ofp-pki req+sign sc switch
+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 secchan would point to these files.
Bug Reporting
-------------
git://git.onelab.eu / sliver-openvswitch.git / blobdiff