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 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
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  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
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  ig‐
125                     nores  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                     The  following  operators  are  available  only  in  Open
174                     vSwitch 2.16 and later:
175
176                     {in}   Selects records in which  every  element  in  col‐
177                            umn[:key]  is  also in value. (This is the same as
178                            {<=}.)
179
180                     {not-in}
181                            Selects records in which  every  element  in  col‐
182                            umn[:key] is not in value.
183
184                     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
191                     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
198                     Don’t  forget to escape < or > from interpretation by the
199                     shell.
200
201                     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
205                     The UUIDs shown for rows created in  the  same  ovs-vsctl
206                     invocation will be wrong.
207
208              [--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
214                     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
219                     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
223                     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
228                     --id and --if-exists cannot be used together.
229
230              [--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
237                     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
241              [--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
248                     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
252              [--if-exists] remove table record column value...
253
254                     [--if-exists] remove table record column key...
255
256                     [--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
266                     It is not an error if the column  does  not  contain  the
267                     specified key or value or pair.
268
269                     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
273              [--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
278                     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
282              [--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
287                     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
292                     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
308              [--if-exists] destroy table record...
309                     Deletes each specified record from table. Unless --if-ex‐
310                     ists is specified, each records must exist.
311
312              --all destroy table
313                     Deletes all records from the table.
314
315                     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
326              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
333                     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
338                     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
348                     Consider specifying --timeout=0 along with  --wait-until,
349                     to  prevent ovs-vsctl from terminating after waiting only
350                     at most 5 seconds.
351
352              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

REMOTE CONNECTIVITY COMMANDS

358       get-connection
359              Prints the configured connection(s).
360
361       del-connection
362              Deletes the configured connection(s).
363
364       [--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

SSL CONFIGURATION COMMANDS

370       get-ssl
371              Prints the SSL configuration.
372
373       del-ssl
374              Deletes the current SSL configuration.
375
376       [--bootstrap] set-ssl private-key  certificate  ca-cert  [ssl-protocol-
377       list [ssl-cipher-list]]
378              Sets the SSL configuration.
379

OPTIONS

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

LOGGING OPTIONS

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
408            •      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
412syslog, 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
418                   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
422off, 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
428            Case is not significant within spec.
429
430            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
433            For compatibility with older versions of OVS, any is accepted as a
434            word but has no effect.
435
436       -v
437       --verbose
438            Sets the maximum logging verbosity  level,  equivalent  to  --ver‐
439            bose=dbg.
440
441       -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
446       -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
456       --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
461       --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
466       --syslog-method=method
467            Specify method as how syslog messages should  be  sent  to  syslog
468            daemon. The following forms are supported:
469
470libc,  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
475unix: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
483udp: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
493null, to discard all messages logged to syslog.
494
495            The default is taken from the OVS_SYSLOG_METHOD environment  vari‐
496            able; if it is unset, the default is libc.
497

TABLE FORMATTING OPTIONS

499       These  options control the format of output from the list and find com‐
500       mands.
501
502              -f format
503              --format=format
504                   Sets the type of table formatting. The following  types  of
505                   format are available:
506
507                   table  2-D text tables with aligned columns.
508
509                   list (default)
510                          A  list  with one column per line and rows separated
511                          by a blank line.
512
513                   html   HTML tables.
514
515                   csv    Comma-separated values as defined in RFC 4180.
516
517                   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
522                          caption
523                                 The  table’s  caption. This member is omitted
524                                 if the table has no caption.
525
526                          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
531                          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
540              -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
547                   string (default)
548                          The simple format described in the  Database  Values
549                          section of ovs-vsctl(8).
550
551                   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
557                   json   The RFC 4627 JSON format as described above.
558
559              --no-headings
560                   This  option  suppresses the heading row that otherwise ap‐
561                   pears in the first row of table output.
562
563              --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
569                   This option does not affect JSON in tables, which is always
570                   printed compactly.
571
572              --bare
573                   Equivalent to --format=list --data=bare --no-headings.
574
575   PKI Options
576       PKI configuration is required to use SSL  for  the  connection  to  the
577       database.
578
579              -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
584              -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
592              -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
601              -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
608              --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
618                     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
622                     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
627                     This option is mutually exclusive with -C and --ca-cert.
628
629   Other Options
630       -h
631       --help
632            Prints a brief help message to the console.
633
634       -V
635       --version
636            Prints version information to the console.
637
638
639
640OVN 21.03.1                      ovn-ic-nbctl                  ovn-ic-nbctl(8)
Impressum