xenserver: Include dbcache in xen-bugtool output
[sliver-openvswitch.git] / vswitchd / ovs-vswitchd.conf.5.in
1 .\" -*- nroff -*-
2 .de TQ
3 .  br
4 .  ns
5 .  TP "\\$1"
6 ..
7 .de IQ
8 .  br
9 .  ns
10 .  IP "\\$1"
11 ..
12 .de ST
13 .  PP
14 .  RS -0.15in
15 .  I "\\$1"
16 .  RE
17 .  PP
18 ..
19 .TH ovs\-vswitchd.conf 5 "April 2009" "Open vSwitch" "Open vSwitch Manual"
20 .
21 .SH NAME
22 ovs\-vswitchd.conf \- configuration file for \fBovs\-vswitchd\fR
23 .
24 .SH DESCRIPTION
25 This manual page explains how to configure \fBovs\-vswitchd\fR, the
26 Open vSwitch virtual switch daemon.  Refer to \fBovs\-vswitchd\fR(8)
27 for instructions on how to start, stop, and control the virtual switch
28 daemon and for an overview of its features.
29 .SS "Overview"
30 \fBovs\-vswitchd\fR configuration is hierarchical.
31 .ST "Global Configuration"
32 A few aspects of configuration apply to the entire \fBovs\-vswitchd\fR
33 process:
34 .IP \(bu
35 Remote management (see \fBRemote Management\fR below).
36 .IP \(bu
37 SSL key and certificate configuration (see \fBSSL Configuration\fR
38 below).
39 .ST "Bridge Configuration"
40 \fBovs\-vswitchd\fR manages one or more ``bridges.''  A bridge is,
41 conceptually, an Ethernet switch.  Properties configurable at the
42 bridge level include:
43 .
44 .IP \(bu
45 The set of bridge ports (see \fBBridge Configuration\fR below).
46 .IP \(bu
47 Mirroring of packets across ports and VLANs (see \fBPort mirroring
48 (SPAN and RSPAN)\fR below).
49 .IP \(bu
50 Flow logging via NetFlow (see \fBNetFlow v5 Flow Logging\fR below).
51 .IP \(bu
52 Connectivity to an OpenFlow controller (see \fBOpenFlow Controller
53 Connectivity\fR below).
54 .IP \(bu
55 Addresses on which to listen for OpenFlow management connections (see
56 \fBOpenFlow Management Connections\fR below) or for snooping on the
57 connection to the primary OpenFlow controller (see \fBOpenFlow
58 Controller Connection Snooping\fR below).
59 .PP
60 .ST "Port Configuration"
61 Each bridge has one or more ``ports.''  The main configurable property
62 of a port is its 802.1Q VLAN configuration (see \fB802.1Q VLAN
63 support\fR below).
64 .PP
65 Most commonly, a port has exactly one ``interface.''  Such a port
66 logically corresponds to a port on a physical Ethernet switch.
67 .PP
68 A port that has more than one interface is a ``bonded port.''  Bonding
69 allows for load balancing and fail-over (see \fBNetwork Device
70 Bonding\fR below).
71 .ST "Interface Configuration"
72 There are two different kinds of interfaces:
73 .IP "``external interfaces''"
74 These interfaces are ordinary network devices, e.g. \fBeth0\fR on
75 Linux.
76 .IP "``internal interfaces''"
77 These interfaces are simulated network device that sent and receive
78 traffic.  Every bridge has one internal interface called the ``local
79 interface'' and may also have additional internal interfaces.  It does
80 not make sense to bond an internal interface, so the terms ``port''
81 and ``interface'' are often used imprecisely for internal interfaces.
82 .PP
83 Interfaces have a few configurable properties of their own:
84 .IP \(bu
85 Ingress rate-limiting (see \fBInterface Rate-Limiting\fR below).
86 .IP \(bu
87 Ethernet address (internal interfaces only, see \fBBridge
88 Configuration\fR below).
89 .SS "Configuration File Syntax"
90 The \fBovs\-vswitchd\fR configuration file syntax is based on
91 key-value pairs, which are given
92 one per line in the form \fIkey\fB=\fIvalue\fR.  Each \fIkey\fR
93 consists of one or more parts separated by dots,
94 e.g. \fIpart1\fB.\fIpart2\fB.\fIpart3\fR.  Each \fIpart\fR may consist
95 only of the English letters, digits, and the special characters
96 \fB_-@$:+\fR.  White space within \fIvalue\fR  and at the beginning of a
97 line is significant, but is otherwise ignored.
98 .PP
99 If a single key is specified more than once, that key has multiple
100 values, one value for each time the key is specified.  The ordering of
101 key-value pairs, and the ordering of multiple values for a single key,
102 within a configuration file is not significant.
103 .PP
104 Blank lines, lines that consist only of white space, and lines that
105 begin with \fB#\fR (optionally preceded by white space) are ignored.
106 Keep in mind that programs that modify the configuration file, such as 
107 \fBovs\-brcompatd\fR and \fBovs-cfg-mod\fR, may alter the order of
108 elements and 
109 strip comments and blank lines.
110 .PP
111 The following subsections describe how key-value pairs are used to
112 configure \fBovs\-vswitchd\fR.
113 .SS "Bridge Configuration"
114 A bridge (switch) with a given \fIname\fR is configured by specifying
115 the names of its network devices as values for key
116 \fBbridge.\fIname\fB.port\fR.  (The specified \fIname\fR may not begin
117 with \fBdp\fR or \fBnl:\fR followed by a digit.)
118 .PP
119 To designate network device \fInetdev\fR as an internal port, add
120 \fBiface.\fInetdev\fB.internal=true\fR to the configuration file,
121 which causes \fBovs\-vswitchd\fR to automatically creates
122 \fInetdev\fR, which may then be configured using the usual system
123 tools (e.g. \fBifconfig\fR, \fBip\fR).  An internal interface by
124 default has a random Ethernet address, but you may configure a
125 specific address by setting \fBiface.\fInetdev\fB.mac\fR to a MAC
126 address in the format
127 \fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR, where each
128 \fIx\fR is a hex digit.
129 .PP
130 A bridge with a given \fIname\fR always has an internal port with the
131 same \fIname\fR, called the ``local port.''  This network device may
132 be included
133 in the bridge, by specifying it as one of the values for key
134 \fBbridge.\fIname\fB.port\fR, or it may be omitted.  If it is
135 included, then its MAC address is by default the lowest-numbered MAC
136 address among the other bridge ports, ignoring other internal ports
137 and bridge ports that are
138 used as port mirroring destinations (see \fBPort Mirroring\fR, below).
139 For this purpose, the MAC of a bonded port (see \fBNetwork Device
140 Bonding\fR, below) is by default the MAC of its slave whose name is first in
141 alphabetical order.
142 There are two ways to modify this algorithm for selecting the MAC
143 address of the local port:
144 .IP \(bu
145 To use a specific MAC address for the local port, set
146 \fBbridge.\fIname\fB.mac\fR to a MAC address in the format
147 \fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR, where each
148 \fIx\fR is a hex digit.
149 .IP \(bu
150 To override the MAC of a port for the purpose of this algorithm, set
151 \fBport.\fIport\fB.mac\fR to a MAC address in the format described
152 above.
153 .PP
154 If no valid MAC address can be determined
155 either of these ways, then a MAC address is randomly generated.
156 .PP
157 The following syntax defines a bridge named \fBmybr\fR, configured
158 with network devices \fBeth0\fR, \fBeth1\fR, and \fBeth2\fR:
159 .RS
160 .nf
161
162 bridge.mybr.port=eth0
163 bridge.mybr.port=eth1
164 bridge.mybr.port=eth2
165
166 .fi
167 .RE
168 .SS "802.1Q VLAN support"
169 A bridge port may be configured either as a trunk port or as belonging
170 to a single, untagged VLAN.  These two options are mutually exclusive,
171 and a port must be configured in one way or the other.
172 .ST "Trunk Ports"
173 By default, bridge ports are trunk ports that carry all VLANs.  To
174 limit the VLANs that a trunk port carries, define
175 \fBvlan.\fIport\fB.trunks\fR to one or more integers between 0 and
176 4095 designating VLANs.  Only frames that have an 802.1Q header with
177 one of the listed VLANs are accepted on a trunk port.  If 0 is
178 included in the list, then frames without an 802.1Q header are also
179 accepted.  Other frames are discarded.
180 .PP
181 The following syntax makes network device \fBeth0\fR a trunk port that
182 carries VLANs 1, 2, and 3:
183 .PP
184 .RS
185 .nf
186
187 vlan.eth0.trunks=1
188 vlan.eth0.trunks=2
189 vlan.eth0.trunks=3
190         
191 .fi
192 .RE
193 .ST "Untagged VLAN Ports"
194 A bridge port may be configured with an implicit, untagged VLAN.  
195 Define key
196 \fBvlan.\fIport\fB.tag\fR to an integer value \fIvid\fR between 0 and
197 4095, inclusive, to designate the named \fIport\fR as a member
198 of 802.1Q VLAN \fIvid\fR.  When \fIport\fR is assigned a VLAN tag this
199 way, frames arriving on trunk ports will be forwarded to \fIport\fR
200 only if they are tagged with VLAN \fIvid\fR, and frames arriving on
201 other VLAN ports will be forwarded to \fIport\fR only if their
202 \fIvid\fR values are equal.  Frames forwarded to \fIport\fR will not
203 have an 802.1Q header.
204 .PP
205 When \fIvid\fR is 0, frames arriving on trunk ports without an 802.1Q
206 VLAN header will also be forwarded to \fIport\fR.
207 .PP
208 When a frame with a 802.1Q header that indicates a nonzero VLAN is
209 received on an implicit VLAN port, it is discarded.
210 .PP
211 The following syntax makes network device \fBeth0\fR a member of VLAN
212 101:
213 .PP
214 .RS
215 .nf
216
217 vlan.eth0.tag=101
218         
219 .fi
220 .RE
221 .SS "Network Device Bonding"
222 Bonding allows multiple ``slave'' network devices to be treated as if
223 they were a single virtual ``bonded'' network device.  It is useful for
224 load balancing and fail-over.
225 .PP
226 \fBovs\-vswitchd\fR supports ``source load balancing'' (SLB) bonding, which
227 assigns flows to slaves based on source MAC address, with periodic
228 rebalancing as traffic patterns change.  This form of bonding does not
229 require 802.3ad or other special support from the upstream switch to
230 which the slave devices are connected.
231 .PP
232 To configure bonding, create a virtual bonding device by specifying
233 the slave network device names as values for
234 \fBbonding.\fIname\fB.slave\fR, then specify \fIname\fR as a bridge
235 port.  The chosen \fIname\fR should not be the name of any real
236 network device on the host system.
237 .PP
238 By default, bonding interfaces are enabled or disabled immediately
239 when a carrier is detected or dropped on the underlying network
240 device.  To insert a delay when carrier comes up or goes down before
241 enabling or disabling an interface, set the value of
242 \fBbonding.\fIname\fB.updelay\fR or
243 \fBbonding.\fIname\fB.downdelay\fR, respectively, to a positive
244 integer, interpreted in milliseconds.
245 The \fBupdelay\fR setting is honored only when at least one bonded
246 interface is already enabled.  When no interfaces are enabled, then
247 the first bond interface to come up is enabled immediately.  The
248 \fBdowndelay\fR setting is always honored.
249 .PP
250 The following syntax bonds \fBeth0\fR and \fBeth1\fR into a bonding
251 device named \fBbond0\fR, which is added to bridge \fBmybr\fR along
252 with physical network devices \fBeth2\fR and \fBeth3\fR:
253 .PP
254 .RS
255 .nf
256
257 bridge.mybr.port=bond0
258 bridge.mybr.port=eth2
259 bridge.mybr.port=eth3
260
261 bonding.bond0.slave=eth0
262 bonding.bond0.slave=eth1
263         
264 .fi
265 .RE
266 .SS "Port Mirroring (SPAN and RSPAN)"
267 \fBovs\-vswitchd\fR may be configured to send selected frames to special
268 ``mirrored'' ports, in addition to their normal destinations.  Mirroring
269 traffic may also be referred to as SPAN or RSPAN, depending on the
270 mechanism used for delivery.
271 .PP
272 Up to 32 instances of port mirroring may be configured on a given
273 bridge.  Each must be given a name that is unique within the bridge.
274 The keys associated with port mirroring instance \fIpmname\fR for
275 bridge \fIbrname\fR begin with \fBmirror.\fIbrname\fB.\fIpmname\fR.
276 .PP
277 The selection of the frames to mirror and the form in which they
278 should be output is configured separately for each port mirroring
279 instances, through a subsection of
280 \fBmirror.\fIbrname\fB.\fIpmname\fR, named \fBselect\fR, and
281 \fBoutput\fR, respectively.
282 .ST "Selecting Frames to Mirror"
283 The values for the following keys, if specified, limit the frames that
284 are chosen for mirroring.  If none of these keys is specified, then
285 all frames received by the bridge are mirrored.  If more than one of
286 these keys is specified, then a frame must meet all specified criteria
287 to be mirrored.
288 .TP
289 \fBmirror.\fIbrname\fB.\fIpmname\fB.select.src-port=\fIport\fR
290 .TQ
291 \fBmirror.\fIbrname\fB.\fIpmname\fB.select.dst-port=\fIport\fR
292 .TQ
293 \fBmirror.\fIbrname\fB.\fIpmname\fB.select.port=\fIport\fR
294 Frame received on \fIport\fR, output to \fIport\fR, or either received
295 on or output to \fIport\fR, respectively.  \fIport\fR must be part of
296 the bridge \fIbrname\fR; that is, it must be listed on
297 \fBbridge.\fIbrname\fB.port\fR.
298 .TP
299 \fBmirror.\fIbrname\fB.\fIpmname\fB.select.vlan=\fIvid\fR
300 .
301 \fIvid\fR must be an integer between 0 and 4095, inclusive.  A nonzero
302 \fIvid\fR selects frames that belong to VLAN \fIvid\fR, that is,
303 frames that arrived on a trunk port tagged with VLAN \fIvid\fR or on a
304 port that is configured as part of VLAN \fIvid\fR (see \fB802.1Q VLAN
305 tagging\fR, above).  A \fIvid\fR of zero selects frames that do not
306 belong to a VLAN, that is, frames that arrived on a trunk port without
307 a VLAN tag or tagged with VLAN 0.
308 .ST "Mirror Output"
309 The values of the following keys determine how frames selected for
310 mirroring are output.  Only one of the keys may be specified.
311 .TP
312 \fBmirror.\fIbrname\fB.\fIpmname\fB.output.port=\fIport\fR
313 .
314 Causes the selected frames to be sent out \fIport\fR, which must be
315 part of the bridge \fIbrname\fR; that is, it must be listed on
316 \fBbridge.\fIbrname\fB.port\fR.
317 .IP
318 Specifying a \fIport\fR in this way reserves that port exclusively for
319 mirroring.  No frames other than those selected for mirroring will be
320 forwarded to \fIport\fR, and any frames received on \fIport\fR will be
321 discarded.  This type of mirroring may be referred to as SPAN.
322 .TP
323 \fBmirror.\fIbrname\fB.\fIpmname\fB.output.vlan=\fIvid\fR
324 .
325 Causes the selected frames to be sent on the VLAN numbered \fIvid\fR,
326 which must be an integer between 0 and 4095, inclusive.  The frames
327 will be sent out all ports that trunk VLAN \fIvid\fR, as well as any
328 ports with implicit VLAN \fIvid\fR.  When a mirrored frame is sent out
329 a trunk port, the frame's VLAN tag will be set to \fIvid\fR, replacing
330 any existing tag; when it is sent out an implicit VLAN port, the frame
331 will not be tagged.  This type of mirroring may be referred to as
332 RSPAN.
333 .IP
334 Please note that mirroring to a VLAN can disrupt a network that
335 contains unmanaged switches.  Consider an unmanaged physical switch
336 with two ports: port 1, connected to an end host, and port 2,
337 connected to an Open vSwitch configured to mirror received packets
338 into VLAN 123 on port 2.  Suppose that the end host sends a packet on
339 port 1 that the physical switch forwards to port 2.  The Open vSwitch
340 forwards this packet to its destination and then reflects it back on
341 port 2 in VLAN 123.  This reflected packet causes the unmanaged
342 physical switch to replace the MAC learning table entry, which
343 correctly pointed to port 1, with one that incorrectly points to port
344 2.  Afterward, the physical switch will direct packets destined for
345 the end host to the Open vSwitch on port 2, instead of to the end host
346 on port 1, disrupting connectivity.  If mirroring to a VLAN is desired
347 in this scenario, then the physical switch must be replaced by one
348 that learns Ethernet addresses on a per-VLAN basis.  In addition,
349 learning should be disabled on the VLAN containing mirrored traffic.
350 If this is not done then the intermediate switch will learn the MAC
351 address of each end host from the mirrored traffic.  If packets being
352 sent to that end host are also mirrored, then they will be dropped
353 since the switch will attempt to send them out the input port.
354 Disabling learning for the VLAN will cause the switch to correctly
355 send the packet out all ports configured for that VLAN.
356 .ST "Example"
357 The following \fBovs\-vswitchd\fR configuration copies all frames received
358 on \fBeth1\fR or \fBeth2\fR to \fBeth3\fR.
359 .PP
360 .RS
361 .nf
362
363 bridge.mybr.port=eth1
364 bridge.mybr.port=eth2
365 bridge.mybr.port=eth3
366
367 mirror.mybr.a.select.src-port=eth1
368 mirror.mybr.a.select.src-port=eth2
369 mirror.mybr.a.output.port=eth3
370         
371 .fi
372 .RE
373 .SS "Interface Rate-Limiting"
374 Traffic policing and shaping are configured on interfaces.  Policing
375 defines a hard limit at which traffic that exceeds the specified rate is
376 dropped.  Shaping uses queues to delay packets so that egress traffic
377 leaves at the specified rate.
378
379 .ST "Ingress Policing"
380 The rate at which traffic is allowed to enter through a interface may be 
381 configured with ingress policing.  Note that "ingress" is from the 
382 perspective of \fBovs\-vswitchd\fR.  If configured on a physical interface, 
383 then it limits the rate at which traffic is allowed into the system from 
384 the outside.  If configured on a virtual interface that is connected to 
385 a virtual machine, then it limits the rate at which the guest is able to 
386 transmit.
387
388 The rate is specified in kilobits (1000 bits) per second with a maximum 
389 burst size specified in kilobits (1000 bits).  The burst size should be at 
390 least the size of the interface's MTU.  
391
392 An interface may be configured to enforce ingress policing by defining the
393 key \fBport.\fIname\fB.ingress.policing-rate\fR with an integer
394 indicating the rate.  The interface \fIname\fR will only allow traffic to be
395 received at the rate specified in kilobits per second.  If the rate is zero 
396 or the key is not defined, then ingress policing is disabled.
397
398 If ingress policing is enabled, then the burst rate may be set by defining 
399 the key \fBport.\fIname\fB.ingress.policing-burst\fR with an integer 
400 indicating the burst rate in kilobits.  If the key is not supplied or is 
401 zero, then the default burst is 10 kilobits.
402
403 .PP
404 The following syntax limits interface \fBeth1\fR to receiving traffic at
405 \fB512\fR kilobits per second with a burst of \fB20\fR kilobits:
406 .PP
407 .RS
408 .nf
409
410 port.eth1.ingress.policing-rate=512
411 port.eth1.ingress.policing-burst=20
412
413 .fi
414 .SS "NetFlow v5 Flow Logging"
415 NetFlow is a protocol that exports a number of details about terminating 
416 IP flows, such as the principals involved and duration.  A bridge may be 
417 configured to send NetFlow v5 records to NetFlow collectors when flows 
418 end.  To enable, define the key \fBnetflow.\fIbridge\fB.host\fR for each 
419 collector in the form \fIip\fB:\fIport\fR.  Records from \fIbridge\fR 
420 will be sent to each \fIip\fR on UDP \fIport\fR.  The \fIip\fR must
421 be specified numerically, not as a DNS name.
422
423 The NetFlow messages will use the datapath index for the engine type and id.  
424 This can be overridden with the \fBnetflow.\fIbridge\fB.engine-type\fR and 
425 \fBnetflow.\fIbridge\fB.engine-id\fR, respectively.  Each takes a value
426 between 0 and 255, inclusive. 
427
428 Many NetFlow collectors do not expect multiple virtual switches to be
429 sending messages from the same host, and they do not store the engine
430 information which could be used to disambiguate the traffic.  To prevent
431 flows from multiple switches appearing as if they came on the interface,
432 add \fBnetflow.\fIbridge\fB.add-id-to-iface=true\fR to the configuration
433 file.  This will place the least significant 7 bits of the engine id
434 into the most significant bits of the ingress and egress interface fields 
435 of flow records.  By default, this behavior is disabled.
436
437 The following syntax sends NetFlow records for \fBmybr\fR to the NetFlow
438 collector \fBnflow.example.com\fR on UDP port \fB9995\fR:
439 .PP
440 .RS
441 .nf
442
443 netflow.mybr.host=nflow.example.com:9995
444
445 .fi
446 .RE
447 .SS "Remote Management"
448 A \fBovs\-vswitchd\fR instance may be remotely managed by a controller that
449 supports the OpenFlow Management Protocol, such as NOX.  This
450 functionality is enabled by setting the key \fBmgmt.controller\fR to one 
451 of the following values:
452 .
453 .IP "\fBssl:\fIip\fR[\fB:\fIport\fR]"
454 The specified SSL \fIport\fR (default: 6633) on the host at the given
455 \fIip\fR, which must be expressed as an IP address (not a DNS name).
456 SSL must be configured when this form is used (see \fBSSL
457 Configuration\fR, below).
458 .
459 .IP "\fBtcp:\fIip\fR[\fB:\fIport\fR]"
460 The specified TCP \fIport\fR (default: 6633) on the host at the given
461 \fIip\fR, which must be expressed as an IP address (not a DNS name).
462 .PP
463 The maximum time between attempts to connect to the controller may be
464 specified in integral seconds with the \fBmgmt.max-backoff\fR key.  The
465 default maximum backoff is 8 seconds, and the minimum value is 1
466 second.
467
468 An inactivity probe may be configured with the \fBmgmt.inactivity-probe\fR
469 key.  If \fBovs\-vswitchd\fR does not communicate with the controller for the
470 specified number of seconds, it will send a probe.  If a response is not
471 received for an additional amount of that time, \fBovs\-vswitchd\fR assumes
472 the connection has been broken and attempts to reconnect.  The default
473 and minimum values are both 5 seconds.
474
475 A management id may be specified with the \fBmgmt.id\fR key.  It takes
476 an id in the form of exactly 12 hexadecimal digits.  If one is not
477 specified, a random id is generated each time \fBovs\-vswitchd\fR is started.
478 .fi
479 .RE
480 .SS "OpenFlow Controller Connectivity"
481 \fBovs\-vswitchd\fR can perform all configured bridging and switching
482 locally, or it can be configured to connect a given bridge to an
483 external OpenFlow controller, such as NOX.  Its behavior depends on
484 the \fBbridge.\fIname\fB.controller\fR setting:
485 .
486 .TP
487 \fI\[la]unset\[ra]\fR
488 When the key is not set, the behavior depends on whether remote 
489 management is configured.  If management is configured, then the switch 
490 will connect to the controller specified on \fBmgmt.controller\fR.  If 
491 management is not configured, the switch will perform all configured 
492 bridging and switching locally.
493 .
494 .TP
495 \fI\[la]empty\[ra]\fR
496 Setting an empty string value disables controller connectivity.  The
497 switch will perform all configured bridging and switching locally.
498 .
499 .TP
500 \fBdiscover\fR
501 Use controller discovery to find the local OpenFlow controller.
502 Refer to \fBsecchan\fR(8) for information on how to configure a DHCP
503 server to support controller discovery.  The following additional
504 options control the discovery process:
505 .
506 .RS
507 .TP
508 \fBbridge.\fIname\fB.controller.accept-regex=\fIregex\fR
509 A POSIX extended regular expression against which the discovered
510 controller location is validated.  Only controllers whose names match
511 the regular expression will be accepted.
512 .IP
513 The default regular expression is \fBssl:.*\fR, meaning that only SSL
514 controller connections will be accepted, when SSL is configured (see
515 \fBSSL Configuration\fR), and \fB.*\fR otherwise, meaning that any
516 controller will be accepted.
517 .IP
518 The regular expression is implicitly anchored at the beginning of the
519 controller location string, as if it begins with \fB^\fR.
520 .TP
521 \fBbridge.\fIname\fB.controller.update-resolv.conf=\fBtrue\fR|\fBfalse\fR
522 By default, or if this is set to \fBtrue\fR, \fBovs\-vswitchd\fR overwrites
523 the system's \fB/etc/resolv.conf\fR with domain information and DNS
524 servers obtained via DHCP.  If this setting is \fBfalse\fR,
525 \fBovs\-vswitchd\fR will not modify \fB/etc/resolv.conf\fR.
526 .IP
527 \fBovs\-vswitchd\fR will only modify \fBresolv.conf\fR if the DHCP response
528 that it receives specifies one or more DNS servers.
529 .RE
530 .
531 .TP
532 \fBssl:\fIip\fR[\fB:\fIport\fR]
533 The specified SSL \fIport\fR (default: 6633) on the host at the given
534 \fIip\fR, which must be expressed as an IP address (not a DNS name).
535 SSL must be configured when this form is used (see \fBSSL
536 Configuration\fR, below).
537 .
538 .TP
539 \fBtcp:\fIip\fR[\fB:\fIport\fR]
540 The specified TCP \fIport\fR (default: 6633) on the host at the given
541 \fIip\fR, which must be expressed as an IP address (not a DNS name).
542 .
543 .TP
544 \fBunix:\fIfile\fR
545 The Unix domain server socket named \fIfile\fR.
546 .PP
547 The datapath ID used by the bridge to identify itself to the remote
548 controller may be specified as \fBbridge.\fIname\fB.datapath-id\fR,
549 in the form of exactly 12 hexadecimal digits.  If the datapath ID
550 is not specified, then it defaults to the bridge's MAC address (see
551 \fBBridge Configuration\fR, above, for information on how the bridge's
552 MAC address is chosen).
553 .ST "Local Port Network Configuration"
554 When an external controller is configured, but controller discovery is
555 not in use, the following additional settings are honored:
556 .TP
557 \fBbridge.\fIname\fB.controller.in-band=\fBtrue\fR|\fBfalse\fR
558 By default, or if this is set to \fBtrue\fR, \fBovs\-vswitchd\fR connects
559 to the controller in-band.  If this is set to \fBfalse\fR,
560 \fBovs\-vswitchd\fR connects to the controller out-of-band.  Refer to
561 \fBsecchan\fR(8) for a description of in-band and out-of-band control.
562 .IP "\fBbridge.\fIname\fB.controller.ip=\fIip\fR"
563 If specified, the IP address to configure on the bridge's local port.
564 .IP "\fBbridge.\fIname\fB.controller.netmask=\fInetmask\fR"
565 When an IP is specified, the corresponding netmask.  The default is
566 255.255.255.0 for a Class C IP address, 255.255.0.0 for Class B, and
567 255.0.0.0 for Class A.
568 .IP "\fBbridge.\fIname\fB.controller.gateway=\fIip\fR"
569 When an IP is specified, the corresponding IP gateway.  There is no
570 default gateway.
571 .ST "Controller Failure Settings"
572 The following additional settings take effect when any remote
573 controller is configured:
574 .IP "\fBbridge.\fIname\fB.controller.inactivity-probe=\fIsecs\fR"
575 This optional setting may be set to \fIsecs\fR, a number of seconds.
576 The minimum value of \fIsecs\fR is 5 seconds.  The default is taken
577 from \fBmgmt.inactivity-probe\fR (see above).
578 .IP
579 When the virtual switch is connected to the controller, it waits for a
580 message to be received from the controller for \fIsecs\fR seconds
581 before it sends a inactivity probe to the controller.  After sending
582 the inactivity probe, if no response is received for an additional
583 \fIsecs\fR seconds, the secure channel assumes that the connection has
584 been broken and attempts to reconnect.
585 .IP
586 Changing the inactivity probe interval also changes the interval
587 before entering standalone mode (see below).
588 .IP "\fBbridge.\fIname\fB.controller.fail-mode=\fBstandalone\fR|\fBsecure\fR"
589 .IQ "\fBmgmt.fail-mode=standalone\fR|\fBsecure\fR"
590 When a controller is configured, it is, ordinarily, responsible for
591 setting up all flows on the virtual switch.  Thus, if the connection to
592 the controller fails, no new network connections can be set up.  If
593 the connection to the controller stays down long enough, no packets
594 can pass through the switch at all.
595 .IP
596 The first of these that is set takes effect.
597 If the value is \fBstandalone\fR, or if neither of these settings
598 is set, \fBovs\-vswitchd\fR will take over
599 responsibility for setting up
600 flows when no message has been received from the controller for three
601 times the inactivity probe interval (see above).  In this mode,
602 \fBovs\-vswitchd\fR causes the datapath to act like an ordinary
603 MAC-learning switch.  \fBovs\-vswitchd\fR will continue to retry connecting
604 to the controller in the background and, when the connection succeeds,
605 it discontinues its standalone behavior.
606 .IP
607 If this option is set to \fBsecure\fR, \fBovs\-vswitchd\fR will not
608 set up flows on its own when the controller connection fails.
609 .IP "\fBbridge.\fIname\fB.controller.max-backoff=\fIsecs\fR"
610 Sets the maximum time between attempts to connect to the controller to
611 \fIsecs\fR, which must be at least 1.  The actual interval between
612 connection attempts starts at 1 second and doubles on each failing
613 attempt until it reaches the maximum.  The default maximum backoff
614 time is taken from \fBmgmt.max-backoff\fR.
615 .ST "Controller Rate-Limiting"
616 These settings configure how the virtual switch applies a ``token
617 bucket'' to limit the rate at which packets in unknown flows are
618 forwarded to the OpenFlow controller for flow-setup processing.  This
619 feature prevents a single bridge from overwhelming a controller.
620 .IP "\fBbridge.\fIname\fB.controller.rate-limit=\fIrate\fR"
621 .IQ "\fBmgmt.rate-limit=\fIrate\fR"
622 Limits the maximum rate at which packets will be forwarded to the
623 OpenFlow controller to \fIrate\fR packets per second.  A rate specified
624 explicitly for \fIname\fR overrides a value configured using the
625 \fBmgmt.rate-limit\fR key.
626 .IP
627 If neither one of these settings is set, then the bridge does not
628 limit the rate at which packets are forwarded to the controller.
629 .IP "\fBbridge.\fIname\fB.controller.burst-limit=\fIburst\fR"
630 .IQ "\fBmgmt.burst-limit=\fIburst\fR"
631 Sets the maximum number of unused packet credits that the bridge will
632 allow to accumulate during the time in which no packets are being
633 forwarded to the OpenFlow controller to \fIburst\fR (measured in
634 packets).  The default \fIburst\fR is one-quarter of the \fIrate\fR
635 specified in the rate-limit setting.
636 .IP
637 A burst specified explicitly for \fIname\fR overrides a value configured 
638 using the \fBmgmt.burst-limit\fR key.  This option takes effect only 
639 when a rate-limit is specified.
640 .ST "Remote Command Execution Settings"
641 These settings configure the commands that remote OpenFlow connections
642 are allowed to invoke using (e.g.) \fBovs\-ofctl execute\fR.  To be
643 permitted, a command name must be whitelisted and must not be
644 blacklisted.  When the whitelist and blacklist permit a command name,
645 \fBovs\-vswitchd\fR looks for a program with the same name as the command
646 in the commands directory (see below).  Other directories are not
647 searched.
648 .IP "\fBbridge.\fIname\fB.controller.commands.acl=\fIglob\fR"
649 Whitelists commands whose names match shell glob pattern \fIglob\fR,
650 allowing those commands to be invoked by the remote controller.
651 .IP
652 By default, no commands are whitelisted, so this setting is mandatory
653 if any remote command execution is to be allowed.
654 .IP "\fBbridge.\fIname\fB.controller.commands.acl=\fB!\fR\fIglob\fR"
655 Blacklists commands whose names match shell glob pattern \fIglob\fR,
656 prohibiting those commands from being invoked by the remote
657 controller.  Command names that include characters other than upper-
658 and lower-case English letters, digits, and the underscore and hyphen
659 characters are blacklisted unconditionally.
660 .IP "\fBbridge.\fIname\fB.controller.commands.dir=\fIdirectory\fR"
661 Sets the directory searched for remote command execution to
662 \fIdirectory\fR.  The default directory is
663 \fB@pkgdatadir@/commands\fR.
664 .SS "SSL Configuration"
665 When \fBovs\-vswitchd\fR is configured to connect over SSL for management or
666 for controller connectivity, the following settings are required:
667 .TP
668 \fBssl.private-key=\fIprivkey.pem\fR
669 Specifies a PEM file containing the private key used as the virtual
670 switch's identity for SSL connections to the controller.
671 .TP
672 \fBssl.certificate=\fIcert.pem\fR
673 Specifies a PEM file containing a certificate, signed by the
674 certificate authority (CA) used by the controller and manager, that
675 certifies the virtual switch's private key, identifying a trustworthy
676 switch.
677 .TP
678 \fBssl.ca-cert=\fIcacert.pem\fR
679 Specifies a PEM file containing the CA certificate used to verify that
680 the virtual switch is connected to a trustworthy controller.
681 .PP
682 These files are read only once, at \fBovs\-vswitchd\fR startup time.  If
683 their contents change, \fBovs\-vswitchd\fR must be killed and restarted.
684 .PP
685 These SSL settings apply to all SSL connections made by the virtual
686 switch.
687 .ST "CA Certificate Bootstrap"
688 Ordinarily, all of the files named in the SSL configuration must exist
689 when \fBovs\-vswitchd\fR starts.  However, if \fBssl.bootstrap-ca-cert\fR
690 is set to \fBtrue\fR, then \fBovs\-vswitchd\fR will attempt to obtain the
691 CA certificate from the controller on its first SSL connection and
692 save it to the named PEM file.  If it is successful, it will
693 immediately drop the connection and reconnect, and from then on all
694 SSL connections must be authenticated by a certificate signed by the
695 CA certificate thus obtained.
696 .PP
697 \fBThis option exposes the SSL connection to a man-in-the-middle
698 attack obtaining the initial CA certificate\fR, but it may be useful
699 for bootstrapping.
700 .PP
701 This option is only useful if the controller sends its CA certificate
702 as part of the SSL certificate chain.  The SSL protocol does not
703 require the controller to send the CA certificate, but
704 \fBcontroller\fR(8) can be configured to do so with the
705 \fB--peer-ca-cert\fR option.
706 .SS "OpenFlow Management Connections"
707 By default, each bridge \fIname\fR listens for OpenFlow management
708 connections on a Unix domain socket named
709 \fB@RUNDIR@/\fIname\fB.mgmt\fR.  This socket can be used to perform
710 local OpenFlow monitoring and administration, e.g., \fBovs\-ofctl dump-flows
711 unix:@RUNDIR@/\fIname\fB.mgmt\fR to display the flows currently set up
712 in bridge \fIname\fR.
713 .PP
714 If \fBbridge.\fIname\fB.openflow.listeners\fR is set to one or more
715 values, \fBovs\-vswitchd\fR instead listens on the specified connection
716 methods.  Acceptable connection methods include:
717 .RS
718 .IP "\fBpunix:\fIfile\fR"
719 Listens for connections on the Unix domain server socket named \fIfile\fR.
720 .IP "\fBpssl:\fR[\fIport\fR]"
721 Listens for SSL connections on \fIport\fR (default: 6633).  SSL must
722 be configured when this form is used (see \fBSSL Configuration\fR,
723 above).
724 .IP "\fBptcp:\fR[\fIport\fR]"
725 Listens for TCP connections on \fIport\fR (default: 6633).
726 .RE
727 To entirely disable listening for management connections, set
728 \fBbridge.\fIname\fB.openflow.listeners\fR to the single value
729 \fBnone\fR.
730
731 .SS "OpenFlow Controller Connection Snooping"
732 By default, each bridge \fIname\fR listens for OpenFlow controller
733 connection snooping connections on a Unix domain socket named
734 \fB@RUNDIR@/\fIname\fB.snoop\fR.  A client that connects to this
735 socket, e.g., \fBovs\-ofctl monitor unix:@RUNDIR@/\fIname\fB.snoop\fR, will
736 receive a copy of every OpenFlow message sent by the switch to the
737 controller, or vice versa, on the primary OpenFlow controller
738 connection.
739 .PP
740 If \fBbridge.\fIname\fB.openflow.snoops\fR is set to one or more
741 values, \fBovs\-vswitchd\fR instead listens on the specified connection
742 methods.  The acceptable connection methods are the same as for
743 OpenFlow management connections (see above).
744 .PP
745 To entirely disable controller connection snooping, set
746 \fBbridge.\fIname\fB.openflow.snoops\fR to the single value
747 \fBnone\fR.
748 .SH "SEE ALSO"
749 .BR ovs\-brcompatd (8),
750 .BR ovs\-cfg\-mod (8),
751 .BR ovs\-vswitchd (8)