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