. RE
. PP
..
-.TH vswitchd.conf 5 "March 2009" "OpenFlow" "OpenFlow Manual"
+.TH vswitchd.conf 5 "April 2009" "OpenFlow" "OpenFlow Manual"
.
.SH NAME
vswitchd.conf \- configuration file for \fBvswitchd\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.
+\fB_-@$:+\fR. White space within \fIvalue\fR and at the beginning of a
+line is significant, but is otherwise ignored.
.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
.PP
Blank lines, lines that consist only of white space, and lines that
begin with \fB#\fR (optionally preceded by white space) are ignored.
+Keep in mind that programs that modify the configuration file, such as
+\fBbrcompatd\fR and \fBcfg-mod\fR, may alter the order of elements and
+strip comments and blank lines.
.PP
The following subsections describe how key-value pairs are used to
configure \fBvswitchd\fR.
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.
+either of these ways, then a MAC address is randomly generated.
.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
+bridge.mybr.port=eth0
+bridge.mybr.port=eth1
+bridge.mybr.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
+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
.RS
.nf
-[vlan "eth0"]
- trunks = 1
- trunks = 2
- trunks = 3
+vlan.eth0.trunks=1
+vlan.eth0.trunks=2
+vlan.eth0.trunks=3
.fi
.RE
.RS
.nf
-[vlan "eth0"]
- tag = 101
+vlan.eth0.tag=101
.fi
.RE
.RS
.nf
-[bridge "mybr"]
- port = bond0
- port = eth2
- port = eth3
+bridge.mybr.port=bond0
+bridge.mybr.port=eth2
+bridge.mybr.port=eth3
-[bonding "bond0"]
- slave = eth0
- slave = eth1
+bonding.bond0.slave=eth0
+bonding.bond0.slave=eth1
.fi
.RE
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
+\fBmirror.\fIbrname\fB.\fIpmname\fB.select.src-port=\fIport\fR
.TQ
-\fBmirror.\fIbrname\fB.\fIpmname\fB.select.dst-port = \fIport\fR
+\fBmirror.\fIbrname\fB.\fIpmname\fB.select.dst-port=\fIport\fR
.TQ
-\fBmirror.\fIbrname\fB.\fIpmname\fB.select.port = \fIport\fR
+\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
+the bridge \fIbrname\fR; that is, it must be listed on
\fBbridge.\fIbrname\fB.port\fR.
.TP
-\fBmirror.\fIbrname\fB.\fIpmname\fB.select.vlan = \fIvid\fR
+\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,
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
+\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
+part of the bridge \fIbrname\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. This type of mirroring may also be referred to as SPAN.
+discarded. This type of mirroring may be referred to as SPAN.
.TP
-\fBmirror.\fIbrname\fB.\fIpmname\fB.output.vlan = \fIvid\fR
+\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
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. This type of mirroring may also be referred to as
+will not be tagged. This type of mirroring may be referred to as
RSPAN.
.ST "Example"
The following \fBvswitchd\fR configuration copies all frames received
.RS
.nf
-[bridge "mybr"]
- port = eth1
- port = eth2
- port = eth3
+bridge.mybr.port=eth1
+bridge.mybr.port=eth2
+bridge.mybr.port=eth3
-[mirror "mybr.a"]
- select.src-port = eth1
- select.src-port = eth2
- output.port = eth3
+mirror.mybr.a.select.src-port=eth1
+mirror.mybr.a.select.src-port=eth2
+mirror.mybr.a.output.port=eth3
.fi
.RE
If ingress policing is enabled, then the burst rate may be set by defining
the key \fBport.\fIname\fB.ingress.policing-burst\fR with an integer
-indicating the burst rate in kilobits. If a key is not supplied or is
+indicating the burst rate in kilobits. If the key is not supplied or is
zero, then the default burst is 10 kilobits.
.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.
+\fBstp.\fIbridge\fB.priority\fR to a number between 0 and 65535,
+inclusive. Lower numbers correspond to higher priorities.
.PP
\fBvswitchd\fR does not implement IEEE 802.1D-2004 Rapid Spanning Tree
Protocol (RSTP).
.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
+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
+and 65535, inclusive, to override this default. (Future versions of
\fBvswitchd\fR will choose a default path cost based on the port's
current data rate.)
.PP
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.
+255, inclusive. 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
.RS
.nf
-[bridge "mybr"]
- port = eth0
- port = eth1
- port = eth2
+bridge.mybr.port=eth0
+bridge.mybr.port=eth1
+bridge.mybr.port=eth2
+
+stp.mybr.enabled=true
+stp.mybr.address=00:02:e3:0f:80:a4
+stp.mybr.port.eth2.priority=64
-[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 NetFlow collectors when flows end. To enable,
-define the key \fBnetflow.\fIbridge\fB.host\fR for each collector in the
-form \fIhost\fB:\fIport\fR. Records from \fIbridge\fR will be sent to
-each \fIhost\fR on UDP \fIport\fR.
+NetFlow is a protocol that exports 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 NetFlow collectors when flows
+end. To enable, define the key \fBnetflow.\fIbridge\fB.host\fR for each
+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:
.RS
.nf
-[netflow "mybr"]
- host = nflow.example.com:9995
+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:
+functionality is enabled by setting the key \fBmgmt.controller\fR to one
+of the following values:
.
.TP
\fBssl:\fIhost\fR[\fB:\fIport\fR]
.
.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.
+When the key is not set, 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
.
.RS
.TP
-\fBbridge.\fIname\fB.controller.accept-regex = \fIregex\fR
+\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.
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
+\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,
.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
+in 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).
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
+\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"
+.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"
+.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"
+.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"
+.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
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"
-.IQ "\fBmgmt.fail-mode = standalone\fR|\fBsecure\fR"
+.IP "\fBbridge.\fIname\fB.controller.fail-mode=\fBstandalone\fR|\fBsecure\fR"
+.IQ "\fBmgmt.fail-mode=standalone\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
+setting up all flows on the 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.
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
+MAC-learning switch. \fBvswitchd\fR will continue to retry ionnecting
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"
+.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
bucket'' to limit the rate at which packets in unknown flows are
forwarded to the OpenFlow controller for flow-setup processing. This
feature prevents a single bridge from overwhelming a controller.
-.IP "\fBbridge.\fIname\fB.controller.rate-limit = \fIrate\fR"
-.IQ "\fBmgmt.rate-limit = \fIrate\fR"
+.IP "\fBbridge.\fIname\fB.controller.rate-limit=\fIrate\fR"
+.IQ "\fBmgmt.rate-limit=\fIrate\fR"
Limits the maximum rate at which packets will be forwarded to the
-OpenFlow controller to \fIrate\fR packets per second. The first of
-these that is set takes effect.
+OpenFlow controller to \fIrate\fR packets per second. A rate specified
+explicitly for \fIname\fR overrides a value configured using the
+\fBmgmt.rate-limit\fR key.
.IP
If neither one of these settings is set, then the bridge does not
limit the rate at which packets are forwarded to the controller.
-.IP "\fBbridge.\fIname\fB.controller.burst-limit = \fIburst\fR"
-.IQ "\fBmgmt.burst-limit = \fIburst\fR"
+.IP "\fBbridge.\fIname\fB.controller.burst-limit=\fIburst\fR"
+.IQ "\fBmgmt.burst-limit=\fIburst\fR"
Sets the maximum number of unused packet credits that the bridge will
-allow to accumulate during time in which no packets are being
+allow to accumulate during the time in which no packets are being
forwarded to the OpenFlow controller to \fIburst\fR (measured in
packets). The default \fIburst\fR is one-quarter of the \fIrate\fR
specified in the rate-limit setting.
.IP
-The first of these that is set takes effect. This option takes effect
-only when a rate-limit is specified.
+A burst specified explicitly for \fIname\fR overrides a value configured
+using the \fBmgmt.burst-limit\fR key. This option takes effect only
+when a rate-limit is specified.
.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
\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"
+.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"
+.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"
+.IP "\fBbridge.\fIname\fB.controller.commands.dir=\fIdirectory\fR"
Sets the directory searched for remote command execution to
-\fBdirectory\fR. The default directory is
+\fIdirectory\fR. The default directory is
\fB@pkgdatadir@/commands\fR.
.SS "SSL Configuration"
-When \fBswitchd\fR is configured to connect over SSL for management or
+When \fBvswitchd\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
+\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
+\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
+\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
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
+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
methods. Acceptable connection methods include:
.RS
.IP "\fBpunix:\fIfile\fR"
-Listens for connections on Unix domain server socket named \fIfile\fR.
+Listens for connections on the 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,
.RE
To entirely disable listening for management connections, set
\fBbridge.\fIname\fB.openflow.listeners\fR to the single value
+\fBnone\fR.
+
.SS "OpenFlow Controller Connection Snooping"
By default, each bridge \fIname\fR listens for OpenFlow controller
connection snooping connections on a Unix domain socket named
\fB@RUNDIR@/\fIname\fB.snoop\fR. A client that connects to this
-socket, e.g. \fBdpctl monitor unix:@RUNDIR@/\fIname\fB.snoop\fR, will
+socket, e.g., \fBdpctl monitor unix:@RUNDIR@/\fIname\fB.snoop\fR, will
receive a copy of every OpenFlow message sent by the switch to the
controller, or vice versa, on the primary OpenFlow controller
connection.
\fBbridge.\fIname\fB.openflow.snoops\fR to the single value
\fBnone\fR.
.SH "SEE ALSO"
-.BR vswitchd (8).
+.BR vswitchd (8),
+.BR brcompatd (8),
+.BR cfg-mod (8).
projects / openvswitch / commitdiff