INSTALL

   1    Installation Instructions for OpenFlow Reference Release v0.1.5
   2
   3 This document describes how to build, install, and execute the v0.1.5
   4 reference implementation of OpenFlow.  Please send any comments to:
   5
   6                       <info@openflowswitch.org>
   7
   8 Setting up the Kernel Build Environment
   9 ---------------------------------------
  10
  11 The datapath kernel module must be compiled against a kernel build
  12 directory for the Linux version the module is to run on.  The datapath
  13 module has been mainly tested on Linux 2.6.23.  Support for Linux 2.4
  14 is also in place, although it has only been lightly tested under 2.4.35.
  15
  16 For example, if compiling on Debian or Ubuntu, the Linux headers
  17 and image packages must be installed (apt-get install
  18 linux-headers-<version> linux-image-<version>).
  19
  20 Note: the OpenFlow datapath requires that bridging support has been
  21 configured in the kernel, but not enabled or in use.  If the bridge
  22 module is running (check with "lsmod | grep bridge"), you must remove
  23 it ("rmmod bridge") before starting the datapath.
  24
  25 Building the Code
  26 -----------------
  27
  28 1. In the top source directory, configure the package, passing the
  29    location of the kernel build directory as an argument.  Use
  30    --with-l26 for Linux 2.6, --with-l24 for Linux 2.4:
  31
  32     For example, if compiling for a running instance of Linux 2.6:
  33       % ./configure --with-l26=/lib/modules/`uname -r`/build
  34
  35     Or if compiling for a running instance of Linux 2.4:
  36       % ./configure --with-l24=/lib/modules/`uname -r`/build
  37
  38    To use a specific C compiler for compiling OpenFlow user programs,
  39    also specify it on the configure command line, like so:
  40       % ./configure CC=gcc-4.2
  41
  42 2. Run make in the top source directory:
  43
  44     % make
  45
  46     The following binaries will be built:
  47
  48     Datapath kernel module:
  49         ./datapath/linux-2.6/openflow_mod.ko (If compiling for Linux 2.6)
  50         ./datapath/linux-2.4/openflow_mod.o  (If compiling for Linux 2.4)
  51
  52     Secure channel executable:
  53         ./secchan/secchan
  54
  55     Controller executable:
  56         ./controller/controller
  57
  58     Datapath administration utility:
  59         ./utilities/dpctl
  60
  61 3. (Optional) Run "make install" to install the executables and
  62    manpages into the running system, by default under /usr/local.
  63
  64 Installing the datapath
  65 -----------------------
  66
  67 To run the module, simply insmod it:
  68
  69      (Linux 2.6)
  70      % insmod datapath/linux-2.6/openflow_mod.ko
  71
  72      (Linux 2.4)
  73      % insmod datapath/linux-2.4/compat24_mod.o
  74      % insmod datapath/linux-2.4/openflow_mod.o
  75
  76
  77 Testing the datapath
  78 --------------------
  79
  80 Once the OpenFlow datapath has been installed (you can verify that it is
  81 running if it appears in lsmod's listing), you can configure it using
  82 the dpctl command line utility.
  83
  84 1. Create a datapath instance.  The command below creates a datapath with
  85    ID 0 (see dpctl(8) for more detailed usage information).
  86
  87    % dpctl adddp 0
  88
  89   (note, while in principle openflow_mod supports multiple datapaths
  90   within the same host, this is rarely useful in practice)
  91
  92 2. Use dpctl to attach the datapath to physical interfaces on the
  93    machine.  Say, for example, you want to create a trivial 2-port
  94    switch using interfaces eth1 and eth2, you would issue the following
  95    commands:
  96
  97    % dpctl addif 0 eth1
  98    % dpctl addif 0 eth2
  99
 100    You can verify that the interfaces were successfully added by asking
 101    dpctl to print the current status of datapath 0:
 102
 103    % dpctl show 0
 104
 105 3. (Optional) You can manually add flows to the datapath to test using
 106    dpctl add-flows and view them using dpctl dump-flows.  See dpctl(8)
 107    for more details.
 108
 109 4. The simplest way to test the datapath is to run the provided sample
 110    controller on the host machine to manage the datapath directly using
 111    netlink.
 112
 113    % controller -v nl:0
 114
 115    Once the controller is running, the datapath should operate like a
 116    learning Ethernet switch.  You may monitor the flows in the datapath
 117    flow table using "dpctl dump-flows" command.
 118
 119 Running the datapath with a remote controller
 120 ---------------------------------------------
 121
 122 1. Start the datapath and attach it to two or more physical ports as
 123    described in the previous section.
 124
 125    Note: The current version of the secure channel and controller
 126    require at least one interface not be connected to the datapath
 127    to be functional.  This interface will be used for communication
 128    between the secure channel and the controller.  Future releases will
 129    support in-band control communication.
 130
 131 2. Run the controller in passive tcp mode on the host which will act as
 132    the controller. In the example below, the controller will bind to
 133    port 975 (the default) awaiting connections from secure channels.
 134
 135    % controller -v ptcp:
 136
 137    (See controller(8) for more details)
 138
 139    Make sure the machine hosting the controller is reachable by the switch.
 140
 141 3. Run secchan on the datapath host to start the secure channel
 142    connecting the datapath to a remote controller.  (See secchan(8)
 143    for usage details).  The channel should be configured to connect to
 144    the controller's IP address on the port configured in step 2.
 145
 146    If the controller is running on host 192.168.1.2 port 975 (the
 147    default port) and the datapath ID is 0, the secchan invocation
 148    would look like:
 149
 150    % secchan -v nl:0 tcp:192.168.1.2
 151
 152 Bug Reporting
 153 -------------
 154
 155 Please report problems to:
 156 info@openflowswitch.org