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