sflow: Write "sFlow" as "sFlow(R)" in documentation.

[sliver-openvswitch.git] / vswitchd / ovs-vswitchd.conf.5.in

.\" -*- nroff -*-
.de TQ
.  br
.  ns
.  TP "\\$1"
..
.de IQ
.  br
.  ns
.  IP "\\$1"
..
.de ST
.  PP
.  RS -0.15in
.  I "\\$1"
.  RE
.  PP
..
.TH ovs\-vswitchd.conf 5 "June 2009" "Open vSwitch" "Open vSwitch Manual"
.
.SH NAME
ovs\-vswitchd.conf \- configuration file for \fBovs\-vswitchd\fR
.
.SH DESCRIPTION
This manual page explains how to configure \fBovs\-vswitchd\fR, the
Open vSwitch virtual switch daemon.  Refer to \fBovs\-vswitchd\fR(8)
for instructions on how to start, stop, and control the virtual switch
daemon and for an overview of its features.
.SS "Overview"
\fBovs\-vswitchd\fR configuration is hierarchical.
.ST "Global Configuration"
A few aspects of configuration apply to the entire \fBovs\-vswitchd\fR
process:
.IP \(bu
Remote management (see \fBRemote Management\fR below).
.IP \(bu
SSL key and certificate configuration (see \fBSSL Configuration\fR
below).
.ST "Bridge Configuration"
\fBovs\-vswitchd\fR manages one or more ``bridges.''  A bridge is,
conceptually, an Ethernet switch.  Properties configurable at the
bridge level include:
.
.IP \(bu
The set of bridge ports (see \fBBridge Configuration\fR below).
.IP \(bu
Mirroring of packets across ports and VLANs (see \fBPort mirroring
(SPAN and RSPAN)\fR below).
.IP \(bu
Flow logging via NetFlow (see \fBNetFlow v5 Flow Logging\fR below).
.IP \(bu
Connectivity to an OpenFlow controller (see \fBOpenFlow Controller
Connectivity\fR below).
.IP \(bu
Addresses on which to listen for OpenFlow management connections (see
\fBOpenFlow Management Connections\fR below) or for snooping on the
connection to the primary OpenFlow controller (see \fBOpenFlow
Controller Connection Snooping\fR below).
.PP
.ST "Port Configuration"
Each bridge has one or more ``ports.''  The main configurable property
of a port is its 802.1Q VLAN configuration (see \fB802.1Q VLAN
support\fR below).
.PP
Most commonly, a port has exactly one ``interface.''  Such a port
logically corresponds to a port on a physical Ethernet switch.
.PP
A port that has more than one interface is a ``bonded port.''  Bonding
allows for load balancing and fail-over (see \fBNetwork Device
Bonding\fR below).
.ST "Interface Configuration"
There are two different kinds of interfaces:
.IP "``external interfaces''"
These interfaces are ordinary network devices, e.g. \fBeth0\fR on
Linux.
.IP "``internal interfaces''"
These interfaces are simulated network device that sent and receive
traffic.  Every bridge has one internal interface called the ``local
interface'' and may also have additional internal interfaces.  It does
not make sense to bond an internal interface, so the terms ``port''
and ``interface'' are often used imprecisely for internal interfaces.
.PP
Interfaces have a few configurable properties of their own:
.IP \(bu
Ingress rate-limiting (see \fBInterface Rate-Limiting\fR below).
.IP \(bu
Ethernet address (internal interfaces only, see \fBBridge
Configuration\fR below).
.SS "Configuration File Syntax"
The \fBovs\-vswitchd\fR configuration file syntax 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  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
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.
Keep in mind that programs that modify the configuration file, such as 
\fBovs\-brcompatd\fR and \fBovs-cfg-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 \fBovs\-vswitchd\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.
.PP
To designate network device \fInetdev\fR as an internal port, add
\fBiface.\fInetdev\fB.internal=true\fR to the configuration file,
which causes \fBovs\-vswitchd\fR to automatically creates
\fInetdev\fR, which may then be configured using the usual system
tools (e.g. \fBifconfig\fR, \fBip\fR).  An internal interface by
default has a random Ethernet address, but you may configure a
specific address by setting \fBiface.\fInetdev\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.
.PP
A bridge with a given \fIname\fR always has an internal port with the
same \fIname\fR, called the ``local port.''  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 other internal ports
and bridge ports that are
used as port mirroring destinations (see \fBPort Mirroring\fR, below).
For this purpose, the MAC of a bonded port (see \fBNetwork Device
Bonding\fR, below) is by default the MAC of its slave whose name is first in
alphabetical order.
There are two ways to modify this algorithm for selecting the MAC
address of the local port:
.IP \(bu
To use a specific MAC address for the local port, 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.
.IP \(bu
To override the MAC of a port for the purpose of this algorithm, set
\fBport.\fIport\fB.mac\fR to a MAC address in the format described
above.
.PP
If no valid MAC address can be determined
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
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,
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
vlan.eth0.trunks=2
vlan.eth0.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
\fBovs\-vswitchd\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.
The \fBupdelay\fR setting is honored only when at least one bonded
interface is already enabled.  When no interfaces are enabled, then
the first bond interface to come up is enabled immediately.  The
\fBdowndelay\fR setting is always honored.
.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
bridge.mybr.port=eth2
bridge.mybr.port=eth3

bonding.bond0.slave=eth0
bonding.bond0.slave=eth1
        
.fi
.RE
.SS "Port Mirroring (SPAN and RSPAN)"
\fBovs\-vswitchd\fR may be configured to send selected frames to special
``mirrored'' ports, in addition to their normal destinations.  Mirroring
traffic may also be referred to as SPAN or RSPAN, depending on the
mechanism used for delivery.
.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
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
.
\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 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 be referred to as SPAN.
.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.  This type of mirroring may be referred to as
RSPAN.
.IP
Please note that mirroring to a VLAN can disrupt a network that
contains unmanaged switches.  Consider an unmanaged physical switch
with two ports: port 1, connected to an end host, and port 2,
connected to an Open vSwitch configured to mirror received packets
into VLAN 123 on port 2.  Suppose that the end host sends a packet on
port 1 that the physical switch forwards to port 2.  The Open vSwitch
forwards this packet to its destination and then reflects it back on
port 2 in VLAN 123.  This reflected packet causes the unmanaged
physical switch to replace the MAC learning table entry, which
correctly pointed to port 1, with one that incorrectly points to port
2.  Afterward, the physical switch will direct packets destined for
the end host to the Open vSwitch on port 2, instead of to the end host
on port 1, disrupting connectivity.  If mirroring to a VLAN is desired
in this scenario, then the physical switch must be replaced by one
that learns Ethernet addresses on a per-VLAN basis.  In addition,
learning should be disabled on the VLAN containing mirrored traffic.
If this is not done then intermediate switches will learn the MAC
address of each end host from the mirrored traffic.  If packets being
sent to that end host are also mirrored, then they will be dropped
since the switch will attempt to send them out the input port.
Disabling learning for the VLAN will cause the switch to correctly
send the packet out all ports configured for that VLAN.  If Open
vSwitch is being used as an intermediate switch learning can be disabled
by setting the key \fBvlan.\fIbrname\fB.learning-disable=\fIvid\fR
to the mirrored VLAN.
.ST "Example"
The following \fBovs\-vswitchd\fR configuration copies all frames received
on \fBeth1\fR or \fBeth2\fR to \fBeth3\fR.
.PP
.RS
.nf

bridge.mybr.port=eth1
bridge.mybr.port=eth2
bridge.mybr.port=eth3

mirror.mybr.a.select.src-port=eth1
mirror.mybr.a.select.src-port=eth2
mirror.mybr.a.output.port=eth3
        
.fi
.RE
.SS "Interface Rate-Limiting"
Traffic policing and shaping are configured on interfaces.  Policing
defines a hard limit at which traffic that exceeds the specified rate is
dropped.  Shaping uses queues to delay packets so that egress traffic
leaves at the specified rate.

.ST "Ingress Policing"
The rate at which traffic is allowed to enter through a interface may be 
configured with ingress policing.  Note that "ingress" is from the 
perspective of \fBovs\-vswitchd\fR.  If configured on a physical interface, 
then it limits the rate at which traffic is allowed into the system from 
the outside.  If configured on a virtual interface that is connected to 
a virtual machine, then it limits the rate at which the guest is able to 
transmit.

The rate is specified in kilobits (1000 bits) per second with a maximum 
burst size specified in kilobits (1000 bits).  The burst size should be at 
least the size of the interface's MTU.  

An interface may be configured to enforce ingress policing by defining the
key \fBport.\fIname\fB.ingress.policing-rate\fR with an integer
indicating the rate.  The interface \fIname\fR will only allow traffic to be
received at the rate specified in kilobits per second.  If the rate is zero 
or the key is not defined, then ingress policing is disabled.

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 the key is not supplied or is 
zero, then the default burst is 10 kilobits.

.PP
The following syntax limits interface \fBeth1\fR to receiving traffic at
\fB512\fR kilobits per second with a burst of \fB20\fR kilobits:
.PP
.RS
.nf

port.eth1.ingress.policing-rate=512
port.eth1.ingress.policing-burst=20

.fi
.SS "NetFlow v5 Flow Logging"
NetFlow is a protocol that exports a number of details about terminating
IP 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 \fIip\fB:\fIport\fR.  Records from \fIbridge\fR
will be sent to each \fIip\fR on UDP \fIport\fR.  The \fIip\fR must
be specified numerically, not as a DNS name.

In addition to terminating flows, NetFlow can also send records at a set
interval for flows that are still active.  This interval can be configured
by defining the key \fBnetflow.\fIbridge\fB\.active-timeout\fR.  The value
is in seconds.  An active timeout of 0 will disable this functionality.  By
default there is timeout value of 600 seconds.

The NetFlow messages will use the datapath index for the engine type and id.
This can be overridden with the \fBnetflow.\fIbridge\fB.engine-type\fR and
\fBnetflow.\fIbridge\fB.engine-id\fR, respectively.  Each takes a value
between 0 and 255, inclusive.

Many NetFlow collectors do not expect multiple switches to be
sending messages from the same host, and they do not store the engine
information which could be used to disambiguate the traffic.  To prevent
flows from multiple switches appearing as if they came on the interface,
add \fBnetflow.\fIbridge\fB.add-id-to-iface=true\fR to the configuration
file.  This will place the least significant 7 bits of the engine id
into the most significant bits of the ingress and egress interface fields
of flow records.  When this option is enabled, a maximum of 508 ports are
supported.  By default, this behavior is disabled.

The egress interface field normally contains the OpenFlow port number,
however, certain port values have special meaning: 0xFFFF indicates
flooding, 0xFFFE is multiple controller-specified output interfaces, and
0xFFFD means that packets from the flow were dropped.  If add-id-to-iface
is enabled then these values become 0x1FF, 0x1FE, and 0x1FD respectively.

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 "sFlow Monitoring"
sFlow(R) is a protocol for monitoring switches.  A bridge may be
configured to send sFlow records to sFlow collectors by defining the
key \fBsflow.\fIbridge\fB.host\fR for each collector in the form
\fIip\fR[\fB:\fIport\fR].  Records from \fIbridge\fR will be sent to
each \fIip\fR on UDP \fIport\fR.  The \fIip\fR must be specified
numerically, not as a DNS name.  If \Iport\fR is omitted, port 6343 is
used.
.PP
By default, 1 out of every 400 packets is sent to the configured sFlow
collector.  To override this, set \fBsflow.\fIbridge\fB.sampling\fR to
the number of switched packets out of which 1, on average, will be
sent to the sFlow collector, e.g. a value of 1 sends every packet to
the collector, a value of 2 sends 50% of the packets to the collector,
and so on.
.PP
\fBovs\-vswitchd\fR also occasionally sends switch port statistics to
sFlow collectors, by default every 30 seconds.  To override this, set
\fBsflow.\fIbridge\fB.polling\fR to a duration in seconds.
.PP
By default, \fBovs\-vswitchd\fR sends the first 128 bytes of sampled
packets to sFlow collectors.  To override this, set
\fBsflow.\fIbridge\fB.header\fR to a size in bytes.
.SS "Remote Management"
A \fBovs\-vswitchd\fR instance may be remotely managed by a controller that
supports the OpenFlow Management Protocol, such as NOX.  This
functionality is enabled by setting the key \fBmgmt.controller\fR to one 
of the following values:
.
.IP "\fBssl:\fIip\fR[\fB:\fIport\fR]"
The specified SSL \fIport\fR (default: 6633) on the host at the given
\fIip\fR, which must be expressed as an IP address (not a DNS name).
SSL must be configured when this form is used (see \fBSSL
Configuration\fR, below).
.
.IP "\fBtcp:\fIip\fR[\fB:\fIport\fR]"
The specified TCP \fIport\fR (default: 6633) on the host at the given
\fIip\fR, which must be expressed as an IP address (not a DNS name).
.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 8 seconds, and the minimum value is 1
second.

An inactivity probe may be configured with the \fBmgmt.inactivity-probe\fR
key.  If \fBovs\-vswitchd\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, \fBovs\-vswitchd\fR assumes
the connection has been broken and attempts to reconnect.  The default
and minimum values are both 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 \fBovs\-vswitchd\fR is started.
.fi
.RE
.SS "OpenFlow Controller Connectivity"
\fBovs\-vswitchd\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 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
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 \fBovs\-openflowd\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 \fBtcp:.*\fR otherwise, meaning that only
TCP controller connections 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, \fBovs\-vswitchd\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,
\fBovs\-vswitchd\fR will not modify \fB/etc/resolv.conf\fR.
.IP
\fBovs\-vswitchd\fR will only modify \fBresolv.conf\fR if the DHCP response
that it receives specifies one or more DNS servers.
.RE
.
.TP
\fBssl:\fIip\fR[\fB:\fIport\fR]
The specified SSL \fIport\fR (default: 6633) on the host at the given
\fIip\fR, which must be expressed as an IP address (not a DNS name).
SSL must be configured when this form is used (see \fBSSL
Configuration\fR, below).
.
.TP
\fBtcp:\fIip\fR[\fB:\fIport\fR]
The specified TCP \fIport\fR (default: 6633) on the host at the given
\fIip\fR, which must be expressed as an IP address (not a DNS name).
.
.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,
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).
.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, \fBovs\-vswitchd\fR connects
to the controller in-band.  If this is set to \fBfalse\fR,
\fBovs\-vswitchd\fR connects to the controller out-of-band.  Refer to
\fBovs\-openflowd\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 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, \fBovs-vswitchd\fR 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"
.IQ "\fBmgmt.fail-mode=standalone\fR|\fBsecure\fR"
When a controller is configured, it is, ordinarily, responsible for
setting up all flows on the 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
The first of these that is set takes effect.
If the value is \fBstandalone\fR, or if neither of these settings
is set, \fBovs\-vswitchd\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,
\fBovs\-vswitchd\fR causes the datapath to act like an ordinary
MAC-learning switch.  \fBovs\-vswitchd\fR will continue to retry connecting
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, \fBovs\-vswitchd\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 "Controller Rate-Limiting"
These settings configure how the switch applies a ``token
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.
.PP
In addition, when a high rate triggers rate-limiting,
\fBovs\-vswitchd\fR queues controller packets for each port and
transmits them to the controller at the configured rate.  The number
of queued packets is limited by a ``burst size'' parameter.  The
packet queue is shared fairly among the ports on a bridge.
.PP
\fBovs\-vswitchd\fR maintains two such packet rate-limiters per
bridge.  One of these applies to packets sent up to the controller
because they do not correspond to any flow.  The other applies to
packets sent up to the controller by request through flow actions.
When both rate-limiters are filled with packets, the actual rate that
packets are sent to the controller is up to twice the specified rate.
.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.  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"
Sets the maximum number of unused packet credits that the bridge will
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
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.) \fBovs\-ofctl 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,
\fBovs\-vswitchd\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=\fIdirectory\fR"
Sets the directory searched for remote command execution to
\fIdirectory\fR.  The default directory is
\fB@pkgdatadir@/commands\fR.
.SS "SSL Configuration"
When \fBovs\-vswitchd\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 
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 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 switch is connected to a trustworthy controller.
.PP
These files are read only once, at \fBovs\-vswitchd\fR startup time.  If
their contents change, \fBovs\-vswitchd\fR must be killed and restarted.
.PP
These SSL settings apply to all SSL connections made by the switch.
.ST "CA Certificate Bootstrap"
Ordinarily, all of the files named in the SSL configuration must exist
when \fBovs\-vswitchd\fR starts.  However, if \fBssl.bootstrap-ca-cert\fR
is set to \fBtrue\fR, then \fBovs\-vswitchd\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., \fBovs\-ofctl 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, \fBovs\-vswitchd\fR instead listens on the specified connection
methods.  Acceptable connection methods include:
.RS
.IP "\fBpunix:\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,
above).
.IP "\fBptcp:\fR[\fIport\fR][\fB:\fIip\fR]"
Listens for TCP connections on \fIport\fR (default: 6633).
By default, \fB\ovs\-vswitchd\fR listens for connections to any local
IP address, but \fIip\fR may be specified to limit connections to the
specified local \fIip\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., \fBovs\-ofctl 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.
.PP
If \fBbridge.\fIname\fB.openflow.snoops\fR is set to one or more
values, \fBovs\-vswitchd\fR instead listens on the specified connection
methods.  The acceptable connection methods are the same as for
OpenFlow management connections (see above).
.PP
To entirely disable controller connection snooping, set
\fBbridge.\fIname\fB.openflow.snoops\fR to the single value
\fBnone\fR.
.SH "SEE ALSO"
.BR ovs\-brcompatd (8),
.BR ovs\-cfg\-mod (8),
.BR ovs\-vswitchd (8)