1ovn-ic-nbctl(8)                   OVN Manual                   ovn-ic-nbctl(8)
2
3
4

NAME

6       ovn-ic-nbctl  - Open Virtual Network interconnection northbound db man‐
7       agement utility
8

SYNOPSIS

10       ovn-ic-nbctl [options] command [arg...]
11

DESCRIPTION

13       This utility can be used to manage the OVN  interconnection  northbound
14       database.
15

GENERAL COMMANDS

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

TRANSIT SWITCH COMMANDS

23       [--may-exist] ts-add switch
24              Creates a new transit switch named switch.
25
26              Transit switch names must be unique. Adding  a  duplicated  name
27              results in error. With --may-exist, adding a duplicate name suc‐
28              ceeds but does not create a new transit switch.
29
30       [--if-exists] ts-del switch
31              Deletes switch. It is an error if switch does not exist,  unless
32              --if-exists is specified.
33
34       ts-list
35              Lists all existing switches on standard output, one per line.
36

DATABASE COMMANDS

38       These  commands query and modify the contents of ovsdb tables. They are
39       a slight abstraction of the ovsdb interface and as such they operate at
40       a lower level than other ovn-ic-nbctl commands.
41
42       Identifying Tables, Records, and Columns
43
44       Each of these commands has a table parameter to identify a table within
45       the database. Many of them also take a record parameter that identifies
46       a  particular  record  within  a table. The record parameter may be the
47       UUID for a record, which may be abbreviated to its first  4  (or  more)
48       hex  digits,  as  long  as that is unique. Many tables offer additional
49       ways to identify records. Some commands  also  take  column  parameters
50       that identify a particular field within the records in a table.
51
52       For a list of tables and their columns, see ovn-ic-nb(5) or see the ta‐
53       ble listing from the --help option.
54
55       Record names must be specified in full and with correct capitalization,
56       except  that  UUIDs  may  be abbreviated to their first 4 (or more) hex
57       digits, as long as that is unique within the table. Names of tables and
58       columns  are  not  case-sensitive, and - and _ are treated interchange‐
59       ably. Unique abbreviations of table and column  names  are  acceptable,
60       e.g. t or transit is sufficient to identify the Transit_Switch table.
61
62       Database Values
63
64       Each column in the database accepts a fixed type of data. The currently
65       defined basic types, and their representations, are:
66
67              integer
68                     A decimal integer in the range -2**63 to 2**63-1,  inclu‐
69                     sive.
70
71              real   A floating-point number.
72
73              Boolean
74                     True or false, written true or false, respectively.
75
76              string An  arbitrary  Unicode string, except that null bytes are
77                     not allowed. Quotes are optional for  most  strings  that
78                     begin  with  an  English letter or underscore and consist
79                     only of letters, underscores, hyphens, and periods.  How‐
80                     ever, true and false and strings that match the syntax of
81                     UUIDs (see below) must be enclosed in  double  quotes  to
82                     distinguish  them  from  other  basic  types. When double
83                     quotes are used, the syntax is that of strings  in  JSON,
84                     e.g.  backslashes  may  be used to escape special charac‐
85                     ters. The empty string must be represented as a  pair  of
86                     double quotes ("").
87
88              UUID   Either  a  universally  unique identifier in the style of
89                     RFC 4122, e.g.  f81d4fae-7dec-11d0-a765-00a0c91e6bf6,  or
90                     an  @name  defined  by a get or create command within the
91                     same ovs-vsctl invocation.
92
93       Multiple values in a single column may be separated by spaces or a sin‐
94       gle  comma.  When  multiple  values are present, duplicates are not al‐
95       lowed, and order is not important. Conversely,  some  database  columns
96       can have an empty set of values, represented as [], and square brackets
97       may optionally enclose other non-empty sets or single values as well.
98
99       A few database columns are ``maps’’ of key-value pairs, where  the  key
100       and the value are each some fixed database type. These are specified in
101       the form key=value, where key and value follow the syntax for the  col‐
102       umn’s  key  type  and value type, respectively. When multiple pairs are
103       present (separated by spaces or a comma), duplicate keys  are  not  al‐
104       lowed,  and  again the order is not important. Duplicate values are al‐
105       lowed. An empty map is represented as {}. Curly braces  may  optionally
106       enclose  non-empty  maps  as  well (but use quotes to prevent the shell
107       from expanding other-config={0=x,1=y} into other-config=0=x  other-con‐
108       fig=1=y, which may not have the desired effect).
109
110       Database Command Syntax
111
112              [--if-exists]    [--columns=column[,column]...]    list    table
113              [record]...
114                     Lists the data in each specified record.  If  no  records
115                     are specified, lists all the records in table.
116
117                     If --columns is specified, only the requested columns are
118                     listed, in the specified order.  Otherwise,  all  columns
119                     are listed, in alphabetical order by column name.
120
121                     Without  --if-exists,  it  is  an  error if any specified
122                     record does not exist. With --if-exists, the command  ig‐
123                     nores  any  record that does not exist, without producing
124                     any output.
125
126              [--columns=column[,column]...]      find       table       [col‐
127              umn[:key]=value]...
128                     Lists  the  data  in  each  record  in table whose column
129                     equals value or, if key is specified, whose  column  con‐
130                     tains a key with the specified value. The following oper‐
131                     ators may be used where = is written in the  syntax  sum‐
132                     mary:
133
134                     = != < > <= >=
135                            Selects records in which column[:key] equals, does
136                            not equal, is less than, is greater than, is  less
137                            than  or  equal to, or is greater than or equal to
138                            value, respectively.
139
140                            Consider column[:key] and value as  sets  of  ele‐
141                            ments. Identical sets are considered equal. Other‐
142                            wise, if the sets have different numbers  of  ele‐
143                            ments,  then the set with more elements is consid‐
144                            ered to be larger. Otherwise, consider  a  element
145                            from each set pairwise, in increasing order within
146                            each set. The first pair that  differs  determines
147                            the  result. (For a column that contains key-value
148                            pairs, first all the keys are compared, and values
149                            are  considered only if the two sets contain iden‐
150                            tical keys.)
151
152                     {=} {!=}
153                            Test for set equality or inequality, respectively.
154
155                     {<=}   Selects records in which column[:key] is a  subset
156                            of  value. For example, flood-vlans{<=}1,2 selects
157                            records in which the  flood-vlans  column  is  the
158                            empty set or contains 1 or 2 or both.
159
160                     {<}    Selects  records in which column[:key] is a proper
161                            subset of value.  For  example,  flood-vlans{<}1,2
162                            selects records in which the flood-vlans column is
163                            the empty set or contains 1 or 2 but not both.
164
165                     {>=} {>}
166                            Same as {<=} and {<},  respectively,  except  that
167                            the   relationship   is   reversed.  For  example,
168                            flood-vlans{>=}1,2 selects records  in  which  the
169                            flood-vlans column contains both 1 and 2.
170
171                     The  following  operators  are  available  only  in  Open
172                     vSwitch 2.16 and later:
173
174                     {in}   Selects records in which  every  element  in  col‐
175                            umn[:key]  is  also in value. (This is the same as
176                            {<=}.)
177
178                     {not-in}
179                            Selects records in which  every  element  in  col‐
180                            umn[:key] is not in value.
181
182                     For  arithmetic  operators  (= != < > <= >=), when key is
183                     specified but a particular record’s column does not  con‐
184                     tain  key, the record is always omitted from the results.
185                     Thus,  the   condition   other-config:mtu!=1500   matches
186                     records  that have a mtu key whose value is not 1500, but
187                     not those that lack an mtu key.
188
189                     For the set operators, when key is specified but  a  par‐
190                     ticular record’s column does not contain key, the compar‐
191                     ison is done against an empty set.  Thus,  the  condition
192                     other-config:mtu{!=}1500  matches records that have a mtu
193                     key whose value is not 1500 and those that  lack  an  mtu
194                     key.
195
196                     Don’t  forget to escape < or > from interpretation by the
197                     shell.
198
199                     If --columns is specified, only the requested columns are
200                     listed, in the specified order. Otherwise all columns are
201                     listed, in alphabetical order by column name.
202
203                     The UUIDs shown for rows created in  the  same  ovs-vsctl
204                     invocation will be wrong.
205
206              [--if-exists] [--id=@name] get table record [column[:key]]...
207                     Prints  the  value  of each specified column in the given
208                     record in table. For map columns, a key may optionally be
209                     specified, in which case the value associated with key in
210                     the column is printed, instead of the entire map.
211
212                     Without --if-exists, it is an error if  record  does  not
213                     exist  or  key  is  specified,  if  key does not exist in
214                     record. With --if-exists, a missing record yields no out‐
215                     put and a missing key prints a blank line.
216
217                     If  @name  is  specified, then the UUID for record may be
218                     referred to by that name later in the same ovs-vsctl  in‐
219                     vocation in contexts where a UUID is expected.
220
221                     Both --id and the column arguments are optional, but usu‐
222                     ally at least one or the other should  be  specified.  If
223                     both are omitted, then get has no effect except to verify
224                     that record exists in table.
225
226                     --id and --if-exists cannot be used together.
227
228              [--if-exists] set table record column[:key]=value...
229                     Sets the value of each  specified  column  in  the  given
230                     record  in table to value. For map columns, a key may op‐
231                     tionally be specified, in which case the value associated
232                     with key in that column is changed (or added, if none ex‐
233                     ists), instead of the entire map.
234
235                     Without --if-exists, it is an error if  record  does  not
236                     exist.  With  --if-exists,  this  command does nothing if
237                     record does not exist.
238
239              [--if-exists] add table record column [key=]value...
240                     Adds the specified value or key-value pair to  column  in
241                     record  in  table.  If  column  is a map, then key is re‐
242                     quired, otherwise it is prohibited. If key already exists
243                     in  a  map column, then the current value is not replaced
244                     (use the set command to replace an existing value).
245
246                     Without --if-exists, it is an error if  record  does  not
247                     exist.  With  --if-exists,  this  command does nothing if
248                     record does not exist.
249
250              [--if-exists] remove table record column value...
251
252                     [--if-exists] remove table record column key...
253
254                     [--if-exists] remove  table  record  column  key=value...
255                     Removes the specified values or key-value pairs from col‐
256                     umn in record in table. The first form applies to columns
257                     that  are  not maps: each specified value is removed from
258                     the column. The second and third forms apply to map  col‐
259                     umns: if only a key is specified, then any key-value pair
260                     with the given key is removed, regardless of  its  value;
261                     if  a  value is given then a pair is removed only if both
262                     key and value match.
263
264                     It is not an error if the column  does  not  contain  the
265                     specified key or value or pair.
266
267                     Without  --if-exists,  it  is an error if record does not
268                     exist. With --if-exists, this  command  does  nothing  if
269                     record does not exist.
270
271              [--if-exists] clear table record column...
272                     Sets  each  column in record in table to the empty set or
273                     empty map, as appropriate. This command applies  only  to
274                     columns that are allowed to be empty.
275
276                     Without  --if-exists,  it  is an error if record does not
277                     exist. With --if-exists, this  command  does  nothing  if
278                     record does not exist.
279
280              [--id=@name] create table column[:key]=value...
281                     Creates a new record in table and sets the initial values
282                     of each column. Columns not explicitly set  will  receive
283                     their default values. Outputs the UUID of the new row.
284
285                     If  @name is specified, then the UUID for the new row may
286                     be referred to by that name elsewhere in the  same  \*(PN
287                     invocation  in  contexts  where  a UUID is expected. Such
288                     references may precede or follow the create command.
289
290                     Caution (ovs-vsctl as example)
291                            Records in the Open vSwitch database are  signifi‐
292                            cant only when they can be reached directly or in‐
293                            directly from the Open_vSwitch table.  Except  for
294                            records  in  the QoS or Queue tables, records that
295                            are not reachable from the Open_vSwitch table  are
296                            automatically  deleted  from  the  database.  This
297                            deletion happens immediately, without waiting  for
298                            additional  ovs-vsctl  commands  or other database
299                            activity. Thus, a create command must generally be
300                            accompanied by additional commands within the same
301                            ovs-vsctl invocation to add a chain of  references
302                            to  the  newly  created  record from the top-level
303                            Open_vSwitch record. The  EXAMPLES  section  gives
304                            some examples that show how to do this.
305
306              [--if-exists] destroy table record...
307                     Deletes each specified record from table. Unless --if-ex‐
308                     ists is specified, each records must exist.
309
310              --all destroy table
311                     Deletes all records from the table.
312
313                     Caution (ovs-vsctl as example)
314                            The destroy command is only useful for records  in
315                            the  QoS  or Queue tables. Records in other tables
316                            are automatically deleted from the  database  when
317                            they  become unreachable from the Open_vSwitch ta‐
318                            ble. This means that deleting the  last  reference
319                            to  a record is sufficient for deleting the record
320                            itself. For records in these  tables,  destroy  is
321                            silently  ignored.  See the EXAMPLES section below
322                            for more information.
323
324              wait-until table record [column[:key]=value]...
325                     Waits until table contains a record  named  record  whose
326                     column equals value or, if key is specified, whose column
327                     contains a key with the  specified  value.  This  command
328                     supports  the  same operators and semantics described for
329                     the find command above.
330
331                     If no column[:key]=value arguments are given,  this  com‐
332                     mand  waits  only  until  record exists. If more than one
333                     such argument is given, the command waits  until  all  of
334                     them are satisfied.
335
336                     Caution (ovs-vsctl as example)
337                            Usually  wait-until should be placed at the begin‐
338                            ning of a set of ovs-vsctl commands. For  example,
339                            wait-until  bridge  br0  --  get  bridge br0 data‐
340                            path_id waits until a bridge named br0 is created,
341                            then  prints  its  datapath_id column, whereas get
342                            bridge br0 datapath_id --  wait-until  bridge  br0
343                            will  abort  if  no  bridge  named br0 exists when
344                            ovs-vsctl initially connects to the database.
345
346                     Consider specifying --timeout=0 along with  --wait-until,
347                     to  prevent ovs-vsctl from terminating after waiting only
348                     at most 5 seconds.
349
350              comment [arg]...
351                     This command has no effect on behavior, but any  database
352                     log  record  created by the command will include the com‐
353                     mand and its arguments.
354

REMOTE CONNECTIVITY COMMANDS

356       get-connection
357              Prints the configured connection(s).
358
359       del-connection
360              Deletes the configured connection(s).
361
362       [--inactivity-probe=msecs] set-connection target...
363              Sets the configured manager target or  targets.  Use  --inactiv‐
364              ity-probe=msecs to override the default idle connection inactiv‐
365              ity probe time. Use 0 to disable inactivity probes.
366

SSL CONFIGURATION COMMANDS

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

OPTIONS

379       --db database
380              The  OVSDB database remote to contact. If the OVN_IC_NB_DB envi‐
381              ronment variable is set, its value is used as the default.  Oth‐
382              erwise, the default is unix:/ovn_ic_nb_db.sock, but this default
383              is unlikely to be useful outside of single-machine OVN test  en‐
384              vironments.
385
386       --leader-only
387       --no-leader-only
388            By  default,  or with --leader-only, when the database server is a
389            clustered database, ovn-ic-nbctl will avoid servers other than the
390            cluster leader. This ensures that any data that ovn-ic-nbctl reads
391            and reports is  up-to-date.  With  --no-leader-only,  ovn-ic-nbctl
392            will use any server in the cluster, which means that for read-only
393            transactions it can report and act  on  stale  data  (transactions
394            that   modify   the  database  are  always  serialized  even  with
395            --no-leader-only). Refer to Understanding Cluster  Consistency  in
396            ovsdb(7) for more information.
397

LOGGING OPTIONS

399       -v[spec]
400       --verbose=[spec]
401            Sets  logging levels. Without any spec, sets the log level for ev‐
402            ery module and destination to dbg. Otherwise, spec is  a  list  of
403            words separated by spaces or commas or colons, up to one from each
404            category below:
405
406            •      A valid module name, as displayed by the vlog/list  command
407                   on ovs-appctl(8), limits the log level change to the speci‐
408                   fied module.
409
410syslog, console, or file, to limit the log level change  to
411                   only  to  the system log, to the console, or to a file, re‐
412                   spectively. (If --detach is specified,  the  daemon  closes
413                   its  standard  file  descriptors, so logging to the console
414                   will have no effect.)
415
416                   On Windows platform, syslog is accepted as a  word  and  is
417                   only useful along with the --syslog-target option (the word
418                   has no effect otherwise).
419
420off, emer, err, warn, info, or  dbg,  to  control  the  log
421                   level.  Messages  of  the  given severity or higher will be
422                   logged, and messages of lower  severity  will  be  filtered
423                   out.  off filters out all messages. See ovs-appctl(8) for a
424                   definition of each log level.
425
426            Case is not significant within spec.
427
428            Regardless of the log levels set for file, logging to a file  will
429            not take place unless --log-file is also specified (see below).
430
431            For compatibility with older versions of OVS, any is accepted as a
432            word but has no effect.
433
434       -v
435       --verbose
436            Sets the maximum logging verbosity  level,  equivalent  to  --ver‐
437            bose=dbg.
438
439       -vPATTERN:destination:pattern
440       --verbose=PATTERN:destination:pattern
441            Sets  the log pattern for destination to pattern. Refer to ovs-ap‐
442            pctl(8) for a description of the valid syntax for pattern.
443
444       -vFACILITY:facility
445       --verbose=FACILITY:facility
446            Sets the RFC5424 facility of the log message. facility can be  one
447            of kern, user, mail, daemon, auth, syslog, lpr, news, uucp, clock,
448            ftp, ntp, audit, alert, clock2, local0,  local1,  local2,  local3,
449            local4, local5, local6 or local7. If this option is not specified,
450            daemon is used as the default for the local system syslog and  lo‐
451            cal0  is  used  while sending a message to the target provided via
452            the --syslog-target option.
453
454       --log-file[=file]
455            Enables logging to a file. If file is specified, then it  is  used
456            as the exact name for the log file. The default log file name used
457            if file is omitted is /var/log/ovn/program.log.
458
459       --syslog-target=host:port
460            Send syslog messages to UDP port on host, in addition to the  sys‐
461            tem  syslog.  The host must be a numerical IP address, not a host‐
462            name.
463
464       --syslog-method=method
465            Specify method as how syslog messages should  be  sent  to  syslog
466            daemon. The following forms are supported:
467
468libc,  to use the libc syslog() function. Downside of using
469                   this options is that libc adds fixed prefix to  every  mes‐
470                   sage  before  it is actually sent to the syslog daemon over
471                   /dev/log UNIX domain socket.
472
473unix:file, to use a UNIX domain socket directly. It is pos‐
474                   sible to specify arbitrary message format with this option.
475                   However, rsyslogd 8.9 and older  versions  use  hard  coded
476                   parser  function anyway that limits UNIX domain socket use.
477                   If you want to use  arbitrary  message  format  with  older
478                   rsyslogd  versions, then use UDP socket to localhost IP ad‐
479                   dress instead.
480
481udp:ip:port, to use a UDP socket. With this  method  it  is
482                   possible  to  use  arbitrary message format also with older
483                   rsyslogd. When sending syslog messages over UDP socket  ex‐
484                   tra precaution needs to be taken into account, for example,
485                   syslog daemon needs to be configured to listen on the spec‐
486                   ified  UDP  port, accidental iptables rules could be inter‐
487                   fering with local syslog traffic and there are  some  secu‐
488                   rity  considerations  that apply to UDP sockets, but do not
489                   apply to UNIX domain sockets.
490
491null, to discard all messages logged to syslog.
492
493            The default is taken from the OVS_SYSLOG_METHOD environment  vari‐
494            able; if it is unset, the default is libc.
495

TABLE FORMATTING OPTIONS

497       These  options control the format of output from the list and find com‐
498       mands.
499
500              -f format
501              --format=format
502                   Sets the type of table formatting. The following  types  of
503                   format are available:
504
505                   table  2-D text tables with aligned columns.
506
507                   list (default)
508                          A  list  with one column per line and rows separated
509                          by a blank line.
510
511                   html   HTML tables.
512
513                   csv    Comma-separated values as defined in RFC 4180.
514
515                   json   JSON format as defined in RFC 4627. The output is  a
516                          sequence  of JSON objects, each of which corresponds
517                          to one table. Each JSON  object  has  the  following
518                          members with the noted values:
519
520                          caption
521                                 The  table’s  caption. This member is omitted
522                                 if the table has no caption.
523
524                          headings
525                                 An array with one element per  table  column.
526                                 Each  array  element  is  a string giving the
527                                 corresponding column’s heading.
528
529                          data   An array with one element per table row. Each
530                                 element is also an array with one element per
531                                 table column. The elements  of  this  second-
532                                 level array are the cells that constitute the
533                                 table. Cells that  represent  OVSDB  data  or
534                                 data  types  are  expressed in the format de‐
535                                 scribed in  the  OVSDB  specification;  other
536                                 cells are simply expressed as text strings.
537
538              -d format
539              --data=format
540                   Sets  the  formatting for cells within output tables unless
541                   the table format is set to json, in which case json format‐
542                   ting  is  always  used when formatting cells. The following
543                   types of format are available:
544
545                   string (default)
546                          The simple format described in the  Database  Values
547                          section of ovs-vsctl(8).
548
549                   bare   The  simple format with punctuation stripped off: []
550                          and {} are omitted around sets, maps, and empty col‐
551                          umns,  items  within  sets  and maps are space-sepa‐
552                          rated, and strings are never quoted. This format may
553                          be easier for scripts to parse.
554
555                   json   The RFC 4627 JSON format as described above.
556
557              --no-headings
558                   This  option  suppresses the heading row that otherwise ap‐
559                   pears in the first row of table output.
560
561              --pretty
562                   By default, JSON in output is printed as compactly as  pos‐
563                   sible. This option causes JSON in output to be printed in a
564                   more readable fashion. Members of objects and  elements  of
565                   arrays are printed one per line, with indentation.
566
567                   This option does not affect JSON in tables, which is always
568                   printed compactly.
569
570              --bare
571                   Equivalent to --format=list --data=bare --no-headings.
572
573   PKI Options
574       PKI configuration is required to use SSL  for  the  connection  to  the
575       database.
576
577              -p privkey.pem
578              --private-key=privkey.pem
579                   Specifies  a  PEM  file  containing the private key used as
580                   identity for outgoing SSL connections.
581
582              -c cert.pem
583              --certificate=cert.pem
584                   Specifies a PEM file containing a certificate  that  certi‐
585                   fies the private key specified on -p or --private-key to be
586                   trustworthy. The certificate must be signed by the certifi‐
587                   cate  authority  (CA) that the peer in SSL connections will
588                   use to verify it.
589
590              -C cacert.pem
591              --ca-cert=cacert.pem
592                   Specifies a PEM file containing the CA certificate for ver‐
593                   ifying certificates presented to this program by SSL peers.
594                   (This may be the same certificate that  SSL  peers  use  to
595                   verify the certificate specified on -c or --certificate, or
596                   it may be a different one, depending on the PKI  design  in
597                   use.)
598
599              -C none
600              --ca-cert=none
601                   Disables  verification  of  certificates  presented  by SSL
602                   peers. This introduces a security risk,  because  it  means
603                   that  certificates  cannot be verified to be those of known
604                   trusted hosts.
605
606              --bootstrap-ca-cert=cacert.pem
607                     When cacert.pem exists, this option has the  same  effect
608                     as  -C  or --ca-cert. If it does not exist, then the exe‐
609                     cutable will attempt to obtain the  CA  certificate  from
610                     the  SSL  peer on its first SSL connection and save it to
611                     the named PEM file. If it is successful, it will  immedi‐
612                     ately drop the connection and reconnect, and from then on
613                     all SSL connections must be authenticated by  a  certifi‐
614                     cate signed by the CA certificate thus obtained.
615
616                     This  option  exposes the SSL connection to a man-in-the-
617                     middle attack obtaining the initial CA  certificate,  but
618                     it may be useful for bootstrapping.
619
620                     This  option  is only useful if the SSL peer sends its CA
621                     certificate as part of the SSL certificate chain. The SSL
622                     protocol  does not require the server to send the CA cer‐
623                     tificate.
624
625                     This option is mutually exclusive with -C and --ca-cert.
626
627   Other Options
628       -h
629       --help
630            Prints a brief help message to the console.
631
632       -V
633       --version
634            Prints version information to the console.
635
636
637
638OVN 22.06.1                      ovn-ic-nbctl                  ovn-ic-nbctl(8)
Impressum