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 Building the Code
  54 -----------------
  55
  56 1. In the top source directory, configure the package by running the
  57    configure script.  To compile without building a kernel module, you
  58    can usually invoke configure without any arguments:
  59       % ./configure
  60
  61    To build a kernel module as well as the rest of the distribution,
  62    pass the location of the kernel build directory as an argument.
  63    Use --with-l26 for Linux 2.6, --with-l24 for Linux 2.4.  For
  64    example, to build for a running instance of Linux 2.6:
  65       % ./configure --with-l26=/lib/modules/`uname -r`/build
  66
  67    To build for a running instance of Linux 2.4:
  68       % ./configure --with-l24=/lib/modules/`uname -r`/build
  69
  70    To use a specific C compiler for compiling OpenFlow user programs,
  71    also specify it on the configure command line, like so:
  72       % ./configure CC=gcc-4.2
  73
  74    The configure script accepts a number of other options and honors a
  75    additional environment variables.  For a full list, invoke
  76    configure with the --help option.
  77
  78 2. Run make in the top source directory:
  79       % make
  80
  81    The following binaries will be built:
  82
  83    Datapath kernel module:
  84       datapath/linux-2.6/openflow_mod.ko (if --with-l26 was specified)
  85       datapath/linux-2.4/openflow_mod.o  (if --with-l24 was specified)
  86
  87    Secure channel executable:
  88       secchan/secchan
  89
  90    Controller executable:
  91       controller/controller
  92
  93    Datapath administration utility:
  94       utilities/dpctl
  95
  96    Runtime logging configuration utility:
  97       utilities/vlogconf
  98
  99 3. (Optional) Run "make install" to install the executables and
 100    manpages into the running system, by default under /usr/local.
 101
 102 Installing the datapath
 103 -----------------------
 104
 105 To run the module, simply insmod it:
 106
 107       (Linux 2.6)
 108       % insmod datapath/linux-2.6/openflow_mod.ko
 109
 110       (Linux 2.4)
 111       % insmod datapath/linux-2.4/compat24_mod.o
 112       % insmod datapath/linux-2.4/openflow_mod.o
 113
 114
 115 Testing the datapath
 116 --------------------
 117
 118 Once the OpenFlow datapath has been installed (you can verify that it is
 119 running if it appears in lsmod's listing), you can configure it using
 120 the dpctl command line utility.
 121
 122 1. Create a datapath instance.  The command below creates a datapath with
 123    ID 0 (see dpctl(8) for more detailed usage information).
 124       % dpctl adddp 0
 125
 126   (note, while in principle openflow_mod supports multiple datapaths
 127   within the same host, this is rarely useful in practice)
 128
 129 2. Use dpctl to attach the datapath to physical interfaces on the
 130    machine.  Say, for example, you want to create a trivial 2-port
 131    switch using interfaces eth1 and eth2, you would issue the following
 132    commands:
 133       % dpctl addif 0 eth1
 134       % dpctl addif 0 eth2
 135
 136    You can verify that the interfaces were successfully added by asking
 137    dpctl to print the current status of datapath 0:
 138       % dpctl show 0
 139
 140 3. (Optional) You can manually add flows to the datapath to test using
 141    dpctl add-flows and view them using dpctl dump-flows.  See dpctl(8)
 142    for more details.
 143
 144 4. The simplest way to test the datapath is to run the provided sample
 145    controller on the host machine to manage the datapath directly using
 146    netlink:
 147       % controller -v nl:0
 148
 149    Once the controller is running, the datapath should operate like a
 150    learning Ethernet switch.  You may monitor the flows in the datapath
 151    flow table using "dpctl dump-flows" command.
 152
 153 Running the datapath with a remote controller
 154 ---------------------------------------------
 155
 156 1. Start the datapath and attach it to two or more physical ports as
 157    described in the previous section.
 158
 159    Note: The current version of the secure channel and controller
 160    require at least one interface not be connected to the datapath
 161    to be functional.  This interface will be used for communication
 162    between the secure channel and the controller.  Future releases will
 163    support in-band control communication.
 164
 165 2. Run the controller in passive tcp mode on the host which will act as
 166    the controller. In the example below, the controller will bind to
 167    port 975 (the default) awaiting connections from secure channels.
 168       % controller -v ptcp:
 169
 170    (See controller(8) for more details)
 171
 172    Make sure the machine hosting the controller is reachable by the switch.
 173
 174 3. Run secchan on the datapath host to start the secure channel
 175    connecting the datapath to a remote controller.  (See secchan(8)
 176    for usage details).  The channel should be configured to connect to
 177    the controller's IP address on the port configured in step 2.
 178
 179    If the controller is running on host 192.168.1.2 port 975 (the
 180    default port) and the datapath ID is 0, the secchan invocation
 181    would look like:
 182       % secchan -v nl:0 tcp:192.168.1.2
 183
 184 Secure operation over SSL
 185 -------------------------
 186
 187 The instructions above set up OpenFlow for operation over a plaintext
 188 TCP connection.  Production use of OpenFlow should use SSL to ensure
 189 confidentiality and authenticity of traffic among switches and
 190 controllers.
 191
 192 To use SSL with OpenFlow, you must set up a public-key infrastructure
 193 (PKI) including a pair of certificate authorities (CAs), one for
 194 controllers and one for switches.  If you have an established PKI,
 195 OpenFlow can use it directly.  Otherwise, refer to "Establishing a
 196 Public Key Infrastructure" below.
 197
 198 To configure the controller to listen for SSL connections on the
 199 default port, invoke it as follows:
 200       % controller -v pssl: --private-key=PRIVKEY --certificate=CERT \
 201             --ca-cert=CACERT
 202 where PRIVKEY is a file containing the controller's private key, CERT
 203 is a file containing the controller CA's certificate for the
 204 controller's public key, and CACERT is a file containing the root
 205 certificate for the switch CA.  If, for example, your PKI was created
 206 with the instructions below, then the invocation would look like:
 207       % controller -v pssl: --private-key=ctl-privkey.pem \
 208             --certificate=ctl-cert.pem --ca-cert=pki/switchca/cacert.pem
 209
 210 To configure a switch to connect to a controller running on the
 211 default port on host 192.168.1.2 over SSL, invoke it as follows:
 212       % secchan -v nl:0 ssl:192.168.1.2 --private-key=PRIVKEY \
 213             --certificate=CERT --ca-cert=CACERT
 214 where PRIVKEY is a file containing the switch's private key, CERT is a
 215 file containing the switch CA's certificate for the switch's public
 216 key, and CACERT is a file containing the root certificate for the
 217 controller CA.  If, for example, your PKI was created with the
 218 instructions below, then the invocation would look like:
 219       % secchan -v nl:0 ssl:192.168.1.2 --private-key=sc-privkey.pem \
 220             --certificate=sc-cert.pem --ca-cert=pki/controllerca/cacert.pem
 221
 222 Establishing a Public Key Infrastructure
 223 ----------------------------------------
 224
 225 If you do not have a PKI, the ofp-pki script included with OpenFlow
 226 can help.  To create an initial PKI structure, invoke it as:
 227       % ofp-pki new-pki
 228 which will create and populate a new directory named "pki" under the
 229 current directory.
 230
 231 The pki directory contains two important subdirectories.  The
 232 controllerca subdirectory contains controller certificate authority
 233 related files, including the following:
 234
 235     - cacert.pem: Root certificate for the controller certificate
 236       authority.  This file must be provided to the secchan
 237       program with the --ca-cert option to enable it to
 238       authenticate valid controllers.
 239
 240     - private/cakey.pem: Private signing key for the controller
 241       certificate authority.  This file must be kept secret.  There is
 242       no need for switches or controllers to have a copy of it.
 243
 244 The switchca subdirectory contains switch certificate authority
 245 related files, analogous to those in the controllerca subdirectory:
 246
 247     - cacert.pem: Root certificate for the switch certificate
 248       authority.  This file must be provided to the controller program
 249       with the --ca-cert option to enable it to authenticate valid
 250       switches.
 251
 252     - private/cakey.pem: Private signing key for the switch
 253       certificate authority.  This file must be kept secret.  There is
 254       no need for switches or controllers to have a copy of it.
 255
 256 After you create the initial structure, you can create keys and
 257 certificates for switches and controllers with ofp-pki.  To create a
 258 controller private key and certificate in files named ctl-privkey.pem
 259 and ctl-cert.pem, for example, you could run:
 260       % ofp-pki req+sign ctl controller
 261 ctl-privkey.pem and ctl-cert.pem would need to be copied to the
 262 controller for its use at runtime (they could then be deleted from
 263 their original locations).  The --private-key and --certificate
 264 options of controller, respectively, would point to these files.
 265
 266 Analogously, to create a switch private key and certificate in files
 267 named sc-privkey.pem and sc-cert.pem, for example, you could run:
 268       % ofp-pki req+sign sc switch
 269 sc-privkey.pem and sc-cert.pem would need to be copied to the switch
 270 for its use at runtime (they could then be deleted from their original
 271 locations).  The --private-key and --certificate options of secchan,
 272 respectively, would point to these files.
 273
 274 Bug Reporting
 275 -------------
 276
 277 Please report problems to:
 278 info@openflowswitch.org