(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.1 or 4.2.
+ with version 4.2 or 4.3.
- libssl, from OpenSSL (http://www.openssl.org/), is optional but
recommended. libssl is required to establish confidentiality
"lsmod | grep bridge"), you must remove it ("rmmod bridge")
before starting the datapath.
- In kernels prior to 2.6.9, VLAN support (CONFIG_VLAN_8021Q) must
- be compiled either directly or as a module. Failure to do this
- will cause an error on module insertion due to the
+ In 2.4.x kernels, VLAN support (CONFIG_VLAN_8021Q) must be
+ compiled either directly or as a module. Failure to do this
+ will cause an error on module insertion due to the
"dev_change_flags" symbol being undefined.
- The correct version of GCC for the kernel that you are building
program such as "su" to become root temporarily.
1. Create a datapath instance. The command below creates a datapath
- identified as nl:0 (see dpctl(8) for more detailed usage
+ identified as dp0 (see dpctl(8) for more detailed usage
information).
- # dpctl adddp nl:0
+ # dpctl adddp dp0
- (nl:0 is the first datapath within a host. openflow_mod supports
+ (dp0 is the first datapath within a host. openflow_mod supports
multiple datapaths within the same host, which would be identified
- as nl:1, nl:2, etc.)
+ as dp1, dp2, etc.)
- Creating datapath nl:0 also creates a new network device named of0.
+ 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.
switch using interfaces eth1 and eth2, you would issue the following
commands:
- # dpctl addif nl:0 eth1
- # dpctl addif nl:0 eth2
+ # dpctl addif dp0 eth1
+ # dpctl addif dp0 eth2
You can verify that the interfaces were successfully added by asking
- dpctl to print the current status of datapath nl:0:
+ dpctl to print the current status of datapath dp0:
- # dpctl show nl:0
+ # dpctl show dp0
3. Arrange so that the switch can reach the controller over the
network.
network.
- If you are using in-band control, then at this point you must
- configure the of0 network device created in step 1. This
+ 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
* If the switch has a static IP address, you may configure
its IP address now, e.g.:
- # ifconfig of0 192.168.1.1
+ # 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
192.168.1.2 port 6633 (the default port), the secchan invocation
would look like this:
- # secchan nl:0 tcp:192.168.1.2
+ # 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.
# 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. nl:0 or
+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
- udatapath.
-- A lot of the manpages and documentation need to be updated.
+- Linux 2.4.x support.
An OpenFlow switch consists of three parts: (1) A "flow table" in
which each flow entry is associated with an action telling the switch
-how to process the flow, (2) a "secure channel" connecting the switch
+how to process the flow, (2) a "secure channel" that connects the switch
to a remote process (a controller), allowing commands and packets to
be sent between the controller and the switch, and (3) an OpenFlow
protocol implementation, providing an open and standard way for a
Linux because it is partially implemented in the Linux kernel, has the
following components:
- - A Linux kernel module that implements the flow table and
- OpenFlow protocol, in the datapath directory.
+ - A Linux kernel module that implements the flow table, in the
+ datapath directory.
- secchan, a program that implements the secure channel
component of the reference switch.
- - dpctl, a tool for configuring the kernel module.
+ - dpctl, a tool for configuring the datapath and OpenFlow
+ switches in general.
The second implementation has the following components:
GCC is the expected compiler.
-Bugs/Shortcomings
------------------
-
-- The flow table does not support the "normal processing" action.
-
References
----------
-.TH controller 8 "May 2008" "OpenFlow" "OpenFlow Manual"
+.TH controller 8 "March 2009" "OpenFlow" "OpenFlow Manual"
.ds PN controller
.SH NAME
[\fIoptions\fR] \fImethod\fR \fB[\fImethod\fR]\&...
.SH DESCRIPTION
-A sample OpenFlow controller which functions as an L2 MAC-learning
-switch or hub. \fBcontroller\fR can manage a remote datapath through
-a secure channel (see \fBsecchan(8)\fR). It can also connect directly
-to a local datapath via Netlink.
+\fBcontroller\fR manages any number of remote switches over OpenFlow
+protocol, causing them to function as L2 MAC-learning switches or hub.
\fBcontroller\fR controls one or more OpenFlow switches, specified as
one or more of the following OpenFlow connection methods:
Listens for connections from OpenFlow switches on the Unix domain
server socket named \fIfile\fR.
-.TP
-\fBnl:\fIdp_idx\fR
-The local Netlink datapath numbered \fIdp_idx\fR, as configured with
-.BR dpctl (8).
-This form requires that the local host has the OpenFlow kernel
-module for Linux loaded.
-
.TP
\fBssl:\fIhost\fR[\fB:\fIport\fR]
The specified SSL \fIport\fR (default: 6633) on the given remote
first boot using, e.g., the \fB--bootstrap-ca-cert\fR option to
\fBsecchan\fR(8).
-.TP
-.BR \-n ", " \-\^\-noflow
+.IP "\fB-n\fR, \fB--noflow\fR"
By default, the controller sets up a flow in each OpenFlow switch
whenever it receives a packet whose destination is known due through
MAC learning. This option disables flow setup, so that every packet
This option has no effect when \fB-n\fR (or \fB--noflow\fR) is in use
(because the controller does not set up flows in that case).
-.TP
-.BR \-H ", " \-\^\-hub
+.IP "\fB-H\fR, \fB--hub\fR"
By default, the controller acts as an L2 MAC-learning switch. This
option changes its behavior to that of a hub that floods packets on
all but the incoming port.
.SH EXAMPLES
-.TP
-To connect directly to local datapath 0 over netlink (Linux only):
-
-.B % controller nl:0
-
.TP
To bind locally to port 6633 (the default) and wait for incoming connections from OpenFlow switches:
# * "pctp:[PORT]": Listen for TCP connections on the specified PORT
# (default: 6633). Not recommended for security reasons.
#
-# * "nl:DP_IDX": Listen on local datapath DP_IDX. Used only if this
-# machine is also an OpenFlow switch and not running the secure
-# channel, and only if you know what you're doing.
-#
LISTEN="pssl:"
# PRIVKEY: Name of file containing controller's private key.
check_op "Removing IP address from $netdev" ifconfig $netdev 0.0.0.0
done
- must_succeed "Adding datapath" dpctl adddp nl:0
- for netdev in $NETDEVS; do
- must_succeed "Adding $netdev to datapath" dpctl addif nl:0 $netdev
- done
+ must_succeed "Creating datapath" dpctl adddp dp0 $NETDEVS
xx='[0-9abcdefABCDEF][0-9abcdefABCDEF]'
case $DATAPATH_ID in
if test "$MODE" = out-of-band; then
set -- "$@" --out-of-band
fi
- set -- "$@" nl:0 "$CONTROLLER"
+ set -- "$@" dp0 "$CONTROLLER"
echo -n "Starting $DESC: "
start-stop-daemon --start --quiet --pidfile $PIDFILE \
--exec $DAEMON -- "$@"
--exec $DAEMON
echo "$NAME."
- for netdev in $NETDEVS; do
- check_op "Removing $netdev from datapath" dpctl delif nl:0 $netdev
- done
- check_op "Deleting datapath" dpctl deldp nl:0
+ check_op "Deleting datapath" dpctl deldp dp0
check_op "Unloading kernel module" modprobe -r openflow_mod
;;
force-stop)
const char *name;
/* Attempts to connect to an OpenFlow device. 'name' is the full
- * connection name provided by the user, e.g. "nl:0", "tcp:1.2.3.4". This
- * name is useful for error messages but must not be modified.
+ * connection name provided by the user, e.g. "tcp:1.2.3.4". This name is
+ * useful for error messages but must not be modified.
*
* 'suffix' is a copy of 'name' following the colon and may be modified.
*
const char *name;
/* Attempts to start listening for OpenFlow connections. 'name' is the
- * full connection name provided by the user, e.g. "nl:0", "tcp:1.2.3.4".
- * This name is useful for error messages but must not be modified.
+ * full connection name provided by the user, e.g. "ptcp:1234". This name
+ * is useful for error messages but must not be modified.
*
* 'suffix' is a copy of 'name' following the colon and may be modified.
*
printf("\n");
if (active) {
printf("Active OpenFlow connection methods:\n");
-#ifdef HAVE_NETLINK
- printf(" nl:DP_IDX "
- "local datapath DP_IDX\n");
-#endif
printf(" tcp:HOST[:PORT] "
"PORT (default: %d) on remote TCP HOST\n", OFP_TCP_PORT);
#ifdef HAVE_OPENSSL
In this ``fail open'' mode, \fBsecchan\fR causes the datapath to act
like an ordinary MAC-learning switch. \fBsecchan\fR 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
+connection succeeds, it discontinues its fail-open behavior.
If this option is set to \fBclosed\fR, then \fBsecchan\fR will not
set up flows on its own when the controller connection fails.
bin_PROGRAMS += vswitchd/vswitchd
-dist_man_MANS += vswitchd/vswitchd.conf.5
-man_MANS += vswitchd/vswitchd.8
-DISTCLEANFILES += vswitchd/vswitchd.8
+man_MANS += vswitchd/vswitchd.conf.5 vswitchd/vswitchd.8
+DISTCLEANFILES += vswitchd/vswitchd.conf.5 vswitchd/vswitchd.8
vswitchd_vswitchd_SOURCES = \
vswitchd/brcompat.c \
$(FAULT_LIBS) \
$(SSL_LIBS)
-EXTRA_DIST += vswitchd/vswitchd.8.in
+EXTRA_DIST += vswitchd/vswitchd.conf.5.in vswitchd/vswitchd.8.in
}
dpif_close(&dpif);
} else if (retval != ENODEV) {
- VLOG_ERR("failed to delete datapath nl:%d: %s",
+ VLOG_ERR("failed to delete datapath dp%d: %s",
i, strerror(retval));
}
}
if (!strcmp(ctl, "discover")) {
ofproto_set_discovery(br->ofproto, true,
- cfg_get_string(0,
- "%s.accept-controller-regex",
- pfx),
+ cfg_get_string(0, "%s.accept-regex", pfx),
cfg_get_bool(0, "%s.update-resolv.conf",
pfx));
} else {
svec_init(&listeners);
cfg_get_all_strings(&listeners, "bridge.%s.openflow.listeners", br->name);
if (!listeners.n) {
- svec_add_nocopy(&listeners, xasprintf("punix:%s/secchan.mgmt-%s",
+ svec_add_nocopy(&listeners, xasprintf("punix:%s/%s.mgmt",
ofp_rundir, br->name));
}
svec_sort_unique(&listeners);
+++ /dev/null
-.\" -*- nroff -*-
-.de TQ
-. br
-. ns
-. TP \$1
-..
-.de ST
-. RS -0.15in
-. I \\$1
-. RE
-..
-.TH vswitchd.conf 5 "February 2009" "OpenFlow" "OpenFlow Manual"
-.
-.SH NAME
-vswitchd.conf \- configuration file for \fBvswitchd\fR
-.
-.SH DESCRIPTION
-This manual page describes the syntax for the configuration file used
-by \fBvswitchd\fR(8), the virtual switch daemon.
-.PP
-The configuration file is based on key-value pairs, which are given
-one per line in the form \fIkey\fB=\fIvalue\fR. Each \fIkey\fR
-consists of one or more parts separated by dots,
-e.g. \fIpart1\fB.\fIpart2\fB.\fIpart3\fR. Each \fIpart\fR may consist
-only of the English letters, digits, and the special characters
-\fB_-@$:+\fR. White space within \fIvalue\fR is significant, the
-presence of white space at the beginning of a line is used for
-determining whether a key-value pair is within a section (see below),
-and other white space is ignored.
-.PP
-Configuration files may optionally be divided into sections. A
-section begins with a section header, which is a line of the form
-\fB[\fIsection\fB]\fR or \fB[\fIsection\fB "\fIsubsection\fB"]\fR.
-The \fIsection\fR and optional \fIsubsection\fR must fit the syntax
-described for \fIkey\fR above, and the \fB[\fR must appear in the
-leftmost column of the line. Following a section header, key-value
-pairs indented with white space are implicitly within the specified
-\fIsection\fR and optional \fIsubsection\fR; that is,
-.RS
-.nf
-[mysec "mysubsec"]
- key = value
-.fi
-.RE
-and
-.RS
-.nf
-mysec.mysubsec.key = value
-.fi
-.RE
-are equivalent. The first key-value pair at the left margin following
-a section header ends the section; outside a section, indented
-key-value pairs will be flagged as an error.
-.PP
-If a single key is specified more than once, that key has multiple
-values, one value for each time the key is specified. The ordering of
-key-value pairs, and the ordering of multiple values for a single key,
-within a configuration file or a set of configuration files is not
-significant.
-.PP
-Blank lines, lines that consist only of white space, and lines that
-begin with \fB#\fR (optionally preceded by white space) are ignored.
-.PP
-The following subsections describe how key-value pairs are used to
-configure \fBvswitchd\fR.
-.SS "Bridge Configuration"
-A bridge (switch) with a given \fIname\fR is configured by specifying
-the names of its network devices as values for key
-\fBbridge.\fIname\fB.port\fR. (The specified \fIname\fR may not begin
-with \fBdp\fR or \fBnl:\fR followed by a digit.)
-.PP
-A bridge with a given \fIname\fR always has an associated network
-device with the same \fIname\fR. This network device may be included
-in the bridge, by specifying it as one of the values for key
-\fBbridge.\fIname\fB.port\fR, or it may be omitted. If it is
-included, then its MAC address is by default the lowest-numbered MAC
-address among the other bridge ports, ignoring bridge ports that are
-used as port mirroring destinations (see "Port mirroring", below). To
-use a specific MAC address instead, set \fBbridge.\fIname\fB.mac\fR to
-a MAC address in the format
-\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR, where each
-\fIx\fR is a hex digit. If no valid MAC address can be determined
-either of these ways, then a MAC address is chosen randomly.
-.PP
-The following syntax defines a bridge named \fBmybr\fR, configured
-with network devices \fBeth0\fR, \fBeth1\fR, and \fBeth2\fR:
-.RS
-.nf
-
-[bridge "mybr"]
- port = eth0
- port = eth1
- port = eth2
-.fi
-.RE
-.SS "802.1Q VLAN support"
-A bridge port may be configured either as a trunk port or as belonging
-to a single, untagged VLAN. These two options are mutually exclusive
-and a port must be configured in one way or the other.
-.PP
-.ST "Trunk Ports"
-.PP
-By default, bridge ports are trunk ports that carry all VLANs. To
-limit the VLANs that a trunk port carries, define
-\fBvlan.\fIport\fB.trunks\fR to one or more integers between 0 and
-4095 designating VLANs. Only frames that have an 802.1Q header with
-one of the listed VLANs are accepted on a trunk port. If 0 is
-included in the list, then frames without an 802.1Q header are also
-accepted. Other frames are discarded.
-.PP
-The following syntax makes network device \fBeth0\fR a trunk port that
-carries VLANs 1, 2, and 3:
-.PP
-.RS
-.nf
-
-[vlan "eth0"]
- trunks = 1
- trunks = 2
- trunks = 3
-
-.fi
-.RE
-.PP
-.ST "Untagged VLAN Ports"
-.PP
-A bridge port may be configured with an implicit, untagged VLAN.
-Define key
-\fBvlan.\fIport\fB.tag\fR to an integer value \fIvid\fR between 0 and
-4095, inclusive, to designate the named \fIport\fR as a member
-of 802.1Q VLAN \fIvid\fR. When \fIport\fR is assigned a VLAN tag this
-way, frames arriving on trunk ports will be forwarded to \fIport\fR
-only if they are tagged with VLAN \fIvid\fR, and frames arriving on
-other VLAN ports will be forwarded to \fIport\fR only if their
-\fIvid\fR values are equal. Frames forwarded to \fIport\fR will not
-have an 802.1Q header.
-.PP
-When \fIvid\fR is 0, frames arriving on trunk ports without an 802.1Q
-VLAN header will also be forwarded to \fIport\fR.
-.PP
-When a frame with a 802.1Q header that indicates a nonzero VLAN is
-received on an implicit VLAN port, it is discarded.
-.PP
-The following syntax makes network device \fBeth0\fR a member of VLAN
-101:
-.PP
-.RS
-.nf
-
-[vlan "eth0"]
- tag = 101
-
-.fi
-.RE
-.SS "Network Device Bonding"
-Bonding allows multiple "slave" network devices to be treated as if
-they were a single virtual "bonded" network device. It is useful for
-load balancing and fail-over.
-.PP
-\fBvswitchd\fR supports "source load balancing" (SLB) bonding, which
-assigns flows to slaves based on source MAC address, with periodic
-rebalancing as traffic patterns change. This form of bonding does not
-require 802.3ad or other special support from the upstream switch to
-which the slave devices are connected.
-.PP
-To configure bonding, create a virtual bonding device by specifying
-the slave network device names as values for
-\fBbonding.\fIname\fB.slave\fR, then specify \fIname\fR as a bridge
-port. The chosen \fIname\fR should not be the name of any real
-network device on the host system.
-.PP
-By default, bonding interfaces are enabled or disabled immediately
-when a carrier is detected or dropped on the underlying network
-device. To insert a delay when carrier comes up or goes down before
-enabling or disabling an interface, set the value of
-\fBbonding.\fIname\fB.updelay\fR or
-\fBbonding.\fIname\fB.downdelay\fR, respectively, to a positive
-integer, interpreted in milliseconds.
-.PP
-The following syntax bonds \fBeth0\fR and \fBeth1\fR into a bonding
-device named \fBbond0\fR, which is added to bridge \fBmybr\fR along
-with physical network devices \fBeth2\fR and \fBeth3\fR:
-.PP
-.RS
-.nf
-
-[bridge "mybr"]
- port = bond0
- port = eth2
- port = eth3
-
-[bonding "bond0"]
- slave = eth0
- slave = eth1
-
-.fi
-.RE
-.SS "Port mirroring"
-\fBvswitchd\fR may be configured to send selected frames to special
-"mirrored" ports, in addition to their normal destinations.
-.PP
-Up to 32 instances of port mirroring may be configured on a given
-bridge. Each must be given a name that is unique within the bridge.
-The keys associated with port mirroring instance \fIpmname\fR for
-bridge \fIbrname\fR begin with \fBmirror.\fIbrname\fB.\fIpmname\fR.
-.PP
-The selection of the frames to mirror and the form in which they
-should be output is configured separately for each port mirroring
-instances, through a subsection of
-\fBmirror.\fIbrname\fB.\fIpmname\fR, named \fBselect\fR, and
-\fBoutput\fR, respectively.
-.PP
-.ST "Selecting Frames to Mirror"
-.PP
-The values for the following keys, if specified, limit the frames that
-are chosen for mirroring. If none of these keys is specified, then
-all frames received by the bridge are mirrored. If more than one of
-these keys is specified, then a frame must meet all specified criteria
-to be mirrored.
-.TP
-\fBmirror.\fIbrname\fB.\fIpmname\fB.select.src-port = \fIport\fR
-.TQ
-\fBmirror.\fIbrname\fB.\fIpmname\fB.select.dst-port = \fIport\fR
-.TQ
-\fBmirror.\fIbrname\fB.\fIpmname\fB.select.port = \fIport\fR
-Frame received on \fIport\fR, output to \fIport\fR, or either received
-on or output to \fIport\fR, respectively. \fIport\fR must be part of
-\fIbridge\fR; that is, it must be listed on
-\fBbridge.\fIbrname\fB.port\fR.
-.TP
-\fBmirror.\fIbrname\fB.\fIpmname\fB.select.vlan = \fIvid\fR
-.
-\fIvid\fR must be an integer between 0 and 4095, inclusive. A nonzero
-\fIvid\fR selects frames that belong to VLAN \fIvid\fR, that is,
-frames that arrived on a trunk port tagged with VLAN \fIvid\fR or on a
-port that is configured as part of VLAN \fIvid\fR (see "802.1Q VLAN
-tagging," above). A \fIvid\fR of zero selects frames that do not
-belong to a VLAN, that is, frames that arrived on a trunk port without
-a VLAN tag or tagged with VLAN 0.
-.PP
-.ST "Mirror Output"
-.PP
-The values of the following keys determine how frames selected for
-mirroring are output. Only one of the keys may be specified.
-.TP
-\fBmirror.\fIbrname\fB.\fIpmname\fB.output.port = \fIport\fR
-.
-Causes the selected frames to be sent out \fIport\fR, which must be
-part of \fIbridge\fR; that is, it must be listed on
-\fBbridge.\fIbrname\fB.port\fR.
-.IP
-Specifying a \fIport\fR in this way reserves that port exclusively for
-mirroring. No frames other than those selected for mirroring will be
-forwarded to \fIport\fR, and any frames received on \fIport\fR will be
-discarded.
-.TP
-\fBmirror.\fIbrname\fB.\fIpmname\fB.output.vlan = \fIvid\fR
-.
-Causes the selected frames to be sent on the VLAN numbered \fIvid\fR,
-which must be an integer between 0 and 4095, inclusive. The frames
-will be sent out all ports that trunk VLAN \fIvid\fR, as well as any
-ports with implicit VLAN \fIvid\fR. When a mirrored frame is sent out
-a trunk port, the frame's VLAN tag will be set to \fIvid\fR, replacing
-any existing tag; when it is sent out an implicit VLAN port, the frame
-will not be tagged.
-.PP
-.ST "Example"
-.PP
-The following \fBvswitchd\fR configuration copies all frames received
-on \fBeth1\fR or \fBeth2\fR to \fBeth3\fR.
-.PP
-.RS
-.nf
-
-[bridge "mybr"]
- port = eth1
- port = eth2
- port = eth3
-
-[mirror "mybr.a"]
- select.src-port = eth1
- select.src-port = eth2
- output.port = eth3
-
-.fi
-.SS "IEEE 802.1D-1998 Spanning Tree Support"
-.PP
-\fBvswitchd\fR supports IEEE 802.1D-1998 Spanning Tree Protocol (STP),
-which detects and prevents loops in switch topology. By default, STP
-is disabled. To turn it on for a given \fIbridge\fR, set
-\fBstp.\fIbridge\fB.enabled\fR to \fBtrue\fR.
-.PP
-By default, \fBvswitchd\fR chooses a random bridge address each time
-STP is enabled for the switch. To use a specific bridge address
-(which is recommended), set \fBstp.\fIbridge\fB.address\fR to a MAC
-address in the format
-\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR, where each
-\fIx\fR is a hex digit. (A common choice of bridge address is the MAC
-address of one of the bridge ports.)
-.PP
-Bridge priority allows a network administrator to influence the
-construction of the spanning tree. The default bridge priority is
-32768. It may be overridden by setting
-\fBstp.\fIbridge\fB.priority\fR to a number between 0 and 65535.
-Lower numbers correspond to higher priorities.
-.PP
-\fBvswitchd\fR does not implement IEEE 802.1D-2004 Rapid Spanning Tree
-Protocol (RSTP).
-.PP
-.ST "STP Port Configuration"
-.PP
-Some STP features may be configured on a port-by-port basis.
-.PP
-To disable STP on an individual \fIport\fR within \fIbridge\fR, set
-\fBstp.\fIbridge\fB.port.\fIport\fB.enabled\fR to \fBfalse\fR. STP is
-never enabled on a port that is used as an output port for port
-mirroring.
-.PP
-The "path cost" of a port reflects how expensive it is (generally, in
-time) to send data out a particular port. \fBvswitchd\fR uses a cost
-of 19, which is generally appropriate for 100 MB ports, as the default
-path cost for STP ports. Set
-\fBstp.\fIbridge\fB.port.\fIport\fB.path-cost\fR to a number between 1
-and 65535 to override this default. (Future versions of
-\fBvswitchd\fR will choose a default path cost based on the port's
-current data rate.)
-.PP
-Port priority allows a network administrator to influence the
-construction of the spanning tree. The default port priority is 128.
-It may be overridden by setting
-\fBstp.\fIbridge\fB.port.\fIport\fB.priority\fR to a number between 0 and
-255. Lower numbers correspond to higher priorities.
-.PP
-.ST "Example"
-.PP
-The following syntax enables STP on bridge \fBmybr\fR that consists of
-network devices \fBeth0\fR, \fBeth1\fR, and \fBeth2\fR. The bridge
-address is set to 00:02:e3:0f:80:a4 and \fBeth2\fR's port priority is
-set to 64:
-.PP
-.RS
-.nf
-
-[bridge "mybr"]
- port = eth0
- port = eth1
- port = eth2
-
-[stp "mybr"]
- enabled = true
- address = 00:02:e3:0f:80:a4
- port.eth2.priority = 64
-.fi
-.RE
-.SS "NetFlow v5 Flow Logging"
-NetFlow provides a number of details about terminating flows, such as the
-principals involved and duration. A bridge may be configured to send
-NetFlow v5 records to up to eight collectors when flows end. To enable,
-define the key \fBnetflow.\fIbridge\fB.host\fR for each NetFlow collector
-in the form \fIhost\fB:\fIport\fR. Records from \fIbridge\fR will be sent
-to each \fIhost\fR on UDP \fIport\fR.
-.PP
-The following syntax sends NetFlow records for \fBmybr\fR to the NetFlow
-collector \fBnflow.example.com\fR on UDP port \fB9995\fR:
-.PP
-.RS
-.nf
-
-[netflow "mybr"]
- host = nflow.example.com:9995
-
-.fi
-.RE
-.SS "Remote Management"
-A \fBvswitchd\fR instance may be remotely managed by a controller that
-supports the OpenFlow Management Protocol, such as NOX. This
-functionality is enabled by setting \fBmgmt.controller\fR to one of the
-following forms:
-.
-.TP
-\fBssl:\fIhost\fR[\fB:\fIport\fR]
-The specified SSL \fIport\fR (default: 6633) on the given remote
-\fIhost\fR. The \fBssl.private-key\fR, \fBssl.certificate\fR,
-and \fBssl.ca-cert\fR keys must be set appropriately. If the
-\fBssl.bootstrap-ca-cert\fR key is set to "true", then
-\fBvswitchd\fR will attempt to obtain the CA certificate from the
-controller.
-.
-.TP
-\fBtcp:\fIhost\fR[\fB:\fIport\fR]
-The specified TCP \fIport\fR (default: 6633) on the given remote
-\fIhost\fR.
-.PP
-The maximum time between attempts to connect to the controller may be
-specified in integral seconds with the \fBmgmt.max-backoff\fR key. The
-default maximum backoff is 15 seconds, and the minimum value is 1
-second.
-
-An inactivity probe may be configured with the \fBmgmt.inactivity-probe\fR
-key. If \fBvswitchd\fR does not communicate with the controller for the
-specified number of seconds, it will send a probe. If a response is not
-received for an additional amount of that time, \fBvswitchd\fR assumes
-the connection has been broken and attempts to reconnect. The default
-is 15 seconds, and the minimum value is 5 seconds.
-
-A management id may be specified with the \fBmgmt.id\fR key. It takes
-an id in the form of exactly 12 hexadecimal digits. If one is not
-specified, a random id is generated each time \fBvswitchd\fR is started.
-.fi
-.RE
-.SS "OpenFlow controller connectivity"
-If a remote manager is not configured, \fBvswitchd\fR will perform
-all configured bridging and switching locally. It can be configured
-to connect a given bridge to an external OpenFlow controller, such as
-NOX, by setting \fBbridge.\fIname\fB.controller\fR to one of the
-following forms:
-.
-.TP
-\fBdiscover\fR
-Use controller discovery to find the local OpenFlow controller.
-Refer to \fBsecchan\fR(8) for information on how to configure a DHCP
-server to support controller discovery.
-.
-.TP
-\fBssl:\fIhost\fR[\fB:\fIport\fR]
-The specified SSL \fIport\fR (default: 6633) on the given remote
-\fIhost\fR. The \fB--private-key\fR, \fB--certificate\fR, and
-\fB--ca-cert\fR options are mandatory when this form is used.
-.
-.TP
-\fBtcp:\fIhost\fR[\fB:\fIport\fR]
-The specified TCP \fIport\fR (default: 6633) on the given remote
-\fIhost\fR.
-.
-.TP
-\fBunix:\fIfile\fR
-The Unix domain server socket named \fIfile\fR.
-.PP
-If the \fBbridge.\fIname\fB.controller\fR key is set without a value,
-the bridge \fIname\fR will ignore a controller setting specified by
-\fBmgmt.controller\fR. Instead, it will perform all configured bridging
-and switching locally.
-.PP
-When an external controller is configured,
-\fBbridge.\fIname\fB.secchan.options\fR may be used to pass arbitrary
-additional options to \fBsecchan\fR. Each value for this option is
-broken into words at white space, which are then passed as individual
-arguments on \fBsecchan\fR's command line. Single or double quotes
-may be used to prevent word-splitting; outside of single quotes, a
-backslash quotes the following single character.
-.PP
-If an external controller is configured, and in-band control is used,
-but not controller discovery (see \fBsecchan\fR(8) for more
-information on this terminology), the local bridge port must
-configured with an IP address by some entity outside \fBvswitch\fR,
-which will not itself configure an IP address on it.
-
-.SH "SEE ALSO"
-.BR vswitchd (8).
--- /dev/null
+.\" -*- nroff -*-
+.de TQ
+. br
+. ns
+. TP \$1
+..
+.de ST
+. PP
+. RS -0.15in
+. I \\$1
+. RE
+. PP
+..
+.TH vswitchd.conf 5 "March 2009" "OpenFlow" "OpenFlow Manual"
+.
+.SH NAME
+vswitchd.conf \- configuration file for \fBvswitchd\fR
+.
+.SH DESCRIPTION
+This manual page describes the syntax for the configuration file used
+by \fBvswitchd\fR(8), the virtual switch daemon.
+.PP
+The configuration file is based on key-value pairs, which are given
+one per line in the form \fIkey\fB=\fIvalue\fR. Each \fIkey\fR
+consists of one or more parts separated by dots,
+e.g. \fIpart1\fB.\fIpart2\fB.\fIpart3\fR. Each \fIpart\fR may consist
+only of the English letters, digits, and the special characters
+\fB_-@$:+\fR. White space within \fIvalue\fR is significant, the
+presence of white space at the beginning of a line is used for
+determining whether a key-value pair is within a section (see below),
+and other white space is ignored.
+.PP
+Configuration files may optionally be divided into sections. A
+section begins with a section header, which is a line of the form
+\fB[\fIsection\fB]\fR or \fB[\fIsection\fB "\fIsubsection\fB"]\fR.
+The \fIsection\fR and optional \fIsubsection\fR must fit the syntax
+described for \fIkey\fR above, and the \fB[\fR must appear in the
+leftmost column of the line. Following a section header, key-value
+pairs indented with white space are implicitly within the specified
+\fIsection\fR and optional \fIsubsection\fR; that is,
+.RS
+.nf
+[mysec "mysubsec"]
+ key = value
+.fi
+.RE
+and
+.RS
+.nf
+mysec.mysubsec.key = value
+.fi
+.RE
+are equivalent. The first key-value pair at the left margin following
+a section header ends the section; outside a section, indented
+key-value pairs will be flagged as an error.
+.PP
+If a single key is specified more than once, that key has multiple
+values, one value for each time the key is specified. The ordering of
+key-value pairs, and the ordering of multiple values for a single key,
+within a configuration file is not significant.
+.PP
+Blank lines, lines that consist only of white space, and lines that
+begin with \fB#\fR (optionally preceded by white space) are ignored.
+.PP
+The following subsections describe how key-value pairs are used to
+configure \fBvswitchd\fR.
+.SS "Bridge Configuration"
+A bridge (switch) with a given \fIname\fR is configured by specifying
+the names of its network devices as values for key
+\fBbridge.\fIname\fB.port\fR. (The specified \fIname\fR may not begin
+with \fBdp\fR or \fBnl:\fR followed by a digit.)
+.PP
+A bridge with a given \fIname\fR always has an associated network
+device with the same \fIname\fR. This network device may be included
+in the bridge, by specifying it as one of the values for key
+\fBbridge.\fIname\fB.port\fR, or it may be omitted. If it is
+included, then its MAC address is by default the lowest-numbered MAC
+address among the other bridge ports, ignoring bridge ports that are
+used as port mirroring destinations (see \fBPort Mirroring\fR, below). To
+use a specific MAC address instead, set \fBbridge.\fIname\fB.mac\fR to
+a MAC address in the format
+\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR, where each
+\fIx\fR is a hex digit. If no valid MAC address can be determined
+either of these ways, then a MAC address is chosen randomly.
+.PP
+The following syntax defines a bridge named \fBmybr\fR, configured
+with network devices \fBeth0\fR, \fBeth1\fR, and \fBeth2\fR:
+.RS
+.nf
+
+[bridge "mybr"]
+ port = eth0
+ port = eth1
+ port = eth2
+.fi
+.RE
+.SS "802.1Q VLAN support"
+A bridge port may be configured either as a trunk port or as belonging
+to a single, untagged VLAN. These two options are mutually exclusive
+and a port must be configured in one way or the other.
+.ST "Trunk Ports"
+By default, bridge ports are trunk ports that carry all VLANs. To
+limit the VLANs that a trunk port carries, define
+\fBvlan.\fIport\fB.trunks\fR to one or more integers between 0 and
+4095 designating VLANs. Only frames that have an 802.1Q header with
+one of the listed VLANs are accepted on a trunk port. If 0 is
+included in the list, then frames without an 802.1Q header are also
+accepted. Other frames are discarded.
+.PP
+The following syntax makes network device \fBeth0\fR a trunk port that
+carries VLANs 1, 2, and 3:
+.PP
+.RS
+.nf
+
+[vlan "eth0"]
+ trunks = 1
+ trunks = 2
+ trunks = 3
+
+.fi
+.RE
+.ST "Untagged VLAN Ports"
+A bridge port may be configured with an implicit, untagged VLAN.
+Define key
+\fBvlan.\fIport\fB.tag\fR to an integer value \fIvid\fR between 0 and
+4095, inclusive, to designate the named \fIport\fR as a member
+of 802.1Q VLAN \fIvid\fR. When \fIport\fR is assigned a VLAN tag this
+way, frames arriving on trunk ports will be forwarded to \fIport\fR
+only if they are tagged with VLAN \fIvid\fR, and frames arriving on
+other VLAN ports will be forwarded to \fIport\fR only if their
+\fIvid\fR values are equal. Frames forwarded to \fIport\fR will not
+have an 802.1Q header.
+.PP
+When \fIvid\fR is 0, frames arriving on trunk ports without an 802.1Q
+VLAN header will also be forwarded to \fIport\fR.
+.PP
+When a frame with a 802.1Q header that indicates a nonzero VLAN is
+received on an implicit VLAN port, it is discarded.
+.PP
+The following syntax makes network device \fBeth0\fR a member of VLAN
+101:
+.PP
+.RS
+.nf
+
+[vlan "eth0"]
+ tag = 101
+
+.fi
+.RE
+.SS "Network Device Bonding"
+Bonding allows multiple ``slave'' network devices to be treated as if
+they were a single virtual ``bonded'' network device. It is useful for
+load balancing and fail-over.
+.PP
+\fBvswitchd\fR supports ``source load balancing'' (SLB) bonding, which
+assigns flows to slaves based on source MAC address, with periodic
+rebalancing as traffic patterns change. This form of bonding does not
+require 802.3ad or other special support from the upstream switch to
+which the slave devices are connected.
+.PP
+To configure bonding, create a virtual bonding device by specifying
+the slave network device names as values for
+\fBbonding.\fIname\fB.slave\fR, then specify \fIname\fR as a bridge
+port. The chosen \fIname\fR should not be the name of any real
+network device on the host system.
+.PP
+By default, bonding interfaces are enabled or disabled immediately
+when a carrier is detected or dropped on the underlying network
+device. To insert a delay when carrier comes up or goes down before
+enabling or disabling an interface, set the value of
+\fBbonding.\fIname\fB.updelay\fR or
+\fBbonding.\fIname\fB.downdelay\fR, respectively, to a positive
+integer, interpreted in milliseconds.
+.PP
+The following syntax bonds \fBeth0\fR and \fBeth1\fR into a bonding
+device named \fBbond0\fR, which is added to bridge \fBmybr\fR along
+with physical network devices \fBeth2\fR and \fBeth3\fR:
+.PP
+.RS
+.nf
+
+[bridge "mybr"]
+ port = bond0
+ port = eth2
+ port = eth3
+
+[bonding "bond0"]
+ slave = eth0
+ slave = eth1
+
+.fi
+.RE
+.SS "Port Mirroring"
+\fBvswitchd\fR may be configured to send selected frames to special
+``mirrored'' ports, in addition to their normal destinations.
+.PP
+Up to 32 instances of port mirroring may be configured on a given
+bridge. Each must be given a name that is unique within the bridge.
+The keys associated with port mirroring instance \fIpmname\fR for
+bridge \fIbrname\fR begin with \fBmirror.\fIbrname\fB.\fIpmname\fR.
+.PP
+The selection of the frames to mirror and the form in which they
+should be output is configured separately for each port mirroring
+instances, through a subsection of
+\fBmirror.\fIbrname\fB.\fIpmname\fR, named \fBselect\fR, and
+\fBoutput\fR, respectively.
+.ST "Selecting Frames to Mirror"
+The values for the following keys, if specified, limit the frames that
+are chosen for mirroring. If none of these keys is specified, then
+all frames received by the bridge are mirrored. If more than one of
+these keys is specified, then a frame must meet all specified criteria
+to be mirrored.
+.TP
+\fBmirror.\fIbrname\fB.\fIpmname\fB.select.src-port = \fIport\fR
+.TQ
+\fBmirror.\fIbrname\fB.\fIpmname\fB.select.dst-port = \fIport\fR
+.TQ
+\fBmirror.\fIbrname\fB.\fIpmname\fB.select.port = \fIport\fR
+Frame received on \fIport\fR, output to \fIport\fR, or either received
+on or output to \fIport\fR, respectively. \fIport\fR must be part of
+\fIbridge\fR; that is, it must be listed on
+\fBbridge.\fIbrname\fB.port\fR.
+.TP
+\fBmirror.\fIbrname\fB.\fIpmname\fB.select.vlan = \fIvid\fR
+.
+\fIvid\fR must be an integer between 0 and 4095, inclusive. A nonzero
+\fIvid\fR selects frames that belong to VLAN \fIvid\fR, that is,
+frames that arrived on a trunk port tagged with VLAN \fIvid\fR or on a
+port that is configured as part of VLAN \fIvid\fR (see \fB802.1Q VLAN
+tagging\fR, above). A \fIvid\fR of zero selects frames that do not
+belong to a VLAN, that is, frames that arrived on a trunk port without
+a VLAN tag or tagged with VLAN 0.
+.ST "Mirror Output"
+The values of the following keys determine how frames selected for
+mirroring are output. Only one of the keys may be specified.
+.TP
+\fBmirror.\fIbrname\fB.\fIpmname\fB.output.port = \fIport\fR
+.
+Causes the selected frames to be sent out \fIport\fR, which must be
+part of \fIbridge\fR; that is, it must be listed on
+\fBbridge.\fIbrname\fB.port\fR.
+.IP
+Specifying a \fIport\fR in this way reserves that port exclusively for
+mirroring. No frames other than those selected for mirroring will be
+forwarded to \fIport\fR, and any frames received on \fIport\fR will be
+discarded.
+.TP
+\fBmirror.\fIbrname\fB.\fIpmname\fB.output.vlan = \fIvid\fR
+.
+Causes the selected frames to be sent on the VLAN numbered \fIvid\fR,
+which must be an integer between 0 and 4095, inclusive. The frames
+will be sent out all ports that trunk VLAN \fIvid\fR, as well as any
+ports with implicit VLAN \fIvid\fR. When a mirrored frame is sent out
+a trunk port, the frame's VLAN tag will be set to \fIvid\fR, replacing
+any existing tag; when it is sent out an implicit VLAN port, the frame
+will not be tagged.
+.ST "Example"
+The following \fBvswitchd\fR configuration copies all frames received
+on \fBeth1\fR or \fBeth2\fR to \fBeth3\fR.
+.PP
+.RS
+.nf
+
+[bridge "mybr"]
+ port = eth1
+ port = eth2
+ port = eth3
+
+[mirror "mybr.a"]
+ select.src-port = eth1
+ select.src-port = eth2
+ output.port = eth3
+
+.fi
+.SS "IEEE 802.1D-1998 Spanning Tree Support"
+.PP
+\fBvswitchd\fR supports IEEE 802.1D-1998 Spanning Tree Protocol (STP),
+which detects and prevents loops in switch topology. By default, STP
+is disabled. To turn it on for a given \fIbridge\fR, set
+\fBstp.\fIbridge\fB.enabled\fR to \fBtrue\fR.
+.PP
+By default, \fBvswitchd\fR chooses a random bridge address each time
+STP is enabled for the switch. To use a specific bridge address
+(which is recommended), set \fBstp.\fIbridge\fB.address\fR to a MAC
+address in the format
+\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR, where each
+\fIx\fR is a hex digit. (A common choice of bridge address is the MAC
+address of one of the bridge ports.)
+.PP
+Bridge priority allows a network administrator to influence the
+construction of the spanning tree. The default bridge priority is
+32768. It may be overridden by setting
+\fBstp.\fIbridge\fB.priority\fR to a number between 0 and 65535.
+Lower numbers correspond to higher priorities.
+.PP
+\fBvswitchd\fR does not implement IEEE 802.1D-2004 Rapid Spanning Tree
+Protocol (RSTP).
+.ST "STP Port Configuration"
+Some STP features may be configured on a port-by-port basis.
+.PP
+To disable STP on an individual \fIport\fR within \fIbridge\fR, set
+\fBstp.\fIbridge\fB.port.\fIport\fB.enabled\fR to \fBfalse\fR. STP is
+never enabled on a port that is used as an output port for port
+mirroring.
+.PP
+The ``path cost'' of a port reflects how expensive it is (generally, in
+time) to send data out a particular port. \fBvswitchd\fR uses a cost
+of 19, which is generally appropriate for 100 MB ports, as the default
+path cost for STP ports. Set
+\fBstp.\fIbridge\fB.port.\fIport\fB.path-cost\fR to a number between 1
+and 65535 to override this default. (Future versions of
+\fBvswitchd\fR will choose a default path cost based on the port's
+current data rate.)
+.PP
+Port priority allows a network administrator to influence the
+construction of the spanning tree. The default port priority is 128.
+It may be overridden by setting
+\fBstp.\fIbridge\fB.port.\fIport\fB.priority\fR to a number between 0 and
+255. Lower numbers correspond to higher priorities.
+.ST "Example"
+The following syntax enables STP on bridge \fBmybr\fR that consists of
+network devices \fBeth0\fR, \fBeth1\fR, and \fBeth2\fR. The bridge
+address is set to 00:02:e3:0f:80:a4 and \fBeth2\fR's port priority is
+set to 64:
+.PP
+.RS
+.nf
+
+[bridge "mybr"]
+ port = eth0
+ port = eth1
+ port = eth2
+
+[stp "mybr"]
+ enabled = true
+ address = 00:02:e3:0f:80:a4
+ port.eth2.priority = 64
+.fi
+.RE
+.SS "NetFlow v5 Flow Logging"
+NetFlow provides a number of details about terminating flows, such as the
+principals involved and duration. A bridge may be configured to send
+NetFlow v5 records to up to eight collectors when flows end. To enable,
+define the key \fBnetflow.\fIbridge\fB.host\fR for each NetFlow collector
+in the form \fIhost\fB:\fIport\fR. Records from \fIbridge\fR will be sent
+to each \fIhost\fR on UDP \fIport\fR.
+.PP
+The following syntax sends NetFlow records for \fBmybr\fR to the NetFlow
+collector \fBnflow.example.com\fR on UDP port \fB9995\fR:
+.PP
+.RS
+.nf
+
+[netflow "mybr"]
+ host = nflow.example.com:9995
+
+.fi
+.RE
+.SS "Remote Management"
+A \fBvswitchd\fR instance may be remotely managed by a controller that
+supports the OpenFlow Management Protocol, such as NOX. This
+functionality is enabled by setting \fBmgmt.controller\fR to one of the
+following forms:
+.
+.TP
+\fBssl:\fIhost\fR[\fB:\fIport\fR]
+The specified SSL \fIport\fR (default: 6633) on the given remote
+\fIhost\fR. SSL must be configured when this form is used (see \fBSSL
+Configuration\fR, below).
+.
+.TP
+\fBtcp:\fIhost\fR[\fB:\fIport\fR]
+The specified TCP \fIport\fR (default: 6633) on the given remote
+\fIhost\fR.
+.PP
+The maximum time between attempts to connect to the controller may be
+specified in integral seconds with the \fBmgmt.max-backoff\fR key. The
+default maximum backoff is 15 seconds, and the minimum value is 1
+second.
+
+An inactivity probe may be configured with the \fBmgmt.inactivity-probe\fR
+key. If \fBvswitchd\fR does not communicate with the controller for the
+specified number of seconds, it will send a probe. If a response is not
+received for an additional amount of that time, \fBvswitchd\fR assumes
+the connection has been broken and attempts to reconnect. The default
+is 15 seconds, and the minimum value is 5 seconds.
+
+A management id may be specified with the \fBmgmt.id\fR key. It takes
+an id in the form of exactly 12 hexadecimal digits. If one is not
+specified, a random id is generated each time \fBvswitchd\fR is started.
+.fi
+.RE
+.SS "OpenFlow Controller Connectivity"
+\fBvswitchd\fR can perform all configured bridging and switching
+locally, or it can be configured to connect a given bridge to an
+external OpenFlow controller, such as NOX. Its behavior depends on
+the \fBbridge.\fIname\fB.controller\fR setting:
+.
+.TP
+\fI\[la]unset\[ra]\fR
+When this setting is not set at all, even to an empty string, the
+behavior depends on whether remote management is configured. If
+management is configured, then the switch will connect to the
+controller specified on \fBmgmt.controller\fR. If management is not
+configured, the switch will perform all configured bridging and
+switching locally.
+.
+.TP
+\fI\[la]empty\[ra]\fR
+Setting an empty string value disables controller connectivity. The
+switch will perform all configured bridging and switching locally.
+.
+.TP
+\fBdiscover\fR
+Use controller discovery to find the local OpenFlow controller.
+Refer to \fBsecchan\fR(8) for information on how to configure a DHCP
+server to support controller discovery. The following additional
+options control the discovery process:
+.
+.RS
+.TP
+\fBbridge.\fIname\fB.controller.accept-regex = \fIregex\fR
+A POSIX extended regular expression against which the discovered
+controller location is validated. Only controllers whose names match
+the regular expression will be accepted.
+.IP
+The default regular expression is \fBssl:.*\fR, meaning that only SSL
+controller connections will be accepted, when SSL is configured (see
+\fBSSL Configuration\fR), and \fB.*\fR otherwise, meaning that any
+controller will be accepted.
+.IP
+The regular expression is implicitly anchored at the beginning of the
+controller location string, as if it begins with \fB^\fR.
+.TP
+\fBbridge.\fIname\fB.controller.update-resolv.conf = \fBtrue\fR|\fBfalse\fR
+By default, or if this is set to \fBtrue\fR, \fBvswitchd\fR overwrites
+the system's \fB/etc/resolv.conf\fR with domain information and DNS
+servers obtained via DHCP. If this setting is \fBfalse\fR,
+\fBvswitchd\fR will not modify \fB/etc/resolv.conf\fR.
+.IP
+\fBvswitchd\fR will only modify \fBresolv.conf\fR if the DHCP response
+that it receives specifies one or more DNS servers.
+.RE
+.
+.TP
+\fBssl:\fIhost\fR[\fB:\fIport\fR]
+The specified SSL \fIport\fR (default: 6633) on the given remote
+\fIhost\fR. SSL must be configured when this form is used (see \fBSSL
+Configuration\fR, below).
+.
+.TP
+\fBtcp:\fIhost\fR[\fB:\fIport\fR]
+The specified TCP \fIport\fR (default: 6633) on the given remote
+\fIhost\fR.
+.
+.TP
+\fBunix:\fIfile\fR
+The Unix domain server socket named \fIfile\fR.
+.PP
+The datapath ID used by the bridge to identify itself to the remote
+controller may be specified as \fBbridge.\fIname\fB.datapath-id\fR,
+which the form of exactly 12 hexadecimal digits. If the datapath ID
+is not specified, then it defaults to the bridge's MAC address (see
+\fBBridge Configuration\fR, above, for information on how the bridge's
+MAC address is chosen).
+.ST "Local Port Network Configuration"
+When an external controller is configured, but controller discovery is
+not in use, the following additional settings are honored:
+.TP
+\fBbridge.\fIname\fB.controller.in-band = \fBtrue\fR|\fBfalse\fR
+By default, or if this is set to \fBtrue\fR, \fBvswitchd\fR connects
+to the controller in-band. If this is set to \fBfalse\fR,
+\fBvswitchd\fR connects to the controller out-of-band. Refer to
+\fBsecchan\fR(8) for a description of in-band and out-of-band control.
+.IP "\fBbridge.\fIname\fB.controller.ip = \fIip\fR"
+If specified, the IP address to configure on the bridge's local port.
+.IP "\fBbridge.\fIname\fB.controller.netmask = \fInetmask\fR"
+When an IP is specified, the corresponding netmask. The default is
+255.255.255.0 for a Class C IP address, 255.255.0.0 for Class B, and
+255.0.0.0 for Class A.
+.IP "\fBbridge.\fIname\fB.controller.gateway = \fIip\fR"
+When an IP is specified, the corresponding IP gateway. There is no
+default gateway.
+.ST "Controller Failure Settings"
+The following additional settings take effect when any remote
+controller is configured:
+.IP "\fBbridge.\fIname\fB.controller.inactivity-probe = \fIsecs\fR"
+This optional setting may be set to \fIsecs\fR, a number of seconds.
+The minimum value of \fIsecs\fR is 5 seconds. The default is taken
+from \fBmgmt.inactivity-probe\fR (see above).
+.IP
+When the virtual switch is connected to the controller, it waits for a
+message to be received from the controller for \fIsecs\fR seconds
+before it sends a inactivity probe to the controller. After sending
+the inactivity probe, if no response is received for an additional
+\fIsecs\fR seconds, the secure channel assumes that the connection has
+been broken and attempts to reconnect.
+.IP
+Changing the inactivity probe interval also changes the interval
+before entering standalone mode (see below).
+.IP "\fBbridge.\fIname\fB.controller.fail-mode = \fBstandalone\fR|\fBsecure\fR"
+When a controller is configured, it is, ordinarily, responsible for
+setting up all flows on virtual 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.
+.IP
+If this option is unset, or if it is set to \fBstandalone\fR (the
+default), \fBvswitchd\fR will take over responsibility for setting up
+flows when no message has been received from the controller for three
+times the inactivity probe interval (see above). In this mode,
+\fBvswitchd\fR causes the datapath to act like an ordinary
+MAC-learning switch. \fBvswitchd\fR will continue to retry connection
+to the controller in the background and, when the connection succeeds,
+it discontinues its standalone behavior.
+.IP
+If this option is set to \fBsecure\fR, \fBvswitchd\fR will not set up
+flows on its own when the controller connection fails.
+.IP "\fBbridge.\fIname\fB.controller.max-backoff = \fIsecs\fR"
+Sets the maximum time between attempts to connect to the controller to
+\fIsecs\fR, 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 taken from \fBmgmt.max-backoff\fR.
+.ST "Remote Command Execution Settings"
+These settings configure the commands that remote OpenFlow connections
+are allowed to invoke using (e.g.) \fBdpctl execute\fR. To be
+permitted, a command name must be whitelisted and must not be
+blacklisted. When the whitelist and blacklist permit a command name,
+\fBvswitchd\fR looks for a program with the same name as the command
+in the commands directory (see below). Other directories are not
+searched.
+.IP "\fBbridge.\fIname\fB.controller.commands.acl = \fIglob\fR"
+Whitelists commands whose names match shell glob pattern \fIglob\fR,
+allowing those commands to be invoked by the remote controller.
+.IP
+By default, no commands are whitelisted, so this setting is mandatory
+if any remote command execution is to be allowed.
+.IP "\fBbridge.\fIname\fB.controller.commands.acl = \fB!\fR\fIglob\fR"
+Blacklists commands whose names match shell glob pattern \fIglob\fR,
+prohibiting those commands from being invoked by the remote
+controller. Command names that include characters other than upper-
+and lower-case English letters, digits, and the underscore and hyphen
+characters are blacklisted unconditionally.
+.IP "\fBbridge.\fIname\fB.controller.commands.dir = \fIglob\fR"
+Sets the directory searched for remote command execution to
+\fBdirectory\fR. The default directory is
+\fB@pkgdatadir@/commands\fR.
+.SS "SSL Configuration"
+When \fBswitchd\fR is configured to connect over SSL for management or
+for controller connectivity, the following settings are required:
+.TP
+\fBssl.private-key = \fIprivkey.pem\fR
+Specifies a PEM file containing the private key used as the virtual
+switch's identity for SSL connections to the controller.
+.TP
+\fBssl.certificate = \fIcert.pem\fR
+Specifies a PEM file containing a certificate, signed by the
+certificate authority (CA) used by the controller and manager, that
+certifies the virtual switch's private key, identifying a trustworthy
+switch.
+.TP
+\fBssl.ca-cert = \fIcacert.pem\fR
+Specifies a PEM file containing the CA certificate used to verify that
+the virtual switch is connected to a trustworthy controller.
+.PP
+These files are read only once, at \fBvswitchd\fR startup time. If
+their contents change, \fBvswitchd\fR must be killed and restarted.
+.PP
+These SSL settings apply to all SSL connections made by the virtual
+switch.
+.ST "CA Certificate Bootstrap"
+Ordinarily, all of the files named in the SSL configuration must exist
+when \fBvswitchd\fR starts. However, if \fBssl.bootstrap-ca-cert\fR
+is set to \fBtrue\fR, then \fBvswitchd\fR 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.
+.PP
+\fBThis option exposes the SSL connection to a man-in-the-middle
+attack obtaining the initial CA certificate\fR, but it may be useful
+for bootstrapping.
+.PP
+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
+\fBcontroller\fR(8) can be configured to do so with the
+\fB--peer-ca-cert\fR option.
+.SS "OpenFlow Management Connections"
+By default, each bridge \fIname\fR listens for OpenFlow management
+connections on a Unix domain socket named
+\fB@RUNDIR@/\fIname\fB.mgmt\fR. This socket can be used to perform
+local OpenFlow monitoring and administration, e.g. \fBdpctl dump-flows
+unix:@RUNDIR@/\fIname\fB.mgmt\fR to display the flows currently set up
+in bridge \fIname\fR.
+.PP
+If \fBbridge.\fIname\fB.openflow.listeners\fR is set to one or more
+values, \fBvswitchd\fR instead listens on the specified connection
+methods. Acceptable connection methods include:
+.RS
+.IP "\fBpunix:\fIfile\fR"
+Listens for connections on Unix domain server socket named \fIfile\fR.
+.IP "\fBpssl:\fR[\fIport\fR]"
+Listens for SSL connections on \fIport\fR (default: 6633). SSL must
+be configured when this form is used (see \fBSSL Configuration\fR,
+above).
+.IP "\fBptcp:\fR[\fIport\fR]"
+Listens for TCP connections on \fIport\fR (default: 6633).
+.RE
+.SH "SEE ALSO"
+.BR vswitchd (8).
projects / openvswitch / commitdiff