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