Add userspace datapath to openflow.
[sliver-openvswitch.git] / 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 Contents
9 ========
10
11 The OpenFlow reference implementation includes three separate
12 OpenFlow switch implementations:
13
14         - The "kernel-based switch": This divides the switch into a
15           "datapath" Linux kernel module (openflow_mod.o for Linux 2.4
16           or openflow_mod.ko for Linux 2.6) and a userspace program
17           (secchan).  The kernel-based switch is faster than either of
18           the other two implementations but requires building and
19           installing a kernel module, which can sometimes be
20           challenging.
21
22         - The "userspace datapath-based switch": This divides the
23           switch into a userspace "datapath" (built as
24           udatapath/udatapath) and the same userspace program used by
25           the kernel-based switch (secchan).  The userspace
26           datapath-based switch does not require building a kernel
27           module, but it is not as fast as the kernel-based switch.
28
29         - The "userspace switch": This implements an OpenFlow switch
30           as a single user program (built as switch/switch).  The
31           userspace switch is the easiest to build and use but it is
32           much less featureful than the other switch implementations.
33
34           The userspace switch is deprecated in favor of the userspace
35           datapath-based switch.  It will likely be removed in a
36           future OpenFlow release.
37
38 The reference implementation also contains a simple OpenFlow
39 controller (built as controller/controller) and a number of related
40 utilities.
41
42 Build Methods
43 =============
44
45 There are two principal ways to build and install this distribution:
46
47         - Using "configure" and "make" in the ordinary way.  See
48           Building Conventionally below for detailed instructions.
49
50         - As a set of Debian packages.  Refer to Building Debian
51           Packages, below, for instructions.
52
53 Base Prerequisites
54 ------------------
55
56 Regardless of how it is built, OpenFlow has a common set of
57 prerequisites.  To compile the userspace programs in the OpenFlow
58 reference distribution, you will need the following software:
59
60     - A make program, e.g. GNU make
61       (http://www.gnu.org/software/make/).  BSD make should also work.
62
63     - The GNU C compiler (http://gcc.gnu.org/).  We generally test
64       with version 4.1 or 4.2.
65
66     - libssl, from OpenSSL (http://www.openssl.org/), is optional but
67       recommended.  libssl is required to establish confidentiality
68       and authenticity in the connections among OpenFlow switches and
69       controllers.  To enable, configure with --enable-ssl=yes.
70
71 If you are working from a Git tree or snapshot (instead of from a
72 distribution tarball), or if you modify the OpenFlow build system, you
73 will also need the following software:
74
75     - Autoconf version 2.60 or later (http://www.gnu.org/software/autoconf).
76
77     - Automake version 1.10 or later (http://www.gnu.org/software/automake).  
78
79     - pkg-config (http://pkg-config.freedesktop.org/wiki/).  We test
80       with version 0.22.
81
82 Debian Prerequisites
83 --------------------
84
85 To build Debian packages from the OpenFlow distribution, you will need
86 to install a number of Debian packages in addition to the base
87 prerequisites listed above.  These additional prerequisites may be
88 found listed as "Build-Depends" in debian/control in the source tree.
89 To check that they are installed, first install the dpkg-dev package,
90 then run dpkg-checkbuilddeps from the top level of the OpenFlow source
91 tree.
92
93 To build Debian packages without being root, also install the
94 "fakeroot" package.
95
96 Kernel-Based Switch Prerequisites
97 ---------------------------------
98
99 The OpenFlow distribution also includes a Linux kernel module that can
100 be used to achieve higher switching performance.  To compile the
101 kernel module, you must install the following in addition to the
102 software listed in the "Base Prerequisites" section above:
103
104     - A supported Linux kernel version.  Please refer to README for a
105       list of supported versions.
106
107       The OpenFlow datapath requires bridging support (CONFIG_BRIDGE)
108       to be built as a kernel module.  (This is common in kernels
109       provided by Linux distributions.)  The bridge module must not be
110       loaded or in use.  If the bridge module is running (check with
111       "lsmod | grep bridge"), you must remove it ("rmmod bridge")
112       before starting the datapath.
113
114       In kernels prior to 2.6.9, VLAN support (CONFIG_VLAN_8021Q) must 
115       be compiled either directly or as a module.  Failure to do this
116       will cause an error on module insertion due to the 
117       "dev_change_flags" symbol being undefined.
118
119     - The correct version of GCC for the kernel that you are building
120       the module against:
121
122         * To build a kernel module for a Linux 2.6 kernel, you need
123           the same version of GCC that was used to build that kernel
124           (usually version 4.0 or later).
125
126         * To build a kernel module for a Linux 2.4 kernel, you need an
127           earlier version of GCC, typically GCC 2.95, 3.3, or 3.4.
128
129     - A kernel build directory corresponding to the Linux kernel image
130       the module is to run on.  Under Debian and Ubuntu, for example,
131       each linux-image package containing a kernel binary has a
132       corresponding linux-headers package with the required build
133       infrastructure.
134
135 Building Conventionally
136 =======================
137
138 This section explains how to build and install the OpenFlow
139 distribution in the ordinary way using "configure" and "make".
140
141 0. Check that you have installed all the prerequisites listed above in
142    the Base Prerequisites section.  If you want to compile the Linux
143    kernel module, also check that the prequisites listed under
144    Kernel-Based Switch Prequisites are installed.
145
146 1. In the top source directory, configure the package by running the
147    configure script.  You can usually invoke configure without any
148    arguments:
149
150       % ./configure
151
152    To use a specific C compiler for compiling OpenFlow user programs,
153    also specify it on the configure command line, like so:
154
155       % ./configure CC=gcc-4.2
156
157    To build the Linux kernel module, so that you can run the
158    kernel-based switch, add --with-l26 or --with-l24 option, or both,
159    to the configure script's command line.  Refer to Building the
160    Linux Kernel-Based Switch, below, for more information.
161
162    The configure script accepts a number of other options and honors
163    additional environment variables.  For a full list, invoke
164    configure with the --help option.
165
166 2. Run make in the top source directory: 
167
168       % make
169
170    The following binaries will be built:
171
172       - Userspace datapath: udatapath/udatapath.
173
174       - Secure channel executable: secchan/secchan.
175
176       - Controller executable: controller/controller.
177
178       - Datapath administration utility: utilities/dpctl.
179
180       - Runtime logging configuration utility: utilities/vlogconf.
181
182       - Miscellaneous utilities: utilities/ofp-discover,
183         utilities/ofp-kill.
184
185       - Tests: various binaries in tests/.
186
187       - Switch executable: switch/switch.
188
189    If your distribution includes the OpenFlow extensions, the
190    following additional binaries will be built:
191
192       - ANSI terminal support for EZIO 16x2 LCD panel:
193         ext/ezio/ezio-term.
194
195       - Switch monitoring UI for small text displays:
196         ext/ezio/ofp-switchui.
197
198    If you passed --with-l26 to configure, "make" will also build the
199    following kernel modules:
200
201       - datapath/linux-2.6/openflow_mod.ko
202
203       - datapath/linux-2.6/hwtable_<table>_mod.ko for each <table>
204         specified on --enable-hw-tables (if any).
205
206    If you passed --with-l24 to configure, "make" will also build the
207    following kernel modules:
208
209       - datapath/linux-2.4/openflow_mod.o      
210
211       - datapath/linux-2.6/hwtable_<table>_mod.o for each <table>
212         specified on --enable-hw-tables (if any).
213
214 3. Run "make install" to install the executables and manpages into the
215    running system, by default under /usr/local.
216
217 4. If you built kernel modules, you may load them with "insmod", e.g.:
218
219       (Linux 2.6)
220       % insmod datapath/linux-2.6/openflow_mod.ko
221
222       (Linux 2.4)
223       % insmod datapath/linux-2.4/compat24_mod.o
224       % insmod datapath/linux-2.4/openflow_mod.o
225
226    After you load the openflow module, you may load one hardware switch
227    table module (if any were built) to enable support for that hardware
228    switching table.
229
230    The insmod program must be run as root.  You may need to specify a
231    full path to insmod, e.g. /sbin/insmod.  To verify that the modules
232    have been loaded, run "/sbin/lsmod" and check that openflow_mod is
233    listed.
234
235 4. Test the userspace programs, as described under Testing Userspace
236    Programs below.
237
238 5. If you built the kernel module, test the kernel-based switch, as
239    described under Testing the Kernel-Based Implementation below.
240
241 Building the Linux Kernel-Based Switch
242 --------------------------------------
243
244 To build the kernel module, follow the build process described above,
245 but pass the location of the kernel build directory as an additional
246 argument to the configure script, as described under step 1 in that
247 section.  Specify the location on --with-l26 for Linux 2.6, --with-l24
248 for Linux 2.4.  For example, to build for a running instance of Linux
249 2.6:
250
251       % ./configure --with-l26=/lib/modules/`uname -r`/build
252
253 To build for a running instance of Linux 2.4:
254
255       % ./configure --with-l24=/lib/modules/`uname -r`/build
256
257 If you wish to build OpenFlow for an architecture other than the
258 architecture used for compilation, you may specify the kernel
259 architecture string using the KARCH variable when invoking the
260 configure script. For example, to build OpenFlow for MIPS with Linux
261 2.4:
262
263       % ./configure --with-l24=/path/to/linux-2.4 KARCH=mips
264
265 If you have hardware that supports accelerated OpenFlow switching, and
266 you have obtained a hardware table module for your hardware and
267 extracted it into the OpenFlow reference distribution source tree,
268 then you may also enable building support for the hardware switching
269 table with --enable-hw-tables.  For example, if your hardware
270 switching table is in a directory named datapath/hwtable-foomatic, you
271 could compile support for it with the running Linux 2.6 kernel like
272 so:
273
274       % ./configure --with-l26=/lib/modules/`uname -r`/build \
275                     --enable-hw-tables=foomatic
276
277 For more information about hardware table modules, please read
278 README.hwtables at the root of the OpenFlow distribution tree.
279
280 Building Debian Packages
281 ========================
282
283 Follow these instructions to build Debian packages for OpenFlow.
284
285 0. Check that you have installed all the prerequisites listed above in
286    the Base Prerequisites and Debian Prerequisites sections above.
287
288 1. In the top source directory, run the following command, as root:
289
290       % dpkg-buildpackage
291
292    Alternatively, if you installed the "fakeroot" package, you may run
293    dpkg-buildpackage as an ordinary user with the following syntax:
294
295       % dpkg-buildpackage -rfakeroot
296
297    The following packages will be built in the directory above the
298    source tree:
299
300       - openflow-controller: The OpenFlow controller.  Depends on
301         openflow-pki (see below).
302
303       - openflow-switch: Install this package on a machine that acts
304         as an OpenFlow kernel switch.
305
306       - openflow-datapath-source: Source code for OpenFlow's Linux
307         kernel module.
308
309       - openflow-pki: Public-key infrastructure for OpenFlow.  Install
310         this package on a machine that acts as an OpenFlow PKI server
311         (see "Establishing a Public Key Infrastructure" below).
312
313       - openflow-common: Files and utilities required by more than one
314         of the above packages.
315
316 2. To set up an OpenFlow controller, install the openflow-controller
317    package and its dependencies.  You may configure it by editing
318    /etc/default/openflow-controller, e.g. to enable non-SSL
319    connections, which are disabled by default.  If you change the
320    default settings, you will need to restart the controller by
321    running:
322
323       % /etc/init.d/openflow-controller restart
324
325 3. To set up an OpenFlow switch, install the openflow-switch package
326    and its dependencies.  If it is to be a kernel-based switch, also
327    install openflow-datapath-source, then follow the instructions in
328    /usr/share/doc/openflow-datapath-source/README.Debian to build and
329    install the kernel module.
330
331    You may configure the switch one of the following ways:
332
333       - Completely by hand, as described under the Testing section
334         below.
335
336         For the userspace switch, this is the only supported form of
337         configuration.
338
339       - By editing /etc/default/openflow-switch.  You must at least
340         configure some network devices, by uncommenting NETDEVS and
341         adding the appropriate devices to the list, e.g. NETDEVS="eth0
342         eth1".
343
344         After you edit this file, you will need to start the switch by
345         running:
346
347            % /etc/init.d/openflow-switch restart
348
349         This form of configuration is not supported for the userspace
350         switch.
351
352       - By running the ofp-switch-setup program.  This interactive
353         program will walk you through all the steps of configuring an
354         OpenFlow switch, including configuration of SSL certificates.
355         Run it without arguments, as root:
356
357            % ofp-switch-setup
358
359         This form of configuration is not supported for the userspace
360         switch.
361
362 Testing
363 =======
364
365 The following sets of instructions show how to use the OpenFlow
366 reference implementation as a switch on a single machine.  This can be
367 used to verify that the distribution built properly.  For full
368 installation instructions, refer to the Installation section below.
369
370 Userspace Datapath
371 ------------------
372
373 These instructions use the OpenFlow userspace datapath ("udatapath").
374
375 1. Start the OpenFlow controller running in the background, by running
376    the "controller" program with a command like the following:
377
378       # controller punix:/var/run/controller.sock &
379
380    This command causes the controller to bind to the specified Unix
381    domain socket, awaiting connections from OpenFlow switches.  See
382    controller(8) for details.
383
384    The "controller" program does not require any special privilege, so
385    you do not need to run it as root.
386    
387 2. The commands below must run as root, so log in as root, or use a
388    program such as "su" to become root temporarily.
389
390 3. Create a datapath instance running in the background.  The command
391    below creates a datapath that listens for connections from secchan
392    on a Unix domain socket located in /var/run and services physical
393    ports eth1 and eth2:
394
395       # udatapath punix:/var/run/dp0.sock -i eth1,eth2 &
396
397 4. Run secchan to start the secure channel connecting the datapath and
398    the controller:
399
400       # secchan unix:/var/run/controller.sock unix:/var/run/dp0.sock &
401    
402 5. Devices plugged into the network ports specified in step 2 should
403    now be able to send packets to each other, as if they were plugged
404    into ports on a conventional Ethernet switch.
405
406 Userspace Switch
407 ----------------
408
409 These instructions use the OpenFlow userspace switch that runs as an
410 integrated userspace program.  Keep in mind that the userspace switch
411 is deprecated: you should use the userspace datapath instead.
412
413 1. Start the OpenFlow controller running in the background, by running
414    the "controller" program with a command like the following:
415
416       # controller ptcp: &
417
418    This command causes the controller to bind to port 6633 (the
419    default) awaiting connections from OpenFlow switches.  See
420    controller(8) for details.
421
422    The "controller" program does not require any special privilege, so
423    you do not need to run it as root.
424    
425 2. The "switch" program must run as root, so log in as root, or use a
426    program such as "su" to become root temporarily.
427
428 3. On the same machine, use the "switch" program to start an OpenFlow
429    switch, specifying network devices to use as switch ports on the -i
430    option as a comma-separated list, like so:
431
432       # switch tcp:127.0.0.1 -i eth1,eth2
433    
434    The network devices that you specify should not have configured IP
435    addresses.
436
437 4. The controller causes each switch that connects to it to act like a
438    learning Ethernet switch.  Thus, devices plugged into the specified
439    network ports should now be able to send packets to each other, as
440    if they were plugged into ports on a conventional Ethernet switch.
441
442 Installation
443 ============
444
445 This section explains how to install OpenFlow in a network with one
446 controller and one or more switches, each of which runs on a separate
447 machine.  Before you begin, you must decide on one of two ways for
448 each switch to reach the controller over the network:
449
450       - Use a "control network" that is completely separate from the
451         "data network" to be controlled ("out-of-band control").  The
452         location of the controller must be configured manually in this
453         case.
454
455       - Use the same network for control and for data ("in-band
456         control").  When in-band control is used, the location of the
457         controller may be configured manually or discovered
458         automatically.  We will assume manual configuration here;
459         please refer to secchan(8) for instructions on setting up
460         controller discovery.  
461
462         The (deprecated) userspace switch does not support in-band
463         control.
464
465 Controller Setup
466 ----------------
467
468 On the machine that is to be the OpenFlow controller, start the
469 "controller" program listening for connections from switches on TCP
470 port 6633 (the default), as shown below.
471
472    # controller -v ptcp:
473
474 (See controller(8) for more details)
475
476 Make sure the machine hosting the controller is reachable by the
477 switch.
478
479 Userspace Datapath-Based Setup
480 ------------------------------
481
482 On a machine that is to host an OpenFlow userspace datapath-based
483 switch, follow the procedure below.
484
485 0. The commands below must run as root, so log in as root, or use a
486    program such as "su" to become root temporarily.
487
488 1. Create a datapath instance running in the background.  The command
489    below creates a datapath that listens for connections from secchan
490    on a Unix domain socket located in /var/run, services physical
491    ports eth1 and eth2, and creates a TAP network device named "tap0"
492    for use in in-band control:
493
494       # udatapath punix:/var/run/dp0.sock -i eth1,eth2 --local-port=tap:tap0 &
495
496    (See udatapath(8) for details.)
497
498    If the switch will connect to the controller out-of-band, then the
499    --local-port option may be omitted, or --no-local-port may be
500    substituted.
501
502 3. Arrange so that the switch can reach the controller over the
503    network.
504
505       - If you are using out-of-band control, at this point make sure
506         that the switch machine can reach the controller over the
507         network.
508
509       - If you are using in-band control with manual configuration, at
510         this point the TAP network device created in step 1 is not
511         bridged to any physical network, so the next step depends on
512         whether connectivity is required to configure the device's IP
513         address:
514
515            * If the switch has a static IP address, you may configure
516              its IP address now, e.g.:
517
518                 # ifconfig tap0 192.168.1.1
519
520            * If the switch does not have a static IP address, e.g. its
521              IP address is obtained dynamically via DHCP, then proceed
522              to step 4.  The DHCP client will not be able to contact
523              the DHCP server until the secure channel has started up.
524
525       - If you are using in-band control with controller discovery, no
526         configuration is required at this point.  You may proceed to
527         step 4.
528
529 4. Run secchan to start the secure channel connecting the datapath to
530    a remote controller.  If the controller is running on host
531    192.168.1.2 port 6633 (the default port), the secchan invocation
532    would look like this:
533
534       # secchan unix:/var/run/dp0.sock tcp:192.168.1.2
535
536    - If you are using in-band control with controller discovery, omit
537      the second argument to the secchan command.
538
539    - If you are using out-of-band control, add --out-of-band to the
540      command line.
541
542 5. If you are using in-band control with manual configuration, and the
543    switch obtains its IP address dynamically, then you may now obtain
544    the switch's IP address, e.g. by invoking a DHCP client.  The
545    secure channel will only be able to connect to the controller after
546    an IP address has been obtained.
547
548 6. The secure channel should connect to the controller within a few
549    seconds.  It may take a little longer if controller discovery is in
550    use, because the switch must then also obtain its own IP address
551    and the controller's location via DHCP.
552
553 Testing the Kernel-Based Implementation
554 ---------------------------------------
555
556 The OpenFlow kernel module must be loaded, as described under
557 "Building Conventionally", before it may be used.
558
559 0. The commands below must run as root, so log in as root, or use a
560    program such as "su" to become root temporarily.
561
562 1. Create a datapath instance.  The command below creates a datapath
563    identified as nl:0 (see dpctl(8) for more detailed usage
564    information).
565
566       # dpctl adddp nl:0
567    
568    (nl:0 is the first datapath within a host.  openflow_mod supports
569    multiple datapaths within the same host, which would be identified
570    as nl:1, nl:2, etc.)
571
572    Creating datapath nl:0 also creates a new network device named of0.
573    This network device, called the datapath's "local port", will be
574    bridged to the physical switch ports by the secchan, for use in
575    in-band control.
576
577    If you built a support module for hardware accelerated OpenFlow
578    switching and you want to use it, you must load it before creating
579    the datapath with "dpctl adddp".
580
581 2. Use dpctl to attach the datapath to physical interfaces on the
582    machine.  Say, for example, you want to create a trivial 2-port
583    switch using interfaces eth1 and eth2, you would issue the following
584    commands:
585
586       # dpctl addif nl:0 eth1
587       # dpctl addif nl:0 eth2
588
589    You can verify that the interfaces were successfully added by asking
590    dpctl to print the current status of datapath nl:0:
591
592       # dpctl show nl:0
593
594 3. Arrange so that the switch can reach the controller over the
595    network.
596
597       - If you are using out-of-band control, at this point make sure
598         that the switch machine can reach the controller over the
599         network.
600
601       - If you are using in-band control, then at this point you must
602         configure the of0 network device created in step 1.  This
603         device is not yet bridged to any physical network (because
604         secchan does that, and it is not yet running), so the next
605         step depends on whether connectivity is required to configure
606         the device's IP address:
607
608            * If the switch has a static IP address, you may configure
609              its IP address now, e.g.:
610
611                 # ifconfig of0 192.168.1.1
612
613            * If the switch does not have a static IP address, e.g. its
614              IP address is obtained dynamically via DHCP, then proceed
615              to step 4.  The DHCP client will not be able to contact
616              the DHCP server until the secure channel has started up.
617
618       - If you are using in-band control with controller discovery, no
619         configuration is required at this point.  You may proceed to
620         step 4.
621
622 4. Run secchan to start the secure channel connecting the datapath to
623    a remote controller.  If the controller is running on host
624    192.168.1.2 port 6633 (the default port), the secchan invocation
625    would look like this:
626
627       # secchan nl:0 tcp:192.168.1.2
628
629    - If you are using in-band control with controller discovery, omit
630      the second argument to the secchan command.
631
632    - If you are using out-of-band control, add --out-of-band to the
633      command line.
634
635 5. If you are using in-band control with manual configuration, and the
636    switch obtains its IP address dynamically, then you may now obtain
637    the switch's IP address, e.g. by invoking a DHCP client.  The
638    secure channel will only be able to connect to the controller after
639    an IP address has been obtained.
640
641 6. The secure channel should connect to the controller within a few
642    seconds.  It may take a little longer if controller discovery is in
643    use, because the switch must then also obtain its own IP address
644    and the controller's location via DHCP.
645
646 Userspace Switch-Based Setup
647 ----------------------------
648
649 To set up an OpenFlow switch using the (deprecated) userspace switch,
650 follow this procedure.  The userspace switch must be connected to the
651 controller over a "control network" that is physically separate from
652 the one that the switch and controller are controlling.  (The other
653 switch implementations do not have this limitation.)
654
655 0. The commands below must run as root, so log in as root, or use a
656    program such as "su" to become root temporarily.
657
658 1. Use the "switch" program to start an OpenFlow switch, specifying
659    the IP address of the controller as the first argument to the
660    switch program, and the network devices to include in the switch as
661    arguments to the -i option.  For example, if the controller is
662    running on host 192.168.1.2 port 6633 (the default port), and eth1
663    and eth2 are to be the switch ports, the switch invocation would
664    look like this:
665
666       # switch tcp:127.0.0.1 -i eth1,eth2
667    
668    The network devices that you specify should not have configured IP
669    addresses.
670
671 2. The controller causes each switch that connects to it to act like a
672    learning Ethernet switch.  Thus, devices plugged into the specified
673    network ports should now be able to send packets to each other, as
674    if they were plugged into ports on a conventional Ethernet switch.
675
676 Configuration
677 =============
678
679 Secure operation over SSL
680 -------------------------
681
682 The instructions above set up OpenFlow for operation over a plaintext
683 TCP connection.  Production use of OpenFlow should use SSL[*] to
684 ensure confidentiality and authenticity of traffic among switches and
685 controllers.  The source must be configured with --enable-ssl=yes to
686 build with SSL support.
687
688 To use SSL with OpenFlow, you must set up a public-key infrastructure
689 (PKI) including a pair of certificate authorities (CAs), one for
690 controllers and one for switches.  If you have an established PKI,
691 OpenFlow can use it directly.  Otherwise, refer to "Establishing a
692 Public Key Infrastructure" below.
693
694 To configure the controller to listen for SSL connections on port 6633
695 (the default), invoke it as follows:
696
697       # controller -v pssl: --private-key=PRIVKEY --certificate=CERT \
698             --ca-cert=CACERT
699
700 where PRIVKEY is a file containing the controller's private key, CERT
701 is a file containing the controller CA's certificate for the
702 controller's public key, and CACERT is a file containing the root
703 certificate for the switch CA.  If, for example, your PKI was created
704 with the instructions below, then the invocation would look like:
705
706       # controller -v pssl: --private-key=ctl-privkey.pem \
707             --certificate=ctl-cert.pem --ca-cert=pki/switchca/cacert.pem
708
709 To configure a switch to connect to a controller running on port 6633
710 (the default) on host 192.168.1.2 over SSL, invoke secchan as follows:
711
712       # secchan -v DATAPATH ssl:192.168.1.2 --private-key=PRIVKEY \
713             --certificate=CERT --ca-cert=CACERT
714
715 where DATAPATH is the datapath to connect to (e.g. nl:0 or
716 unix:/var/run/dp0.sock), PRIVKEY is a file containing the switch's
717 private key, CERT is a file containing the switch CA's certificate for
718 the switch's public key, and CACERT is a file containing the root
719 certificate for the controller CA.  If, for example, your PKI was
720 created with the instructions below, then the invocation would look
721 like:
722
723       # secchan -v DATAPATH ssl:192.168.1.2 --private-key=sc-privkey.pem \
724             --certificate=sc-cert.pem --ca-cert=pki/controllerca/cacert.pem
725
726 [*] To be specific, OpenFlow uses TLS version 1.0 or later (TLSv1), as
727     specified by RFC 2246, which is very similar to SSL version 3.0.
728     TLSv1 was released in January 1999, so all current software and
729     hardware should implement it.
730
731 Establishing a Public Key Infrastructure
732 ----------------------------------------
733
734 If you do not have a PKI, the ofp-pki script included with OpenFlow
735 can help.  To create an initial PKI structure, invoke it as:
736       % ofp-pki init
737 which will create and populate a new PKI directory.  The default
738 location for the PKI directory depends on how the OpenFlow tree was
739 configured (to see the configured default, look for the --dir option
740 description in the output of "ofp-pki --help").
741
742 The pki directory contains two important subdirectories.  The
743 controllerca subdirectory contains controller certificate authority
744 related files, including the following:
745
746     - cacert.pem: Root certificate for the controller certificate
747       authority.  This file must be provided to the switch or secchan
748       program with the --ca-cert option to enable it to authenticate
749       valid controllers.
750
751     - private/cakey.pem: Private signing key for the controller
752       certificate authority.  This file must be kept secret.  There is
753       no need for switches or controllers to have a copy of it.
754
755 The switchca subdirectory contains switch certificate authority
756 related files, analogous to those in the controllerca subdirectory:
757
758     - cacert.pem: Root certificate for the switch certificate
759       authority.  This file must be provided to the controller program
760       with the --ca-cert option to enable it to authenticate valid
761       switches.
762
763     - private/cakey.pem: Private signing key for the switch
764       certificate authority.  This file must be kept secret.  There is
765       no need for switches or controllers to have a copy of it.
766
767 After you create the initial structure, you can create keys and
768 certificates for switches and controllers with ofp-pki.  To create a
769 controller private key and certificate in files named ctl-privkey.pem
770 and ctl-cert.pem, for example, you could run:
771       % ofp-pki req+sign ctl controller
772 ctl-privkey.pem and ctl-cert.pem would need to be copied to the
773 controller for its use at runtime (they could then be deleted from
774 their original locations).  The --private-key and --certificate
775 options of controller, respectively, would point to these files.
776
777 Analogously, to create a switch private key and certificate in files
778 named sc-privkey.pem and sc-cert.pem, for example, you could run: 
779       % ofp-pki req+sign sc switch
780 sc-privkey.pem and sc-cert.pem would need to be copied to the switch
781 for its use at runtime (they could then be deleted from their original
782 locations).  The --private-key and --certificate options,
783 respectively, of switch and secchan would point to these files.
784
785 Bug Reporting
786 -------------
787
788 Please report problems to: 
789 info@openflowswitch.org