]>
Commit | Line | Data |
---|---|---|
3b135da3 BP |
1 | .\" -*- nroff -*- |
2 | .de IQ | |
3 | . br | |
4 | . ns | |
5 | . IP "\\$1" | |
6 | .. | |
5aa00635 JP |
7 | .de ST |
8 | . PP | |
9 | . RS -0.15in | |
10 | . I "\\$1" | |
11 | . RE | |
5aa00635 | 12 | .. |
3fbe1d30 | 13 | .TH ovs\-vsctl 8 "November 2009" "Open vSwitch" "Open vSwitch Manual" |
812560d7 | 14 | .\" This program's name: |
3b135da3 | 15 | .ds PN ovs\-vsctl |
812560d7 BP |
16 | .\" SSL peer program's name: |
17 | .ds SN ovsdb\-server | |
3b135da3 BP |
18 | . |
19 | .SH NAME | |
20 | ovs\-vsctl \- utility for querying and configuring \fBovs\-vswitchd\fR | |
21 | . | |
22 | .SH SYNOPSIS | |
204bad29 BP |
23 | \fBovs\-vsctl\fR [\fIoptions\fR] \fB\-\-\fR [\fIoptions\fR] \fIcommand |
24 | \fR[\fIargs\fR] [\fB\-\-\fR [\fIoptions\fR] \fIcommand \fR[\fIargs\fR]]... | |
3b135da3 BP |
25 | . |
26 | .SH DESCRIPTION | |
dfbe07ba | 27 | The \fBovs\-vsctl\fR program configures \fBovs\-vswitchd\fR(8) by |
204bad29 | 28 | providing a high\-level interface to its configuration |
dfbe07ba BP |
29 | database. This program is mainly intended for use when |
30 | \fBovs\-vswitchd\fR is running. If it is used when | |
31 | \fBovs\-vswitchd\fR is not running, then \fB\-\-no\-wait\fR should be | |
32 | specified and configuration changes will only take effect when | |
33 | \fBovs\-vswitchd\fR is started. | |
3b135da3 | 34 | .PP |
dfbe07ba BP |
35 | By default, each time \fBovs\-vsctl\fR runs, it connects to an |
36 | \fBovsdb\-server\fR process that maintains an Open vSwitch | |
37 | configuration database. Using this connection, it queries and | |
38 | possibly applies changes to the database, depending on the supplied | |
39 | commands. Then, if it applied any changes, it waits until | |
40 | \fBovs\-vswitchd\fR has finished reconfiguring itself before it exits. | |
460aad80 BP |
41 | .PP |
42 | \fBovs\-vsctl\fR can perform any number of commands in a single run, | |
43 | implemented as a single atomic transaction against the database. | |
204bad29 BP |
44 | .PP |
45 | The \fBovs\-vsctl\fR command line begins with global options (see | |
46 | \fBOPTIONS\fR below for details). The global options are followed by | |
47 | one or more commands. Each command should begin with \fB\-\-\fR by | |
48 | itself as a command-line argument, to separate it from the global | |
49 | options and following commands. (If the first command does not have | |
50 | any options, then the first \fB\-\-\fR may be omitted.) The command | |
51 | itself starts with command-specific options, if any, followed by the | |
52 | command name and any arguments. See \fBEXAMPLES\fR below for syntax | |
53 | examples. | |
3b135da3 BP |
54 | . |
55 | .SS "Linux VLAN Bridging Compatibility" | |
56 | The \fBovs\-vsctl\fR program supports the model of a bridge | |
57 | implemented by Open vSwitch, in which a single bridge supports ports | |
58 | on multiple VLANs. In this model, each port on a bridge is either a | |
59 | trunk port that potentially passes packets tagged with 802.1Q headers | |
60 | that designate VLANs or it is assigned a single implicit VLAN that is | |
61 | never tagged with an 802.1Q header. | |
62 | .PP | |
63 | For compatibility with software designed for the Linux bridge, | |
64 | \fBovs\-vsctl\fR also supports a model in which traffic associated | |
65 | with a given 802.1Q VLAN is segregated into a separate bridge. A | |
66 | special form of the \fBadd\-br\fR command (see below) creates a ``fake | |
67 | bridge'' within an Open vSwitch bridge to simulate this behavior. | |
68 | When such a ``fake bridge'' is active, \fBovs\-vsctl\fR will treat it | |
69 | much like a bridge separate from its ``parent bridge,'' but the actual | |
70 | implementation in Open vSwitch uses only a single bridge, with ports on | |
71 | the fake bridge assigned the implicit VLAN of the fake bridge of which | |
5341d046 BP |
72 | they are members. (A fake bridge for VLAN 0 receives packets that |
73 | have no 802.1Q tag or a tag with VLAN 0.) | |
3b135da3 BP |
74 | . |
75 | .SH OPTIONS | |
76 | . | |
460aad80 BP |
77 | The following options affect the behavior \fBovs\-vsctl\fR as a whole. |
78 | Some individual commands also accept their own options, which are | |
79 | given just before the command name. If the first command on the | |
80 | command line has options, then those options must be separated from | |
81 | the global options by \fB\-\-\fR. | |
3b135da3 | 82 | . |
dfbe07ba BP |
83 | .IP "\fB\-\-db=\fIserver\fR" |
84 | Sets \fIserver\fR as the database server that \fBovs\-vsctl\fR | |
85 | contacts to query or modify configuration. The default is | |
bc391960 | 86 | \fBunix:@RUNDIR@/db.sock\fR. \fIserver\fR must take one of the |
dfbe07ba BP |
87 | following forms: |
88 | .RS | |
9467fe62 | 89 | .so ovsdb/remote-active.man |
c9f3f37a | 90 | .so ovsdb/remote-passive.man |
dfbe07ba | 91 | .RE |
9467fe62 | 92 | . |
dfbe07ba BP |
93 | .IP "\fB\-\-no\-wait\fR" |
94 | Prevents \fBovs\-vsctl\fR from waiting for \fBovs\-vswitchd\fR to | |
95 | reconfigure itself according to the the modified database. This | |
96 | option should be used if \fBovs\-vswitchd\fR is not running; | |
4e312e69 | 97 | otherwise, \fBovs\-vsctl\fR will not exit until \fBovs\-vswitchd\fR |
dfbe07ba | 98 | starts. |
3b135da3 | 99 | .IP |
dfbe07ba BP |
100 | This option has no effect if the commands specified do not change the |
101 | database. | |
3b135da3 | 102 | . |
37c84020 BP |
103 | .IP "\fB\-\-no\-syslog\fR" |
104 | By default, \fBovs\-vsctl\fR logs its arguments and the details of any | |
105 | changes that it makes to the system log. This option disables this | |
106 | logging. | |
dfbe07ba | 107 | .IP |
ae9a3235 | 108 | This option is equivalent to \fB\-\-verbose=vsctl:syslog:warn\fR. |
dfbe07ba | 109 | . |
2792c2ad | 110 | .IP "\fB\-\-oneline\fR" |
4d14e30f | 111 | Modifies the output format so that the output for each command is printed |
2792c2ad | 112 | on a single line. New-line characters that would otherwise separate |
4d14e30f | 113 | lines are printed as \fB\\n\fR, and any instances of \fB\\\fR that |
2792c2ad | 114 | would otherwise appear in the output are doubled. |
4d14e30f | 115 | Prints a blank line for each command that has no output. |
e051b42c BP |
116 | This option does not affect the formatting of output from the |
117 | \fBlist\fR or \fBfind\fR commands; see \fBTable Formatting Options\fR | |
118 | below. | |
37c84020 | 119 | . |
577aebdf BP |
120 | .IP "\fB\-\-dry\-run\fR" |
121 | Prevents \fBovs\-vsctl\fR from actually modifying the database. | |
122 | . | |
4e312e69 BP |
123 | .IP "\fB\-t \fIsecs\fR" |
124 | .IQ "\fB\-\-timeout=\fIsecs\fR" | |
6b7b9d34 BP |
125 | By default, or with a \fIsecs\fR of \fB0\fR, \fBovs\-vsctl\fR waits |
126 | forever for a response from the database. This option limits runtime | |
127 | to approximately \fIsecs\fR seconds. If the timeout expires, | |
128 | \fBovs\-vsctl\fR will exit with a \fBSIGALRM\fR signal. (A timeout | |
129 | would normally happen only if the database cannot be contacted, or if | |
130 | the system is overloaded.) | |
342045e1 | 131 | . |
e051b42c BP |
132 | .SS "Table Formatting Options" |
133 | These options control the format of output from the \fBlist\fR and | |
134 | \fBfind\fR commands. | |
135 | .so lib/table.man | |
136 | . | |
ac300505 | 137 | .SS "Public Key Infrastructure Options" |
84ee7bcf | 138 | .so lib/ssl.man |
812560d7 BP |
139 | .so lib/ssl-bootstrap.man |
140 | .so lib/ssl-peer-ca-cert.man | |
dfbe07ba BP |
141 | .so lib/vlog.man |
142 | . | |
3b135da3 BP |
143 | .SH COMMANDS |
144 | The commands implemented by \fBovs\-vsctl\fR are described in the | |
145 | sections below. | |
524555d1 BP |
146 | .SS "Open vSwitch Commands" |
147 | These commands work with an Open vSwitch as a whole. | |
148 | . | |
149 | .IP "\fBinit\fR" | |
150 | Initializes the Open vSwitch database, if it is empty. If the | |
151 | database has already been initialized, this command has no effect. | |
152 | .IP | |
153 | Any successful \fBovs\-vsctl\fR command automatically initializes the | |
154 | Open vSwitch database if it is empty. This command is provided to | |
155 | initialize the database without executing any other command. | |
3b135da3 | 156 | . |
9b1735a7 BP |
157 | .IP "\fBshow\fR" |
158 | Prints a brief overview of the database contents. | |
159 | . | |
18ee958b | 160 | .IP "\fBemer\-reset\fR" |
26b31540 BP |
161 | Reset the configuration into a clean state. It deconfigures OpenFlow |
162 | controllers, OVSDB servers, and SSL, and deletes port mirroring, | |
f67e3b66 EJ |
163 | \fBfail_mode\fR, NetFlow, and sFlow configuration. This command also |
164 | removes all \fBother\-config\fR keys from all database records, except | |
165 | that \fBother\-config:hwaddr\fR is preserved if it is present in a | |
166 | Bridge record. Other networking configuration is left as-is. | |
18ee958b | 167 | . |
3b135da3 BP |
168 | .SS "Bridge Commands" |
169 | These commands examine and manipulate Open vSwitch bridges. | |
170 | . | |
aeee85aa | 171 | .IP "[\fB\-\-may\-exist\fR] \fBadd\-br \fIbridge\fR" |
3b135da3 BP |
172 | Creates a new bridge named \fIbridge\fR. Initially the bridge will |
173 | have no ports (other than \fIbridge\fR itself). | |
aeee85aa BP |
174 | .IP |
175 | Without \fB\-\-may\-exist\fR, attempting to create a bridge that | |
cefb3cc6 BP |
176 | exists is an error. With \fB\-\-may\-exist\fR, this command does |
177 | nothing if \fIbridge\fR already exists as a real bridge. | |
3b135da3 | 178 | . |
aeee85aa | 179 | .IP "[\fB\-\-may\-exist\fR] \fBadd\-br \fIbridge parent vlan\fR" |
3b135da3 BP |
180 | Creates a ``fake bridge'' named \fIbridge\fR within the existing Open |
181 | vSwitch bridge \fIparent\fR, which must already exist and must not | |
182 | itself be a fake bridge. The new fake bridge will be on 802.1Q VLAN | |
5341d046 | 183 | \fIvlan\fR, which must be an integer between 0 and 4095. Initially |
3b135da3 | 184 | \fIbridge\fR will have no ports (other than \fIbridge\fR itself). |
aeee85aa BP |
185 | .IP |
186 | Without \fB\-\-may\-exist\fR, attempting to create a bridge that | |
cefb3cc6 BP |
187 | exists is an error. With \fB\-\-may\-exist\fR, this command does |
188 | nothing if \fIbridge\fR already exists as a VLAN bridge under | |
189 | \fIparent\fR for \fIvlan\fR. | |
3b135da3 | 190 | . |
460aad80 | 191 | .IP "[\fB\-\-if\-exists\fR] \fBdel\-br \fIbridge\fR" |
3b135da3 BP |
192 | Deletes \fIbridge\fR and all of its ports. If \fIbridge\fR is a real |
193 | bridge, this command also deletes any fake bridges that were created | |
194 | with \fIbridge\fR as parent, including all of their ports. | |
460aad80 BP |
195 | .IP |
196 | Without \fB\-\-if\-exists\fR, attempting to delete a bridge that does | |
197 | not exist is an error. With \fB\-\-if\-exists\fR, attempting to | |
198 | delete a bridge that does not exist has no effect. | |
3b135da3 BP |
199 | . |
200 | .IP "\fBlist\-br\fR" | |
201 | Lists all existing real and fake bridges on standard output, one per | |
202 | line. | |
203 | . | |
204 | .IP "\fBbr\-exists \fIbridge\fR" | |
205 | Tests whether \fIbridge\fR exists as a real or fake bridge. If so, | |
206 | \fBovs\-vsctl\fR exits successfully with exit code 0. If not, | |
207 | \fBovs\-vsctl\fR exits unsuccessfully with exit code 2. | |
208 | . | |
8e58fa9a BP |
209 | .IP "\fBbr\-to\-vlan \fIbridge\fR" |
210 | If \fIbridge\fR is a fake bridge, prints the bridge's 802.1Q VLAN as a | |
211 | decimal integer. If \fIbridge\fR is a real bridge, prints 0. | |
212 | . | |
213 | .IP "\fBbr\-to\-parent \fIbridge\fR" | |
214 | If \fIbridge\fR is a fake bridge, prints the name of its parent | |
215 | bridge. If \fIbridge\fR is a real bridge, print \fIbridge\fR. | |
216 | . | |
457e1eb0 BP |
217 | .IP "\fBbr\-set\-external\-id \fIbridge key\fR [\fIvalue\fR]" |
218 | Sets or clears an ``external ID'' value on \fIbridge\fR. These values | |
219 | are intended to identify entities external to Open vSwitch with which | |
220 | \fIbridge\fR is associated, e.g. the bridge's identifier in a | |
221 | virtualization management platform. The Open vSwitch database schema | |
222 | specifies well-known \fIkey\fR values, but \fIkey\fR and \fIvalue\fR | |
223 | are otherwise arbitrary strings. | |
224 | .IP | |
225 | If \fIvalue\fR is specified, then \fIkey\fR is set to \fIvalue\fR for | |
226 | \fIbridge\fR, overwriting any previous value. If \fIvalue\fR is | |
227 | omitted, then \fIkey\fR is removed from \fIbridge\fR's set of external | |
228 | IDs (if it was present). | |
e328faad BP |
229 | .IP |
230 | For real bridges, the effect of this command is similar to that of a | |
231 | \fBset\fR or \fBremove\fR command in the \fBexternal\-ids\fR column of | |
232 | the \fBBridge\fR table. For fake bridges, it actually modifies keys | |
233 | with names prefixed by \fBfake\-bridge\-\fR in the \fBPort\fR table. | |
457e1eb0 BP |
234 | . |
235 | .IP "\fBbr\-get\-external\-id \fIbridge\fR [\fIkey\fR]" | |
236 | Queries the external IDs on \fIbridge\fR. If \fIkey\fR is specified, | |
237 | the output is the value for that \fIkey\fR or the empty string if | |
238 | \fIkey\fR is unset. If \fIkey\fR is omitted, the output is | |
239 | \fIkey\fB=\fIvalue\fR, one per line, for each key-value pair. | |
e328faad BP |
240 | .IP |
241 | For real bridges, the effect of this command is similar to that of a | |
242 | \fBget\fR command in the \fBexternal\-ids\fR column of the | |
243 | \fBBridge\fR table. For fake bridges, it queries keys with names | |
244 | prefixed by \fBfake\-bridge\-\fR in the \fBPort\fR table. | |
457e1eb0 | 245 | . |
3b135da3 BP |
246 | .SS "Port Commands" |
247 | . | |
248 | These commands examine and manipulate Open vSwitch ports. These | |
249 | commands treat a bonded port as a single entity. | |
250 | . | |
251 | .IP "\fBlist\-ports \fIbridge\fR" | |
252 | Lists all of the ports within \fIbridge\fR on standard output, one per | |
253 | line. The local port \fIbridge\fR is not included in the list. | |
254 | . | |
18b239f5 | 255 | .IP "[\fB\-\-may\-exist\fR] \fBadd\-port \fIbridge port \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fR=\fIvalue\fR]\&...\fR" |
3b135da3 BP |
256 | Creates on \fIbridge\fR a new port named \fIport\fR from the network |
257 | device of the same name. | |
bb1c67c8 | 258 | .IP |
18b239f5 BP |
259 | Optional arguments set values of column in the Port record created by |
260 | the command. For example, \fBtag=9\fR would make the port an access | |
261 | port for VLAN 9. The syntax is the same as that for the \fBset\fR | |
262 | command (see \fBDatabase Commands\fR below). | |
263 | .IP | |
bb1c67c8 | 264 | Without \fB\-\-may\-exist\fR, attempting to create a port that exists |
cefb3cc6 BP |
265 | is an error. With \fB\-\-may\-exist\fR, this command does nothing if |
266 | \fIport\fR already exists on \fIbridge\fR and is not a bonded port. | |
3b135da3 | 267 | . |
18b239f5 | 268 | .IP "[\fB\-\-fake\-iface\fR] \fBadd\-bond \fIbridge port iface\fR\&... [\fIcolumn\fR[\fB:\fIkey\fR]\fR=\fIvalue\fR]\&...\fR" |
3b135da3 BP |
269 | Creates on \fIbridge\fR a new port named \fIport\fR that bonds |
270 | together the network devices given as each \fIiface\fR. At least two | |
271 | interfaces must be named. | |
b4182c7f | 272 | .IP |
18b239f5 BP |
273 | Optional arguments set values of column in the Port record created by |
274 | the command. The syntax is the same as that for the \fBset\fR command | |
275 | (see \fBDatabase Commands\fR below). | |
276 | .IP | |
b4182c7f JP |
277 | With \fB\-\-fake\-iface\fR, a fake interface with the name \fIport\fR is |
278 | created. This should only be used for compatibility with legacy | |
279 | software that requires it. | |
bb1c67c8 BP |
280 | .IP |
281 | Without \fB\-\-may\-exist\fR, attempting to create a port that exists | |
cefb3cc6 BP |
282 | is an error. With \fB\-\-may\-exist\fR, this command does nothing if |
283 | \fIport\fR already exists on \fIbridge\fR and bonds together exactly | |
284 | the specified interfaces. | |
3b135da3 | 285 | . |
460aad80 | 286 | .IP "[\fB\-\-if\-exists\fR] \fBdel\-port \fR[\fIbridge\fR] \fIport\fR" |
3d1b9636 BP |
287 | Deletes \fIport\fR. If \fIbridge\fR is omitted, \fIport\fR is removed |
288 | from whatever bridge contains it; if \fIbridge\fR is specified, it | |
289 | must be the real or fake bridge that contains \fIport\fR. | |
460aad80 BP |
290 | .IP |
291 | Without \fB\-\-if\-exists\fR, attempting to delete a port that does | |
292 | not exist is an error. With \fB\-\-if\-exists\fR, attempting to | |
293 | delete a port that does not exist has no effect. | |
3b135da3 | 294 | . |
7c79588e BP |
295 | .IP "[\fB\-\-if\-exists\fR] \fB\-\-with\-iface del\-port \fR[\fIbridge\fR] \fIiface\fR" |
296 | Deletes the port named \fIiface\fR or that has an interface named | |
297 | \fIiface\fR. If \fIbridge\fR is omitted, the port is removed from | |
298 | whatever bridge contains it; if \fIbridge\fR is specified, it must be | |
299 | the real or fake bridge that contains the port. | |
300 | .IP | |
301 | Without \fB\-\-if\-exists\fR, attempting to delete the port for an | |
302 | interface that does not exist is an error. With \fB\-\-if\-exists\fR, | |
303 | attempting to delete the port for an interface that does not exist has | |
304 | no effect. | |
305 | . | |
3b135da3 BP |
306 | .IP "\fBport\-to\-br \fIport\fR" |
307 | Prints the name of the bridge that contains \fIport\fR on standard | |
308 | output. | |
309 | . | |
310 | .SS "Interface Commands" | |
311 | . | |
312 | These commands examine the interfaces attached to an Open vSwitch | |
313 | bridge. These commands treat a bonded port as a collection of two or | |
314 | more interfaces, rather than as a single port. | |
315 | . | |
316 | .IP "\fBlist\-ifaces \fIbridge\fR" | |
317 | Lists all of the interfaces within \fIbridge\fR on standard output, | |
318 | one per line. The local port \fIbridge\fR is not included in the | |
319 | list. | |
320 | . | |
321 | .IP "\fBiface\-to\-br \fIiface\fR" | |
322 | Prints the name of the bridge that contains \fIiface\fR on standard | |
323 | output. | |
457e1eb0 | 324 | . |
5aa00635 JP |
325 | .SS "OpenFlow Controller Connectivity" |
326 | . | |
327 | \fBovs\-vswitchd\fR can perform all configured bridging and switching | |
c0de82d9 JP |
328 | locally, or it can be configured to communicate with one or more |
329 | external OpenFlow controllers. The switch is typically configured to | |
330 | connect to a primary controller that takes charge of the bridge's flow | |
331 | table to implement a network policy. In addition, the switch can be | |
332 | configured to listen to connections from service controllers. Service | |
333 | controllers are typically used for occasional support and maintenance, | |
334 | e.g. with \fBovs\-ofctl\fR. | |
5aa00635 | 335 | . |
1a048029 | 336 | .IP "\fBget\-controller\fR \fIbridge\fR" |
5aa00635 JP |
337 | Prints the configured controller target. |
338 | . | |
1a048029 | 339 | .IP "\fBdel\-controller\fR \fIbridge\fR" |
5aa00635 JP |
340 | Deletes the configured controller target. |
341 | . | |
1a048029 JP |
342 | .IP "\fBset\-controller\fR \fIbridge\fR \fItarget\fR\&..." |
343 | Sets the configured controller target or targets. Each \fItarget\fR may | |
344 | use any of the following forms: | |
5aa00635 JP |
345 | . |
346 | .RS | |
84ee7bcf | 347 | .so lib/vconn-active.man |
c0de82d9 | 348 | .so lib/vconn-passive.man |
5aa00635 | 349 | .RE |
84ee7bcf | 350 | . |
5aa00635 | 351 | .ST "Controller Failure Settings" |
89365653 | 352 | .PP |
5aa00635 JP |
353 | When a controller is configured, it is, ordinarily, responsible for |
354 | setting up all flows on the switch. Thus, if the connection to | |
355 | the controller fails, no new network connections can be set up. If | |
356 | the connection to the controller stays down long enough, no packets | |
357 | can pass through the switch at all. | |
63f08492 | 358 | .PP |
5aa00635 JP |
359 | If the value is \fBstandalone\fR, or if neither of these settings |
360 | is set, \fBovs\-vswitchd\fR will take over | |
361 | responsibility for setting up | |
362 | flows when no message has been received from the controller for three | |
dd1dcc23 | 363 | times the inactivity probe interval. In this mode, |
5aa00635 JP |
364 | \fBovs\-vswitchd\fR causes the datapath to act like an ordinary |
365 | MAC-learning switch. \fBovs\-vswitchd\fR will continue to retry connecting | |
366 | to the controller in the background and, when the connection succeeds, | |
367 | it discontinues its standalone behavior. | |
63f08492 | 368 | .PP |
5aa00635 JP |
369 | If this option is set to \fBsecure\fR, \fBovs\-vswitchd\fR will not |
370 | set up flows on its own when the controller connection fails. | |
371 | . | |
1a048029 | 372 | .IP "\fBget\-fail\-mode\fR \fIbridge\fR" |
5aa00635 JP |
373 | Prints the configured failure mode. |
374 | . | |
1a048029 | 375 | .IP "\fBdel\-fail\-mode\fR \fIbridge\fR" |
5aa00635 JP |
376 | Deletes the configured failure mode. |
377 | . | |
1a048029 | 378 | .IP "\fBset\-fail\-mode\fR \fIbridge\fR \fBstandalone\fR|\fBsecure\fR" |
5aa00635 JP |
379 | Sets the configured failure mode. |
380 | . | |
24b8b259 AE |
381 | .SS "Manager Connectivity" |
382 | . | |
289df16d AE |
383 | These commands manipulate the \fBmanager_options\fR column in the |
384 | \fBOpen_vSwitch\fR table and rows in the \fBManagers\fR table. When | |
385 | \fBovsdb\-server\fR is configured to use the \fBmanager_options\fR column for | |
386 | OVSDB connections (as described in \fBINSTALL.Linux\fR and in the startup | |
387 | scripts provided with Open vSwitch), this allows the administrator to use | |
24b8b259 AE |
388 | \fBovs\-vsctl\fR to configure database connections. |
389 | . | |
390 | .IP "\fBget\-manager\fR" | |
391 | Prints the configured manager(s). | |
392 | . | |
393 | .IP "\fBdel\-manager\fR" | |
394 | Deletes the configured manager(s). | |
395 | . | |
396 | .IP "\fBset\-manager\fR \fItarget\fR\&..." | |
397 | Sets the configured manager target or targets. Each \fItarget\fR may | |
398 | use any of the following forms: | |
399 | . | |
400 | .RS | |
401 | .so ovsdb/remote-active.man | |
402 | .so ovsdb/remote-passive.man | |
403 | .RE | |
404 | . | |
dd8ac6fe JP |
405 | .SS "SSL Configuration" |
406 | When \fBovs\-vswitchd\fR is configured to connect over SSL for management or | |
407 | controller connectivity, the following parameters are required: | |
408 | .TP | |
ae9a3235 | 409 | \fIprivate-key\fR |
dd8ac6fe JP |
410 | Specifies a PEM file containing the private key used as the virtual |
411 | switch's identity for SSL connections to the controller. | |
412 | .TP | |
ae9a3235 | 413 | \fIcertificate\fR |
dd8ac6fe JP |
414 | Specifies a PEM file containing a certificate, signed by the |
415 | certificate authority (CA) used by the controller and manager, that | |
416 | certifies the virtual switch's private key, identifying a trustworthy | |
417 | switch. | |
418 | .TP | |
ae9a3235 | 419 | \fIca-cert\fR |
dd8ac6fe JP |
420 | Specifies a PEM file containing the CA certificate used to verify that |
421 | the virtual switch is connected to a trustworthy controller. | |
422 | .PP | |
423 | These files are read only once, at \fBovs\-vswitchd\fR startup time. If | |
424 | their contents change, \fBovs\-vswitchd\fR must be killed and restarted. | |
425 | .PP | |
426 | These SSL settings apply to all SSL connections made by the virtual | |
427 | switch. | |
428 | . | |
429 | .IP "\fBget\-ssl\fR" | |
430 | Prints the SSL configuration. | |
431 | . | |
432 | .IP "\fBdel\-ssl\fR" | |
433 | Deletes the current SSL configuration. | |
434 | . | |
435 | .IP "[\fB\-\-bootstrap\fR] \fBset\-ssl\fR \fIprivate-key\fR \fIcertificate\fR \fIca-cert\fR" | |
436 | Sets the SSL configuration. The \fB\-\-bootstrap\fR option is described | |
437 | below. | |
438 | . | |
439 | .ST "CA Certificate Bootstrap" | |
89365653 | 440 | .PP |
dd8ac6fe | 441 | Ordinarily, all of the files named in the SSL configuration must exist |
40a09c8a BP |
442 | when \fBovs\-vswitchd\fR starts. However, if the \fIca-cert\fR file |
443 | does not exist and the \fB\-\-bootstrap\fR | |
dd8ac6fe JP |
444 | option is given, then \fBovs\-vswitchd\fR will attempt to obtain the |
445 | CA certificate from the controller on its first SSL connection and | |
446 | save it to the named PEM file. If it is successful, it will | |
447 | immediately drop the connection and reconnect, and from then on all | |
448 | SSL connections must be authenticated by a certificate signed by the | |
449 | CA certificate thus obtained. | |
450 | .PP | |
451 | \fBThis option exposes the SSL connection to a man-in-the-middle | |
452 | attack obtaining the initial CA certificate\fR, but it may be useful | |
453 | for bootstrapping. | |
454 | .PP | |
455 | This option is only useful if the controller sends its CA certificate | |
456 | as part of the SSL certificate chain. The SSL protocol does not | |
457 | require the controller to send the CA certificate, but | |
a946ed39 | 458 | \fBovs\-controller\fR(8) can be configured to do so with the |
4e312e69 | 459 | \fB\-\-peer\-ca\-cert\fR option. |
dd8ac6fe | 460 | . |
ad83bfa6 BP |
461 | .SS "Database Commands" |
462 | . | |
463 | These commands query and modify the contents of \fBovsdb\fR tables. | |
464 | They are a slight abstraction of the \fBovsdb\fR interface and as such | |
465 | they operate at a lower level than other \fBovs\-vsctl\fR commands. | |
466 | .PP | |
467 | .ST "Identifying Tables, Records, and Columns" | |
468 | .PP | |
469 | Each of these commands has a \fItable\fR parameter to identify a table | |
470 | within the database. Many of them also take a \fIrecord\fR parameter | |
471 | that identifies a particular record within a table. The \fIrecord\fR | |
472 | parameter may be the UUID for a record, and many tables offer | |
473 | additional ways to identify records. Some commands also take | |
474 | \fIcolumn\fR parameters that identify a particular field within the | |
475 | records in a table. | |
476 | .PP | |
477 | The following tables are currently defined: | |
478 | .IP "\fBOpen_vSwitch\fR" | |
479 | Global configuration for an \fBovs\-vswitchd\fR. This table contains | |
480 | exactly one record, identified by specifying \fB.\fR as the record | |
481 | name. | |
482 | .IP "\fBBridge\fR" | |
483 | Configuration for a bridge within an Open vSwitch. Records may be | |
484 | identified by bridge name. | |
485 | .IP "\fBPort\fR" | |
486 | A bridge port. Records may be identified by port name. | |
487 | .IP "\fBInterface\fR" | |
488 | A network device attached to a port. Records may be identified by | |
489 | name. | |
254750ce BP |
490 | .IP "\fBFlow_Table\fR" |
491 | Configuration for a particular OpenFlow flow table. Records may be | |
492 | identified by name. | |
7b63fa03 | 493 | .IP "\fBQoS\fR" |
c5f341ab BP |
494 | Quality-of-service configuration for a \fBPort\fR. Records may be |
495 | identified by port name. | |
7b63fa03 | 496 | .IP "\fBQueue\fR" |
c5f341ab BP |
497 | Configuration for one queue within a \fBQoS\fR configuration. Records |
498 | may only be identified by UUID. | |
ef1e753e BP |
499 | .IP "\fBMirror\fR" |
500 | A port mirroring configuration attached to a bridge. Records may be | |
501 | identified by mirror name. | |
ad83bfa6 BP |
502 | .IP "\fBController\fR" |
503 | Configuration for an OpenFlow controller. A controller attached to a | |
1a048029 | 504 | particular bridge may be identified by the bridge's name. |
94db5407 BP |
505 | .IP "\fBManager\fR" |
506 | Configuration for an OVSDB connection. Records may be identified | |
507 | by target (e.g. \fBtcp:1.2.3.4\fR). | |
ad83bfa6 BP |
508 | .IP "\fBNetFlow\fR" |
509 | A NetFlow configuration attached to a bridge. Records may be | |
ef1e753e BP |
510 | identified by bridge name. |
511 | .IP "\fBSSL\fR" | |
512 | The global SSL configuration for \fBovs\-vswitchd\fR. The record | |
513 | attached to the \fBOpen_vSwitch\fR table may be identified by | |
514 | specifying \fB.\fR as the record name. | |
515 | .IP "\fBsFlow\fR" | |
516 | An sFlow configuration attached to a bridge. Records may be | |
ad83bfa6 BP |
517 | identified by bridge name. |
518 | .PP | |
e111e681 BP |
519 | Record names must be specified in full and with correct |
520 | capitalization. Names of tables and columns are not case-sensitive, | |
521 | and \fB\-\-\fR and \fB_\fR are treated interchangeably. Unique | |
5de48440 | 522 | abbreviations are acceptable, e.g. \fBnet\fR or \fBn\fR is sufficient |
ad83bfa6 BP |
523 | to identify the \fBNetFlow\fR table. |
524 | . | |
525 | .ST "Database Values" | |
89365653 | 526 | .PP |
ad83bfa6 BP |
527 | Each column in the database accepts a fixed type of data. The |
528 | currently defined basic types, and their representations, are: | |
529 | .IP "integer" | |
530 | A decimal integer in the range \-2**63 to 2**63\-1, inclusive. | |
531 | .IP "real" | |
532 | A floating-point number. | |
533 | .IP "Boolean" | |
534 | True or false, written \fBtrue\fR or \fBfalse\fR, respectively. | |
535 | .IP "string" | |
536 | An arbitrary Unicode string, except that null bytes are not allowed. | |
537 | Quotes are optional for most strings that begin with an English letter | |
538 | or underscore and consist only of letters, underscores, hyphens, and | |
539 | periods. However, \fBtrue\fR and \fBfalse\fR and strings that match | |
540 | the syntax of UUIDs (see below) must be enclosed in double quotes to | |
541 | distinguish them from other basic types. When double quotes are used, | |
542 | the syntax is that of strings in JSON, e.g. backslashes may be used to | |
543 | escape special characters. The empty string must be represented as a | |
544 | pair of double quotes (\fB""\fR). | |
545 | .IP "UUID" | |
ce5a3e38 BP |
546 | Either a universally unique identifier in the style of RFC 4122, |
547 | e.g. \fBf81d4fae\-7dec\-11d0\-a765\-00a0c91e6bf6\fR, or an \fB@\fIname\fR | |
aed133bf | 548 | defined by a \fBget\fR or \fBcreate\fR command within the same \fBovs\-vsctl\fR |
ce5a3e38 | 549 | invocation. |
ad83bfa6 BP |
550 | .PP |
551 | Multiple values in a single column may be separated by spaces or a | |
552 | single comma. When multiple values are present, duplicates are not | |
553 | allowed, and order is not important. Conversely, some database | |
554 | columns can have an empty set of values, represented as \fB[]\fR, and | |
555 | square brackets may optionally enclose other non-empty sets or single | |
556 | values as well. | |
557 | .PP | |
558 | A few database columns are ``maps'' of key-value pairs, where the key | |
559 | and the value are each some fixed database type. These are specified | |
560 | in the form \fIkey\fB=\fIvalue\fR, where \fIkey\fR and \fIvalue\fR | |
561 | follow the syntax for the column's key type and value type, | |
562 | respectively. When multiple pairs are present (separated by spaces or | |
563 | a comma), duplicate keys are not allowed, and again the order is not | |
564 | important. Duplicate values are allowed. An empty map is represented | |
424202bc BP |
565 | as \fB{}\fR. Curly braces may optionally enclose non-empty maps as |
566 | well (but use quotes to prevent the shell from expanding | |
567 | \fBother-config={0=x,1=y}\fR into \fBother-config=0=x | |
568 | other-config=1=y\fR, which may not have the desired effect). | |
ad83bfa6 BP |
569 | . |
570 | .ST "Database Command Syntax" | |
9591fefe BP |
571 | .IP "[\fB\-\-columns=\fIcolumn\fR[\fB,\fIcolumn\fR]...] \fBlist \fItable \fR[\fIrecord\fR]..." |
572 | Lists the data in each specified \fIrecord\fR. If no | |
ad83bfa6 | 573 | records are specified, lists all the records in \fItable\fR. |
3ef917b5 | 574 | .IP |
9591fefe BP |
575 | If \fB\-\-columns\fR is specified, only the requested columns are |
576 | listed, in the specified order. Otherwise, all columns are listed, in | |
577 | alphabetical order by column name. | |
578 | . | |
0a140468 BP |
579 | .IP "[\fB\-\-columns=\fIcolumn\fR[\fB,\fIcolumn\fR]...] \fBfind \fItable \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR]..." |
580 | Lists the data in each record in \fItable\fR whose \fIcolumn\fR equals | |
581 | \fIvalue\fR or, if \fIkey\fR is specified, whose \fIcolumn\fR contains | |
2a9537e2 BP |
582 | a \fIkey\fR with the specified \fIvalue\fR. The following operators |
583 | may be used where \fB=\fR is written in the syntax summary: | |
584 | .RS | |
585 | .IP "\fB= != < > <= >=\fR" | |
586 | Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] equals, does not | |
587 | equal, is less than, is greater than, is less than or equal to, or is | |
588 | greater than or equal to \fIvalue\fR, respectively. | |
589 | .IP | |
590 | Consider \fIcolumn\fR[\fB:\fIkey\fR] and \fIvalue\fR as sets of | |
591 | elements. Identical sets are considered equal. Otherwise, if the | |
592 | sets have different numbers of elements, then the set with more | |
593 | elements is considered to be larger. Otherwise, consider a element | |
594 | from each set pairwise, in increasing order within each set. The | |
595 | first pair that differs determines the result. (For a column that | |
596 | contains key-value pairs, first all the keys are compared, and values | |
597 | are considered only if the two sets contain identical keys.) | |
598 | .IP "\fB{=} {!=}\fR" | |
599 | Test for set equality or inequality, respectively. | |
600 | .IP "\fB{<=}\fR" | |
601 | Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] is a subset of | |
602 | \fIvalue\fR. For example, \fBflood-vlans{<=}1,2\fR selects records in | |
603 | which the \fBflood-vlans\fR column is the empty set or contains 1 or 2 | |
604 | or both. | |
605 | .IP "\fB{<}\fR" | |
606 | Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] is a proper | |
607 | subset of \fIvalue\fR. For example, \fBflood-vlans{<}1,2\fR selects | |
608 | records in which the \fBflood-vlans\fR column is the empty set or | |
609 | contains 1 or 2 but not both. | |
610 | .IP "\fB{>=} {>}\fR" | |
611 | Same as \fB{<=}\fR and \fB{<}\fR, respectively, except that the | |
612 | relationship is reversed. For example, \fBflood-vlans{>=}1,2\fR | |
613 | selects records in which the \fBflood-vlans\fR column contains both 1 | |
614 | and 2. | |
615 | .RE | |
616 | .IP | |
617 | For arithmetic operators (\fB= != < > <= >=\fR), when \fIkey\fR is | |
618 | specified but a particular record's \fIcolumn\fR does not contain | |
619 | \fIkey\fR, the record is always omitted from the results. Thus, the | |
620 | condition \fBother-config:mtu!=1500\fR matches records that have a | |
621 | \fBmtu\fR key whose value is not 1500, but not those that lack an | |
622 | \fBmtu\fR key. | |
623 | .IP | |
624 | For the set operators, when \fIkey\fR is specified but a particular | |
625 | record's \fIcolumn\fR does not contain \fIkey\fR, the comparison is | |
626 | done against an empty set. Thus, the condition | |
627 | \fBother-config:mtu{!=}1500\fR matches records that have a \fBmtu\fR | |
628 | key whose value is not 1500 and those that lack an \fBmtu\fR key. | |
629 | .IP | |
630 | Don't forget to escape \fB<\fR or \fB>\fR from interpretation by the | |
631 | shell. | |
0a140468 BP |
632 | .IP |
633 | If \fB\-\-columns\fR is specified, only the requested columns are | |
634 | listed, in the specified order. Otherwise all columns are listed, in | |
635 | alphabetical order by column name. | |
9591fefe | 636 | .IP |
3ef917b5 BP |
637 | The UUIDs shown for rows created in the same \fBovs\-vsctl\fR |
638 | invocation will be wrong. | |
ad83bfa6 | 639 | . |
aed133bf | 640 | .IP "[\fB\-\-id=@\fIname\fR] [\fB\-\-if\-exists\fR] \fBget \fItable record \fR[\fIcolumn\fR[\fB:\fIkey\fR]]..." |
ad83bfa6 BP |
641 | Prints the value of each specified \fIcolumn\fR in the given |
642 | \fIrecord\fR in \fItable\fR. For map columns, a \fIkey\fR may | |
643 | optionally be specified, in which case the value associated with | |
644 | \fIkey\fR in the column is printed, instead of the entire map. | |
870aeb4a BP |
645 | .IP |
646 | For a map column, without \fB\-\-if\-exists\fR it is an error if | |
647 | \fIkey\fR does not exist; with it, a blank line is printed. If | |
648 | \fIcolumn\fR is not a map column or if \fIkey\fR is not specified, | |
649 | \fB\-\-if\-exists\fR has no effect. | |
aed133bf BP |
650 | .IP |
651 | If \fB@\fIname\fR is specified, then the UUID for \fIrecord\fR may be | |
652 | referred to by that name later in the same \fBovs\-vsctl\fR | |
653 | invocation in contexts where a UUID is expected. | |
6d5abe94 BP |
654 | .IP |
655 | Both \fB\-\-id\fR and the \fIcolumn\fR arguments are optional, but | |
656 | usually at least one or the other should be specified. If both are | |
657 | omitted, then \fBget\fR has no effect except to verify that | |
658 | \fIrecord\fR exists in \fItable\fR. | |
ad83bfa6 | 659 | . |
bd76d25d | 660 | .IP "\fBset \fItable record column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..." |
ad83bfa6 BP |
661 | Sets the value of each specified \fIcolumn\fR in the given |
662 | \fIrecord\fR in \fItable\fR to \fIvalue\fR. For map columns, a | |
663 | \fIkey\fR may optionally be specified, in which case the value | |
664 | associated with \fIkey\fR in that column is changed (or added, if none | |
665 | exists), instead of the entire map. | |
666 | . | |
bd76d25d | 667 | .IP "\fBadd \fItable record column \fR[\fIkey\fB=\fR]\fIvalue\fR..." |
ad83bfa6 BP |
668 | Adds the specified value or key-value pair to \fIcolumn\fR in |
669 | \fIrecord\fR in \fItable\fR. If \fIcolumn\fR is a map, then \fIkey\fR | |
670 | is required, otherwise it is prohibited. If \fIkey\fR already exists | |
671 | in a map column, then the current \fIvalue\fR is not replaced (use the | |
672 | \fBset\fR command to replace an existing value). | |
90c4bd00 | 673 | . |
bd76d25d BP |
674 | .IP "\fBremove \fItable record column \fR\fIvalue\fR..." |
675 | .IQ "\fBremove \fItable record column \fR\fIkey\fR..." | |
676 | .IQ "\fBremove \fItable record column \fR\fIkey\fB=\fR\fIvalue\fR..." | |
90c4bd00 BP |
677 | Removes the specified values or key-value pairs from \fIcolumn\fR in |
678 | \fIrecord\fR in \fItable\fR. The first form applies to columns that | |
679 | are not maps: each specified \fIvalue\fR is removed from the column. | |
680 | The second and third forms apply to map columns: if only a \fIkey\fR | |
681 | is specified, then any key-value pair with the given \fIkey\fR is | |
682 | removed, regardless of its value; if a \fIvalue\fR is given then a | |
683 | pair is removed only if both key and value match. | |
684 | .IP | |
685 | It is not an error if the column does not contain the specified key or | |
686 | value or pair. | |
687 | . | |
bd76d25d | 688 | .IP "\fBclear\fR \fItable record column\fR..." |
90c4bd00 BP |
689 | Sets each \fIcolumn\fR in \fIrecord\fR in \fItable\fR to the empty set |
690 | or empty map, as appropriate. This command applies only to columns | |
691 | that are allowed to be empty. | |
692 | . | |
4e312e69 | 693 | .IP "[\fB\-\-id=@\fIname\fR] \fBcreate\fR \fItable column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..." |
557e3718 BP |
694 | Creates a new record in \fItable\fR and sets the initial values of |
695 | each \fIcolumn\fR. Columns not explicitly set will receive their | |
3ef917b5 | 696 | default values. Outputs the UUID of the new row. |
ce5a3e38 BP |
697 | .IP |
698 | If \fB@\fIname\fR is specified, then the UUID for the new row may be | |
699 | referred to by that name elsewhere in the same \fBovs\-vsctl\fR | |
700 | invocation in contexts where a UUID is expected. Such references may | |
701 | precede or follow the \fBcreate\fR command. | |
c5f341ab BP |
702 | .IP |
703 | Records in the Open vSwitch database are significant only when they | |
704 | can be reached directly or indirectly from the \fBOpen_vSwitch\fR | |
705 | table. Except for records in the \fBQoS\fR or \fBQueue\fR tables, | |
706 | records that are not reachable from the \fBOpen_vSwitch\fR table are | |
707 | automatically deleted from the database. This deletion happens | |
708 | immediately, without waiting for additional \fBovs\-vsctl\fR commands | |
709 | or other database activity. Thus, a \fBcreate\fR command must | |
710 | generally be accompanied by additional commands \fIwithin the same | |
711 | \fBovs\-vsctl\fI invocation\fR to add a chain of references to the | |
712 | newly created record from the top-level \fBOpen_vSwitch\fR record. | |
713 | The \fBEXAMPLES\fR section gives some examples that show how to do | |
714 | this. | |
b7f74b6f | 715 | . |
0d0f05b9 | 716 | .IP "\fR[\fB\-\-if\-exists\fR] \fBdestroy \fItable record\fR..." |
b7f74b6f BP |
717 | Deletes each specified \fIrecord\fR from \fItable\fR. Unless |
718 | \fB\-\-if\-exists\fR is specified, each \fIrecord\fRs must exist. | |
c5f341ab | 719 | .IP |
dcd1dbc5 BP |
720 | The \fBdestroy\fR command is only useful for records in the \fBQoS\fR |
721 | or \fBQueue\fR tables. Records in other tables are automatically | |
722 | deleted from the database when they become unreachable from the | |
723 | \fBOpen_vSwitch\fR table. This means that deleting the last reference | |
724 | to a record is sufficient for deleting the record itself. For records | |
725 | in these tables, \fBdestroy\fR is silently ignored. See the | |
726 | \fBEXAMPLES\fR section below for more information. | |
7db03f7c BP |
727 | . |
728 | .IP "\fBwait\-until \fItable record \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR]..." | |
729 | Waits until \fItable\fR contains a record named \fIrecord\fR whose | |
730 | \fIcolumn\fR equals \fIvalue\fR or, if \fIkey\fR is specified, whose | |
731 | \fIcolumn\fR contains a \fIkey\fR with the specified \fIvalue\fR. Any | |
732 | of the operators \fB!=\fR, \fB<\fR, \fB>\fR, \fB<=\fR, or \fB>=\fR may | |
733 | be substituted for \fB=\fR to test for inequality, less than, greater | |
734 | than, less than or equal to, or greater than or equal to, | |
735 | respectively. (Don't forget to escape \fB<\fR or \fB>\fR from | |
736 | interpretation by the shell.) | |
737 | .IP | |
738 | If no \fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR arguments are given, | |
739 | this command waits only until \fIrecord\fR exists. If more than one | |
740 | such argument is given, the command waits until all of them are | |
741 | satisfied. | |
742 | .IP | |
743 | Usually \fBwait\-until\fR should be placed at the beginning of a set | |
744 | of \fBovs\-vsctl\fR commands. For example, \fBwait\-until bridge br0 | |
745 | \-\- get bridge br0 datapath_id\fR waits until a bridge named | |
746 | \fBbr0\fR is created, then prints its \fBdatapath_id\fR column, | |
747 | whereas \fBget bridge br0 datapath_id \-\- wait\-until bridge br0\fR | |
748 | will abort if no bridge named \fBbr0\fR exists when \fBovs\-vsctl\fR | |
749 | initially connects to the database. | |
750 | .IP | |
7db03f7c BP |
751 | Consider specifying \fB\-\-timeout=0\fR along with |
752 | \fB\-\-wait\-until\fR, to prevent \fBovs\-vsctl\fR from terminating | |
753 | after waiting only at most 5 seconds. | |
ffd66ea9 BP |
754 | .IP "\fBcomment \fR[\fIarg\fR]..." |
755 | This command has no effect on behavior, but any database log record | |
756 | created by the command will include the command and its arguments. | |
4d14e30f BP |
757 | .SH "EXAMPLES" |
758 | Create a new bridge named br0 and add port eth0 to it: | |
759 | .IP | |
4e312e69 | 760 | .B "ovs\-vsctl add\-br br0" |
4d14e30f | 761 | .br |
4e312e69 | 762 | .B "ovs\-vsctl add\-port br0 eth0" |
4d14e30f BP |
763 | .PP |
764 | Alternatively, perform both operations in a single atomic transaction: | |
765 | .IP | |
4e312e69 | 766 | .B "ovs\-vsctl add\-br br0 \-\- add\-port br0 eth0" |
460aad80 BP |
767 | .PP |
768 | Delete bridge \fBbr0\fR, reporting an error if it does not exist: | |
769 | .IP | |
770 | .B "ovs\-vsctl del\-br br0" | |
771 | .PP | |
772 | Delete bridge \fBbr0\fR if it exists (the \fB\-\-\fR is required to | |
773 | separate \fBdel\-br\fR's options from the global options): | |
774 | .IP | |
775 | .B "ovs\-vsctl \-\- \-\-if\-exists del\-br br0" | |
ce5a3e38 BP |
776 | .PP |
777 | Set the \fBqos\fR column of the \fBPort\fR record for \fBeth0\fR to | |
778 | point to a new \fBQoS\fR record, which in turn points with its queue 0 | |
779 | to a new \fBQueue\fR record: | |
780 | .IP | |
4e312e69 | 781 | .B "ovs\-vsctl \-\- set port eth0 qos=@newqos \-\- \-\-id=@newqos create qos type=linux\-htb other\-config:max\-rate=1000000 queues:0=@newqueue \-\- \-\-id=@newqueue create queue other\-config:min\-rate=1000000 other\-config:max\-rate=1000000" |
bad973d7 BP |
782 | .SH "CONFIGURATION COOKBOOK" |
783 | .SS "Port Configuration" | |
784 | .PP | |
785 | Add an ``internal port'' \fBvlan10\fR to bridge \fBbr0\fR as a VLAN | |
786 | access port for VLAN 10, and configure it with an IP address: | |
787 | .IP | |
788 | .B "ovs\-vsctl add\-port br0 vlan10 tag=10 \-\- set Interface vlan10 type=internal" | |
789 | .IP | |
790 | .B "ifconfig vlan10 192.168.0.123" | |
3b135da3 | 791 | . |
19a79607 BP |
792 | .PP |
793 | Add a GRE tunnel port \fBgre0\fR to remote IP address 1.2.3.4 to | |
794 | bridge \fBbr0\fR: | |
795 | .IP | |
796 | .B "ovs\-vsctl add\-port br0 gre0 \-\- set Interface gre0 type=gre options:remote_ip=1.2.3.4" | |
797 | . | |
bad973d7 BP |
798 | .SS "Port Mirroring" |
799 | .PP | |
800 | Mirror all packets received or sent on \fBeth0\fR or \fBeth1\fR onto | |
801 | \fBeth2\fR, assuming that all of those ports exist on bridge \fBbr0\fR | |
802 | (as a side-effect this causes any packets received on \fBeth2\fR to be | |
803 | ignored): | |
804 | .IP | |
805 | .B "ovs\-vsctl \-\- set Bridge br0 mirrors=@m \(rs" | |
806 | .IP | |
807 | .B "\-\- \-\-id=@eth0 get Port eth0 \(rs" | |
808 | .IP | |
809 | .B "\-\- \-\-id=@eth1 get Port eth1 \(rs" | |
810 | .IP | |
811 | .B "\-\- \-\-id=@eth2 get Port eth2 \(rs" | |
812 | .IP | |
813 | .B "\-\- \-\-id=@m create Mirror name=mymirror select-dst-port=@eth0,@eth1 select-src-port=@eth0,@eth1 output-port=@eth2" | |
814 | .PP | |
c5f341ab BP |
815 | Remove the mirror created above from \fBbr0\fR, which also destroys |
816 | the Mirror record (since it is now unreferenced): | |
bad973d7 | 817 | .IP |
c5f341ab | 818 | .B "remove Bridge br0 mirrors mymirror" |
bad973d7 BP |
819 | .SS "Quality of Service (QoS)" |
820 | .PP | |
821 | Create a \fBlinux\-htb\fR QoS record that points to a few queues and | |
822 | use it on \fBeth0\fR and \fBeth1\fR: | |
823 | .IP | |
824 | .B "ovs\-vsctl \-\- set Port eth0 qos=@newqos \(rs" | |
825 | .IP | |
826 | .B "\-\- set Port eth1 qos=@newqos \(rs" | |
827 | .IP | |
828 | .B "\-\- \-\-id=@newqos create QoS type=linux\-htb other\-config:max\-rate=1000000000 queues=0=@q0,1=@q1 \(rs" | |
829 | .IP | |
830 | .B "\-\- \-\-id=@q0 create Queue other\-config:min\-rate=100000000 other\-config:max\-rate=100000000 \(rs" | |
831 | .IP | |
832 | .B "\-\- \-\-id=@q1 create Queue other\-config:min\-rate=500000000" | |
833 | .PP | |
834 | Deconfigure the QoS record above from \fBeth1\fR only: | |
835 | .IP | |
836 | .B "ovs\-vsctl clear Port eth1 qos" | |
837 | .PP | |
838 | To deconfigure the QoS record from both \fBeth0\fR and \fBeth1\fR and | |
c5f341ab BP |
839 | then delete the QoS record (which must be done explicitly because |
840 | unreferenced QoS records are not automatically destroyed): | |
bad973d7 BP |
841 | .IP |
842 | .B "ovs\-vsctl \-\- destroy QoS eth0 \-\- clear Port eth0 qos \-\- clear Port eth1 qos" | |
843 | .PP | |
844 | (This command will leave two unreferenced Queue records in the | |
845 | database. To delete them, use "\fBovs\-vsctl list Queue\fR" to find | |
846 | their UUIDs, then "\fBovs\-vsctl destroy Queue \fIuuid1\fR | |
847 | \fIuuid2\fR" to destroy each of them.) | |
b31bcf60 EJ |
848 | .SS "Connectivity Monitoring" |
849 | .PP | |
93b8df38 | 850 | Monitor connectivity to a remote maintenance point on eth0. |
b31bcf60 | 851 | .IP |
a6e198ea | 852 | .B "ovs\-vsctl set Interface eth0 cfm_mpid=1" |
b31bcf60 | 853 | .PP |
93b8df38 | 854 | Deconfigure connectivity monitoring from above: |
b31bcf60 | 855 | .IP |
a6e198ea | 856 | .B "ovs\-vsctl clear Interface eth0 cfm_mpid" |
bad973d7 BP |
857 | .SS "NetFlow" |
858 | .PP | |
859 | Configure bridge \fBbr0\fR to send NetFlow records to UDP port 5566 on | |
860 | host 192.168.0.34, with an active timeout of 30 seconds: | |
861 | .IP | |
862 | .B "ovs\-vsctl \-\- set Bridge br0 netflow=@nf \(rs" | |
863 | .IP | |
864 | .B "\-\- \-\-id=@nf create NetFlow targets=\(rs\(dq192.168.0.34:5566\(rs\(dq active\-timeout=30" | |
865 | .PP | |
866 | Update the NetFlow configuration created by the previous command to | |
867 | instead use an active timeout of 60 seconds: | |
868 | .IP | |
869 | .B "ovs\-vsctl set NetFlow br0 active_timeout=60" | |
870 | .PP | |
c5f341ab BP |
871 | Deconfigure the NetFlow settings from \fBbr0\fR, which also destroys |
872 | the NetFlow record (since it is now unreferenced): | |
bad973d7 | 873 | .IP |
c5f341ab | 874 | .B "ovs\-vsctl clear Bridge br0 netflow" |
bad973d7 BP |
875 | .SS "sFlow" |
876 | .PP | |
877 | Configure bridge \fBbr0\fR to send sFlow records to a collector on | |
878 | 10.0.0.1 at port 6343, using \fBeth1\fR\'s IP address as the source, | |
879 | with specific sampling parameters: | |
880 | .IP | |
881 | .B "ovs\-vsctl \-\- \-\-id=@s create sFlow agent=eth1 target=\(rs\(dq10.0.0.1:6343\(rs\(dq header=128 sampling=64 polling=10 \(rs" | |
882 | .IP | |
883 | .B "\-\- set Bridge br0 sflow=@s" | |
884 | .PP | |
f0f87cbd | 885 | Deconfigure sFlow from \fBbr0\fR, which also destroys the sFlow record |
c5f341ab | 886 | (since it is now unreferenced): |
bad973d7 | 887 | .IP |
c5f341ab | 888 | .B "ovs\-vsctl \-\- clear Bridge br0 sflow" |
21f7563c JP |
889 | .SS "802.1D Spanning Tree Protocol (STP)" |
890 | .PP | |
891 | Configure bridge \fBbr0\fR to participate in an 802.1D spanning tree: | |
892 | .IP | |
893 | .B "ovs\-vsctl set Bridge br0 stp_enable=true" | |
894 | .PP | |
895 | Set the bridge priority of \fBbr0\fR to 0x7800: | |
896 | .IP | |
897 | .B "ovs\-vsctl set Bridge br0 other_config:stp-priority=0x7800" | |
898 | .PP | |
899 | Set the path cost of port \fBeth0\fR to 10: | |
900 | .IP | |
901 | .B "ovs\-vsctl set Port eth0 other_config:stp-path-cost=10" | |
902 | .PP | |
903 | Deconfigure STP from above: | |
904 | .IP | |
905 | .B "ovs\-vsctl clear Bridge br0 stp_enable" | |
906 | .PP | |
3b135da3 BP |
907 | .SH "EXIT STATUS" |
908 | .IP "0" | |
909 | Successful program execution. | |
910 | .IP "1" | |
911 | Usage, syntax, or configuration file error. | |
912 | .IP "2" | |
913 | The \fIbridge\fR argument to \fBbr\-exists\fR specified the name of a | |
914 | bridge that does not exist. | |
915 | .SH "SEE ALSO" | |
916 | . | |
dfbe07ba | 917 | .BR ovsdb\-server (1), |
3b135da3 | 918 | .BR ovs\-vswitchd (8). |