1ovn-ic-nbctl(8)                   OVN Manual                   ovn-ic-nbctl(8)
2
3
4
5build/.PP
6

NAME

8       ovn-ic-nbctl  - Open Virtual Network interconnection northbound db man‐
9       agement utility
10

SYNOPSIS

12       ovn-ic-nbctl [options] command [arg...]
13

DESCRIPTION

15       This utility can be used to manage the OVN  interconnection  northbound
16       database.
17

GENERAL COMMANDS

19       init   Initializes  the  database,  if it is empty. If the database has
20              already been initialized, this command has no effect.
21
22       show   Prints a brief overview of the database contents.
23

TRANSIT SWITCH COMMANDS

25       [--may-exist] ts-add switch
26              Creates a new transit switch named switch.
27
28              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
32       [--if-exists] ts-del switch
33              Deletes switch. It is an error if switch does not exist,  unless
34              --if-exists is specified.
35
36       ts-list
37              Lists all existing switches on standard output, one per line.
38

DATABASE COMMANDS

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
44       Identifying Tables, Records, and Columns
45
46       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
54       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
57       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
64       Database Values
65
66       Each column in the database accepts a fixed type of data. The currently
67       defined basic types, and their representations, are:
68
69              integer
70                     A decimal integer in the range -2**63 to 2**63-1,  inclu‐
71                     sive.
72
73              real   A floating-point number.
74
75              Boolean
76                     True or false, written true or false, respectively.
77
78              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
90              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
95       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
101       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
112       Database Command Syntax
113
114              [--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
119                     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
123                     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
128              [--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
136                     = != < > <= >=
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
142                            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
154                     {=} {!=}
155                            Test for set equality or inequality, respectively.
156
157                     {<=}   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
162                     {<}    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
167                     {>=} {>}
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
173                     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
180                     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
187                     Don’t  forget to escape < or > from interpretation by the
188                     shell.
189
190                     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
194                     The UUIDs shown for rows created in  the  same  ovs-vsctl
195                     invocation will be wrong.
196
197              [--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
203                     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
208                     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
212                     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
217                     --id and --if-exists cannot be used together.
218
219              [--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
226                     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
230              [--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
238                     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
242              [--if-exists] remove table record column value...
243
244                     [--if-exists] remove table record column key...
245
246                     [--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
256                     It  is  not  an  error if the column does not contain the
257                     specified key or value or pair.
258
259                     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
263              [--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
268                     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
272              [--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
277                     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
282                     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
298              [--if-exists] destroy table record...
299                     Deletes  each  specified  record   from   table.   Unless
300                     --if-exists is specified, each records must exist.
301
302              --all destroy table
303                     Deletes all records from the table.
304
305                     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
316              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
326                     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
331                     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
341                     Consider specifying --timeout=0 along with  --wait-until,
342                     to  prevent ovs-vsctl from terminating after waiting only
343                     at most 5 seconds.
344
345              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

REMOTE CONNECTIVITY COMMANDS

351       get-connection
352              Prints the configured connection(s).
353
354       del-connection
355              Deletes the configured connection(s).
356
357       [--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

SSL CONFIGURATION COMMANDS

363       get-ssl
364              Prints the SSL configuration.
365
366       del-ssl
367              Deletes the current SSL configuration.
368
369       [--bootstrap] set-ssl private-key  certificate  ca-cert  [ssl-protocol-
370       list [ssl-cipher-list]]
371              Sets the SSL configuration.
372

OPTIONS

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
381       --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

LOGGING OPTIONS

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
401            ·      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
405            ·      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
411                   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
415            ·      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
421            Case is not significant within spec.
422
423            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
426            For compatibility with older versions of OVS, any is accepted as a
427            word but has no effect.
428
429       -v
430       --verbose
431            Sets the maximum logging verbosity  level,  equivalent  to  --ver‐
432            bose=dbg.
433
434       -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
439       -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
449       --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
454       --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
459       --syslog-method=method
460            Specify method as how syslog messages should  be  sent  to  syslog
461            daemon. The following forms are supported:
462
463            ·      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
468            ·      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
476            ·      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
486            ·      null, to discard all messages logged to syslog.
487
488            The default is taken from the OVS_SYSLOG_METHOD environment  vari‐
489            able; if it is unset, the default is libc.
490

TABLE FORMATTING OPTIONS

492       These  options control the format of output from the list and find com‐
493       mands.
494
495              -f format
496              --format=format
497                   Sets the type of table formatting. The following  types  of
498                   format are available:
499
500                   table  2-D text tables with aligned columns.
501
502                   list (default)
503                          A  list  with one column per line and rows separated
504                          by a blank line.
505
506                   html   HTML tables.
507
508                   csv    Comma-separated values as defined in RFC 4180.
509
510                   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
515                          caption
516                                 The  table’s  caption. This member is omitted
517                                 if the table has no caption.
518
519                          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
524                          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
533              -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
540                   string (default)
541                          The simple format described in the  Database  Values
542                          section of ovs-vsctl(8).
543
544                   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
550                   json   The RFC 4627 JSON format as described above.
551
552              --no-headings
553                   This  option  suppresses  the  heading  row  that otherwise
554                   appears in the first row of table output.
555
556              --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
562                   This option does not affect JSON in tables, which is always
563                   printed compactly.
564
565              --bare
566                   Equivalent to --format=list --data=bare --no-headings.
567
568   PKI Options
569       PKI configuration is required to use SSL  for  the  connection  to  the
570       database.
571
572              -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
577              -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
585              -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
594              -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
601              --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
611                     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
615                     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
620                     This option is mutually exclusive with -C and --ca-cert.
621
622   Other Options
623       -h
624       --help
625            Prints a brief help message to the console.
626
627       -V
628       --version
629            Prints version information to the console.
630
631
632
633OVN 20.12.0                      ovn-ic-nbctl                  ovn-ic-nbctl(8)
Impressum