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|uuid)] 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 If a valid uuid is specified, then it is used as the UUID
279 of the new row.
280 Caution (ovs-vsctl as example)
282 Records in the Open vSwitch database are signifi‐
283 cant only when they can be reached directly or in‐
284 directly from the Open_vSwitch table. Except for
285 records in the QoS or Queue tables, records that
286 are not reachable from the Open_vSwitch table are
287 automatically deleted from the database. This
288 deletion happens immediately, without waiting for
289 additional ovs-vsctl commands or other database
290 activity. Thus, a create command must generally be
291 accompanied by additional commands within the same
292 ovs-vsctl invocation to add a chain of references
293 to the newly created record from the top-level
294 Open_vSwitch record. The EXAMPLES section gives
295 some examples that show how to do this.
296 [--if-exists] destroy table record...
298 Deletes each specified record from table. Unless --if-ex‐
299 ists is specified, each records must exist.
300 --all destroy table
302 Deletes all records from the table.
303 Caution (ovs-vsctl as example)
305 The destroy command is only useful for records in
306 the QoS or Queue tables. Records in other tables
307 are automatically deleted from the database when
308 they become unreachable from the Open_vSwitch ta‐
309 ble. This means that deleting the last reference
310 to a record is sufficient for deleting the record
311 itself. For records in these tables, destroy is
312 silently ignored. See the EXAMPLES section below
313 for more information.
314 wait-until table record [column[:key]=value]...
316 Waits until table contains a record named record whose
317 column equals value or, if key is specified, whose column
318 contains a key with the specified value. This command
319 supports the same operators and semantics described for
320 the find command above.
321 If no column[:key]=value arguments are given, this com‐
323 mand waits only until record exists. If more than one
324 such argument is given, the command waits until all of
325 them are satisfied.
326 Caution (ovs-vsctl as example)
328 Usually wait-until should be placed at the begin‐
329 ning of a set of ovs-vsctl commands. For example,
330 wait-until bridge br0 -- get bridge br0 data‐
331 path_id waits until a bridge named br0 is created,
332 then prints its datapath_id column, whereas get
333 bridge br0 datapath_id -- wait-until bridge br0
334 will abort if no bridge named br0 exists when
335 ovs-vsctl initially connects to the database.
336 Consider specifying --timeout=0 along with --wait-until,
338 to prevent ovs-vsctl from terminating after waiting only
339 at most 5 seconds.
340 comment [arg]...
342 This command has no effect on behavior, but any database
343 log record created by the command will include the com‐
344 mand and its arguments.
345
347 get-connection
348 Prints the configured connection(s).
349 del-connection
351 Deletes the configured connection(s).
352 [--inactivity-probe=msecs] set-connection target...
354 Sets the configured manager target or targets. Use --inactiv‐
355 ity-probe=msecs to override the default idle connection inactiv‐
356 ity probe time. Use 0 to disable inactivity probes.
357
359 get-ssl
360 Prints the SSL configuration.
361 del-ssl
363 Deletes the current SSL configuration.
364 [--bootstrap] set-ssl private-key certificate ca-cert [ssl-protocol-
366 list [ssl-cipher-list]]
367 Sets the SSL configuration.
368
370 --db database
371 The OVSDB database remote to contact. If the OVN_IC_SB_DB envi‐
372 ronment variable is set, its value is used as the default. Oth‐
373 erwise, the default is unix:/ovn_ic_sb_db.sock, but this default
374 is unlikely to be useful outside of single-machine OVN test en‐
375 vironments.
376 --leader-only
378 --no-leader-only
379 By default, or with --leader-only, when the database server is a
380 clustered database, ovn-ic-sbctl will avoid servers other than the
381 cluster leader. This ensures that any data that ovn-ic-sbctl reads
382 and reports is up-to-date. With --no-leader-only, ovn-ic-sbctl
383 will use any server in the cluster, which means that for read-only
384 transactions it can report and act on stale data (transactions
385 that modify the database are always serialized even with
386 --no-leader-only). Refer to Understanding Cluster Consistency in
387 ovsdb(7) for more information.
388
390 -v[spec]
391 --verbose=[spec]
392 Sets logging levels. Without any spec, sets the log level for ev‐
393 ery module and destination to dbg. Otherwise, spec is a list of
394 words separated by spaces or commas or colons, up to one from each
395 category below:
396 • A valid module name, as displayed by the vlog/list command
398 on ovs-appctl(8), limits the log level change to the speci‐
399 fied module.
400 • syslog, console, or file, to limit the log level change to
402 only to the system log, to the console, or to a file, re‐
403 spectively. (If --detach is specified, the daemon closes
404 its standard file descriptors, so logging to the console
405 will have no effect.)
406 On Windows platform, syslog is accepted as a word and is
408 only useful along with the --syslog-target option (the word
409 has no effect otherwise).
410 • off, emer, err, warn, info, or dbg, to control the log
412 level. Messages of the given severity or higher will be
413 logged, and messages of lower severity will be filtered
414 out. off filters out all messages. See ovs-appctl(8) for a
415 definition of each log level.
416 Case is not significant within spec.
418 Regardless of the log levels set for file, logging to a file will
420 not take place unless --log-file is also specified (see below).
421 For compatibility with older versions of OVS, any is accepted as a
423 word but has no effect.
424 -v
426 --verbose
427 Sets the maximum logging verbosity level, equivalent to --ver‐
428 bose=dbg.
429 -vPATTERN:destination:pattern
431 --verbose=PATTERN:destination:pattern
432 Sets the log pattern for destination to pattern. Refer to ovs-ap‐
433 pctl(8) for a description of the valid syntax for pattern.
434 -vFACILITY:facility
436 --verbose=FACILITY:facility
437 Sets the RFC5424 facility of the log message. facility can be one
438 of kern, user, mail, daemon, auth, syslog, lpr, news, uucp, clock,
439 ftp, ntp, audit, alert, clock2, local0, local1, local2, local3,
440 local4, local5, local6 or local7. If this option is not specified,
441 daemon is used as the default for the local system syslog and lo‐
442 cal0 is used while sending a message to the target provided via
443 the --syslog-target option.
444 --log-file[=file]
446 Enables logging to a file. If file is specified, then it is used
447 as the exact name for the log file. The default log file name used
448 if file is omitted is /var/log/ovn/program.log.
449 --syslog-target=host:port
451 Send syslog messages to UDP port on host, in addition to the sys‐
452 tem syslog. The host must be a numerical IP address, not a host‐
453 name.
454 --syslog-method=method
456 Specify method as how syslog messages should be sent to syslog
457 daemon. The following forms are supported:
458 • libc, to use the libc syslog() function. Downside of using
460 this options is that libc adds fixed prefix to every mes‐
461 sage before it is actually sent to the syslog daemon over
462 /dev/log UNIX domain socket.
463 • unix:file, to use a UNIX domain socket directly. It is pos‐
465 sible to specify arbitrary message format with this option.
466 However, rsyslogd 8.9 and older versions use hard coded
467 parser function anyway that limits UNIX domain socket use.
468 If you want to use arbitrary message format with older
469 rsyslogd versions, then use UDP socket to localhost IP ad‐
470 dress instead.
471 • udp:ip:port, to use a UDP socket. With this method it is
473 possible to use arbitrary message format also with older
474 rsyslogd. When sending syslog messages over UDP socket ex‐
475 tra precaution needs to be taken into account, for example,
476 syslog daemon needs to be configured to listen on the spec‐
477 ified UDP port, accidental iptables rules could be inter‐
478 fering with local syslog traffic and there are some secu‐
479 rity considerations that apply to UDP sockets, but do not
480 apply to UNIX domain sockets.
481 • null, to discard all messages logged to syslog.
483 The default is taken from the OVS_SYSLOG_METHOD environment vari‐
485 able; if it is unset, the default is libc.
486
488 These options control the format of output from the list and find com‐
489 mands.
490 -f format
492 --format=format
493 Sets the type of table formatting. The following types of
494 format are available:
495 table 2-D text tables with aligned columns.
497 list (default)
499 A list with one column per line and rows separated
500 by a blank line.
501 html HTML tables.
503 csv Comma-separated values as defined in RFC 4180.
505 json JSON format as defined in RFC 4627. The output is a
507 sequence of JSON objects, each of which corresponds
508 to one table. Each JSON object has the following
509 members with the noted values:
510 caption
512 The table’s caption. This member is omitted
513 if the table has no caption.
514 headings
516 An array with one element per table column.
517 Each array element is a string giving the
518 corresponding column’s heading.
519 data An array with one element per table row. Each
521 element is also an array with one element per
522 table column. The elements of this second-
523 level array are the cells that constitute the
524 table. Cells that represent OVSDB data or
525 data types are expressed in the format de‐
526 scribed in the OVSDB specification; other
527 cells are simply expressed as text strings.
528 -d format
530 --data=format
531 Sets the formatting for cells within output tables unless
532 the table format is set to json, in which case json format‐
533 ting is always used when formatting cells. The following
534 types of format are available:
535 string (default)
537 The simple format described in the Database Values
538 section of ovs-vsctl(8).
539 bare The simple format with punctuation stripped off: []
541 and {} are omitted around sets, maps, and empty col‐
542 umns, items within sets and maps are space-sepa‐
543 rated, and strings are never quoted. This format may
544 be easier for scripts to parse.
545 json The RFC 4627 JSON format as described above.
547 --no-headings
549 This option suppresses the heading row that otherwise ap‐
550 pears in the first row of table output.
551 --pretty
553 By default, JSON in output is printed as compactly as pos‐
554 sible. This option causes JSON in output to be printed in a
555 more readable fashion. Members of objects and elements of
556 arrays are printed one per line, with indentation.
557 This option does not affect JSON in tables, which is always
559 printed compactly.
560 --bare
562 Equivalent to --format=list --data=bare --no-headings.
563 PKI Options
565 PKI configuration is required to use SSL for the connection to the
566 database.
567 -p privkey.pem
569 --private-key=privkey.pem
570 Specifies a PEM file containing the private key used as
571 identity for outgoing SSL connections.
572 -c cert.pem
574 --certificate=cert.pem
575 Specifies a PEM file containing a certificate that certi‐
576 fies the private key specified on -p or --private-key to be
577 trustworthy. The certificate must be signed by the certifi‐
578 cate authority (CA) that the peer in SSL connections will
579 use to verify it.
580 -C cacert.pem
582 --ca-cert=cacert.pem
583 Specifies a PEM file containing the CA certificate for ver‐
584 ifying certificates presented to this program by SSL peers.
585 (This may be the same certificate that SSL peers use to
586 verify the certificate specified on -c or --certificate, or
587 it may be a different one, depending on the PKI design in
588 use.)
589 -C none
591 --ca-cert=none
592 Disables verification of certificates presented by SSL
593 peers. This introduces a security risk, because it means
594 that certificates cannot be verified to be those of known
595 trusted hosts.
596 --bootstrap-ca-cert=cacert.pem
598 When cacert.pem exists, this option has the same effect
599 as -C or --ca-cert. If it does not exist, then the exe‐
600 cutable will attempt to obtain the CA certificate from
601 the SSL peer on its first SSL connection and save it to
602 the named PEM file. If it is successful, it will immedi‐
603 ately drop the connection and reconnect, and from then on
604 all SSL connections must be authenticated by a certifi‐
605 cate signed by the CA certificate thus obtained.
606 This option exposes the SSL connection to a man-in-the-
608 middle attack obtaining the initial CA certificate, but
609 it may be useful for bootstrapping.
610 This option is only useful if the SSL peer sends its CA
612 certificate as part of the SSL certificate chain. The SSL
613 protocol does not require the server to send the CA cer‐
614 tificate.
615 This option is mutually exclusive with -C and --ca-cert.
617 Other Options
619 -h
620 --help
621 Prints a brief help message to the console.
622 -V
624 --version
625 Prints version information to the console.
626OVN 22.12.0 ovn-ic-sbctl ovn-ic-sbctl(8)