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