ofprotocol(8)

NAME
ofprotocol - secure channel connecting an OpenFlow datapath to a controller

SYNOPSIS
ofprotocol [options] datapath controller[,controller...]

DESCRIPTION
The ofprotocol program sets up a secure channel between a local OpenFlow datapath and a remote controller. ofprotocol connects to the local datapath over Netlink and to the controller over TCP or SSL, and then forwards OpenFlow messages from one endpoint to the other.

The mandatory datapath argument argument specifies the local datapath to relay. It takes one of the following forms:

nl:dp_idx
    Attach to the local kernel-based datapath over the Netlink protocol. The dp_idx argument is the number of a datapath created with dpctl(8).

unix:file
    Attach to the userspace datapath implemented by ofdatapath(8). The file argument must the same one specified on the ofdatapath command line.

The optional controller argument specifies how to connect to an OpenFlow controller. Up to four controllers may be specified, using the following forms:

ssl:host[:port]
    The specified SSL port (default: 6633) on the given remote host. The --private-key, --certificate, and --ca-cert options are mandatory when this form is used.

tcp:host[:port]
    The specified TCP port (default: 6633) on the given remote host.

unix:file
    The Unix domain server socket named file.

If multiple controllers are specified, ofprotocol will attempt to connect to a new controller when a controller connection fails, times out, or is closed, or when a controller stops responding to echo requests.

If controller is omitted, ofprotocol attempts to discover the location of the controller automatically (see below).

CONTACTING THE CONTROLLER
The OpenFlow switch must be able to contact the OpenFlow controller over the network. It can do so in one of two ways:

out-of-band
    In this configuration, OpenFlow traffic uses a network separate from the data traffic that it controls, that is, the switch does not use any of the network devices added to the datapath with dpctl addif in its communication with the controller.

    To use ofprotocol in a network with out-of-band control, specify --out-of-band on the ofprotocol command line. The control network must be configured separately, before or after ofprotocol is started.

in-band
    In this configuration, a single network is used for OpenFlow traffic and other data traffic, that is, the switch contacts the controller over one of the network devices added to the datapath with dpctl addif. This configuration is often more convenient than out-of-band control, because it is not necessary to maintain two independent networks.

    In-band control is the default for ofprotocol, so no special command-line option is required.

    With in-band control, the location of the controller can be configured manually or discovered automatically:

    controller discovery
        To make ofprotocol discover the location of the controller automatically, do not specify the location of the controller on the ofprotocol command line.

        In this mode, ofprotocol will broadcast a DHCP request with vendor class identifier OpenFlow across the network devices added to the datapath with dpctl addif. It will accept any valid DHCP reply that has the same vendor class identifier and includes a vendor-specific option with code 1 whose contents are a string specifying the location of the controller in the same format used on the ofprotocol command line (e.g. ssl:192.168.0.1).

        The DHCP reply may also, optionally, include a vendor-specific option with code 2 whose contents are a string specifying the URI to the base of the OpenFlow PKI (e.g. http://192.168.0.1/openflow/pki). This URI is used only for bootstrapping the OpenFlow PKI at initial switch setup; ofprotocol does not use it at all.

        The following ISC DHCP server configuration file assigns the IP address range 192.168.0.20 through 192.168.0.30 to OpenFlow switches that follow the switch protocol and addresses 192.168.0.1 through 192.168.0.10 to all other DHCP clients:

        default-lease-time 600;
        max-lease-time 7200;
        option space openflow;
        option openflow.controller-vconn code 1 = text;
        option openflow.pki-uri code 2 = text;
        class "OpenFlow" {
          match if option vendor-class-identifier = "OpenFlow";
          vendor-option-space openflow;
          option openflow.controller-vconn "tcp:192.168.0.10";
          option openflow.pki-uri "http://192.168.0.10/openflow/pki";
          option vendor-class-identifier "OpenFlow";
        }
        subnet 192.168.0.0 netmask 255.255.255.0 {
            pool {
                allow members of "OpenFlow";
                range 192.168.0.20 192.168.0.30;
            }
            pool {
                deny members of "OpenFlow";
                range 192.168.0.1 192.168.0.10;
            }
        }

    manual configuration
        To configure in-band control manually, specify the location of the controller on the ofprotocol command line as the controller argument. You must also configure the network device for the OpenFlow ``local port'' to allow ofprotocol to connect to that controller. The OpenFlow local port is a virtual network port that ofprotocol bridges to the physical switch ports. Its network device name depends on the datapath specified on the ofprotocol command line:

        nl:dp_idx
            The local port network device for nl:dp_idx is always named ofdp_idx, i.e. the device for nl:0 is of0.

        unix:file
            The local port network device name may be specified on the ofdatapath command line, using the --local-port option. It is often tap0.

        Before ofprotocol starts, the local port network device is not bridged to any physical network, 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 with a command such as:

            ifconfig of0 192.168.1.1

        and then invoke ofprotocol.

        On the other hand, if the switch does not have a static IP address, e.g. it obtains its IP address dynamically via DHCP, the DHCP client will not be able to contact the DHCP server until the secure channel has started up. Thus, start ofprotocol without configuring the local port network device, and start the DHCP client afterward.

OPTIONS

  Controller Discovery Options

--accept-vconn=regex
    When ofprotocol performs controller discovery (see CONTACTING THE CONTROLLER, above, for more information about controller discovery), it validates the controller location obtained via DHCP with a POSIX extended regular expression. Only controllers whose names match the regular expression will be accepted.

    The default regular expression is ssl:.* (meaning that only SSL controller connections will be accepted) when any of the SSL configuration options --private-key, --certificate, or --ca-cert is specified. The default is .* otherwise (meaning that any controller will be accepted).

    The regex is implicitly anchored at the beginning of the controller location string, as if it begins with ^.

    When controller discovery is not performed, this option has no effect.

--no-resolv-conf
    When ofprotocol performs controller discovery (see CONTACTING THE CONTROLLER, above, for more information about controller discovery), by default it overwrites the system's /etc/resolv.conf with domain information and DNS servers obtained via DHCP. If the location of the controller is specified using a hostname, rather than an IP address, and the network's DNS servers ever change, this behavior is essential. But because it also interferes with any administrator or process that manages /etc/resolv.conf, when this option is specified, ofprotocol will not modify /etc/resolv.conf.

    ofprotocol will only modify resolv.conf if the DHCP response that it receives specifies one or more DNS servers.

    When controller discovery is not performed, this option has no effect.

  Networking Options

-F, --fail=[open|closed]
    The controller is, ordinarily, responsible for setting up all flows on the OpenFlow switch. Thus, if the connection to the controller fails, no new network connections can be set up. If the connection to the controller stays down long enough, no packets can pass through the switch at all.

    If this option is set to open (the default), ofprotocol will take over responsibility for setting up flows in the local datapath when no message has been received from the controller for three times the inactivity probe interval (see below), or 45 seconds by default. In this ``fail open'' mode, ofprotocol causes the datapath to act like an ordinary MAC-learning switch. ofprotocol will continue to retry connection to the controller in the background and, when the connection succeeds, it discontinues its fail-open behavior. The secure channel enters the fail-open mode when

    If this option is set to closed, then ofprotocol will not set up flows on its own when the controller connection fails.

--inactivity-probe=secs
    When the secure channel is connected to the controller, the secure channel waits for a message to be received from the controller for secs seconds before it sends a inactivity probe to the controller. After sending the inactivity probe, if no response is received for an additional secs seconds, the secure channel assumes that the connection has been broken and attempts to reconnect. The default is 15 seconds, and the minimum value is 1 seconds.

    When fail-open mode is configured, changing the inactivity probe interval also changes the interval before entering fail-open mode (see above).

--max-idle=secs|permanent
    Sets secs as the number of seconds that a flow set up by the secure channel will remain in the switch's flow table without any matching packets being seen. If permanent is specified, which is not recommended, flows set up by the secure channel will never expire. The default is 15 seconds.

    Most flows are set up by the OpenFlow controller, not by the secure channel. This option affects only the following flows, which the secure channel sets up itself:

    •   When --fail=open is specified, flows set up when the secure channel has not been able to contact the controller for the configured fail-open delay.

    •   When in-band control is in use, flows set up to bootstrap contacting the controller (see CONTACTING THE CONTROLLER, above, for more information about in-band control).

    As a result, when both --fail=closed and --out-of-band are specified, this option has no effect.

--max-backoff=secs
    Sets the maximum time between attempts to connect to the controller to secs, which must be at least 1. The actual interval between connection attempts starts at 1 second and doubles on each failing attempt until it reaches the maximum. The default maximum backoff time is 15 seconds.

-l, --listen=method
    Configures the switch to additionally listen for incoming OpenFlow connections for switch management with dpctl. The method must be given as one of the passive OpenFlow connection methods listed below. This option may be specified multiple times to listen to multiple connection methods.

    pssl:[port]
        Listens for SSL connections on port (default: 6633). The --private-key, --certificate, and --ca-cert options are mandatory when this form is used.

    ptcp:[port]
        Listens for TCP connections on port (default: 6633).

    punix:file
        Listens for connections on Unix domain server socket named file.

-m, --monitor=method
    Configures the switch to additionally listen for incoming OpenFlow connections for switch monitoring with dpctl's monitor command. The method must be given as one of the passive OpenFlow connection methods listed above as acceptable for --listen.

    When dpctl monitor makes a monitoring connection, ofprotocol sends it a copy of every OpenFlow message sent to or received from the kernel in the normal course of its operations. It does not send a copy of any messages sent to or from the OpenFlow connection to the controller. Most of these messages will be seen anyhow, however, because ofprotocol mainly acts as a relay between the controller and the kernel. ofprotocol also does not send a copy of any messages sent to or from the OpenFlow connection to the controller. Such messages will typically not be seen, because ofprotocol maintains a separate connection to the kernel for each management connection.

    Messages are copied to the monitoring connections on a best-effort basis. In particular, if the socket buffer of the monitoring connection fills up, some messages will be lost.

--in-band, --out-of-band
    Configures ofprotocol to operate in in-band or out-of-band control mode (see CONTACTING THE CONTROLLER above). When neither option is given, the default is in-band control.

--stp, --no-stp
    Enable or disable implementation of IEEE 802.1D Spanning Tree Protocol at the switch. The default is --no-stp in this distribution, because bugs in the STP implementation are still being worked out. The default will change to --stp at some point in the future.

--emerg-flow
    Enable emergecny flow protection and restration at the switch. If emergency flow enabled, ofprotocol will attempt to switch flow table to emergency's one when a controller connection fails. The default is disabled in this distribution.

  Rate-Limiting Options

These options configure how the switch applies a ``token bucket'' to limit the rate at which packets in unknown flows are forwarded to an OpenFlow controller for flow-setup processing. This feature prevents a single OpenFlow switch from overwhelming a controller.

--rate-limit[=rate]
    Limits the maximum rate at which packets will be forwarded to the OpenFlow controller to rate packets per second. If rate is not specified then the default of 1,000 packets per second is used.

    If --rate-limit is not used, then the switch does not limit the rate at which packets are forwarded to the controller.

--burst-limit=burst
    Sets the maximum number of unused packet credits that the switch will allow to accumulate during time in which no packets are being forwarded to the OpenFlow controller to burst (measured in packets). The default burst is one-quarter of the rate specified on --rate-limit.

    This option takes effect only when --rate-limit is also specified.

  Daemon Options

-P[pidfile], --pidfile[=pidfile]
    Causes a file (by default, ofprotocol.pid) to be created indicating the PID of the running process. If pidfile is not specified, or if it does not begin with /, then it is created in /var/run.

-f, --force
    By default, when -P or --pidfile is specified and the specified pidfile already exists and is locked by a running process, ofprotocol refuses to start. Specify -f or --force to cause it to instead overwrite the pidfile.

    When -P or --pidfile is not specified, this option has no effect.

-D, --detach
    Causes ofprotocol to detach itself from the foreground session and run as a background process.

  Public Key Infrastructure Options

-p, --private-key=privkey.pem
    Specifies a PEM file containing the private key used as the switch's identity for SSL connections to the controller.

-c, --certificate=cert.pem
    Specifies a PEM file containing a certificate, signed by the controller's certificate authority (CA), that certifies the switch's private key to identify a trustworthy switch.

-C, --ca-cert=cacert.pem
    Specifies a PEM file containing the CA certificate used to verify that the switch is connected to a trustworthy controller.

--bootstrap-ca-cert=cacert.pem
    When cacert.pem exists, this option has the same effect as -C or --ca-cert. If it does not exist, then ofprotocol will attempt to obtain the CA certificate from the controller on its first SSL connection and save it to the named PEM file. If it is successful, it will immediately drop the connection and reconnect, and from then on all SSL connections must be authenticated by a certificate signed by the CA certificate thus obtained.

    This option exposes the SSL connection to a man-in-the-middle attack obtaining the initial CA certificate, but it may be useful for bootstrapping.

    This option is only useful if the controller sends its CA certificate as part of the SSL certificate chain. The SSL protocol does not require the controller to send the CA certificate, but controller(8) can be configured to do so with the --peer-ca-cert option.

  Logging Options

-vmodule[:facility[:level]], --verbose=module[:facility[:level]]

    Sets the logging level for module in facility to level:

    •   module may be any valid module name (as displayed by the --list action on vlogconf(8)), or the special name ANY to set the logging levels for all modules.

    •   facility may be syslog, console, or file to set the levels for logging to the system log, the console, or a file respectively, or ANY to set the logging levels for both facilities. If it is omitted, facility defaults to ANY.

        Regardless of the log levels set for file, logging to a file will not take place unless --log-file is also specified (see below).

    •   level must be one of emer, err, warn, info, or dbg, designating the minimum severity of a message for it to be logged. If it is omitted, level defaults to dbg.

-v, --verbose
    Sets the maximum logging verbosity level, equivalent to --verbose=ANY:ANY:dbg.

-vPATTERN:facility:pattern, --verbose=PATTERN:facility:pattern
    Sets the log pattern for facility to pattern. Refer to vlogconf(8) for a description of the valid syntax for pattern.

--log-file[=file]
    Enables logging to a file. If file is specified, then it is used as the exact name for the log file. The default log file name used if file is omitted is /var/log/openflow/ofprotocol.log.

  Other Options

-h, --help
    Prints a brief help message to the console.

-V, --version
    Prints version information to the console.

--check-leaks=file
    Logs information about memory allocation and deallocation to file, to allow for debugging memory leaks in ofprotocol. This option slows down ofprotocol considerably, so it should only be used when a memory leak is suspected.

SEE ALSO

dpctl(8), ofp-discover(8), controller(8), ofp-pki(8), ofdatapath(8), vlogconf(8)