Import from old repository commit 61ef2b42a9c4ba8e1600f15bb0236765edc2ad45.

[sliver-openvswitch.git] / INSTALL

                Open vSwitch Installation Instructions

This document describes how to build, install, and execute
Open vSwitch.

Open vSwitch implements an Ethernet switch with MAC learning that may
be configured with any of the following features:

        * NIC bonding with automatic fail-over and source MAC-based TX
          load balancing ("SLB").

        * 802.1Q VLAN support.

        * Port mirroring, with optional VLAN tagging.

        * NetFlow v5 flow logging.

        * Connectivity to an external OpenFlow controller, such as
          NOX.

The current version of this distribution requires a kernel module to
be built and loaded.  An (optional) entirely userspace switch is on
the roadmap for future versions.

The distribution also contains a number of related utilities.

Build Methods
=============

There are two principal ways to build and install this distribution:

        - Using "configure" and "make" in the ordinary way.  See
          Building Conventionally below for detailed instructions.

        - As a set of Debian packages.  Refer to Building Debian
          Packages, below, for instructions.

Base Prerequisites
------------------

Regardless of how it is built, Open vSwitch has a common set of
prerequisites.  To compile the userspace programs in the OpenFlow
reference distribution, you will need the following software:

    - A make program, e.g. GNU make
      (http://www.gnu.org/software/make/).  BSD make should also work.

    - The GNU C compiler (http://gcc.gnu.org/).  We generally test
      with version 4.2 or 4.3.

    - libssl, from OpenSSL (http://www.openssl.org/), is optional but
      recommended if you plan to connect the Open vSwitch to an
      OpenFlow controller.  libssl is required to establish
      confidentiality and authenticity in the connections from an
      Open vSwitch to an OpenFlow controller.  To enable, configure
      with --enable-ssl=yes.

To compile the kernel module, you must also install the following:

    - A supported Linux kernel version.  Please refer to README for a
      list of supported versions.

      The OpenFlow datapath requires bridging support (CONFIG_BRIDGE)
      to be built as a kernel module.  (This is common in kernels
      provided by Linux distributions.)  The bridge module must not be
      loaded or in use.  If the bridge module is running (check with
      "lsmod | grep bridge"), you must remove it ("rmmod bridge")
      before starting the datapath.

    - To build a kernel module, you need the same version of GCC that
      was used to build that kernel (usually version 4.0 or later).

    - A kernel build directory corresponding to the Linux kernel image
      the module is to run on.  Under Debian and Ubuntu, for example,
      each linux-image package containing a kernel binary has a
      corresponding linux-headers package with the required build
      infrastructure.

If you are working from a Git tree or snapshot (instead of from a
distribution tarball), or if you modify the Open vSwitch build system,
you will also need the following software:

    - Autoconf version 2.60 or later (http://www.gnu.org/software/autoconf).

    - Automake version 1.10 or later (http://www.gnu.org/software/automake).

    - pkg-config (http://pkg-config.freedesktop.org/wiki/).  We test
      with version 0.22.

Debian Prerequisites
--------------------

To build Debian packages from the Open vSwitch distribution, you will
need to install a number of Debian packages in addition to the base
prerequisites listed above.  These additional prerequisites may be
found listed as "Build-Depends" in debian/control in the source tree.
To check that they are installed, first install the dpkg-dev package,
then run dpkg-checkbuilddeps from the top level of the OpenFlow source
tree.

To build Debian packages without being root, also install the
"fakeroot" package.

Building Conventionally
=======================

This section explains how to build and install the Open vSwitch
distribution in the ordinary way using "configure" and "make".

0. Check that you have installed all the prerequisites listed above in
   the Base Prerequisites section.

1. In the top source directory, configure the package by running the
   configure script.  You can usually invoke configure without any
   arguments:

      % ./configure

   To use a specific C compiler for compiling OpenFlow user programs,
   also specify it on the configure command line, like so:

      % ./configure CC=gcc-4.2

   To build the Linux kernel module, so that you can run the
   kernel-based switch, pass the location of the kernel build
   directory on --with-l26.  For example, to build for a running
   instance of Linux 2.6:

      % ./configure --with-l26=/lib/modules/`uname -r`/build

   If you wish to build the kernel module for an architecture other
   than the architecture of the machine used for the build, you may
   specify the kernel architecture string using the KARCH variable
   when invoking the configure script.  For example, to build for MIPS
   with Linux 2.6:

         % ./configure --with-l26=/path/to/linux-2.6 KARCH=mips

   The configure script accepts a number of other options and honors
   additional environment variables.  For a full list, invoke
   configure with the --help option.

2. Run make in the top source directory: 

      % make

   The following main binaries will be built:

      - Virtual switch daemon: vswitchd/ovs-vswitchd

      - Bridge compatibility daemon: vswitchd/ovs-brcompatd

      - Datapath administration utility: utilities/ovs-dpctl.

   Some less important binaries will be built also:

      - Runtime configuration utility: utilities/ovs-appctl.

      - Simple OpenFlow controller: utilities/ovs-controller.

      - Secure channel executable: secchan/secchan.

      - Miscellaneous utilities: utilities/ovs-discover,
        utilities/ovs-kill.

      - ANSI terminal support for EZIO 16x2 LCD panel:
        extras/ezio/ezio-term (only if the proper libraries are
        installed).

      - Switch monitoring UI for small text displays:
        extras/ezio/ovs-switchui (only if the proper libraries are
        installed).

      - Tests: various binaries in tests/.

   If you passed --with-l26 to configure, "make" will also build the
   following kernel modules:

      - datapath/linux-2.6/brcompat_mod.ko

      - datapath/linux-2.6/openflow_mod.ko

3. Run "make install" to install the executables and manpages into the
   running system, by default under /usr/local.

4. If you built kernel modules, you may load them with "insmod", e.g.:

      % insmod datapath/linux-2.6/openflow_mod.ko

   The insmod program must be run as root.  You may need to specify a
   full path to insmod, e.g. /sbin/insmod.  To verify that the modules
   have been loaded, run "/sbin/lsmod" and check that openflow_mod is
   listed.

5. Test the virtuaal switch, as described under Testing the Virtual
Switch below.

Building Debian Packages
========================

Follow these instructions to build Debian packages for OpenFlow.

0. Check that you have installed all the prerequisites listed above in
   the Base Prerequisites and Debian Prerequisites sections above.

1. In the top source directory, run the following command, as root:

      % dpkg-buildpackage

   Alternatively, if you installed the "fakeroot" package, you may run
   dpkg-buildpackage as an ordinary user with the following syntax:

      % dpkg-buildpackage -rfakeroot

   The following packages will be built in the directory above the
   source tree:

      - openflow-controller: The OpenFlow controller.  Depends on
        openflow-pki (see below).

      - openflow-switch: Install this package on a machine that acts
        as an OpenFlow kernel switch.

      - openflow-datapath-source: Source code for OpenFlow's Linux
        kernel module.

      - openflow-pki: Public-key infrastructure for OpenFlow.  Install
        this package on a machine that acts as an OpenFlow PKI server
        (see "Establishing a Public Key Infrastructure" below).

      - openflow-common: Files and utilities required by more than one
        of the above packages.

2. To set up an OpenFlow controller, install the openflow-controller
   package and its dependencies.  You may configure it by editing
   /etc/default/openflow-controller, e.g. to enable non-SSL
   connections, which are disabled by default.  If you change the
   default settings, you will need to restart the controller by
   running:

      % /etc/init.d/openflow-controller restart

3. To set up an OpenFlow switch, install the openflow-switch package
   and its dependencies.  If it is to be a kernel-based switch, also
   install openflow-datapath-source, then follow the instructions in
   /usr/share/doc/openflow-datapath-source/README.Debian to build and
   install the kernel module.

   You may configure the switch one of the following ways:

      - Completely by hand, as described under the Testing section
        below.

        For the userspace datapath-based switch, this is the only
        supported form of configuration.

      - By editing /etc/default/openflow-switch.  You must at least
        configure some network devices, by uncommenting NETDEVS and
        adding the appropriate devices to the list, e.g. NETDEVS="eth0
        eth1".

        After you edit this file, you will need to start the switch by
        running:

           % /etc/init.d/openflow-switch restart

        This form of configuration is not supported for the userspace
        datapath-based switch.

      - By running the ovs-switch-setup program.  This interactive
        program will walk you through all the steps of configuring an
        OpenFlow switch, including configuration of SSL certificates.
        Run it without arguments, as root:

           % ovs-switch-setup

        This form of configuration is not supported for the userspace
        datapath-based switch.

Installation
============

This section explains how to install Open vSwitch in a network with one
controller and one or more switches, each of which runs on a separate
machine.  Before you begin, you must decide on one of two ways for
each switch to reach the controller over the network:

      - Use a "control network" that is completely separate from the
        "data network" to be controlled ("out-of-band control").  The
        location of the controller must be configured manually in this
        case.

      - Use the same network for control and for data ("in-band
        control").  When in-band control is used, the location of the
        controller may be configured manually or discovered
        automatically.  We will assume manual configuration here;
        please refer to secchan(8) for instructions on setting up
        controller discovery.  

Controller Setup
----------------

On the machine that is to be the OpenFlow controller, start the
"ovs-controller" program listening for connections from switches on
TCP port 6633 (the default), as shown below.

   # ovs-controller -v ptcp:

(See ovs-controller(8) for more details)

Make sure the machine hosting the controller is reachable by the
switch.

Testing the Virtual Switch
--------------------------

The Open vSwitch kernel module must be loaded, as described under
"Building Conventionally", before it may be used.

0. The commands below must run as root, so log in as root, or use a
   program such as "su" to become root temporarily.

1. Create a datapath instance.  The command below creates a datapath
   identified as dp0 (see ovs-dpctl(8) for more detailed usage
   information).

      # ovs-dpctl add-dp dp0
   
   (dp0 is the first datapath within a host.  openvswitch_mod supports
   multiple datapaths within the same host, which would be identified
   as dp1, dp2, etc.)

   Creating datapath dp0 creates a new network device, also named dp0.
   This network device, called the datapath's "local port", will be
   bridged to the physical switch ports by the secchan, for use in
   in-band control.

2. Use ovs-dpctl to attach the datapath to physical interfaces on the
   machine.  Say, for example, you want to create a trivial 2-port
   switch using interfaces eth1 and eth2, you would issue the
   following commands:

      # ovs-dpctl add-if dp0 eth1
      # ovs-dpctl add-if dp0 eth2

   You can verify that the interfaces were successfully added by asking
   ovs-dpctl to print the current status of datapath dp0:

      # ovs-dpctl show dp0

3. Arrange so that the switch can reach the controller over the
   network.

      - If you are using out-of-band control, at this point make sure
        that the switch machine can reach the controller over the
        network.

      - If you are using in-band control, then at this point you must
        configure the dp0 network device created in step 1.  This
        device is not yet bridged to any physical network (because
        secchan does that, and it is not yet running), so the next
        step depends on whether connectivity is required to configure
        the device's IP address:

           * If the switch has a static IP address, you may configure
             its IP address now, e.g.:

                # ifconfig dp0 192.168.1.1

           * If the switch does not have a static IP address, e.g. its
             IP address is obtained dynamically via DHCP, then proceed
             to step 4.  The DHCP client will not be able to contact
             the DHCP server until the secure channel has started up.

      - If you are using in-band control with controller discovery, no
        configuration is required at this point.  You may proceed to
        step 4.

4. Run secchan to start the secure channel connecting the datapath to
   a remote controller.  If the controller is running on host
   192.168.1.2 port 6633 (the default port), the secchan invocation
   would look like this:

      # secchan dp0 tcp:192.168.1.2

   - If you are using in-band control with controller discovery, omit
     the second argument to the secchan command.

   - If you are using out-of-band control, add --out-of-band to the
     command line.

5. If you are using in-band control with manual configuration, and the
   switch obtains its IP address dynamically, then you may now obtain
   the switch's IP address, e.g. by invoking a DHCP client.  The
   secure channel will only be able to connect to the controller after
   an IP address has been obtained.

6. The secure channel should connect to the controller within a few
   seconds.  It may take a little longer if controller discovery is in
   use, because the switch must then also obtain its own IP address
   and the controller's location via DHCP.

Configuration
=============

Secure operation over SSL
-------------------------

The instructions above set up Open vSwitch for operation over a
plaintext TCP connection.  Production use of Open vSwitch should use
SSL[*] to ensure confidentiality and authenticity of traffic among
switches and controllers.  The source must be configured with
--enable-ssl=yes to build with SSL support.

To use SSL with Open vSwitch, you must set up a public-key infrastructure
(PKI) including a pair of certificate authorities (CAs), one for
controllers and one for switches.  If you have an established PKI,
Open vSwitch can use it directly.  Otherwise, refer to "Establishing a
Public Key Infrastructure" below.

To configure the controller to listen for SSL connections on port 6633
(the default), invoke it as follows:

      # ovs-controller -v pssl: --private-key=PRIVKEY --certificate=CERT \
            --ca-cert=CACERT

where PRIVKEY is a file containing the controller's private key, CERT
is a file containing the controller CA's certificate for the
controller's public key, and CACERT is a file containing the root
certificate for the switch CA.  If, for example, your PKI was created
with the instructions below, then the invocation would look like:

      # ovs-controller -v pssl: --private-key=ctl-privkey.pem \
            --certificate=ctl-cert.pem --ca-cert=pki/switchca/cacert.pem

To configure a switch to connect to a controller running on port 6633
(the default) on host 192.168.1.2 over SSL, invoke secchan as follows:

      # secchan -v DATAPATH ssl:192.168.1.2 --private-key=PRIVKEY \
            --certificate=CERT --ca-cert=CACERT

where DATAPATH is the datapath to connect to (e.g. dp0 or
unix:/var/run/dp0.sock), PRIVKEY is a file containing the switch's
private key, CERT is a file containing the switch CA's certificate for
the switch's public key, and CACERT is a file containing the root
certificate for the controller CA.  If, for example, your PKI was
created with the instructions below, then the invocation would look
like:

      # secchan -v DATAPATH ssl:192.168.1.2 --private-key=sc-privkey.pem \
            --certificate=sc-cert.pem --ca-cert=pki/controllerca/cacert.pem

[*] To be specific, Open vSwitch uses TLS version 1.0 or later (TLSv1), as
    specified by RFC 2246, which is very similar to SSL version 3.0.
    TLSv1 was released in January 1999, so all current software and
    hardware should implement it.

Establishing a Public Key Infrastructure
----------------------------------------

If you do not have a PKI, the ovs-pki script included with Open vSwitch
can help.  To create an initial PKI structure, invoke it as:
      % ovs-pki init
which will create and populate a new PKI directory.  The default
location for the PKI directory depends on how the Open vSwitch tree was
configured (to see the configured default, look for the --dir option
description in the output of "ovs-pki --help").

The pki directory contains two important subdirectories.  The
controllerca subdirectory contains controller certificate authority
related files, including the following:

    - cacert.pem: Root certificate for the controller certificate
      authority.  This file must be provided to secchan with the
      --ca-cert option to enable it to authenticate valid controllers.

    - private/cakey.pem: Private signing key for the controller
      certificate authority.  This file must be kept secret.  There is
      no need for switches or controllers to have a copy of it.

The switchca subdirectory contains switch certificate authority
related files, analogous to those in the controllerca subdirectory:

    - cacert.pem: Root certificate for the switch certificate
      authority.  This file must be provided to the controller program
      with the --ca-cert option to enable it to authenticate valid
      switches.

    - private/cakey.pem: Private signing key for the switch
      certificate authority.  This file must be kept secret.  There is
      no need for switches or controllers to have a copy of it.

After you create the initial structure, you can create keys and
certificates for switches and controllers with ovs-pki.  To create a
controller private key and certificate in files named ctl-privkey.pem
and ctl-cert.pem, for example, you could run:
      % ovs-pki req+sign ctl controller
ctl-privkey.pem and ctl-cert.pem would need to be copied to the
controller for its use at runtime (they could then be deleted from
their original locations).  The --private-key and --certificate
options of ovs-controller, respectively, would point to these files.

Analogously, to create a switch private key and certificate in files
named sc-privkey.pem and sc-cert.pem, for example, you could run: 
      % ovs-pki req+sign sc switch
sc-privkey.pem and sc-cert.pem would need to be copied to the switch
for its use at runtime (they could then be deleted from their original
locations).  The --private-key and --certificate options,
respectively, of secchan would point to these files.

Bug Reporting
-------------

Please report problems to ovs-bugs@openvswitch.org.