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

NAME

6       ovn-ic-sbctl  - Open Virtual Network interconnection southbound db man‐
7       agement utility
8

SYNOPSIS

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

DESCRIPTION

13       This utility can be used to manage the OVN  interconnection  southbound
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 [availability_zone]
21              Prints a brief overview of the database contents. If  availabil‐
22              ity_zone  is provided, only records related to that availability
23              zone are shown.
24

DATABASE COMMANDS

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

REMOTE CONNECTIVITY COMMANDS

347       get-connection
348              Prints the configured connection(s).
349
350       del-connection
351              Deletes the configured connection(s).
352
353       [--inactivity-probe=msecs] set-connection target...
354              Sets the configured manager target or  targets.  Use  --inactiv‐
355              ity-probe=msecs to override the default idle connection inactiv‐
356              ity probe time. Use 0 to disable inactivity probes.
357

SSL CONFIGURATION COMMANDS

359       get-ssl
360              Prints the SSL configuration.
361
362       del-ssl
363              Deletes the current SSL configuration.
364
365       [--bootstrap] set-ssl private-key  certificate  ca-cert  [ssl-protocol-
366       list [ssl-cipher-list]]
367              Sets the SSL configuration.
368

OPTIONS

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

LOGGING OPTIONS

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

TABLE FORMATTING OPTIONS

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