1ovn-ic-sbctl(8) OVN Manual ovn-ic-sbctl(8)
2build/.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 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 Identifying Tables, Records, and Columns
33 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 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 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 Database Values
53 Each column in the database accepts a fixed type of data. The currently
55 defined basic types, and their representations, are:
56 integer
58 A decimal integer in the range -2**63 to 2**63-1, inclu‐
59 sive.
60 real A floating-point number.
62 Boolean
64 True or false, written true or false, respectively.
65 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 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 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 al‐
85 lowed, 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 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 al‐
94 lowed, and again the order is not important. Duplicate values are al‐
95 lowed. 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 Database Command Syntax
101 [--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 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 Without --if-exists, it is an error if any specified
112 record does not exist. With --if-exists, the command ig‐
113 nores any record that does not exist, without producing
114 any output.
115 [--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 = != < > <= >=
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 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 {=} {!=}
143 Test for set equality or inequality, respectively.
144 {<=} 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 {<} 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 {>=} {>}
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 The following operators are available only in Open
162 vSwitch 2.16 and later:
163 {in} Selects records in which every element in col‐
165 umn[:key] is also in value. (This is the same as
166 {<=}.)
167 {not-in}
169 Selects records in which every element in col‐
170 umn[:key] is not in value.
171 For arithmetic operators (= != < > <= >=), when key is
173 specified but a particular record’s column does not con‐
174 tain key, the record is always omitted from the results.
175 Thus, the condition other-config:mtu!=1500 matches
176 records that have a mtu key whose value is not 1500, but
177 not those that lack an mtu key.
178 For the set operators, when key is specified but a par‐
180 ticular record’s column does not contain key, the compar‐
181 ison is done against an empty set. Thus, the condition
182 other-config:mtu{!=}1500 matches records that have a mtu
183 key whose value is not 1500 and those that lack an mtu
184 key.
185 Don’t forget to escape < or > from interpretation by the
187 shell.
188 If --columns is specified, only the requested columns are
190 listed, in the specified order. Otherwise all columns are
191 listed, in alphabetical order by column name.
192 The UUIDs shown for rows created in the same ovs-vsctl
194 invocation will be wrong.
195 [--if-exists] [--id=@name] get table record [column[:key]]...
197 Prints the value of each specified column in the given
198 record in table. For map columns, a key may optionally be
199 specified, in which case the value associated with key in
200 the column is printed, instead of the entire map.
201 Without --if-exists, it is an error if record does not
203 exist or key is specified, if key does not exist in
204 record. With --if-exists, a missing record yields no out‐
205 put and a missing key prints a blank line.
206 If @name is specified, then the UUID for record may be
208 referred to by that name later in the same ovs-vsctl in‐
209 vocation in contexts where a UUID is expected.
210 Both --id and the column arguments are optional, but usu‐
212 ally at least one or the other should be specified. If
213 both are omitted, then get has no effect except to verify
214 that record exists in table.
215 --id and --if-exists cannot be used together.
217 [--if-exists] set table record column[:key]=value...
219 Sets the value of each specified column in the given
220 record in table to value. For map columns, a key may op‐
221 tionally be specified, in which case the value associated
222 with key in that column is changed (or added, if none ex‐
223 ists), instead of the entire map.
224 Without --if-exists, it is an error if record does not
226 exist. With --if-exists, this command does nothing if
227 record does not exist.
228 [--if-exists] add table record column [key=]value...
230 Adds the specified value or key-value pair to column in
231 record in table. If column is a map, then key is re‐
232 quired, otherwise it is prohibited. If key already exists
233 in a map column, then the current value is not replaced
234 (use the set command to replace an existing value).
235 Without --if-exists, it is an error if record does not
237 exist. With --if-exists, this command does nothing if
238 record does not exist.
239 [--if-exists] remove table record column value...
241 [--if-exists] remove table record column key...
243 [--if-exists] remove table record column key=value...
245 Removes the specified values or key-value pairs from col‐
246 umn in record in table. The first form applies to columns
247 that are not maps: each specified value is removed from
248 the column. The second and third forms apply to map col‐
249 umns: if only a key is specified, then any key-value pair
250 with the given key is removed, regardless of its value;
251 if a value is given then a pair is removed only if both
252 key and value match.
253 It is not an error if the column does not contain the
255 specified key or value or pair.
256 Without --if-exists, it is an error if record does not
258 exist. With --if-exists, this command does nothing if
259 record does not exist.
260 [--if-exists] clear table record column...
262 Sets each column in record in table to the empty set or
263 empty map, as appropriate. This command applies only to
264 columns that are allowed to be empty.
265 Without --if-exists, it is an error if record does not
267 exist. With --if-exists, this command does nothing if
268 record does not exist.
269 [--id=@name] create table column[:key]=value...
271 Creates a new record in table and sets the initial values
272 of each column. Columns not explicitly set will receive
273 their default values. Outputs the UUID of the new row.
274 If @name is specified, then the UUID for the new row may
276 be referred to by that name elsewhere in the same \*(PN
277 invocation in contexts where a UUID is expected. Such
278 references may precede or follow the create command.
279 Caution (ovs-vsctl as example)
281 Records in the Open vSwitch database are signifi‐
282 cant only when they can be reached directly or in‐
283 directly from the Open_vSwitch table. Except for
284 records in the QoS or Queue tables, records that
285 are not reachable from the Open_vSwitch table are
286 automatically deleted from the database. This
287 deletion happens immediately, without waiting for
288 additional ovs-vsctl commands or other database
289 activity. Thus, a create command must generally be
290 accompanied by additional commands within the same
291 ovs-vsctl invocation to add a chain of references
292 to the newly created record from the top-level
293 Open_vSwitch record. The EXAMPLES section gives
294 some examples that show how to do this.
295 [--if-exists] destroy table record...
297 Deletes each specified record from table. Unless --if-ex‐
298 ists is specified, each records must exist.
299 --all destroy table
301 Deletes all records from the table.
302 Caution (ovs-vsctl as example)
304 The destroy command is only useful for records in
305 the QoS or Queue tables. Records in other tables
306 are automatically deleted from the database when
307 they become unreachable from the Open_vSwitch ta‐
308 ble. This means that deleting the last reference
309 to a record is sufficient for deleting the record
310 itself. For records in these tables, destroy is
311 silently ignored. See the EXAMPLES section below
312 for more information.
313 wait-until table record [column[:key]=value]...
315 Waits until table contains a record named record whose
316 column equals value or, if key is specified, whose column
317 contains a key with the specified value. This command
318 supports the same operators and semantics described for
319 the find command above.
320 If no column[:key]=value arguments are given, this com‐
322 mand waits only until record exists. If more than one
323 such argument is given, the command waits until all of
324 them are satisfied.
325 Caution (ovs-vsctl as example)
327 Usually wait-until should be placed at the begin‐
328 ning of a set of ovs-vsctl commands. For example,
329 wait-until bridge br0 -- get bridge br0 data‐
330 path_id waits until a bridge named br0 is created,
331 then prints its datapath_id column, whereas get
332 bridge br0 datapath_id -- wait-until bridge br0
333 will abort if no bridge named br0 exists when
334 ovs-vsctl initially connects to the database.
335 Consider specifying --timeout=0 along with --wait-until,
337 to prevent ovs-vsctl from terminating after waiting only
338 at most 5 seconds.
339 comment [arg]...
341 This command has no effect on behavior, but any database
342 log record created by the command will include the com‐
343 mand and its arguments.
344
346 get-connection
347 Prints the configured connection(s).
348 del-connection
350 Deletes the configured connection(s).
351 [--inactivity-probe=msecs] set-connection target...
353 Sets the configured manager target or targets. Use --inactiv‐
354 ity-probe=msecs to override the default idle connection inactiv‐
355 ity probe time. Use 0 to disable inactivity probes.
356
358 get-ssl
359 Prints the SSL configuration.
360 del-ssl
362 Deletes the current SSL configuration.
363 [--bootstrap] set-ssl private-key certificate ca-cert [ssl-protocol-
365 list [ssl-cipher-list]]
366 Sets the SSL configuration.
367
369 --db database
370 The OVSDB database remote to contact. If the OVN_IC_SB_DB envi‐
371 ronment variable is set, its value is used as the default. Oth‐
372 erwise, the default is unix:/ovn_ic_sb_db.sock, but this default
373 is unlikely to be useful outside of single-machine OVN test en‐
374 vironments.
375 --leader-only
377 --no-leader-only
378 By default, or with --leader-only, when the database server is a
379 clustered database, ovn-ic-sbctl will avoid servers other than the
380 cluster leader. This ensures that any data that ovn-ic-sbctl reads
381 and reports is up-to-date. With --no-leader-only, ovn-ic-sbctl
382 will use any server in the cluster, which means that for read-only
383 transactions it can report and act on stale data (transactions
384 that modify the database are always serialized even with
385 --no-leader-only). Refer to Understanding Cluster Consistency in
386 ovsdb(7) for more information.
387
389 -v[spec]
390 --verbose=[spec]
391 Sets logging levels. Without any spec, sets the log level for ev‐
392 ery module and destination to dbg. Otherwise, spec is a list of
393 words separated by spaces or commas or colons, up to one from each
394 category below:
395 • A valid module name, as displayed by the vlog/list command
397 on ovs-appctl(8), limits the log level change to the speci‐
398 fied module.
399 • syslog, console, or file, to limit the log level change to
401 only to the system log, to the console, or to a file, re‐
402 spectively. (If --detach is specified, the daemon closes
403 its standard file descriptors, so logging to the console
404 will have no effect.)
405 On Windows platform, syslog is accepted as a word and is
407 only useful along with the --syslog-target option (the word
408 has no effect otherwise).
409 • off, emer, err, warn, info, or dbg, to control the log
411 level. Messages of the given severity or higher will be
412 logged, and messages of lower severity will be filtered
413 out. off filters out all messages. See ovs-appctl(8) for a
414 definition of each log level.
415 Case is not significant within spec.
417 Regardless of the log levels set for file, logging to a file will
419 not take place unless --log-file is also specified (see below).
420 For compatibility with older versions of OVS, any is accepted as a
422 word but has no effect.
423 -v
425 --verbose
426 Sets the maximum logging verbosity level, equivalent to --ver‐
427 bose=dbg.
428 -vPATTERN:destination:pattern
430 --verbose=PATTERN:destination:pattern
431 Sets the log pattern for destination to pattern. Refer to ovs-ap‐
432 pctl(8) for a description of the valid syntax for pattern.
433 -vFACILITY:facility
435 --verbose=FACILITY:facility
436 Sets the RFC5424 facility of the log message. facility can be one
437 of kern, user, mail, daemon, auth, syslog, lpr, news, uucp, clock,
438 ftp, ntp, audit, alert, clock2, local0, local1, local2, local3,
439 local4, local5, local6 or local7. If this option is not specified,
440 daemon is used as the default for the local system syslog and lo‐
441 cal0 is used while sending a message to the target provided via
442 the --syslog-target option.
443 --log-file[=file]
445 Enables logging to a file. If file is specified, then it is used
446 as the exact name for the log file. The default log file name used
447 if file is omitted is /var/log/ovn/program.log.
448 --syslog-target=host:port
450 Send syslog messages to UDP port on host, in addition to the sys‐
451 tem syslog. The host must be a numerical IP address, not a host‐
452 name.
453 --syslog-method=method
455 Specify method as how syslog messages should be sent to syslog
456 daemon. The following forms are supported:
457 • libc, to use the libc syslog() function. Downside of using
459 this options is that libc adds fixed prefix to every mes‐
460 sage before it is actually sent to the syslog daemon over
461 /dev/log UNIX domain socket.
462 • unix:file, to use a UNIX domain socket directly. It is pos‐
464 sible to specify arbitrary message format with this option.
465 However, rsyslogd 8.9 and older versions use hard coded
466 parser function anyway that limits UNIX domain socket use.
467 If you want to use arbitrary message format with older
468 rsyslogd versions, then use UDP socket to localhost IP ad‐
469 dress instead.
470 • udp:ip:port, to use a UDP socket. With this method it is
472 possible to use arbitrary message format also with older
473 rsyslogd. When sending syslog messages over UDP socket ex‐
474 tra precaution needs to be taken into account, for example,
475 syslog daemon needs to be configured to listen on the spec‐
476 ified UDP port, accidental iptables rules could be inter‐
477 fering with local syslog traffic and there are some secu‐
478 rity considerations that apply to UDP sockets, but do not
479 apply to UNIX domain sockets.
480 • null, to discard all messages logged to syslog.
482 The default is taken from the OVS_SYSLOG_METHOD environment vari‐
484 able; if it is unset, the default is libc.
485
487 These options control the format of output from the list and find com‐
488 mands.
489 -f format
491 --format=format
492 Sets the type of table formatting. The following types of
493 format are available:
494 table 2-D text tables with aligned columns.
496 list (default)
498 A list with one column per line and rows separated
499 by a blank line.
500 html HTML tables.
502 csv Comma-separated values as defined in RFC 4180.
504 json JSON format as defined in RFC 4627. The output is a
506 sequence of JSON objects, each of which corresponds
507 to one table. Each JSON object has the following
508 members with the noted values:
509 caption
511 The table’s caption. This member is omitted
512 if the table has no caption.
513 headings
515 An array with one element per table column.
516 Each array element is a string giving the
517 corresponding column’s heading.
518 data An array with one element per table row. Each
520 element is also an array with one element per
521 table column. The elements of this second-
522 level array are the cells that constitute the
523 table. Cells that represent OVSDB data or
524 data types are expressed in the format de‐
525 scribed in the OVSDB specification; other
526 cells are simply expressed as text strings.
527 -d format
529 --data=format
530 Sets the formatting for cells within output tables unless
531 the table format is set to json, in which case json format‐
532 ting is always used when formatting cells. The following
533 types of format are available:
534 string (default)
536 The simple format described in the Database Values
537 section of ovs-vsctl(8).
538 bare The simple format with punctuation stripped off: []
540 and {} are omitted around sets, maps, and empty col‐
541 umns, items within sets and maps are space-sepa‐
542 rated, and strings are never quoted. This format may
543 be easier for scripts to parse.
544 json The RFC 4627 JSON format as described above.
546 --no-headings
548 This option suppresses the heading row that otherwise ap‐
549 pears in the first row of table output.
550 --pretty
552 By default, JSON in output is printed as compactly as pos‐
553 sible. This option causes JSON in output to be printed in a
554 more readable fashion. Members of objects and elements of
555 arrays are printed one per line, with indentation.
556 This option does not affect JSON in tables, which is always
558 printed compactly.
559 --bare
561 Equivalent to --format=list --data=bare --no-headings.
562 PKI Options
564 PKI configuration is required to use SSL for the connection to the
565 database.
566 -p privkey.pem
568 --private-key=privkey.pem
569 Specifies a PEM file containing the private key used as
570 identity for outgoing SSL connections.
571 -c cert.pem
573 --certificate=cert.pem
574 Specifies a PEM file containing a certificate that certi‐
575 fies the private key specified on -p or --private-key to be
576 trustworthy. The certificate must be signed by the certifi‐
577 cate authority (CA) that the peer in SSL connections will
578 use to verify it.
579 -C cacert.pem
581 --ca-cert=cacert.pem
582 Specifies a PEM file containing the CA certificate for ver‐
583 ifying certificates presented to this program by SSL peers.
584 (This may be the same certificate that SSL peers use to
585 verify the certificate specified on -c or --certificate, or
586 it may be a different one, depending on the PKI design in
587 use.)
588 -C none
590 --ca-cert=none
591 Disables verification of certificates presented by SSL
592 peers. This introduces a security risk, because it means
593 that certificates cannot be verified to be those of known
594 trusted hosts.
595 --bootstrap-ca-cert=cacert.pem
597 When cacert.pem exists, this option has the same effect
598 as -C or --ca-cert. If it does not exist, then the exe‐
599 cutable will attempt to obtain the CA certificate from
600 the SSL peer on its first SSL connection and save it to
601 the named PEM file. If it is successful, it will immedi‐
602 ately drop the connection and reconnect, and from then on
603 all SSL connections must be authenticated by a certifi‐
604 cate signed by the CA certificate thus obtained.
605 This option exposes the SSL connection to a man-in-the-
607 middle attack obtaining the initial CA certificate, but
608 it may be useful for bootstrapping.
609 This option is only useful if the SSL peer sends its CA
611 certificate as part of the SSL certificate chain. The SSL
612 protocol does not require the server to send the CA cer‐
613 tificate.
614 This option is mutually exclusive with -C and --ca-cert.
616 Other Options
618 -h
619 --help
620 Prints a brief help message to the console.
621 -V
623 --version
624 Prints version information to the console.
625OVN 21.03.1 ovn-ic-sbctl ovn-ic-sbctl(8)