1ovn-ic-sbctl(8) OVN Manual ovn-ic-sbctl(8)
2
3
4
5build/.PP
6
8 ovn-ic-sbctl - Open Virtual Network interconnection southbound db man‐
9 agement utility
10
12 ovn-ic-sbctl [options] command [arg...]
13
15 This utility can be used to manage the OVN interconnection southbound
16 database.
17
19 init Initializes the database, if it is empty. If the database has
20 already been initialized, this command has no effect.
21
22 show [availability_zone]
23 Prints a brief overview of the database contents. If availabil‐
24 ity_zone is provided, only records related to that availability
25 zone are shown.
26
28 These commands query and modify the contents of ovsdb tables. They are
29 a slight abstraction of the ovsdb interface and as such they operate at
30 a lower level than other ovn-ic-sbctl commands.
31
32 Identifying Tables, Records, and Columns
33
34 Each of these commands has a table parameter to identify a table within
35 the database. Many of them also take a record parameter that identifies
36 a particular record within a table. The record parameter may be the
37 UUID for a record, which may be abbreviated to its first 4 (or more)
38 hex digits, as long as that is unique. Many tables offer additional
39 ways to identify records. Some commands also take column parameters
40 that identify a particular field within the records in a table.
41
42 For a list of tables and their columns, see ovn-ic-sb(5) or see the ta‐
43 ble listing from the --help option.
44
45 Record names must be specified in full and with correct capitalization,
46 except that UUIDs may be abbreviated to their first 4 (or more) hex
47 digits, as long as that is unique within the table. Names of tables and
48 columns are not case-sensitive, and - and _ are treated interchange‐
49 ably. Unique abbreviations of table and column names are acceptable,
50 e.g. g or gatew is sufficient to identify the Gateway table.
51
52 Database Values
53
54 Each column in the database accepts a fixed type of data. The currently
55 defined basic types, and their representations, are:
56
57 integer
58 A decimal integer in the range -2**63 to 2**63-1, inclu‐
59 sive.
60
61 real A floating-point number.
62
63 Boolean
64 True or false, written true or false, respectively.
65
66 string An arbitrary Unicode string, except that null bytes are
67 not allowed. Quotes are optional for most strings that
68 begin with an English letter or underscore and consist
69 only of letters, underscores, hyphens, and periods. How‐
70 ever, true and false and strings that match the syntax of
71 UUIDs (see below) must be enclosed in double quotes to
72 distinguish them from other basic types. When double
73 quotes are used, the syntax is that of strings in JSON,
74 e.g. backslashes may be used to escape special charac‐
75 ters. The empty string must be represented as a pair of
76 double quotes ("").
77
78 UUID Either a universally unique identifier in the style of
79 RFC 4122, e.g. f81d4fae-7dec-11d0-a765-00a0c91e6bf6, or
80 an @name defined by a get or create command within the
81 same ovs-vsctl invocation.
82
83 Multiple values in a single column may be separated by spaces or a sin‐
84 gle comma. When multiple values are present, duplicates are not
85 allowed, and order is not important. Conversely, some database columns
86 can have an empty set of values, represented as [], and square brackets
87 may optionally enclose other non-empty sets or single values as well.
88
89 A few database columns are ``maps’’ of key-value pairs, where the key
90 and the value are each some fixed database type. These are specified in
91 the form key=value, where key and value follow the syntax for the col‐
92 umn’s key type and value type, respectively. When multiple pairs are
93 present (separated by spaces or a comma), duplicate keys are not
94 allowed, and again the order is not important. Duplicate values are
95 allowed. An empty map is represented as {}. Curly braces may optionally
96 enclose non-empty maps as well (but use quotes to prevent the shell
97 from expanding other-config={0=x,1=y} into other-config=0=x other-con‐
98 fig=1=y, which may not have the desired effect).
99
100 Database Command Syntax
101
102 [--if-exists] [--columns=column[,column]...] list table
103 [record]...
104 Lists the data in each specified record. If no records
105 are specified, lists all the records in table.
106
107 If --columns is specified, only the requested columns are
108 listed, in the specified order. Otherwise, all columns
109 are listed, in alphabetical order by column name.
110
111 Without --if-exists, it is an error if any specified
112 record does not exist. With --if-exists, the command
113 ignores any record that does not exist, without producing
114 any output.
115
116 [--columns=column[,column]...] find table [col‐
117 umn[:key]=value]...
118 Lists the data in each record in table whose column
119 equals value or, if key is specified, whose column con‐
120 tains a key with the specified value. The following oper‐
121 ators may be used where = is written in the syntax sum‐
122 mary:
123
124 = != < > <= >=
125 Selects records in which column[:key] equals, does
126 not equal, is less than, is greater than, is less
127 than or equal to, or is greater than or equal to
128 value, respectively.
129
130 Consider column[:key] and value as sets of ele‐
131 ments. Identical sets are considered equal. Other‐
132 wise, if the sets have different numbers of ele‐
133 ments, then the set with more elements is consid‐
134 ered to be larger. Otherwise, consider a element
135 from each set pairwise, in increasing order within
136 each set. The first pair that differs determines
137 the result. (For a column that contains key-value
138 pairs, first all the keys are compared, and values
139 are considered only if the two sets contain iden‐
140 tical keys.)
141
142 {=} {!=}
143 Test for set equality or inequality, respectively.
144
145 {<=} Selects records in which column[:key] is a subset
146 of value. For example, flood-vlans{<=}1,2 selects
147 records in which the flood-vlans column is the
148 empty set or contains 1 or 2 or both.
149
150 {<} Selects records in which column[:key] is a proper
151 subset of value. For example, flood-vlans{<}1,2
152 selects records in which the flood-vlans column is
153 the empty set or contains 1 or 2 but not both.
154
155 {>=} {>}
156 Same as {<=} and {<}, respectively, except that
157 the relationship is reversed. For example,
158 flood-vlans{>=}1,2 selects records in which the
159 flood-vlans column contains both 1 and 2.
160
161 For arithmetic operators (= != < > <= >=), when key is
162 specified but a particular record’s column does not con‐
163 tain key, the record is always omitted from the results.
164 Thus, the condition other-config:mtu!=1500 matches
165 records that have a mtu key whose value is not 1500, but
166 not those that lack an mtu key.
167
168 For the set operators, when key is specified but a par‐
169 ticular record’s column does not contain key, the compar‐
170 ison is done against an empty set. Thus, the condition
171 other-config:mtu{!=}1500 matches records that have a mtu
172 key whose value is not 1500 and those that lack an mtu
173 key.
174
175 Don’t forget to escape < or > from interpretation by the
176 shell.
177
178 If --columns is specified, only the requested columns are
179 listed, in the specified order. Otherwise all columns are
180 listed, in alphabetical order by column name.
181
182 The UUIDs shown for rows created in the same ovs-vsctl
183 invocation will be wrong.
184
185 [--if-exists] [--id=@name] get table record [column[:key]]...
186 Prints the value of each specified column in the given
187 record in table. For map columns, a key may optionally be
188 specified, in which case the value associated with key in
189 the column is printed, instead of the entire map.
190
191 Without --if-exists, it is an error if record does not
192 exist or key is specified, if key does not exist in
193 record. With --if-exists, a missing record yields no out‐
194 put and a missing key prints a blank line.
195
196 If @name is specified, then the UUID for record may be
197 referred to by that name later in the same ovs-vsctl
198 invocation in contexts where a UUID is expected.
199
200 Both --id and the column arguments are optional, but usu‐
201 ally at least one or the other should be specified. If
202 both are omitted, then get has no effect except to verify
203 that record exists in table.
204
205 --id and --if-exists cannot be used together.
206
207 [--if-exists] set table record column[:key]=value...
208 Sets the value of each specified column in the given
209 record in table to value. For map columns, a key may
210 optionally be specified, in which case the value associ‐
211 ated with key in that column is changed (or added, if
212 none exists), instead of the entire map.
213
214 Without --if-exists, it is an error if record does not
215 exist. With --if-exists, this command does nothing if
216 record does not exist.
217
218 [--if-exists] add table record column [key=]value...
219 Adds the specified value or key-value pair to column in
220 record in table. If column is a map, then key is
221 required, otherwise it is prohibited. If key already
222 exists in a map column, then the current value is not
223 replaced (use the set command to replace an existing
224 value).
225
226 Without --if-exists, it is an error if record does not
227 exist. With --if-exists, this command does nothing if
228 record does not exist.
229
230 [--if-exists] remove table record column value...
231
232 [--if-exists] remove table record column key...
233
234 [--if-exists] remove table record column key=value...
235 Removes the specified values or key-value pairs from col‐
236 umn in record in table. The first form applies to columns
237 that are not maps: each specified value is removed from
238 the column. The second and third forms apply to map col‐
239 umns: if only a key is specified, then any key-value pair
240 with the given key is removed, regardless of its value;
241 if a value is given then a pair is removed only if both
242 key and value match.
243
244 It is not an error if the column does not contain the
245 specified key or value or pair.
246
247 Without --if-exists, it is an error if record does not
248 exist. With --if-exists, this command does nothing if
249 record does not exist.
250
251 [--if-exists] clear table record column...
252 Sets each column in record in table to the empty set or
253 empty map, as appropriate. This command applies only to
254 columns that are allowed to be empty.
255
256 Without --if-exists, it is an error if record does not
257 exist. With --if-exists, this command does nothing if
258 record does not exist.
259
260 [--id=@name] create table column[:key]=value...
261 Creates a new record in table and sets the initial values
262 of each column. Columns not explicitly set will receive
263 their default values. Outputs the UUID of the new row.
264
265 If @name is specified, then the UUID for the new row may
266 be referred to by that name elsewhere in the same \*(PN
267 invocation in contexts where a UUID is expected. Such
268 references may precede or follow the create command.
269
270 Caution (ovs-vsctl as example)
271 Records in the Open vSwitch database are signifi‐
272 cant only when they can be reached directly or
273 indirectly from the Open_vSwitch table. Except for
274 records in the QoS or Queue tables, records that
275 are not reachable from the Open_vSwitch table are
276 automatically deleted from the database. This
277 deletion happens immediately, without waiting for
278 additional ovs-vsctl commands or other database
279 activity. Thus, a create command must generally be
280 accompanied by additional commands within the same
281 ovs-vsctl invocation to add a chain of references
282 to the newly created record from the top-level
283 Open_vSwitch record. The EXAMPLES section gives
284 some examples that show how to do this.
285
286 [--if-exists] destroy table record...
287 Deletes each specified record from table. Unless
288 --if-exists is specified, each records must exist.
289
290 --all destroy table
291 Deletes all records from the table.
292
293 Caution (ovs-vsctl as example)
294 The destroy command is only useful for records in
295 the QoS or Queue tables. Records in other tables
296 are automatically deleted from the database when
297 they become unreachable from the Open_vSwitch ta‐
298 ble. This means that deleting the last reference
299 to a record is sufficient for deleting the record
300 itself. For records in these tables, destroy is
301 silently ignored. See the EXAMPLES section below
302 for more information.
303
304 wait-until table record [column[:key]=value]...
305 Waits until table contains a record named record whose
306 column equals value or, if key is specified, whose column
307 contains a key with the specified value. Any of the oper‐
308 ators !=, <, >, <=, or >= may be substituted for = to
309 test for inequality, less than, greater than, less than
310 or equal to, or greater than or equal to, respectively.
311 (Don’t forget to escape < or > from interpretation by the
312 shell.)
313
314 If no column[:key]=value arguments are given, this com‐
315 mand waits only until record exists. If more than one
316 such argument is given, the command waits until all of
317 them are satisfied.
318
319 Caution (ovs-vsctl as example)
320 Usually wait-until should be placed at the begin‐
321 ning of a set of ovs-vsctl commands. For example,
322 wait-until bridge br0 -- get bridge br0 data‐
323 path_id waits until a bridge named br0 is created,
324 then prints its datapath_id column, whereas get
325 bridge br0 datapath_id -- wait-until bridge br0
326 will abort if no bridge named br0 exists when
327 ovs-vsctl initially connects to the database.
328
329 Consider specifying --timeout=0 along with --wait-until,
330 to prevent ovs-vsctl from terminating after waiting only
331 at most 5 seconds.
332
333 comment [arg]...
334 This command has no effect on behavior, but any database
335 log record created by the command will include the com‐
336 mand and its arguments.
337
339 get-connection
340 Prints the configured connection(s).
341
342 del-connection
343 Deletes the configured connection(s).
344
345 [--inactivity-probe=msecs] set-connection target...
346 Sets the configured manager target or targets. Use --inactiv‐
347 ity-probe=msecs to override the default idle connection inactiv‐
348 ity probe time. Use 0 to disable inactivity probes.
349
351 get-ssl
352 Prints the SSL configuration.
353
354 del-ssl
355 Deletes the current SSL configuration.
356
357 [--bootstrap] set-ssl private-key certificate ca-cert [ssl-protocol-
358 list [ssl-cipher-list]]
359 Sets the SSL configuration.
360
362 --db database
363 The OVSDB database remote to contact. If the OVN_IC_SB_DB envi‐
364 ronment variable is set, its value is used as the default. Oth‐
365 erwise, the default is unix:/ovn_ic_sb_db.sock, but this default
366 is unlikely to be useful outside of single-machine OVN test
367 environments.
368
369 --leader-only
370 --no-leader-only
371 By default, or with --leader-only, when the database server is a
372 clustered database, ovn-ic-sbctl will avoid servers other than the
373 cluster leader. This ensures that any data that ovn-ic-sbctl reads
374 and reports is up-to-date. With --no-leader-only, ovn-ic-sbctl
375 will use any server in the cluster, which means that for read-only
376 transactions it can report and act on stale data (transactions
377 that modify the database are always serialized even with
378 --no-leader-only). Refer to Understanding Cluster Consistency in
379 ovsdb(7) for more information.
380
382 -v[spec]
383 --verbose=[spec]
384 Sets logging levels. Without any spec, sets the log level for
385 every module and destination to dbg. Otherwise, spec is a list of
386 words separated by spaces or commas or colons, up to one from each
387 category below:
388
389 · A valid module name, as displayed by the vlog/list command
390 on ovs-appctl(8), limits the log level change to the speci‐
391 fied module.
392
393 · syslog, console, or file, to limit the log level change to
394 only to the system log, to the console, or to a file,
395 respectively. (If --detach is specified, the daemon closes
396 its standard file descriptors, so logging to the console
397 will have no effect.)
398
399 On Windows platform, syslog is accepted as a word and is
400 only useful along with the --syslog-target option (the word
401 has no effect otherwise).
402
403 · off, emer, err, warn, info, or dbg, to control the log
404 level. Messages of the given severity or higher will be
405 logged, and messages of lower severity will be filtered
406 out. off filters out all messages. See ovs-appctl(8) for a
407 definition of each log level.
408
409 Case is not significant within spec.
410
411 Regardless of the log levels set for file, logging to a file will
412 not take place unless --log-file is also specified (see below).
413
414 For compatibility with older versions of OVS, any is accepted as a
415 word but has no effect.
416
417 -v
418 --verbose
419 Sets the maximum logging verbosity level, equivalent to --ver‐
420 bose=dbg.
421
422 -vPATTERN:destination:pattern
423 --verbose=PATTERN:destination:pattern
424 Sets the log pattern for destination to pattern. Refer to
425 ovs-appctl(8) for a description of the valid syntax for pattern.
426
427 -vFACILITY:facility
428 --verbose=FACILITY:facility
429 Sets the RFC5424 facility of the log message. facility can be one
430 of kern, user, mail, daemon, auth, syslog, lpr, news, uucp, clock,
431 ftp, ntp, audit, alert, clock2, local0, local1, local2, local3,
432 local4, local5, local6 or local7. If this option is not specified,
433 daemon is used as the default for the local system syslog and
434 local0 is used while sending a message to the target provided via
435 the --syslog-target option.
436
437 --log-file[=file]
438 Enables logging to a file. If file is specified, then it is used
439 as the exact name for the log file. The default log file name used
440 if file is omitted is /var/log/ovn/program.log.
441
442 --syslog-target=host:port
443 Send syslog messages to UDP port on host, in addition to the sys‐
444 tem syslog. The host must be a numerical IP address, not a host‐
445 name.
446
447 --syslog-method=method
448 Specify method as how syslog messages should be sent to syslog
449 daemon. The following forms are supported:
450
451 · libc, to use the libc syslog() function. Downside of using
452 this options is that libc adds fixed prefix to every mes‐
453 sage before it is actually sent to the syslog daemon over
454 /dev/log UNIX domain socket.
455
456 · unix:file, to use a UNIX domain socket directly. It is pos‐
457 sible to specify arbitrary message format with this option.
458 However, rsyslogd 8.9 and older versions use hard coded
459 parser function anyway that limits UNIX domain socket use.
460 If you want to use arbitrary message format with older
461 rsyslogd versions, then use UDP socket to localhost IP
462 address instead.
463
464 · udp:ip:port, to use a UDP socket. With this method it is
465 possible to use arbitrary message format also with older
466 rsyslogd. When sending syslog messages over UDP socket
467 extra precaution needs to be taken into account, for exam‐
468 ple, syslog daemon needs to be configured to listen on the
469 specified UDP port, accidental iptables rules could be
470 interfering with local syslog traffic and there are some
471 security considerations that apply to UDP sockets, but do
472 not apply to UNIX domain sockets.
473
474 · null, to discard all messages logged to syslog.
475
476 The default is taken from the OVS_SYSLOG_METHOD environment vari‐
477 able; if it is unset, the default is libc.
478
480 These options control the format of output from the list and find com‐
481 mands.
482
483 -f format
484 --format=format
485 Sets the type of table formatting. The following types of
486 format are available:
487
488 table 2-D text tables with aligned columns.
489
490 list (default)
491 A list with one column per line and rows separated
492 by a blank line.
493
494 html HTML tables.
495
496 csv Comma-separated values as defined in RFC 4180.
497
498 json JSON format as defined in RFC 4627. The output is a
499 sequence of JSON objects, each of which corresponds
500 to one table. Each JSON object has the following
501 members with the noted values:
502
503 caption
504 The table’s caption. This member is omitted
505 if the table has no caption.
506
507 headings
508 An array with one element per table column.
509 Each array element is a string giving the
510 corresponding column’s heading.
511
512 data An array with one element per table row. Each
513 element is also an array with one element per
514 table column. The elements of this second-
515 level array are the cells that constitute the
516 table. Cells that represent OVSDB data or
517 data types are expressed in the format
518 described in the OVSDB specification; other
519 cells are simply expressed as text strings.
520
521 -d format
522 --data=format
523 Sets the formatting for cells within output tables unless
524 the table format is set to json, in which case json format‐
525 ting is always used when formatting cells. The following
526 types of format are available:
527
528 string (default)
529 The simple format described in the Database Values
530 section of ovs-vsctl(8).
531
532 bare The simple format with punctuation stripped off: []
533 and {} are omitted around sets, maps, and empty col‐
534 umns, items within sets and maps are space-sepa‐
535 rated, and strings are never quoted. This format may
536 be easier for scripts to parse.
537
538 json The RFC 4627 JSON format as described above.
539
540 --no-headings
541 This option suppresses the heading row that otherwise
542 appears in the first row of table output.
543
544 --pretty
545 By default, JSON in output is printed as compactly as pos‐
546 sible. This option causes JSON in output to be printed in a
547 more readable fashion. Members of objects and elements of
548 arrays are printed one per line, with indentation.
549
550 This option does not affect JSON in tables, which is always
551 printed compactly.
552
553 --bare
554 Equivalent to --format=list --data=bare --no-headings.
555
556 PKI Options
557 PKI configuration is required to use SSL for the connection to the
558 database.
559
560 -p privkey.pem
561 --private-key=privkey.pem
562 Specifies a PEM file containing the private key used as
563 identity for outgoing SSL connections.
564
565 -c cert.pem
566 --certificate=cert.pem
567 Specifies a PEM file containing a certificate that certi‐
568 fies the private key specified on -p or --private-key to be
569 trustworthy. The certificate must be signed by the certifi‐
570 cate authority (CA) that the peer in SSL connections will
571 use to verify it.
572
573 -C cacert.pem
574 --ca-cert=cacert.pem
575 Specifies a PEM file containing the CA certificate for ver‐
576 ifying certificates presented to this program by SSL peers.
577 (This may be the same certificate that SSL peers use to
578 verify the certificate specified on -c or --certificate, or
579 it may be a different one, depending on the PKI design in
580 use.)
581
582 -C none
583 --ca-cert=none
584 Disables verification of certificates presented by SSL
585 peers. This introduces a security risk, because it means
586 that certificates cannot be verified to be those of known
587 trusted hosts.
588
589 --bootstrap-ca-cert=cacert.pem
590 When cacert.pem exists, this option has the same effect
591 as -C or --ca-cert. If it does not exist, then the exe‐
592 cutable will attempt to obtain the CA certificate from
593 the SSL peer on its first SSL connection and save it to
594 the named PEM file. If it is successful, it will immedi‐
595 ately drop the connection and reconnect, and from then on
596 all SSL connections must be authenticated by a certifi‐
597 cate signed by the CA certificate thus obtained.
598
599 This option exposes the SSL connection to a man-in-the-
600 middle attack obtaining the initial CA certificate, but
601 it may be useful for bootstrapping.
602
603 This option is only useful if the SSL peer sends its CA
604 certificate as part of the SSL certificate chain. The SSL
605 protocol does not require the server to send the CA cer‐
606 tificate.
607
608 This option is mutually exclusive with -C and --ca-cert.
609
610 Other Options
611 -h
612 --help
613 Prints a brief help message to the console.
614
615 -V
616 --version
617 Prints version information to the console.
618
619
620
621OVN 20.03.0 ovn-ic-sbctl ovn-ic-sbctl(8)