README

   1      OpenFlow Reference Release v0.1.5 <http://openflowswitch.org>
   2
   3 What is OpenFlow?
   4 -----------------
   5
   6 OpenFlow is a flow-based switch specification designed to enable
   7 researchers to run experiments in live networks.  OpenFlow is based on a
   8 simple Ethernet flow switch that exposes a standardized interface for
   9 adding and removing flow entries.
  10
  11 An OpenFlow Switch consists of three parts: (1) A Flow Table in which
  12 each flow entry is associated with an action telling the switch how to
  13 process the flow, (2) A Secure Channel connecting the switch to a remote
  14 process (a controller), allowing commands and packets to be sent between
  15 the controller and the switch, and (3) An OpenFlow Protocol
  16 implementation, providing an open and standard way for a controller to
  17 talk to the switch.
  18
  19 An OpenFlow Switch can thus serve as a simple datapath element that
  20 forwards packets between ports according to flow actions defined by
  21 the controller using OpenFlow commands.  Example actions are:
  22
  23     - Forward this flow's packets to the given port(s)
  24     - Drop this flow's packets
  25     - Encapsulate and forward this flow's packets to the controller.
  26
  27 The OpenFlow Switch is defined in detail in the OpenFlow Switch
  28 Specification [2].
  29
  30 What's here?
  31 ------------
  32
  33 This software is a reference implementation of an OpenFlow Switch kernel
  34 module for the Linux operating system, a secure channel implementation,
  35 and an example controller that performs switching with MAC learning.
  36
  37 The rest of this file contains the following sections:
  38
  39     - Description of the directory hierarchy
  40     - Platform support
  41     - Quickstart build and install instructions
  42     - Shortcomings
  43     - References
  44
  45 Directory Hierarchy
  46 -------------------
  47
  48   Source:
  49
  50     datapath/     Linux kernel module implementing an OpenFlow Flow Table
  51                   that incoming packets are checked against.  The
  52                   kernel module uses netlink (a socket protocol for
  53                   user-kernel communication, described in RFC 3549) to
  54                   pass OpenFlow messages with the secure channel to be
  55                   relayed to the controller.
  56
  57     secchan/      A Secure Channel that connects to a kernel datapath
  58                   via netlink and a remote controller via TCP,
  59                   relaying OpenFlow packets received on one end to the
  60                   other.  (The current implementation does not
  61                   support SSL, but this will be added in future releases.)
  62
  63     controller/   A simple controller that connects to a datapath via
  64                   a Secure Channel, commanding the datapath to act as
  65                   a regular MAC learning switch.
  66
  67     utilities/    Contains the sorce for "dpctl", a command-line utility
  68                   for controlling the OpenFlow datapath kernel module.
  69                   With it, you can add physical ports to the datapath,
  70                   add flows, monitor received packets, and query the
  71                   datapath state.
  72
  73     include/      Header files common to the datapath, secure channel,
  74                   and controller components.
  75
  76     lib/          Implementation files common to the datapath, secure
  77                   channel, and controller components.
  78
  79     third-party/  Contains third-party software that may be useful for
  80                   debugging.  Currently, it only contains a patch to
  81                   allow tcpdump to parse OpenFlow messages.
  82
  83   Documentation:
  84
  85     README        Text file describing this OpenFlow implementation,
  86                   aka this document.
  87
  88     INSTALLATION  Detailed configure, build, and installation
  89                   instructions
  90
  91     man/          Man pages describing how to administer datapath,
  92                   secure channel, and controller.
  93
  94 Platform support
  95 ----------------
  96
  97     The datapath kernel module supports Linux 2.6.15 and above, however,
  98     testing has focused on Linux 2.6.23.  Support for Linux 2.4.20 and
  99     above is also in place, although testing has focused on Linux 2.6.
 100
 101     Components have been built and tested on Debian and Ubuntu.
 102
 103     If you are able to build/run the code on platforms not mentioned
 104     here, or have problems with supported system, please report your
 105     experiences to:
 106
 107                   <info@openflowswitch.org>
 108
 109     GCC is required for compilation.
 110
 111
 112 Building and Installing (Quick Start)
 113 -------------------------------------
 114
 115     Building the datapath module requires that the source for the
 116     currently running Linux kernel be installed on the machine and
 117     been configured.
 118
 119     The following instructions assume the Linux 2.6 source is located in
 120     /usr/src/linux-2.6.23 and Linux 2.4 in /usr/src/linux-2.4.35
 121
 122     1. ./configure the package, passing the location of one or more
 123        kernel source trees on the command line:
 124
 125        For example, if compiling for Linux 2.6:
 126           % ./configure --with-l26=/usr/src/linux-2.6.23
 127
 128        Or compiling for Linux 2.4:
 129           % ./configure --with-l24=/usr/src/linux-2.4.35
 130
 131     2. Run make:
 132
 133           % make
 134
 135        The following binaries should be built.
 136
 137        Datapath kernel module:
 138            ./datapath/linux-2.6/openflow_mod.ko (If compiling for Linux 2.6)
 139            ./datapath/linux-2.4/openflow_mod.o  (If compiling for Linux 2.4)
 140
 141        Secure channel executable:
 142            ./secchan/secchan
 143
 144        Controller executable:
 145            ./controller/controller
 146
 147         dpctl utility:
 148            ./utility/dpctl
 149
 150     3. Optionally you can "make install" to install binaries and the
 151     man pages (/usr/local/ is the default prefix).  If you just want
 152     access to the man pages without installing, set your MANPATH to
 153     include the openflow/ source root.
 154
 155     4. Insert the datapath kernel module into the running Linux instance.
 156
 157           (Linux 2.6)
 158           % insmod datapath/linux-2.6/openflow_mod.ko
 159
 160           (Linux 2.4)
 161           % insmod datapath/linux-2.4/openflow_mod.o
 162
 163     5.  Create datapaths by running dpctl on the Linux host (see man
 164         dpctl(8)).  Start the controller on a remote host with
 165         controller (see man controller(8)).  Start the Secure Channel
 166         on the datapath host to connect the datapath to the controller
 167         with secchan(see man secchan(8)).
 168
 169     For more detailed installation instructions, refer to [3].
 170
 171
 172 Bugs/Shortcomings
 173 -----------------
 174
 175 - The current flowtable does not support all statistics messages
 176   mentioned in the Type 0 OpenFlow spec
 177 - The secure channel and sample controller don't support SSL
 178 - The flowtable does not support the "normal processing" action
 179 - Configure/build system does not support separate build directory for
 180   the datapath.  ./configure must be run from the source root.
 181 - dpctl dump-flows may freeze when large numbers of flows are in the
 182   flow table.  This has no affect on the datapath
 183
 184 References
 185 ----------
 186
 187     [1] OpenFlow: Enabling Innovation in College Networks.  Whitepaper.
 188         <http://openflowswitch.org/alpha/openflow-wp-v0.1.pdf>
 189
 190     [2] OpenFlow Switch Specification.
 191         <http://openflowswitch.org/alpha/openflow-spec-v0.2.pdf>
 192
 193     [3] Installation Instructions: INSTALL
 194
 195 Contact
 196 -------
 197
 198 e-mail: info@openflowswitch.org
 199 www: http://openflowswitch.org/alpha/