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 al‐
97 lowed, 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 al‐
106 lowed, and again the order is not important. Duplicate values are al‐
107 lowed. 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 ig‐
125 nores 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 The following operators are available only in Open
174 vSwitch 2.16 and later:
175 {in} Selects records in which every element in col‐
177 umn[:key] is also in value. (This is the same as
178 {<=}.)
179 {not-in}
181 Selects records in which every element in col‐
182 umn[:key] is not in value.
183 For arithmetic operators (= != < > <= >=), when key is
185 specified but a particular record’s column does not con‐
186 tain key, the record is always omitted from the results.
187 Thus, the condition other-config:mtu!=1500 matches
188 records that have a mtu key whose value is not 1500, but
189 not those that lack an mtu key.
190 For the set operators, when key is specified but a par‐
192 ticular record’s column does not contain key, the compar‐
193 ison is done against an empty set. Thus, the condition
194 other-config:mtu{!=}1500 matches records that have a mtu
195 key whose value is not 1500 and those that lack an mtu
196 key.
197 Don’t forget to escape < or > from interpretation by the
199 shell.
200 If --columns is specified, only the requested columns are
202 listed, in the specified order. Otherwise all columns are
203 listed, in alphabetical order by column name.
204 The UUIDs shown for rows created in the same ovs-vsctl
206 invocation will be wrong.
207 [--if-exists] [--id=@name] get table record [column[:key]]...
209 Prints the value of each specified column in the given
210 record in table. For map columns, a key may optionally be
211 specified, in which case the value associated with key in
212 the column is printed, instead of the entire map.
213 Without --if-exists, it is an error if record does not
215 exist or key is specified, if key does not exist in
216 record. With --if-exists, a missing record yields no out‐
217 put and a missing key prints a blank line.
218 If @name is specified, then the UUID for record may be
220 referred to by that name later in the same ovs-vsctl in‐
221 vocation in contexts where a UUID is expected.
222 Both --id and the column arguments are optional, but usu‐
224 ally at least one or the other should be specified. If
225 both are omitted, then get has no effect except to verify
226 that record exists in table.
227 --id and --if-exists cannot be used together.
229 [--if-exists] set table record column[:key]=value...
231 Sets the value of each specified column in the given
232 record in table to value. For map columns, a key may op‐
233 tionally be specified, in which case the value associated
234 with key in that column is changed (or added, if none ex‐
235 ists), instead of the entire map.
236 Without --if-exists, it is an error if record does not
238 exist. With --if-exists, this command does nothing if
239 record does not exist.
240 [--if-exists] add table record column [key=]value...
242 Adds the specified value or key-value pair to column in
243 record in table. If column is a map, then key is re‐
244 quired, otherwise it is prohibited. If key already exists
245 in a map column, then the current value is not replaced
246 (use the set command to replace an existing value).
247 Without --if-exists, it is an error if record does not
249 exist. With --if-exists, this command does nothing if
250 record does not exist.
251 [--if-exists] remove table record column value...
253 [--if-exists] remove table record column key...
255 [--if-exists] remove table record column key=value...
257 Removes the specified values or key-value pairs from col‐
258 umn in record in table. The first form applies to columns
259 that are not maps: each specified value is removed from
260 the column. The second and third forms apply to map col‐
261 umns: if only a key is specified, then any key-value pair
262 with the given key is removed, regardless of its value;
263 if a value is given then a pair is removed only if both
264 key and value match.
265 It is not an error if the column does not contain the
267 specified key or value or pair.
268 Without --if-exists, it is an error if record does not
270 exist. With --if-exists, this command does nothing if
271 record does not exist.
272 [--if-exists] clear table record column...
274 Sets each column in record in table to the empty set or
275 empty map, as appropriate. This command applies only to
276 columns that are allowed to be empty.
277 Without --if-exists, it is an error if record does not
279 exist. With --if-exists, this command does nothing if
280 record does not exist.
281 [--id=@name] create table column[:key]=value...
283 Creates a new record in table and sets the initial values
284 of each column. Columns not explicitly set will receive
285 their default values. Outputs the UUID of the new row.
286 If @name is specified, then the UUID for the new row may
288 be referred to by that name elsewhere in the same \*(PN
289 invocation in contexts where a UUID is expected. Such
290 references may precede or follow the create command.
291 Caution (ovs-vsctl as example)
293 Records in the Open vSwitch database are signifi‐
294 cant only when they can be reached directly or in‐
295 directly from the Open_vSwitch table. Except for
296 records in the QoS or Queue tables, records that
297 are not reachable from the Open_vSwitch table are
298 automatically deleted from the database. This
299 deletion happens immediately, without waiting for
300 additional ovs-vsctl commands or other database
301 activity. Thus, a create command must generally be
302 accompanied by additional commands within the same
303 ovs-vsctl invocation to add a chain of references
304 to the newly created record from the top-level
305 Open_vSwitch record. The EXAMPLES section gives
306 some examples that show how to do this.
307 [--if-exists] destroy table record...
309 Deletes each specified record from table. Unless --if-ex‐
310 ists is specified, each records must exist.
311 --all destroy table
313 Deletes all records from the table.
314 Caution (ovs-vsctl as example)
316 The destroy command is only useful for records in
317 the QoS or Queue tables. Records in other tables
318 are automatically deleted from the database when
319 they become unreachable from the Open_vSwitch ta‐
320 ble. This means that deleting the last reference
321 to a record is sufficient for deleting the record
322 itself. For records in these tables, destroy is
323 silently ignored. See the EXAMPLES section below
324 for more information.
325 wait-until table record [column[:key]=value]...
327 Waits until table contains a record named record whose
328 column equals value or, if key is specified, whose column
329 contains a key with the specified value. This command
330 supports the same operators and semantics described for
331 the find command above.
332 If no column[:key]=value arguments are given, this com‐
334 mand waits only until record exists. If more than one
335 such argument is given, the command waits until all of
336 them are satisfied.
337 Caution (ovs-vsctl as example)
339 Usually wait-until should be placed at the begin‐
340 ning of a set of ovs-vsctl commands. For example,
341 wait-until bridge br0 -- get bridge br0 data‐
342 path_id waits until a bridge named br0 is created,
343 then prints its datapath_id column, whereas get
344 bridge br0 datapath_id -- wait-until bridge br0
345 will abort if no bridge named br0 exists when
346 ovs-vsctl initially connects to the database.
347 Consider specifying --timeout=0 along with --wait-until,
349 to prevent ovs-vsctl from terminating after waiting only
350 at most 5 seconds.
351 comment [arg]...
353 This command has no effect on behavior, but any database
354 log record created by the command will include the com‐
355 mand and its arguments.
356
358 get-connection
359 Prints the configured connection(s).
360 del-connection
362 Deletes the configured connection(s).
363 [--inactivity-probe=msecs] set-connection target...
365 Sets the configured manager target or targets. Use --inactiv‐
366 ity-probe=msecs to override the default idle connection inactiv‐
367 ity probe time. Use 0 to disable inactivity probes.
368
370 get-ssl
371 Prints the SSL configuration.
372 del-ssl
374 Deletes the current SSL configuration.
375 [--bootstrap] set-ssl private-key certificate ca-cert [ssl-protocol-
377 list [ssl-cipher-list]]
378 Sets the SSL configuration.
379
381 --db database
382 The OVSDB database remote to contact. If the OVN_IC_NB_DB envi‐
383 ronment variable is set, its value is used as the default. Oth‐
384 erwise, the default is unix:/ovn_ic_nb_db.sock, but this default
385 is unlikely to be useful outside of single-machine OVN test en‐
386 vironments.
387 --leader-only
389 --no-leader-only
390 By default, or with --leader-only, when the database server is a
391 clustered database, ovn-ic-nbctl will avoid servers other than the
392 cluster leader. This ensures that any data that ovn-ic-nbctl reads
393 and reports is up-to-date. With --no-leader-only, ovn-ic-nbctl
394 will use any server in the cluster, which means that for read-only
395 transactions it can report and act on stale data (transactions
396 that modify the database are always serialized even with
397 --no-leader-only). Refer to Understanding Cluster Consistency in
398 ovsdb(7) for more information.
399
401 -v[spec]
402 --verbose=[spec]
403 Sets logging levels. Without any spec, sets the log level for ev‐
404 ery module and destination to dbg. Otherwise, spec is a list of
405 words separated by spaces or commas or colons, up to one from each
406 category below:
407 • A valid module name, as displayed by the vlog/list command
409 on ovs-appctl(8), limits the log level change to the speci‐
410 fied module.
411 • syslog, console, or file, to limit the log level change to
413 only to the system log, to the console, or to a file, re‐
414 spectively. (If --detach is specified, the daemon closes
415 its standard file descriptors, so logging to the console
416 will have no effect.)
417 On Windows platform, syslog is accepted as a word and is
419 only useful along with the --syslog-target option (the word
420 has no effect otherwise).
421 • off, emer, err, warn, info, or dbg, to control the log
423 level. Messages of the given severity or higher will be
424 logged, and messages of lower severity will be filtered
425 out. off filters out all messages. See ovs-appctl(8) for a
426 definition of each log level.
427 Case is not significant within spec.
429 Regardless of the log levels set for file, logging to a file will
431 not take place unless --log-file is also specified (see below).
432 For compatibility with older versions of OVS, any is accepted as a
434 word but has no effect.
435 -v
437 --verbose
438 Sets the maximum logging verbosity level, equivalent to --ver‐
439 bose=dbg.
440 -vPATTERN:destination:pattern
442 --verbose=PATTERN:destination:pattern
443 Sets the log pattern for destination to pattern. Refer to ovs-ap‐
444 pctl(8) for a description of the valid syntax for pattern.
445 -vFACILITY:facility
447 --verbose=FACILITY:facility
448 Sets the RFC5424 facility of the log message. facility can be one
449 of kern, user, mail, daemon, auth, syslog, lpr, news, uucp, clock,
450 ftp, ntp, audit, alert, clock2, local0, local1, local2, local3,
451 local4, local5, local6 or local7. If this option is not specified,
452 daemon is used as the default for the local system syslog and lo‐
453 cal0 is used while sending a message to the target provided via
454 the --syslog-target option.
455 --log-file[=file]
457 Enables logging to a file. If file is specified, then it is used
458 as the exact name for the log file. The default log file name used
459 if file is omitted is /var/log/ovn/program.log.
460 --syslog-target=host:port
462 Send syslog messages to UDP port on host, in addition to the sys‐
463 tem syslog. The host must be a numerical IP address, not a host‐
464 name.
465 --syslog-method=method
467 Specify method as how syslog messages should be sent to syslog
468 daemon. The following forms are supported:
469 • libc, to use the libc syslog() function. Downside of using
471 this options is that libc adds fixed prefix to every mes‐
472 sage before it is actually sent to the syslog daemon over
473 /dev/log UNIX domain socket.
474 • unix:file, to use a UNIX domain socket directly. It is pos‐
476 sible to specify arbitrary message format with this option.
477 However, rsyslogd 8.9 and older versions use hard coded
478 parser function anyway that limits UNIX domain socket use.
479 If you want to use arbitrary message format with older
480 rsyslogd versions, then use UDP socket to localhost IP ad‐
481 dress instead.
482 • udp:ip:port, to use a UDP socket. With this method it is
484 possible to use arbitrary message format also with older
485 rsyslogd. When sending syslog messages over UDP socket ex‐
486 tra precaution needs to be taken into account, for example,
487 syslog daemon needs to be configured to listen on the spec‐
488 ified UDP port, accidental iptables rules could be inter‐
489 fering with local syslog traffic and there are some secu‐
490 rity considerations that apply to UDP sockets, but do not
491 apply to UNIX domain sockets.
492 • null, to discard all messages logged to syslog.
494 The default is taken from the OVS_SYSLOG_METHOD environment vari‐
496 able; if it is unset, the default is libc.
497
499 These options control the format of output from the list and find com‐
500 mands.
501 -f format
503 --format=format
504 Sets the type of table formatting. The following types of
505 format are available:
506 table 2-D text tables with aligned columns.
508 list (default)
510 A list with one column per line and rows separated
511 by a blank line.
512 html HTML tables.
514 csv Comma-separated values as defined in RFC 4180.
516 json JSON format as defined in RFC 4627. The output is a
518 sequence of JSON objects, each of which corresponds
519 to one table. Each JSON object has the following
520 members with the noted values:
521 caption
523 The table’s caption. This member is omitted
524 if the table has no caption.
525 headings
527 An array with one element per table column.
528 Each array element is a string giving the
529 corresponding column’s heading.
530 data An array with one element per table row. Each
532 element is also an array with one element per
533 table column. The elements of this second-
534 level array are the cells that constitute the
535 table. Cells that represent OVSDB data or
536 data types are expressed in the format de‐
537 scribed in the OVSDB specification; other
538 cells are simply expressed as text strings.
539 -d format
541 --data=format
542 Sets the formatting for cells within output tables unless
543 the table format is set to json, in which case json format‐
544 ting is always used when formatting cells. The following
545 types of format are available:
546 string (default)
548 The simple format described in the Database Values
549 section of ovs-vsctl(8).
550 bare The simple format with punctuation stripped off: []
552 and {} are omitted around sets, maps, and empty col‐
553 umns, items within sets and maps are space-sepa‐
554 rated, and strings are never quoted. This format may
555 be easier for scripts to parse.
556 json The RFC 4627 JSON format as described above.
558 --no-headings
560 This option suppresses the heading row that otherwise ap‐
561 pears in the first row of table output.
562 --pretty
564 By default, JSON in output is printed as compactly as pos‐
565 sible. This option causes JSON in output to be printed in a
566 more readable fashion. Members of objects and elements of
567 arrays are printed one per line, with indentation.
568 This option does not affect JSON in tables, which is always
570 printed compactly.
571 --bare
573 Equivalent to --format=list --data=bare --no-headings.
574 PKI Options
576 PKI configuration is required to use SSL for the connection to the
577 database.
578 -p privkey.pem
580 --private-key=privkey.pem
581 Specifies a PEM file containing the private key used as
582 identity for outgoing SSL connections.
583 -c cert.pem
585 --certificate=cert.pem
586 Specifies a PEM file containing a certificate that certi‐
587 fies the private key specified on -p or --private-key to be
588 trustworthy. The certificate must be signed by the certifi‐
589 cate authority (CA) that the peer in SSL connections will
590 use to verify it.
591 -C cacert.pem
593 --ca-cert=cacert.pem
594 Specifies a PEM file containing the CA certificate for ver‐
595 ifying certificates presented to this program by SSL peers.
596 (This may be the same certificate that SSL peers use to
597 verify the certificate specified on -c or --certificate, or
598 it may be a different one, depending on the PKI design in
599 use.)
600 -C none
602 --ca-cert=none
603 Disables verification of certificates presented by SSL
604 peers. This introduces a security risk, because it means
605 that certificates cannot be verified to be those of known
606 trusted hosts.
607 --bootstrap-ca-cert=cacert.pem
609 When cacert.pem exists, this option has the same effect
610 as -C or --ca-cert. If it does not exist, then the exe‐
611 cutable will attempt to obtain the CA certificate from
612 the SSL peer on its first SSL connection and save it to
613 the named PEM file. If it is successful, it will immedi‐
614 ately drop the connection and reconnect, and from then on
615 all SSL connections must be authenticated by a certifi‐
616 cate signed by the CA certificate thus obtained.
617 This option exposes the SSL connection to a man-in-the-
619 middle attack obtaining the initial CA certificate, but
620 it may be useful for bootstrapping.
621 This option is only useful if the SSL peer sends its CA
623 certificate as part of the SSL certificate chain. The SSL
624 protocol does not require the server to send the CA cer‐
625 tificate.
626 This option is mutually exclusive with -C and --ca-cert.
628 Other Options
630 -h
631 --help
632 Prints a brief help message to the console.
633 -V
635 --version
636 Prints version information to the console.
637OVN 21.03.1 ovn-ic-nbctl ovn-ic-nbctl(8)