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