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
 189 ensure 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 [*] To be specific, OpenFlow uses TLS version 1.0 or later (TLSv1), as
 223     specified by RFC 2246, which is very similar to SSL version 3.0.
 224     TLSv1 was released in January 1999, so all current software and
 225     hardware should implement it.
 226
 227 Establishing a Public Key Infrastructure
 228 ----------------------------------------
 229
 230 If you do not have a PKI, the ofp-pki script included with OpenFlow
 231 can help.  To create an initial PKI structure, invoke it as:
 232       % ofp-pki new-pki
 233 which will create and populate a new directory named "pki" under the
 234 current directory.
 235
 236 The pki directory contains two important subdirectories.  The
 237 controllerca subdirectory contains controller certificate authority
 238 related files, including the following:
 239
 240     - cacert.pem: Root certificate for the controller certificate
 241       authority.  This file must be provided to the secchan
 242       program with the --ca-cert option to enable it to
 243       authenticate valid controllers.
 244
 245     - private/cakey.pem: Private signing key for the controller
 246       certificate authority.  This file must be kept secret.  There is
 247       no need for switches or controllers to have a copy of it.
 248
 249 The switchca subdirectory contains switch certificate authority
 250 related files, analogous to those in the controllerca subdirectory:
 251
 252     - cacert.pem: Root certificate for the switch certificate
 253       authority.  This file must be provided to the controller program
 254       with the --ca-cert option to enable it to authenticate valid
 255       switches.
 256
 257     - private/cakey.pem: Private signing key for the switch
 258       certificate authority.  This file must be kept secret.  There is
 259       no need for switches or controllers to have a copy of it.
 260
 261 After you create the initial structure, you can create keys and
 262 certificates for switches and controllers with ofp-pki.  To create a
 263 controller private key and certificate in files named ctl-privkey.pem
 264 and ctl-cert.pem, for example, you could run:
 265       % ofp-pki req+sign ctl controller
 266 ctl-privkey.pem and ctl-cert.pem would need to be copied to the
 267 controller for its use at runtime (they could then be deleted from
 268 their original locations).  The --private-key and --certificate
 269 options of controller, respectively, would point to these files.
 270
 271 Analogously, to create a switch private key and certificate in files
 272 named sc-privkey.pem and sc-cert.pem, for example, you could run:
 273       % ofp-pki req+sign sc switch
 274 sc-privkey.pem and sc-cert.pem would need to be copied to the switch
 275 for its use at runtime (they could then be deleted from their original
 276 locations).  The --private-key and --certificate options of secchan,
 277 respectively, would point to these files.
 278
 279 Bug Reporting
 280 -------------
 281
 282 Please report problems to:
 283 info@openflowswitch.org