INSTALL

   1        Installation Instructions for OpenFlow Reference Release
   2
   3 This document describes how to build, install, and execute the
   4 reference implementation of OpenFlow.  Please send any comments to:
   5
   6                       <info@openflowswitch.org>
   7
   8 Prerequisites
   9 -------------
  10
  11 To compile the userspace programs in the OpenFlow reference
  12 distribution, you will need the following software:
  13
  14     - A make program, e.g. GNU make
  15       (http://www.gnu.org/software/make/).  BSD make should also work.
  16
  17     - The GNU C compiler (http://gcc.gnu.org/).  We generally test
  18       with version 4.1 or 4.2.
  19
  20     - libssl, from OpenSSL (http://www.openssl.org/), is optional but
  21       recommended.  libssl is required to establish confidentiality
  22       and authenticity in the connections among OpenFlow switches and
  23       controllers.
  24
  25 To compile the datapath kernel module, you will additionally need:
  26
  27     - A supported Linux kernel version.  Please refer to README for a
  28       list of supported versions.
  29
  30       The OpenFlow datapath requires bridging support (CONFIG_BRIDGE)
  31       to be built as a kernel module.  (This is common in kernels
  32       provided by Linux distributions.)  The bridge module must not be
  33       loaded or in use.  If the bridge module is running (check with
  34       "lsmod | grep bridge"), you must remove it ("rmmod bridge")
  35       before starting the datapath.
  36
  37     - The correct version of GCC for the kernel that you are building
  38       the module against:
  39
  40         * To build a kernel module for a Linux 2.6 kernel, you need
  41           the same version of GCC that was used to build that kernel
  42           (usually version 4.0 or later).
  43
  44         * To build a kernel module for a Linux 2.4 kernel, you need an
  45           earlier version of GCC, typically GCC 2.95, 3.3, or 3.4.
  46
  47     - A kernel build directory corresponding to the Linux kernel image
  48       the module is to run on.  Under Debian and Ubuntu, for example,
  49       each linux-image package containing a kernel binary has a
  50       corresponding linux-headers package with the required build
  51       infrastructure.
  52
  53 If you are working from a Git tree or snapshot (instead of from a
  54 distribution tarball), or if you modify the OpenFlow build system, you
  55 will also need the following software:
  56
  57     - Autoconf version 2.59 or later (http://www.gnu.org/software/autoconf).
  58
  59     - Automake version 1.10 or later (http://www.gnu.org/software/automake).
  60
  61     - pkg-config (http://pkg-config.freedesktop.org/wiki/).  We test
  62       with version 0.22.
  63
  64 Building the Code
  65 -----------------
  66
  67 1. In the top source directory, configure the package by running the
  68    configure script.  To compile without building a kernel module, you
  69    can usually invoke configure without any arguments:
  70       % ./configure
  71
  72    To build a kernel module as well as the rest of the distribution,
  73    pass the location of the kernel build directory as an argument.
  74    Use --with-l26 for Linux 2.6, --with-l24 for Linux 2.4.  For
  75    example, to build for a running instance of Linux 2.6:
  76       % ./configure --with-l26=/lib/modules/`uname -r`/build
  77
  78    To build for a running instance of Linux 2.4:
  79       % ./configure --with-l24=/lib/modules/`uname -r`/build
  80
  81    To use a specific C compiler for compiling OpenFlow user programs,
  82    also specify it on the configure command line, like so:
  83       % ./configure CC=gcc-4.2
  84
  85    The configure script accepts a number of other options and honors
  86    additional environment variables.  For a full list, invoke
  87    configure with the --help option.
  88
  89 2. Run make in the top source directory:
  90       % make
  91
  92    The following binaries will be built:
  93
  94    Datapath kernel module:
  95       datapath/linux-2.6/openflow_mod.ko (if --with-l26 was specified)
  96       datapath/linux-2.4/openflow_mod.o  (if --with-l24 was specified)
  97
  98    Secure channel executable:
  99       secchan/secchan
 100
 101    Controller executable:
 102       controller/controller
 103
 104    Datapath administration utility:
 105       utilities/dpctl
 106
 107    Runtime logging configuration utility:
 108       utilities/vlogconf
 109
 110 3. (Optional) Run "make install" to install the executables and
 111    manpages into the running system, by default under /usr/local.
 112
 113 Installing the datapath
 114 -----------------------
 115
 116 To run the module, simply insmod it:
 117
 118       (Linux 2.6)
 119       % insmod datapath/linux-2.6/openflow_mod.ko
 120
 121       (Linux 2.4)
 122       % insmod datapath/linux-2.4/compat24_mod.o
 123       % insmod datapath/linux-2.4/openflow_mod.o
 124
 125
 126 Testing the datapath
 127 --------------------
 128
 129 Once the OpenFlow datapath has been installed (you can verify that it is
 130 running if it appears in lsmod's listing), you can configure it using
 131 the dpctl command line utility.
 132
 133 1. Create a datapath instance.  The command below creates a datapath with
 134    ID 0 (see dpctl(8) for more detailed usage information).
 135       % dpctl adddp 0
 136
 137   (note, while in principle openflow_mod supports multiple datapaths
 138   within the same host, this is rarely useful in practice)
 139
 140 2. Use dpctl to attach the datapath to physical interfaces on the
 141    machine.  Say, for example, you want to create a trivial 2-port
 142    switch using interfaces eth1 and eth2, you would issue the following
 143    commands:
 144       % dpctl addif 0 eth1
 145       % dpctl addif 0 eth2
 146
 147    You can verify that the interfaces were successfully added by asking
 148    dpctl to print the current status of datapath 0:
 149       % dpctl show 0
 150
 151 3. (Optional) You can manually add flows to the datapath to test using
 152    dpctl add-flows and view them using dpctl dump-flows.  See dpctl(8)
 153    for more details.
 154
 155 4. The simplest way to test the datapath is to run the provided sample
 156    controller on the host machine to manage the datapath directly using
 157    netlink:
 158       % controller -v nl:0
 159
 160    Once the controller is running, the datapath should operate like a
 161    learning Ethernet switch.  You may monitor the flows in the datapath
 162    flow table using "dpctl dump-flows" command.
 163
 164 Running the datapath with a remote controller
 165 ---------------------------------------------
 166
 167 1. Start the datapath and attach it to two or more physical ports as
 168    described in the previous section.
 169
 170    Note: The current version of the secure channel and controller
 171    require at least one interface not be connected to the datapath
 172    to be functional.  This interface will be used for communication
 173    between the secure channel and the controller.  Future releases will
 174    support in-band control communication.
 175
 176 2. Run the controller in passive tcp mode on the host which will act as
 177    the controller. In the example below, the controller will bind to
 178    port 975 (the default) awaiting connections from secure channels.
 179       % controller -v ptcp:
 180
 181    (See controller(8) for more details)
 182
 183    Make sure the machine hosting the controller is reachable by the switch.
 184
 185 3. Run secchan on the datapath host to start the secure channel
 186    connecting the datapath to a remote controller.  (See secchan(8)
 187    for usage details).  The channel should be configured to connect to
 188    the controller's IP address on the port configured in step 2.
 189
 190    If the controller is running on host 192.168.1.2 port 975 (the
 191    default port) and the datapath ID is 0, the secchan invocation
 192    would look like:
 193       % secchan -v nl:0 tcp:192.168.1.2
 194
 195 Secure operation over SSL
 196 -------------------------
 197
 198 The instructions above set up OpenFlow for operation over a plaintext
 199 TCP connection.  Production use of OpenFlow should use SSL[*] to
 200 ensure confidentiality and authenticity of traffic among switches and
 201 controllers.
 202
 203 To use SSL with OpenFlow, you must set up a public-key infrastructure
 204 (PKI) including a pair of certificate authorities (CAs), one for
 205 controllers and one for switches.  If you have an established PKI,
 206 OpenFlow can use it directly.  Otherwise, refer to "Establishing a
 207 Public Key Infrastructure" below.
 208
 209 To configure the controller to listen for SSL connections on the
 210 default port, invoke it as follows:
 211       % controller -v pssl: --private-key=PRIVKEY --certificate=CERT \
 212             --ca-cert=CACERT
 213 where PRIVKEY is a file containing the controller's private key, CERT
 214 is a file containing the controller CA's certificate for the
 215 controller's public key, and CACERT is a file containing the root
 216 certificate for the switch CA.  If, for example, your PKI was created
 217 with the instructions below, then the invocation would look like:
 218       % controller -v pssl: --private-key=ctl-privkey.pem \
 219             --certificate=ctl-cert.pem --ca-cert=pki/switchca/cacert.pem
 220
 221 To configure a switch to connect to a controller running on the
 222 default port on host 192.168.1.2 over SSL, invoke it as follows:
 223       % secchan -v nl:0 ssl:192.168.1.2 --private-key=PRIVKEY \
 224             --certificate=CERT --ca-cert=CACERT
 225 where PRIVKEY is a file containing the switch's private key, CERT is a
 226 file containing the switch CA's certificate for the switch's public
 227 key, and CACERT is a file containing the root certificate for the
 228 controller CA.  If, for example, your PKI was created with the
 229 instructions below, then the invocation would look like:
 230       % secchan -v nl:0 ssl:192.168.1.2 --private-key=sc-privkey.pem \
 231             --certificate=sc-cert.pem --ca-cert=pki/controllerca/cacert.pem
 232
 233 [*] To be specific, OpenFlow uses TLS version 1.0 or later (TLSv1), as
 234     specified by RFC 2246, which is very similar to SSL version 3.0.
 235     TLSv1 was released in January 1999, so all current software and
 236     hardware should implement it.
 237
 238 Establishing a Public Key Infrastructure
 239 ----------------------------------------
 240
 241 If you do not have a PKI, the ofp-pki script included with OpenFlow
 242 can help.  To create an initial PKI structure, invoke it as:
 243       % ofp-pki new-pki
 244 which will create and populate a new directory named "pki" under the
 245 current directory.
 246
 247 The pki directory contains two important subdirectories.  The
 248 controllerca subdirectory contains controller certificate authority
 249 related files, including the following:
 250
 251     - cacert.pem: Root certificate for the controller certificate
 252       authority.  This file must be provided to the secchan
 253       program with the --ca-cert option to enable it to
 254       authenticate valid controllers.
 255
 256     - private/cakey.pem: Private signing key for the controller
 257       certificate authority.  This file must be kept secret.  There is
 258       no need for switches or controllers to have a copy of it.
 259
 260 The switchca subdirectory contains switch certificate authority
 261 related files, analogous to those in the controllerca subdirectory:
 262
 263     - cacert.pem: Root certificate for the switch certificate
 264       authority.  This file must be provided to the controller program
 265       with the --ca-cert option to enable it to authenticate valid
 266       switches.
 267
 268     - private/cakey.pem: Private signing key for the switch
 269       certificate authority.  This file must be kept secret.  There is
 270       no need for switches or controllers to have a copy of it.
 271
 272 After you create the initial structure, you can create keys and
 273 certificates for switches and controllers with ofp-pki.  To create a
 274 controller private key and certificate in files named ctl-privkey.pem
 275 and ctl-cert.pem, for example, you could run:
 276       % ofp-pki req+sign ctl controller
 277 ctl-privkey.pem and ctl-cert.pem would need to be copied to the
 278 controller for its use at runtime (they could then be deleted from
 279 their original locations).  The --private-key and --certificate
 280 options of controller, respectively, would point to these files.
 281
 282 Analogously, to create a switch private key and certificate in files
 283 named sc-privkey.pem and sc-cert.pem, for example, you could run:
 284       % ofp-pki req+sign sc switch
 285 sc-privkey.pem and sc-cert.pem would need to be copied to the switch
 286 for its use at runtime (they could then be deleted from their original
 287 locations).  The --private-key and --certificate options of secchan,
 288 respectively, would point to these files.
 289
 290 Bug Reporting
 291 -------------
 292
 293 Please report problems to:
 294 info@openflowswitch.org