ovs\-vswitchd.conf \- configuration file for \fBovs\-vswitchd\fR
.
.SH DESCRIPTION
-This manual page describes the syntax for the configuration file used
-by \fBovs\-vswitchd\fR(8), the Open vSwitch daemon.
-.PP
-The configuration file is based on key-value pairs, which are given
+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
the names of its network devices as values for key
\fBbridge.\fIname\fB.port\fR.
.PP
-The names given on \fBbridge.\fIname\fB.port\fR must be the names of
-existing network devices, except for ``internal ports.'' An internal
-port is a simulated network device that receives traffic only
-through the switch and switches any traffic sent it through the
-switch. An internal port may configured with an IP address,
-etc. using the usual system tools (e.g. \fBifconfig\fR, \fBip\fR). To
-designate network device \fInetdev\fR as an internal port, add
-\fBiface.\fInetdev\fB.internal=true\fR to the configuration file.
-\fBovs\-vswitchd\fR will honor this configuration setting by automatically
-creating the named internal port.
+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
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 the intermediate switch 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.
.ST "Example"
The following \fBovs\-vswitchd\fR configuration copies all frames received
on \fBeth1\fR or \fBeth2\fR to \fBeth3\fR.
.fi
.RE
-.SS "Port Rate-Limiting"
-Traffic policing and shaping are configured on physical ports. Policing
+.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 port may be
+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 port,
+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
burst size specified in kilobits (1000 bits). The burst size should be at
least the size of the interface's MTU.
-A port may be configured to enforce ingress policing by defining the
+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 port \fIname\fR will only allow traffic to be
+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.
zero, then the default burst is 10 kilobits.
.PP
-The following syntax limits port \fBeth1\fR to receiving traffic at
+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
can pass through the switch at all.
.IP
The first of these that is set takes effect.
-If the value is \fBstandalone\fR, \fBovs\-vswitchd\fR will take over
+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,
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, or if neither of these settings
-is set, \fBovs\-vswitchd\fR will not set up flows on its own when the
-controller connection fails.
+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
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
git://git.onelab.eu / sliver-openvswitch.git / blobdiff