]>
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 | |
12 | . PP | |
13 | .. | |
3fbe1d30 | 14 | .TH ovs\-vsctl 8 "November 2009" "Open vSwitch" "Open vSwitch Manual" |
3b135da3 BP |
15 | .ds PN ovs\-vsctl |
16 | . | |
17 | .SH NAME | |
18 | ovs\-vsctl \- utility for querying and configuring \fBovs\-vswitchd\fR | |
19 | . | |
20 | .SH SYNOPSIS | |
460aad80 | 21 | \fBovs\-vsctl\fR [\fIoptions\fR] [\fB\-\-\fR] \fIcommand \fR[\fIargs\fR\&...] |
4d14e30f | 22 | [\fB\-\-\fR \fIcommand \fR[\fIargs\fR\&...]] |
3b135da3 BP |
23 | . |
24 | .SH DESCRIPTION | |
dfbe07ba BP |
25 | The \fBovs\-vsctl\fR program configures \fBovs\-vswitchd\fR(8) by |
26 | providing a high\-level interface to editing its configuration | |
27 | database. This program is mainly intended for use when | |
28 | \fBovs\-vswitchd\fR is running. If it is used when | |
29 | \fBovs\-vswitchd\fR is not running, then \fB\-\-no\-wait\fR should be | |
30 | specified and configuration changes will only take effect when | |
31 | \fBovs\-vswitchd\fR is started. | |
3b135da3 | 32 | .PP |
dfbe07ba BP |
33 | By default, each time \fBovs\-vsctl\fR runs, it connects to an |
34 | \fBovsdb\-server\fR process that maintains an Open vSwitch | |
35 | configuration database. Using this connection, it queries and | |
36 | possibly applies changes to the database, depending on the supplied | |
37 | commands. Then, if it applied any changes, it waits until | |
38 | \fBovs\-vswitchd\fR has finished reconfiguring itself before it exits. | |
460aad80 BP |
39 | .PP |
40 | \fBovs\-vsctl\fR can perform any number of commands in a single run, | |
41 | implemented as a single atomic transaction against the database. | |
42 | Commands are separated on the command line by \fB\-\-\fR arguments. | |
3b135da3 BP |
43 | . |
44 | .SS "Linux VLAN Bridging Compatibility" | |
45 | The \fBovs\-vsctl\fR program supports the model of a bridge | |
46 | implemented by Open vSwitch, in which a single bridge supports ports | |
47 | on multiple VLANs. In this model, each port on a bridge is either a | |
48 | trunk port that potentially passes packets tagged with 802.1Q headers | |
49 | that designate VLANs or it is assigned a single implicit VLAN that is | |
50 | never tagged with an 802.1Q header. | |
51 | .PP | |
52 | For compatibility with software designed for the Linux bridge, | |
53 | \fBovs\-vsctl\fR also supports a model in which traffic associated | |
54 | with a given 802.1Q VLAN is segregated into a separate bridge. A | |
55 | special form of the \fBadd\-br\fR command (see below) creates a ``fake | |
56 | bridge'' within an Open vSwitch bridge to simulate this behavior. | |
57 | When such a ``fake bridge'' is active, \fBovs\-vsctl\fR will treat it | |
58 | much like a bridge separate from its ``parent bridge,'' but the actual | |
59 | implementation in Open vSwitch uses only a single bridge, with ports on | |
60 | the fake bridge assigned the implicit VLAN of the fake bridge of which | |
61 | they are members. | |
62 | . | |
63 | .SH OPTIONS | |
64 | . | |
460aad80 BP |
65 | The following options affect the behavior \fBovs\-vsctl\fR as a whole. |
66 | Some individual commands also accept their own options, which are | |
67 | given just before the command name. If the first command on the | |
68 | command line has options, then those options must be separated from | |
69 | the global options by \fB\-\-\fR. | |
3b135da3 | 70 | . |
dfbe07ba BP |
71 | .IP "\fB\-\-db=\fIserver\fR" |
72 | Sets \fIserver\fR as the database server that \fBovs\-vsctl\fR | |
73 | contacts to query or modify configuration. The default is | |
74 | \fBunix:@RUNDIR@/ovsdb\-server\fR. \fIserver\fR must take one of the | |
75 | following forms: | |
76 | .RS | |
9467fe62 | 77 | .so ovsdb/remote-active.man |
dfbe07ba | 78 | .RE |
9467fe62 | 79 | . |
dfbe07ba BP |
80 | .IP "\fB\-\-no\-wait\fR" |
81 | Prevents \fBovs\-vsctl\fR from waiting for \fBovs\-vswitchd\fR to | |
82 | reconfigure itself according to the the modified database. This | |
83 | option should be used if \fBovs\-vswitchd\fR is not running; | |
84 | otherwise, \fBovs-vsctl\fR will not exit until \fBovs-vswitchd\fR | |
85 | starts. | |
3b135da3 | 86 | .IP |
dfbe07ba BP |
87 | This option has no effect if the commands specified do not change the |
88 | database. | |
3b135da3 | 89 | . |
37c84020 BP |
90 | .IP "\fB\-\-no\-syslog\fR" |
91 | By default, \fBovs\-vsctl\fR logs its arguments and the details of any | |
92 | changes that it makes to the system log. This option disables this | |
93 | logging. | |
dfbe07ba BP |
94 | .IP |
95 | This option is equivalent to \fB\-\-verbose=vvsctl:syslog:warn\fR. | |
96 | . | |
2792c2ad | 97 | .IP "\fB\-\-oneline\fR" |
4d14e30f | 98 | Modifies the output format so that the output for each command is printed |
2792c2ad | 99 | on a single line. New-line characters that would otherwise separate |
4d14e30f | 100 | lines are printed as \fB\\n\fR, and any instances of \fB\\\fR that |
2792c2ad | 101 | would otherwise appear in the output are doubled. |
4d14e30f | 102 | Prints a blank line for each command that has no output. |
37c84020 | 103 | . |
577aebdf BP |
104 | .IP "\fB\-\-dry\-run\fR" |
105 | Prevents \fBovs\-vsctl\fR from actually modifying the database. | |
106 | . | |
342045e1 BP |
107 | .IP "\fB-t \fIsecs\fR" |
108 | .IQ "\fB--timeout=\fIsecs\fR" | |
a39a859a JP |
109 | Limits runtime to approximately \fIsecs\fR seconds. A value of |
110 | zero will cause \fBovs\-vsctl\fR to wait forever. If the timeout expires, | |
111 | \fBovs\-vsctl\fR will exit with a \fBSIGALRM\fR signal. If this option is | |
112 | not used, \fBovs\-vsctl\fR uses a timeout of five seconds. | |
113 | (A timeout would normally happen only if the database cannot be contacted.) | |
342045e1 | 114 | . |
84ee7bcf | 115 | .so lib/ssl.man |
dfbe07ba BP |
116 | .so lib/vlog.man |
117 | . | |
3b135da3 BP |
118 | .SH COMMANDS |
119 | The commands implemented by \fBovs\-vsctl\fR are described in the | |
120 | sections below. | |
524555d1 BP |
121 | .SS "Open vSwitch Commands" |
122 | These commands work with an Open vSwitch as a whole. | |
123 | . | |
124 | .IP "\fBinit\fR" | |
125 | Initializes the Open vSwitch database, if it is empty. If the | |
126 | database has already been initialized, this command has no effect. | |
127 | .IP | |
128 | Any successful \fBovs\-vsctl\fR command automatically initializes the | |
129 | Open vSwitch database if it is empty. This command is provided to | |
130 | initialize the database without executing any other command. | |
3b135da3 BP |
131 | . |
132 | .SS "Bridge Commands" | |
133 | These commands examine and manipulate Open vSwitch bridges. | |
134 | . | |
135 | .IP "\fBadd\-br \fIbridge\fR" | |
136 | Creates a new bridge named \fIbridge\fR. Initially the bridge will | |
137 | have no ports (other than \fIbridge\fR itself). | |
138 | . | |
139 | .IP "\fBadd\-br \fIbridge parent vlan\fR" | |
140 | Creates a ``fake bridge'' named \fIbridge\fR within the existing Open | |
141 | vSwitch bridge \fIparent\fR, which must already exist and must not | |
142 | itself be a fake bridge. The new fake bridge will be on 802.1Q VLAN | |
143 | \fIvlan\fR, which must be an integer between 1 and 4095. Initially | |
144 | \fIbridge\fR will have no ports (other than \fIbridge\fR itself). | |
145 | . | |
460aad80 | 146 | .IP "[\fB\-\-if\-exists\fR] \fBdel\-br \fIbridge\fR" |
3b135da3 BP |
147 | Deletes \fIbridge\fR and all of its ports. If \fIbridge\fR is a real |
148 | bridge, this command also deletes any fake bridges that were created | |
149 | with \fIbridge\fR as parent, including all of their ports. | |
460aad80 BP |
150 | .IP |
151 | Without \fB\-\-if\-exists\fR, attempting to delete a bridge that does | |
152 | not exist is an error. With \fB\-\-if\-exists\fR, attempting to | |
153 | delete a bridge that does not exist has no effect. | |
3b135da3 BP |
154 | . |
155 | .IP "\fBlist\-br\fR" | |
156 | Lists all existing real and fake bridges on standard output, one per | |
157 | line. | |
158 | . | |
159 | .IP "\fBbr\-exists \fIbridge\fR" | |
160 | Tests whether \fIbridge\fR exists as a real or fake bridge. If so, | |
161 | \fBovs\-vsctl\fR exits successfully with exit code 0. If not, | |
162 | \fBovs\-vsctl\fR exits unsuccessfully with exit code 2. | |
163 | . | |
8e58fa9a BP |
164 | .IP "\fBbr\-to\-vlan \fIbridge\fR" |
165 | If \fIbridge\fR is a fake bridge, prints the bridge's 802.1Q VLAN as a | |
166 | decimal integer. If \fIbridge\fR is a real bridge, prints 0. | |
167 | . | |
168 | .IP "\fBbr\-to\-parent \fIbridge\fR" | |
169 | If \fIbridge\fR is a fake bridge, prints the name of its parent | |
170 | bridge. If \fIbridge\fR is a real bridge, print \fIbridge\fR. | |
171 | . | |
457e1eb0 BP |
172 | .IP "\fBbr\-set\-external\-id \fIbridge key\fR [\fIvalue\fR]" |
173 | Sets or clears an ``external ID'' value on \fIbridge\fR. These values | |
174 | are intended to identify entities external to Open vSwitch with which | |
175 | \fIbridge\fR is associated, e.g. the bridge's identifier in a | |
176 | virtualization management platform. The Open vSwitch database schema | |
177 | specifies well-known \fIkey\fR values, but \fIkey\fR and \fIvalue\fR | |
178 | are otherwise arbitrary strings. | |
179 | .IP | |
180 | If \fIvalue\fR is specified, then \fIkey\fR is set to \fIvalue\fR for | |
181 | \fIbridge\fR, overwriting any previous value. If \fIvalue\fR is | |
182 | omitted, then \fIkey\fR is removed from \fIbridge\fR's set of external | |
183 | IDs (if it was present). | |
184 | . | |
185 | .IP "\fBbr\-get\-external\-id \fIbridge\fR [\fIkey\fR]" | |
186 | Queries the external IDs on \fIbridge\fR. If \fIkey\fR is specified, | |
187 | the output is the value for that \fIkey\fR or the empty string if | |
188 | \fIkey\fR is unset. If \fIkey\fR is omitted, the output is | |
189 | \fIkey\fB=\fIvalue\fR, one per line, for each key-value pair. | |
190 | . | |
3b135da3 BP |
191 | .SS "Port Commands" |
192 | . | |
193 | These commands examine and manipulate Open vSwitch ports. These | |
194 | commands treat a bonded port as a single entity. | |
195 | . | |
196 | .IP "\fBlist\-ports \fIbridge\fR" | |
197 | Lists all of the ports within \fIbridge\fR on standard output, one per | |
198 | line. The local port \fIbridge\fR is not included in the list. | |
199 | . | |
200 | .IP "\fBadd\-port \fIbridge port\fR" | |
201 | Creates on \fIbridge\fR a new port named \fIport\fR from the network | |
202 | device of the same name. | |
203 | . | |
b4182c7f | 204 | .IP "[\fB\-\-fake\-iface\fR] \fBadd\-bond \fIbridge port iface\fR\&..." |
3b135da3 BP |
205 | Creates on \fIbridge\fR a new port named \fIport\fR that bonds |
206 | together the network devices given as each \fIiface\fR. At least two | |
207 | interfaces must be named. | |
b4182c7f JP |
208 | .IP |
209 | With \fB\-\-fake\-iface\fR, a fake interface with the name \fIport\fR is | |
210 | created. This should only be used for compatibility with legacy | |
211 | software that requires it. | |
3b135da3 | 212 | . |
460aad80 | 213 | .IP "[\fB\-\-if\-exists\fR] \fBdel\-port \fR[\fIbridge\fR] \fIport\fR" |
3d1b9636 BP |
214 | Deletes \fIport\fR. If \fIbridge\fR is omitted, \fIport\fR is removed |
215 | from whatever bridge contains it; if \fIbridge\fR is specified, it | |
216 | must be the real or fake bridge that contains \fIport\fR. | |
460aad80 BP |
217 | .IP |
218 | Without \fB\-\-if\-exists\fR, attempting to delete a port that does | |
219 | not exist is an error. With \fB\-\-if\-exists\fR, attempting to | |
220 | delete a port that does not exist has no effect. | |
3b135da3 BP |
221 | . |
222 | .IP "\fBport\-to\-br \fIport\fR" | |
223 | Prints the name of the bridge that contains \fIport\fR on standard | |
224 | output. | |
225 | . | |
457e1eb0 BP |
226 | .IP "\fBport\-set\-external\-id \fIport key\fR [\fIvalue\fR]" |
227 | Sets or clears an ``external ID'' value on \fIport\fR. These value | |
228 | are intended to identify entities external to Open vSwitch with which | |
229 | \fIport\fR is associated, e.g. the port's identifier in a | |
230 | virtualization management platform. The Open vSwitch database schema | |
231 | specifies well-known \fIkey\fR values, but \fIkey\fR and \fIvalue\fR | |
232 | are otherwise arbitrary strings. | |
233 | .IP | |
234 | If \fIvalue\fR is specified, then \fIkey\fR is set to \fIvalue\fR for | |
235 | \fIport\fR, overwriting any previous value. If \fIvalue\fR is | |
236 | omitted, then \fIkey\fR is removed from \fIport\fR's set of external | |
237 | IDs (if it was present). | |
238 | . | |
239 | .IP "\fBbr\-get\-external\-id \fIport\fR [\fIkey\fR]" | |
240 | Queries the external IDs on \fIport\fR. If \fIkey\fR is specified, | |
241 | the output is the value for that \fIkey\fR or the empty string if | |
242 | \fIkey\fR is unset. If \fIkey\fR is omitted, the output is | |
243 | \fIkey\fB=\fIvalue\fR, one per line, for each key-value pair. | |
244 | . | |
3b135da3 BP |
245 | .SS "Interface Commands" |
246 | . | |
247 | These commands examine the interfaces attached to an Open vSwitch | |
248 | bridge. These commands treat a bonded port as a collection of two or | |
249 | more interfaces, rather than as a single port. | |
250 | . | |
251 | .IP "\fBlist\-ifaces \fIbridge\fR" | |
252 | Lists all of the interfaces within \fIbridge\fR on standard output, | |
253 | one per line. The local port \fIbridge\fR is not included in the | |
254 | list. | |
255 | . | |
256 | .IP "\fBiface\-to\-br \fIiface\fR" | |
257 | Prints the name of the bridge that contains \fIiface\fR on standard | |
258 | output. | |
457e1eb0 BP |
259 | . |
260 | .IP "\fBiface\-set\-external\-id \fIiface key\fR [\fIvalue\fR]" | |
261 | Sets or clears an ``external ID'' value on \fIiface\fR. These value | |
262 | are intended to identify entities external to Open vSwitch with which | |
263 | \fIiface\fR is associated, e.g. the interface's identifier in a | |
264 | virtualization management platform. The Open vSwitch database schema | |
265 | specifies well-known \fIkey\fR values, but \fIkey\fR and \fIvalue\fR | |
266 | are otherwise arbitrary strings. | |
267 | .IP | |
268 | If \fIvalue\fR is specified, then \fIkey\fR is set to \fIvalue\fR for | |
269 | \fIiface\fR, overwriting any previous value. If \fIvalue\fR is | |
270 | omitted, then \fIkey\fR is removed from \fIiface\fR's set of external | |
271 | IDs (if it was present). | |
272 | . | |
273 | .IP "\fBbr\-get\-external\-id \fIiface\fR [\fIkey\fR]" | |
274 | Queries the external IDs on \fIiface\fR. If \fIkey\fR is specified, | |
275 | the output is the value for that \fIkey\fR or the empty string if | |
276 | \fIkey\fR is unset. If \fIkey\fR is omitted, the output is | |
277 | \fIkey\fB=\fIvalue\fR, one per line, for each key-value pair. | |
278 | . | |
5aa00635 JP |
279 | .SS "OpenFlow Controller Connectivity" |
280 | . | |
281 | \fBovs\-vswitchd\fR can perform all configured bridging and switching | |
282 | locally, or it can be configured to connect a given bridge to an | |
283 | external OpenFlow controller, such as NOX. | |
284 | . | |
285 | If a \fIbridge\fR argument is given, the settings apply only to the | |
286 | specified bridge. Otherwise, they apply to the Open vSwitch instance, | |
287 | and its configuration applies to any bridge that has not been explicitly | |
288 | configured through a \fIbridge\fR argument. | |
289 | . | |
290 | .IP "\fBget\-controller\fR [\fIbridge\fR]" | |
291 | Prints the configured controller target. | |
292 | . | |
293 | .IP "\fBdel\-controller\fR [\fIbridge\fR]" | |
294 | Deletes the configured controller target. | |
295 | . | |
296 | .IP "\fBset\-controller\fR [\fIbridge\fR] \fItarget\fR" | |
297 | Sets the configured controller target. The \fItarget\fR may use any of | |
298 | the following forms: | |
299 | . | |
300 | .RS | |
301 | .TP | |
84ee7bcf | 302 | .so lib/vconn-active.man |
5aa00635 | 303 | .RE |
84ee7bcf | 304 | . |
5aa00635 JP |
305 | .ST "Controller Failure Settings" |
306 | . | |
307 | When a controller is configured, it is, ordinarily, responsible for | |
308 | setting up all flows on the switch. Thus, if the connection to | |
309 | the controller fails, no new network connections can be set up. If | |
310 | the connection to the controller stays down long enough, no packets | |
311 | can pass through the switch at all. | |
312 | .ST | |
313 | If the value is \fBstandalone\fR, or if neither of these settings | |
314 | is set, \fBovs\-vswitchd\fR will take over | |
315 | responsibility for setting up | |
316 | flows when no message has been received from the controller for three | |
317 | times the inactivity probe interval (xxx needs to be exposed). In this mode, | |
318 | \fBovs\-vswitchd\fR causes the datapath to act like an ordinary | |
319 | MAC-learning switch. \fBovs\-vswitchd\fR will continue to retry connecting | |
320 | to the controller in the background and, when the connection succeeds, | |
321 | it discontinues its standalone behavior. | |
322 | .ST | |
323 | If this option is set to \fBsecure\fR, \fBovs\-vswitchd\fR will not | |
324 | set up flows on its own when the controller connection fails. | |
325 | . | |
326 | .IP "\fBget\-fail\-mode\fR [\fIbridge\fR]" | |
327 | Prints the configured failure mode. | |
328 | . | |
329 | .IP "\fBdel\-fail\-mode\fR [\fIbridge\fR]" | |
330 | Deletes the configured failure mode. | |
331 | . | |
332 | .IP "\fBset\-fail\-mode\fR [\fIbridge\fR] \fBstandalone\fR|\fBsecure\fR" | |
333 | Sets the configured failure mode. | |
334 | . | |
dd8ac6fe JP |
335 | .SS "SSL Configuration" |
336 | When \fBovs\-vswitchd\fR is configured to connect over SSL for management or | |
337 | controller connectivity, the following parameters are required: | |
338 | .TP | |
339 | \fBprivate-key\fR | |
340 | Specifies a PEM file containing the private key used as the virtual | |
341 | switch's identity for SSL connections to the controller. | |
342 | .TP | |
343 | \fBcertificate\fR | |
344 | Specifies a PEM file containing a certificate, signed by the | |
345 | certificate authority (CA) used by the controller and manager, that | |
346 | certifies the virtual switch's private key, identifying a trustworthy | |
347 | switch. | |
348 | .TP | |
349 | \fBca-cert\fR | |
350 | Specifies a PEM file containing the CA certificate used to verify that | |
351 | the virtual switch is connected to a trustworthy controller. | |
352 | .PP | |
353 | These files are read only once, at \fBovs\-vswitchd\fR startup time. If | |
354 | their contents change, \fBovs\-vswitchd\fR must be killed and restarted. | |
355 | .PP | |
356 | These SSL settings apply to all SSL connections made by the virtual | |
357 | switch. | |
358 | . | |
359 | .IP "\fBget\-ssl\fR" | |
360 | Prints the SSL configuration. | |
361 | . | |
362 | .IP "\fBdel\-ssl\fR" | |
363 | Deletes the current SSL configuration. | |
364 | . | |
365 | .IP "[\fB\-\-bootstrap\fR] \fBset\-ssl\fR \fIprivate-key\fR \fIcertificate\fR \fIca-cert\fR" | |
366 | Sets the SSL configuration. The \fB\-\-bootstrap\fR option is described | |
367 | below. | |
368 | . | |
369 | .ST "CA Certificate Bootstrap" | |
370 | Ordinarily, all of the files named in the SSL configuration must exist | |
371 | when \fBovs\-vswitchd\fR starts. However, if the \fB\-\-bootstrap\fR | |
372 | option is given, then \fBovs\-vswitchd\fR will attempt to obtain the | |
373 | CA certificate from the controller on its first SSL connection and | |
374 | save it to the named PEM file. If it is successful, it will | |
375 | immediately drop the connection and reconnect, and from then on all | |
376 | SSL connections must be authenticated by a certificate signed by the | |
377 | CA certificate thus obtained. | |
378 | .PP | |
379 | \fBThis option exposes the SSL connection to a man-in-the-middle | |
380 | attack obtaining the initial CA certificate\fR, but it may be useful | |
381 | for bootstrapping. | |
382 | .PP | |
383 | This option is only useful if the controller sends its CA certificate | |
384 | as part of the SSL certificate chain. The SSL protocol does not | |
385 | require the controller to send the CA certificate, but | |
386 | \fBcontroller\fR(8) can be configured to do so with the | |
387 | \fB--peer-ca-cert\fR option. | |
388 | . | |
ad83bfa6 BP |
389 | .SS "Database Commands" |
390 | . | |
391 | These commands query and modify the contents of \fBovsdb\fR tables. | |
392 | They are a slight abstraction of the \fBovsdb\fR interface and as such | |
393 | they operate at a lower level than other \fBovs\-vsctl\fR commands. | |
394 | .PP | |
395 | .ST "Identifying Tables, Records, and Columns" | |
396 | .PP | |
397 | Each of these commands has a \fItable\fR parameter to identify a table | |
398 | within the database. Many of them also take a \fIrecord\fR parameter | |
399 | that identifies a particular record within a table. The \fIrecord\fR | |
400 | parameter may be the UUID for a record, and many tables offer | |
401 | additional ways to identify records. Some commands also take | |
402 | \fIcolumn\fR parameters that identify a particular field within the | |
403 | records in a table. | |
404 | .PP | |
405 | The following tables are currently defined: | |
406 | .IP "\fBOpen_vSwitch\fR" | |
407 | Global configuration for an \fBovs\-vswitchd\fR. This table contains | |
408 | exactly one record, identified by specifying \fB.\fR as the record | |
409 | name. | |
410 | .IP "\fBBridge\fR" | |
411 | Configuration for a bridge within an Open vSwitch. Records may be | |
412 | identified by bridge name. | |
413 | .IP "\fBPort\fR" | |
414 | A bridge port. Records may be identified by port name. | |
415 | .IP "\fBInterface\fR" | |
416 | A network device attached to a port. Records may be identified by | |
417 | name. | |
418 | .IP "\fBController\fR" | |
419 | Configuration for an OpenFlow controller. A controller attached to a | |
420 | particular bridge may be identified by the bridge's name. The default | |
421 | controller controller for an Open vSwitch may be identified by | |
422 | specifying \fB.\fR as the record name. | |
423 | .IP "\fBMirror\fR" | |
424 | A port mirroring configuration attached to a bridge. Records may be | |
425 | identified by mirror name. | |
426 | .IP "\fBNetFlow\fR" | |
427 | A NetFlow configuration attached to a bridge. Records may be | |
428 | identified by bridge name. | |
429 | .PP | |
430 | Names of tables, records, and columns are not case-sensitive, and | |
431 | \fB--\fR and \fB_\fR are treated interchangeably. Unique | |
432 | abbreviations are acceptable, e.g. \fBnet\fR or \fRn\fR is sufficient | |
433 | to identify the \fBNetFlow\fR table. | |
434 | . | |
435 | .ST "Database Values" | |
436 | Each column in the database accepts a fixed type of data. The | |
437 | currently defined basic types, and their representations, are: | |
438 | .IP "integer" | |
439 | A decimal integer in the range \-2**63 to 2**63\-1, inclusive. | |
440 | .IP "real" | |
441 | A floating-point number. | |
442 | .IP "Boolean" | |
443 | True or false, written \fBtrue\fR or \fBfalse\fR, respectively. | |
444 | .IP "string" | |
445 | An arbitrary Unicode string, except that null bytes are not allowed. | |
446 | Quotes are optional for most strings that begin with an English letter | |
447 | or underscore and consist only of letters, underscores, hyphens, and | |
448 | periods. However, \fBtrue\fR and \fBfalse\fR and strings that match | |
449 | the syntax of UUIDs (see below) must be enclosed in double quotes to | |
450 | distinguish them from other basic types. When double quotes are used, | |
451 | the syntax is that of strings in JSON, e.g. backslashes may be used to | |
452 | escape special characters. The empty string must be represented as a | |
453 | pair of double quotes (\fB""\fR). | |
454 | .IP "UUID" | |
455 | A universally unique identifier in the style of RFC 4122, | |
456 | e.g. \fBf81d4fae-7dec-11d0-a765-00a0c91e6bf6\fR. | |
457 | .PP | |
458 | Multiple values in a single column may be separated by spaces or a | |
459 | single comma. When multiple values are present, duplicates are not | |
460 | allowed, and order is not important. Conversely, some database | |
461 | columns can have an empty set of values, represented as \fB[]\fR, and | |
462 | square brackets may optionally enclose other non-empty sets or single | |
463 | values as well. | |
464 | .PP | |
465 | A few database columns are ``maps'' of key-value pairs, where the key | |
466 | and the value are each some fixed database type. These are specified | |
467 | in the form \fIkey\fB=\fIvalue\fR, where \fIkey\fR and \fIvalue\fR | |
468 | follow the syntax for the column's key type and value type, | |
469 | respectively. When multiple pairs are present (separated by spaces or | |
470 | a comma), duplicate keys are not allowed, and again the order is not | |
471 | important. Duplicate values are allowed. An empty map is represented | |
472 | as \fB{}\fR, and curly braces may be optionally enclose non-empty maps | |
473 | as well. | |
474 | . | |
475 | .ST "Database Command Syntax" | |
476 | . | |
477 | .IP "\fBlist \fItable \fR[\fIrecord\fR]..." | |
478 | List the values of all columns of each specified \fIrecord\fR. If no | |
479 | records are specified, lists all the records in \fItable\fR. | |
480 | . | |
481 | .IP "\fBget \fItable record column\fR[\fB:\fIkey\fR]..." | |
482 | Prints the value of each specified \fIcolumn\fR in the given | |
483 | \fIrecord\fR in \fItable\fR. For map columns, a \fIkey\fR may | |
484 | optionally be specified, in which case the value associated with | |
485 | \fIkey\fR in the column is printed, instead of the entire map. | |
486 | . | |
487 | .IP "\fBset \fItable record column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..." | |
488 | Sets the value of each specified \fIcolumn\fR in the given | |
489 | \fIrecord\fR in \fItable\fR to \fIvalue\fR. For map columns, a | |
490 | \fIkey\fR may optionally be specified, in which case the value | |
491 | associated with \fIkey\fR in that column is changed (or added, if none | |
492 | exists), instead of the entire map. | |
493 | . | |
494 | .IP "\fBadd \fItable record column \fR[\fIkey\fB=\fR]\fIvalue\fR..." | |
495 | Adds the specified value or key-value pair to \fIcolumn\fR in | |
496 | \fIrecord\fR in \fItable\fR. If \fIcolumn\fR is a map, then \fIkey\fR | |
497 | is required, otherwise it is prohibited. If \fIkey\fR already exists | |
498 | in a map column, then the current \fIvalue\fR is not replaced (use the | |
499 | \fBset\fR command to replace an existing value). | |
4d14e30f BP |
500 | .SH "EXAMPLES" |
501 | Create a new bridge named br0 and add port eth0 to it: | |
502 | .IP | |
503 | .B "ovs-vsctl add\-br br0" | |
504 | .br | |
505 | .B "ovs-vsctl add\-port br0 eth0" | |
506 | .PP | |
507 | Alternatively, perform both operations in a single atomic transaction: | |
508 | .IP | |
509 | .B "ovs-vsctl add\-br br0 \-\- add\-port br0 eth0" | |
460aad80 BP |
510 | .PP |
511 | Delete bridge \fBbr0\fR, reporting an error if it does not exist: | |
512 | .IP | |
513 | .B "ovs\-vsctl del\-br br0" | |
514 | .PP | |
515 | Delete bridge \fBbr0\fR if it exists (the \fB\-\-\fR is required to | |
516 | separate \fBdel\-br\fR's options from the global options): | |
517 | .IP | |
518 | .B "ovs\-vsctl \-\- \-\-if\-exists del\-br br0" | |
3b135da3 BP |
519 | . |
520 | .SH "EXIT STATUS" | |
521 | .IP "0" | |
522 | Successful program execution. | |
523 | .IP "1" | |
524 | Usage, syntax, or configuration file error. | |
525 | .IP "2" | |
526 | The \fIbridge\fR argument to \fBbr\-exists\fR specified the name of a | |
527 | bridge that does not exist. | |
528 | .SH "SEE ALSO" | |
529 | . | |
dfbe07ba | 530 | .BR ovsdb\-server (1), |
3b135da3 | 531 | .BR ovs\-vswitchd (8). |