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