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

NAME

8       ovn-ic-sbctl  - Open Virtual Network interconnection southbound db man‐
9       agement utility
10

SYNOPSIS

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

DESCRIPTION

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

DATABASE COMMANDS

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

REMOTE CONNECTIVITY COMMANDS

339       get-connection
340              Prints the configured connection(s).
341
342       del-connection
343              Deletes the configured connection(s).
344
345       [--inactivity-probe=msecs] set-connection target...
346              Sets  the  configured  manager target or targets. Use --inactiv‐
347              ity-probe=msecs to override the default idle connection inactiv‐
348              ity probe time. Use 0 to disable inactivity probes.
349

SSL CONFIGURATION COMMANDS

351       get-ssl
352              Prints the SSL configuration.
353
354       del-ssl
355              Deletes the current SSL configuration.
356
357       [--bootstrap]  set-ssl  private-key  certificate ca-cert [ssl-protocol-
358       list [ssl-cipher-list]]
359              Sets the SSL configuration.
360

OPTIONS

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

LOGGING OPTIONS

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

TABLE FORMATTING OPTIONS

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