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

NAME

6       ovn-sbctl - Open Virtual Network southbound db management utility
7

SYNOPSIS

9       ovn-sbctl [options] command [arg...]
10

DESCRIPTION

12       The ovn-sbctl program configures the OVN_Southbound database by provid‐
13       ing a high-level interface to its configuration database. See ovn-sb(5)
14       for comprehensive documentation of the database schema.
15
16       ovn-sbctl  connects  to  an  ovsdb-server  process  that  maintains  an
17       OVN_Southbound  configuration  database.  Using  this  connection,   it
18       queries  and possibly applies changes to the database, depending on the
19       supplied commands.
20
21       ovn-sbctl can perform any number of commands in a  single  run,  imple‐
22       mented as a single atomic transaction against the database.
23
24       The  ovn-sbctl command line begins with global options (see OPTIONS be‐
25       low for details). The global options are followed by one or  more  com‐
26       mands.  Each  command  should begin with -- by itself as a command-line
27       argument, to separate it from the following commands.  (The  --  before
28       the first command is optional.) The command itself starts with command-
29       specific options, if any, followed by the command name  and  any  argu‐
30       ments.
31

DAEMON MODE

33       When  it  is invoked in the most ordinary way, ovn-sbctl connects to an
34       OVSDB server that hosts the southbound database,  retrieves  a  partial
35       copy  of  the  database that is complete enough to do its work, sends a
36       transaction request to the  server,  and  receives  and  processes  the
37       server’s  reply.  In  common  interactive use, this is fine, but if the
38       database is large, the step in which ovn-sbctl retrieves a partial copy
39       of  the  database  can  take a long time, which yields poor performance
40       overall.
41
42       To improve performance in such  a  case,  ovn-sbctl  offers  a  "daemon
43       mode,"  in  which  the user first starts ovn-sbctl running in the back‐
44       ground and afterward uses the daemon to execute operations.  Over  sev‐
45       eral  ovn-sbctl  command  invocations, this performs better overall be‐
46       cause it retrieves a copy of the database only once at  the  beginning,
47       not once per program run.
48
49       Use the --detach option to start an ovn-sbctl daemon. With this option,
50       ovn-sbctl prints the name of a control socket  to  stdout.  The  client
51       should  save this name in environment variable OVN_SB_DAEMON. Under the
52       Bourne shell this might be done like this:
53
54             export OVN_SB_DAEMON=$(ovn-sbctl --pidfile --detach)
55
56
57       When OVN_SB_DAEMON is set, ovn-sbctl  automatically  and  transparently
58       uses the daemon to execute its commands.
59
60       When  the daemon is no longer needed, kill it and unset the environment
61       variable, e.g.:
62
63             kill $(cat $OVN_RUNDIR/ovn-sbctl.pid)
64             unset OVN_SB_DAEMON
65
66
67       When using daemon mode, an alternative to the OVN_SB_DAEMON environment
68       variable  is  to  specify a path for the Unix socket. When starting the
69       ovn-sbctl daemon, specify the -u option with a full path to  the  loca‐
70       tion of the socket file. Here is an exmple:
71
72             ovn-sbctl --detach -u /tmp/mysock.ctl
73
74
75       Then  to connect to the running daemon, use the -u option with the full
76       path to the socket created when the daemon was started:
77
78             ovn-sbctl -u /tmp/mysock.ctl show
79
80
81     Daemon Commands
82
83       Daemon mode is internally implemented using the same mechanism used  by
84       ovn-appctl.  One  may  also  use ovn-appctl directly with the following
85       commands:
86
87              run [options] command [arg...] [--  [options]  command  [arg...]
88              ...]
89                     Instructs the daemon process to run one or more ovn-sbctl
90                     commands described above and reply with  the  results  of
91                     running  these  commands.  Accepts the --no-wait, --wait,
92                     --timeout, --dry-run,  --oneline,  and  the  options  de‐
93                     scribed under Table Formatting Options in addition to the
94                     the command-specific options.
95
96              exit   Causes ovn-sbctl to gracefully terminate.
97

OPTIONS

99       The options listed below affect the behavior of ovn-sbctl as  a  whole.
100       Some individual commands also accept their own options, which are given
101       just before the command name. If the first command on the command  line
102       has  options,  then those options must be separated from the global op‐
103       tions by --.
104
105       ovn-sbctl also accepts options from the  OVN_SBCTL_OPTIONS  environment
106       variable,  in  the same format as on the command line. Options from the
107       command line override those in the environment.
108
109              --db database
110                     The OVSDB database remote to contact.  If  the  OVN_SB_DB
111                     environment variable is set, its value is used as the de‐
112                     fault. Otherwise, the default is unix:/ovnsb_db.sock, but
113                     this  default is unlikely to be useful outside of single-
114                     machine OVN test environments.
115
116              --leader-only
117              --no-leader-only
118                   By default, or with --leader-only, when the database server
119                   is a clustered database, ovn-sbctl will avoid servers other
120                   than the cluster leader. This ensures that  any  data  that
121                   ovn-sbctl   reads   and   reports   is   up-to-date.   With
122                   --no-leader-only, ovn-sbctl will  use  any  server  in  the
123                   cluster, which means that for read-only transactions it can
124                   report and act on stale data (transactions that modify  the
125                   database are always serialized even with --no-leader-only).
126                   Refer to Understanding Cluster Consistency in ovsdb(7)  for
127                   more information.
128
129              --shuffle-remotes
130              --no-shuffle-remotes
131                   By  default, or with --shuffle-remotes, when there are mul‐
132                   tiple remotes specified  in  the  OVSDB  connection  string
133                   specified  by  --db  or the OVN_SB_DB environment variable,
134                   the order of the remotes will be shuffled before the client
135                   tries to connect. The remotes will be shuffled only once to
136                   a new order before the first connection attempt.  The  fol‐
137                   lowing retries, if any, will follow the same new order. The
138                   default behavior is to make sure  clients  of  a  clustered
139                   database  can  distribute  evenly  to  all memembers of the
140                   cluster. With --no-shuffle-remotes, ovn-sbctl will use  the
141                   original  order  specified in the connection string to con‐
142                   nect. This allows user  to  specify  the  preferred  order,
143                   which is particularly useful for testing.
144
145              --no-syslog
146                   By default, ovn-sbctl logs its arguments and the details of
147                   any changes that it makes to the system  log.  This  option
148                   disables this logging.
149
150                   This option is equivalent to --verbose=sbctl:syslog:warn.
151
152              --oneline
153                   Modifies the output format so that the output for each com‐
154                   mand is printed on a single line. New-line characters  that
155                   would  otherwise  separate  lines are printed as \fB\\n\fR,
156                   and any instances of \fB\\\fR that would  otherwise  appear
157                   in  the  output  are  doubled. Prints a blank line for each
158                   command that has no output. This option does not affect the
159                   formatting  of  output  from the list or find commands; see
160                   Table Formatting Options below.
161
162              --dry-run
163                   Prevents ovn-sbctl from actually modifying the database.
164
165              -t secs
166              --timeout=secs
167                   By default, or with a secs of 0,  ovn-sbctl  waits  forever
168                   for  a  response from the database. This option limits run‐
169                   time to approximately secs seconds. If the timeout expires,
170                   ovn-sbctl will exit with a SIGALRM signal. (A timeout would
171                   normally happen only if the database cannot  be  contacted,
172                   or if the system is overloaded.)
173
174   Daemon Options
175       --pidfile[=pidfile]
176              Causes a file (by default, program.pid) to be created indicating
177              the PID of the running process. If the pidfile argument  is  not
178              specified, or if it does not begin with /, then it is created in
179              .
180
181              If --pidfile is not specified, no pidfile is created.
182
183       --overwrite-pidfile
184              By default, when --pidfile is specified and the  specified  pid‐
185              file already exists and is locked by a running process, the dae‐
186              mon refuses to start. Specify --overwrite-pidfile to cause it to
187              instead overwrite the pidfile.
188
189              When --pidfile is not specified, this option has no effect.
190
191       --detach
192              Runs  this  program  as a background process. The process forks,
193              and in the child it starts a new session,  closes  the  standard
194              file descriptors (which has the side effect of disabling logging
195              to the console), and changes its current directory to  the  root
196              (unless  --no-chdir is specified). After the child completes its
197              initialization, the parent exits.
198
199       --monitor
200              Creates an additional process to monitor  this  program.  If  it
201              dies  due  to a signal that indicates a programming error (SIGA‐
202              BRT, SIGALRM, SIGBUS, SIGFPE, SIGILL, SIGPIPE, SIGSEGV, SIGXCPU,
203              or SIGXFSZ) then the monitor process starts a new copy of it. If
204              the daemon dies or exits for another reason, the monitor process
205              exits.
206
207              This  option  is  normally used with --detach, but it also func‐
208              tions without it.
209
210       --no-chdir
211              By default, when --detach is specified, the daemon  changes  its
212              current  working  directory  to  the root directory after it de‐
213              taches. Otherwise, invoking the daemon from a carelessly  chosen
214              directory  would  prevent  the administrator from unmounting the
215              file system that holds that directory.
216
217              Specifying --no-chdir suppresses this behavior,  preventing  the
218              daemon  from changing its current working directory. This may be
219              useful for collecting core files, since it is common behavior to
220              write core dumps into the current working directory and the root
221              directory is not a good directory to use.
222
223              This option has no effect when --detach is not specified.
224
225       --no-self-confinement
226              By default this daemon will try to self-confine itself  to  work
227              with  files  under  well-known  directories  determined at build
228              time. It is better to stick with this default behavior  and  not
229              to  use  this  flag  unless some other Access Control is used to
230              confine daemon. Note that in contrast to  other  access  control
231              implementations  that  are  typically enforced from kernel-space
232              (e.g. DAC or MAC), self-confinement is imposed  from  the  user-
233              space daemon itself and hence should not be considered as a full
234              confinement strategy, but instead should be viewed as  an  addi‐
235              tional layer of security.
236
237       --user=user:group
238              Causes  this  program  to  run  as a different user specified in
239              user:group, thus dropping most of  the  root  privileges.  Short
240              forms  user  and  :group  are also allowed, with current user or
241              group assumed, respectively. Only daemons started  by  the  root
242              user accepts this argument.
243
244              On   Linux,   daemons   will   be   granted   CAP_IPC_LOCK   and
245              CAP_NET_BIND_SERVICES before dropping root  privileges.  Daemons
246              that  interact  with  a  datapath, such as ovs-vswitchd, will be
247              granted three  additional  capabilities,  namely  CAP_NET_ADMIN,
248              CAP_NET_BROADCAST  and  CAP_NET_RAW.  The capability change will
249              apply even if the new user is root.
250
251              On Windows, this option is not currently supported. For security
252              reasons,  specifying  this  option will cause the daemon process
253              not to start.
254
255   Logging options
256       -v[spec]
257       --verbose=[spec]
258            Sets logging levels. Without any spec, sets the log level for  ev‐
259            ery  module  and  destination to dbg. Otherwise, spec is a list of
260            words separated by spaces or commas or colons, up to one from each
261            category below:
262
263            •      A  valid module name, as displayed by the vlog/list command
264                   on ovs-appctl(8), limits the log level change to the speci‐
265                   fied module.
266
267syslog,  console, or file, to limit the log level change to
268                   only to the system log, to the console, or to a  file,  re‐
269                   spectively.  (If  --detach  is specified, the daemon closes
270                   its standard file descriptors, so logging  to  the  console
271                   will have no effect.)
272
273                   On  Windows  platform,  syslog is accepted as a word and is
274                   only useful along with the --syslog-target option (the word
275                   has no effect otherwise).
276
277off,  emer,  err,  warn,  info,  or dbg, to control the log
278                   level. Messages of the given severity  or  higher  will  be
279                   logged,  and  messages  of  lower severity will be filtered
280                   out. off filters out all messages. See ovs-appctl(8) for  a
281                   definition of each log level.
282
283            Case is not significant within spec.
284
285            Regardless  of the log levels set for file, logging to a file will
286            not take place unless --log-file is also specified (see below).
287
288            For compatibility with older versions of OVS, any is accepted as a
289            word but has no effect.
290
291       -v
292       --verbose
293            Sets  the  maximum  logging  verbosity level, equivalent to --ver‐
294            bose=dbg.
295
296       -vPATTERN:destination:pattern
297       --verbose=PATTERN:destination:pattern
298            Sets the log pattern for destination to pattern. Refer to  ovs-ap‐
299            pctl(8) for a description of the valid syntax for pattern.
300
301       -vFACILITY:facility
302       --verbose=FACILITY:facility
303            Sets  the RFC5424 facility of the log message. facility can be one
304            of kern, user, mail, daemon, auth, syslog, lpr, news, uucp, clock,
305            ftp,  ntp,  audit,  alert, clock2, local0, local1, local2, local3,
306            local4, local5, local6 or local7. If this option is not specified,
307            daemon  is used as the default for the local system syslog and lo‐
308            cal0 is used while sending a message to the  target  provided  via
309            the --syslog-target option.
310
311       --log-file[=file]
312            Enables  logging  to a file. If file is specified, then it is used
313            as the exact name for the log file. The default log file name used
314            if file is omitted is /var/log/ovn/program.log.
315
316       --syslog-target=host:port
317            Send  syslog messages to UDP port on host, in addition to the sys‐
318            tem syslog. The host must be a numerical IP address, not  a  host‐
319            name.
320
321       --syslog-method=method
322            Specify  method  as  how  syslog messages should be sent to syslog
323            daemon. The following forms are supported:
324
325libc, to use the libc syslog() function. Downside of  using
326                   this  options  is that libc adds fixed prefix to every mes‐
327                   sage before it is actually sent to the syslog  daemon  over
328                   /dev/log UNIX domain socket.
329
330unix:file, to use a UNIX domain socket directly. It is pos‐
331                   sible to specify arbitrary message format with this option.
332                   However,  rsyslogd  8.9  and  older versions use hard coded
333                   parser function anyway that limits UNIX domain socket  use.
334                   If  you  want  to  use  arbitrary message format with older
335                   rsyslogd versions, then use UDP socket to localhost IP  ad‐
336                   dress instead.
337
338udp:ip:port,  to  use  a UDP socket. With this method it is
339                   possible to use arbitrary message format  also  with  older
340                   rsyslogd.  When sending syslog messages over UDP socket ex‐
341                   tra precaution needs to be taken into account, for example,
342                   syslog daemon needs to be configured to listen on the spec‐
343                   ified UDP port, accidental iptables rules could  be  inter‐
344                   fering  with  local syslog traffic and there are some secu‐
345                   rity considerations that apply to UDP sockets, but  do  not
346                   apply to UNIX domain sockets.
347
348null, to discard all messages logged to syslog.
349
350            The  default is taken from the OVS_SYSLOG_METHOD environment vari‐
351            able; if it is unset, the default is libc.
352
353   Table Formatting Options
354       These options control the format of output from the list and find  com‐
355       mands.
356
357              -f format
358              --format=format
359                   Sets  the  type of table formatting. The following types of
360                   format are available:
361
362                   table  2-D text tables with aligned columns.
363
364                   list (default)
365                          A list with one column per line and  rows  separated
366                          by a blank line.
367
368                   html   HTML tables.
369
370                   csv    Comma-separated values as defined in RFC 4180.
371
372                   json   JSON  format as defined in RFC 4627. The output is a
373                          sequence of JSON objects, each of which  corresponds
374                          to  one  table.  Each  JSON object has the following
375                          members with the noted values:
376
377                          caption
378                                 The table’s caption. This member  is  omitted
379                                 if the table has no caption.
380
381                          headings
382                                 An  array  with one element per table column.
383                                 Each array element is  a  string  giving  the
384                                 corresponding column’s heading.
385
386                          data   An array with one element per table row. Each
387                                 element is also an array with one element per
388                                 table  column.  The  elements of this second-
389                                 level array are the cells that constitute the
390                                 table.  Cells  that  represent  OVSDB data or
391                                 data types are expressed in  the  format  de‐
392                                 scribed  in  the  OVSDB  specification; other
393                                 cells are simply expressed as text strings.
394
395              -d format
396              --data=format
397                   Sets the formatting for cells within output  tables  unless
398                   the table format is set to json, in which case json format‐
399                   ting is always used when formatting  cells.  The  following
400                   types of format are available:
401
402                   string (default)
403                          The  simple  format described in the Database Values
404                          section of ovs-vsctl(8).
405
406                   bare   The simple format with punctuation stripped off:  []
407                          and {} are omitted around sets, maps, and empty col‐
408                          umns, items within sets  and  maps  are  space-sepa‐
409                          rated, and strings are never quoted. This format may
410                          be easier for scripts to parse.
411
412                   json   The RFC 4627 JSON format as described above.
413
414              --no-headings
415                   This option suppresses the heading row that  otherwise  ap‐
416                   pears in the first row of table output.
417
418              --pretty
419                   By  default, JSON in output is printed as compactly as pos‐
420                   sible. This option causes JSON in output to be printed in a
421                   more  readable  fashion. Members of objects and elements of
422                   arrays are printed one per line, with indentation.
423
424                   This option does not affect JSON in tables, which is always
425                   printed compactly.
426
427              --bare
428                   Equivalent to --format=list --data=bare --no-headings.
429
430   PKI Options
431       PKI  configuration  is  required  to  use SSL for the connection to the
432       database.
433
434              -p privkey.pem
435              --private-key=privkey.pem
436                   Specifies a PEM file containing the  private  key  used  as
437                   identity for outgoing SSL connections.
438
439              -c cert.pem
440              --certificate=cert.pem
441                   Specifies  a  PEM file containing a certificate that certi‐
442                   fies the private key specified on -p or --private-key to be
443                   trustworthy. The certificate must be signed by the certifi‐
444                   cate authority (CA) that the peer in SSL  connections  will
445                   use to verify it.
446
447              -C cacert.pem
448              --ca-cert=cacert.pem
449                   Specifies a PEM file containing the CA certificate for ver‐
450                   ifying certificates presented to this program by SSL peers.
451                   (This  may  be  the  same certificate that SSL peers use to
452                   verify the certificate specified on -c or --certificate, or
453                   it  may  be a different one, depending on the PKI design in
454                   use.)
455
456              -C none
457              --ca-cert=none
458                   Disables verification  of  certificates  presented  by  SSL
459                   peers.  This  introduces  a security risk, because it means
460                   that certificates cannot be verified to be those  of  known
461                   trusted hosts.
462
463              --bootstrap-ca-cert=cacert.pem
464                     When  cacert.pem  exists, this option has the same effect
465                     as -C or --ca-cert. If it does not exist, then  the  exe‐
466                     cutable  will  attempt  to obtain the CA certificate from
467                     the SSL peer on its first SSL connection and save  it  to
468                     the  named PEM file. If it is successful, it will immedi‐
469                     ately drop the connection and reconnect, and from then on
470                     all  SSL  connections must be authenticated by a certifi‐
471                     cate signed by the CA certificate thus obtained.
472
473                     This option exposes the SSL connection to  a  man-in-the-
474                     middle  attack  obtaining the initial CA certificate, but
475                     it may be useful for bootstrapping.
476
477                     This option is only useful if the SSL peer sends  its  CA
478                     certificate as part of the SSL certificate chain. The SSL
479                     protocol does not require the server to send the CA  cer‐
480                     tificate.
481
482                     This option is mutually exclusive with -C and --ca-cert.
483
484   Other Options
485       -h
486       --help
487            Prints a brief help message to the console.
488
489       -V
490       --version
491            Prints version information to the console.
492

COMMANDS

494       The following sections describe the commands that ovn-sbctl supports.
495
496   OVN_Southbound Commands
497       These commands work with an OVN_Southbound database as a whole.
498
499              init   Initializes the database, if it is empty. If the database
500                     has already been initialized, this command has no effect.
501
502              show   Prints a brief overview of the database contents.
503
504   Chassis Commands
505       These commands manipulate OVN_Southbound chassis.
506
507              [--may-exist] chassis-add chassis encap-type encap-ip
508                     Creates a new chassis  named  chassis.  encap-type  is  a
509                     comma-separated  list  of  tunnel types. The chassis will
510                     have one encap entry for each specified tunnel type  with
511                     encap-ip as the destination IP for each.
512
513                     Without  --may-exist, attempting to create a chassis that
514                     exists is an error. With --may-exist, this  command  does
515                     nothing if chassis already exists.
516
517              [--if-exists] chassis-del chassis
518                     Deletes chassis and its encaps and gateway_ports.
519
520                     Without  --if-exists, attempting to delete a chassis that
521                     does not exist is an error. With  --if-exists  attempting
522                     to delete a chassis that does not exist has no effect.
523
524   Port Binding Commands
525       These commands manipulate OVN_Southbound port bindings.
526
527              [--may-exist] lsp-bind logical-port chassis
528                     Binds the logical port named logical-port to chassis.
529
530                     Without  --may-exist,  attempting  to bind a logical port
531                     that has already been bound is an error.  With  --may-ex‐
532                     ist,  this  command  does nothing if logical-port has al‐
533                     ready been bound to a chassis.
534
535              [--if-exists] lsp-unbind logical-port
536                     Removes the binding of logical-port.
537
538                     Without --if-exists, attempting to unbind a logical  port
539                     that is not bound is an error. With --if-exists, attempt‐
540                     ing to unbind logical port that is not bound has  no  ef‐
541                     fect.
542
543   Logical Flow Commands
544       [--uuid]  [--ovs[=remote]]  [--stats]  [--vflows]  lflow-list [logical-
545       datapath] [lflow...]
546              List logical flows. If logical-datapath is specified, only  list
547              flows  for  that  logical  datapath. The logical-datapath may be
548              given as a UUID or as a datapath name  (reporting  an  error  if
549              multiple datapaths have the same name).
550
551              If  at least one lflow is given, only matching logical flows, if
552              any, are listed. Each lflow may be specified as a  UUID  or  the
553              first  few characters of a UUID, optionally prefixed by 0x. (Be‐
554              cause ovn-controller sets OpenFlow flow cookies to the first  32
555              bits  of  the  corresponding  logical flow’s UUID, this makes it
556              easy to look up the logical flow  that  generated  a  particular
557              OpenFlow flow.)
558
559              If --uuid is specified, the output includes the first 32 bits of
560              each logical flow’s UUID. This makes it easier to find the Open‐
561              Flow flows that correspond to a given logical flow.
562
563              If  --ovs  is included, ovn-sbctl attempts to obtain and display
564              the OpenFlow flows that correspond to each OVN logical flow.  To
565              do    so,    ovn-sbctl   connects   to   remote   (by   default,
566              unix:/br-int.mgmt) over OpenFlow and retrieves the flows. If re‐
567              mote  is  specified,  it  must  be an active OpenFlow connection
568              method described in ovsdb(7). Please see the discussion  of  the
569              similar  --ovs option in ovn-trace(8) for more information about
570              the OpenFlow flow output.
571
572              By default, OpenFlow flow output includes  only  match  and  ac‐
573              tions.  Add --stats to include all OpenFlow information, such as
574              packet and byte counters, duration, and timeouts.
575
576              If --vflows is included, other southbound database  records  di‐
577              rectly  used for generating OpenFlow flows are also listed. This
578              includes: port-bindings, mac-bindings,  multicast-groups,  chas‐
579              sis.  The --ovs and --stats can also be used in conjunction with
580              --vflows.
581
582       [--uuid] dump-flows [logical-datapath]
583              Alias for lflow-list.
584
585       count-flows [logical-datapath]
586              prints numbers of logical flows per table and per datapath.
587
588   Remote Connectivity Commands
589       These commands manipulate the connections column in the SB_Global table
590       and  rows  in  the Connection table. When ovsdb-server is configured to
591       use the connections column for OVSDB connections, this allows  the  ad‐
592       ministrator to use \fBovn\-sbctl\fR to configure database connections.
593
594              get-connection
595                     Prints the configured connection(s).
596
597              del-connection
598                     Deletes the configured connection(s).
599
600              [--inactivity-probe=msecs] set-connection target...
601                     Sets  the configured manager target or targets. Use --in‐
602                     activity-probe=msecs to override the default idle connec‐
603                     tion  inactivity  probe time. Use 0 to disable inactivity
604                     probes.
605
606   SSL Configuration Commands
607       When ovsdb-server is configured to connect using SSL, the following pa‐
608       rameters are required:
609
610              private-key
611                     Specifies  a PEM file containing the private key used for
612                     SSL connections.
613
614              certificate
615                     Specifies a PEM file containing a certificate, signed  by
616                     the  certificate  authority  (CA)  used by the connection
617                     peers, that certifies  the  private  key,  identifying  a
618                     trustworthy peer.
619
620              ca-cert
621                     Specifies  a  PEM file containing the CA certificate used
622                     to verify that the connection peers are trustworthy.
623
624       These SSL settings apply to all SSL connections made by the  southbound
625       database server.
626
627              get-ssl
628                     Prints the SSL configuration.
629
630              del-ssl
631                     Deletes the current SSL configuration.
632
633              [--bootstrap]  set-ssl private-key certificate ca-cert [ssl-pro‐
634              tocol-list [ssl-cipher-list]]
635                     Sets the SSL configuration.
636
637   Database Commands
638       These commands query and modify the contents of ovsdb tables. They  are
639       a slight abstraction of the ovsdb interface and as such they operate at
640       a lower level than other ovn-sbctl commands.
641
642       Identifying Tables, Records, and Columns
643
644       Each of these commands has a table parameter to identify a table within
645       the database. Many of them also take a record parameter that identifies
646       a particular record within a table. The record  parameter  may  be  the
647       UUID  for  a  record, which may be abbreviated to its first 4 (or more)
648       hex digits, as long as that is unique.  Many  tables  offer  additional
649       ways  to  identify  records.  Some commands also take column parameters
650       that identify a particular field within the records in a table.
651
652       For a list of tables and their columns, see ovn-sb(5) or see the  table
653       listing from the --help option.
654
655       Record names must be specified in full and with correct capitalization,
656       except that UUIDs may be abbreviated to their first  4  (or  more)  hex
657       digits, as long as that is unique within the table. Names of tables and
658       columns are not case-sensitive, and - and _  are  treated  interchange‐
659       ably.  Unique  abbreviations  of table and column names are acceptable,
660       e.g. d or dhcp is sufficient to identify the DHCP_Options table.
661
662       Database Values
663
664       Each column in the database accepts a fixed type of data. The currently
665       defined basic types, and their representations, are:
666
667              integer
668                     A  decimal integer in the range -2**63 to 2**63-1, inclu‐
669                     sive.
670
671              real   A floating-point number.
672
673              Boolean
674                     True or false, written true or false, respectively.
675
676              string An arbitrary Unicode string, except that null  bytes  are
677                     not  allowed.  Quotes  are optional for most strings that
678                     begin with an English letter or  underscore  and  consist
679                     only  of letters, underscores, hyphens, and periods. How‐
680                     ever, true and false and strings that match the syntax of
681                     UUIDs  (see  below)  must be enclosed in double quotes to
682                     distinguish them from  other  basic  types.  When  double
683                     quotes  are  used, the syntax is that of strings in JSON,
684                     e.g. backslashes may be used to  escape  special  charac‐
685                     ters.  The  empty string must be represented as a pair of
686                     double quotes ("").
687
688              UUID   Either a universally unique identifier in  the  style  of
689                     RFC  4122,  e.g. f81d4fae-7dec-11d0-a765-00a0c91e6bf6, or
690                     an @name defined by a get or create  command  within  the
691                     same ovs-vsctl invocation.
692
693       Multiple values in a single column may be separated by spaces or a sin‐
694       gle comma. When multiple values are present,  duplicates  are  not  al‐
695       lowed,  and  order  is not important. Conversely, some database columns
696       can have an empty set of values, represented as [], and square brackets
697       may optionally enclose other non-empty sets or single values as well.
698
699       A  few  database columns are ``maps’’ of key-value pairs, where the key
700       and the value are each some fixed database type. These are specified in
701       the  form key=value, where key and value follow the syntax for the col‐
702       umn’s key type and value type, respectively. When  multiple  pairs  are
703       present  (separated  by  spaces or a comma), duplicate keys are not al‐
704       lowed, and again the order is not important. Duplicate values  are  al‐
705       lowed.  An  empty map is represented as {}. Curly braces may optionally
706       enclose non-empty maps as well (but use quotes  to  prevent  the  shell
707       from  expanding other-config={0=x,1=y} into other-config=0=x other-con‐
708       fig=1=y, which may not have the desired effect).
709
710       Database Command Syntax
711
712              [--if-exists]    [--columns=column[,column]...]    list    table
713              [record]...
714                     Lists  the  data  in each specified record. If no records
715                     are specified, lists all the records in table.
716
717                     If --columns is specified, only the requested columns are
718                     listed,  in  the  specified order. Otherwise, all columns
719                     are listed, in alphabetical order by column name.
720
721                     Without --if-exists, it is  an  error  if  any  specified
722                     record  does not exist. With --if-exists, the command ig‐
723                     nores any record that does not exist,  without  producing
724                     any output.
725
726              [--columns=column[,column]...]       find       table      [col‐
727              umn[:key]=value]...
728                     Lists the data in  each  record  in  table  whose  column
729                     equals  value  or, if key is specified, whose column con‐
730                     tains a key with the specified value. The following oper‐
731                     ators  may  be used where = is written in the syntax sum‐
732                     mary:
733
734                     = != < > <= >=
735                            Selects records in which column[:key] equals, does
736                            not  equal, is less than, is greater than, is less
737                            than or equal to, or is greater than or  equal  to
738                            value, respectively.
739
740                            Consider  column[:key]  and  value as sets of ele‐
741                            ments. Identical sets are considered equal. Other‐
742                            wise,  if  the sets have different numbers of ele‐
743                            ments, then the set with more elements is  consid‐
744                            ered  to  be larger. Otherwise, consider a element
745                            from each set pairwise, in increasing order within
746                            each  set.  The first pair that differs determines
747                            the result. (For a column that contains  key-value
748                            pairs, first all the keys are compared, and values
749                            are considered only if the two sets contain  iden‐
750                            tical keys.)
751
752                     {=} {!=}
753                            Test for set equality or inequality, respectively.
754
755                     {<=}   Selects  records in which column[:key] is a subset
756                            of value. For example, flood-vlans{<=}1,2  selects
757                            records  in  which  the  flood-vlans column is the
758                            empty set or contains 1 or 2 or both.
759
760                     {<}    Selects records in which column[:key] is a  proper
761                            subset  of  value.  For example, flood-vlans{<}1,2
762                            selects records in which the flood-vlans column is
763                            the empty set or contains 1 or 2 but not both.
764
765                     {>=} {>}
766                            Same  as  {<=}  and {<}, respectively, except that
767                            the  relationship  is   reversed.   For   example,
768                            flood-vlans{>=}1,2  selects  records  in which the
769                            flood-vlans column contains both 1 and 2.
770
771                     The  following  operators  are  available  only  in  Open
772                     vSwitch 2.16 and later:
773
774                     {in}   Selects  records  in  which  every element in col‐
775                            umn[:key] is also in value. (This is the  same  as
776                            {<=}.)
777
778                     {not-in}
779                            Selects  records  in  which  every element in col‐
780                            umn[:key] is not in value.
781
782                     For arithmetic operators (= != < > <= >=),  when  key  is
783                     specified  but a particular record’s column does not con‐
784                     tain key, the record is always omitted from the  results.
785                     Thus,   the   condition   other-config:mtu!=1500  matches
786                     records that have a mtu key whose value is not 1500,  but
787                     not those that lack an mtu key.
788
789                     For  the  set operators, when key is specified but a par‐
790                     ticular record’s column does not contain key, the compar‐
791                     ison  is  done  against an empty set. Thus, the condition
792                     other-config:mtu{!=}1500 matches records that have a  mtu
793                     key  whose  value  is not 1500 and those that lack an mtu
794                     key.
795
796                     Don’t forget to escape < or > from interpretation by  the
797                     shell.
798
799                     If --columns is specified, only the requested columns are
800                     listed, in the specified order. Otherwise all columns are
801                     listed, in alphabetical order by column name.
802
803                     The  UUIDs  shown  for rows created in the same ovs-vsctl
804                     invocation will be wrong.
805
806              [--if-exists] [--id=@name] get table record [column[:key]]...
807                     Prints the value of each specified column  in  the  given
808                     record in table. For map columns, a key may optionally be
809                     specified, in which case the value associated with key in
810                     the column is printed, instead of the entire map.
811
812                     Without  --if-exists,  it  is an error if record does not
813                     exist or key is specified,  if  key  does  not  exist  in
814                     record. With --if-exists, a missing record yields no out‐
815                     put and a missing key prints a blank line.
816
817                     If @name is specified, then the UUID for  record  may  be
818                     referred  to by that name later in the same ovs-vsctl in‐
819                     vocation in contexts where a UUID is expected.
820
821                     Both --id and the column arguments are optional, but usu‐
822                     ally  at  least  one or the other should be specified. If
823                     both are omitted, then get has no effect except to verify
824                     that record exists in table.
825
826                     --id and --if-exists cannot be used together.
827
828              [--if-exists] set table record column[:key]=value...
829                     Sets  the  value  of  each  specified column in the given
830                     record in table to value. For map columns, a key may  op‐
831                     tionally be specified, in which case the value associated
832                     with key in that column is changed (or added, if none ex‐
833                     ists), instead of the entire map.
834
835                     Without  --if-exists,  it  is an error if record does not
836                     exist. With --if-exists, this  command  does  nothing  if
837                     record does not exist.
838
839              [--if-exists] add table record column [key=]value...
840                     Adds  the  specified value or key-value pair to column in
841                     record in table. If column is a  map,  then  key  is  re‐
842                     quired, otherwise it is prohibited. If key already exists
843                     in a map column, then the current value is  not  replaced
844                     (use the set command to replace an existing value).
845
846                     Without  --if-exists,  it  is an error if record does not
847                     exist. With --if-exists, this  command  does  nothing  if
848                     record does not exist.
849
850              [--if-exists] remove table record column value...
851
852                     [--if-exists] remove table record column key...
853
854                     [--if-exists]  remove  table  record  column key=value...
855                     Removes the specified values or key-value pairs from col‐
856                     umn in record in table. The first form applies to columns
857                     that are not maps: each specified value is  removed  from
858                     the  column. The second and third forms apply to map col‐
859                     umns: if only a key is specified, then any key-value pair
860                     with  the  given key is removed, regardless of its value;
861                     if a value is given then a pair is removed only  if  both
862                     key and value match.
863
864                     It  is  not  an  error if the column does not contain the
865                     specified key or value or pair.
866
867                     Without --if-exists, it is an error if  record  does  not
868                     exist.  With  --if-exists,  this  command does nothing if
869                     record does not exist.
870
871              [--if-exists] clear table record column...
872                     Sets each column in record in table to the empty  set  or
873                     empty  map,  as appropriate. This command applies only to
874                     columns that are allowed to be empty.
875
876                     Without --if-exists, it is an error if  record  does  not
877                     exist.  With  --if-exists,  this  command does nothing if
878                     record does not exist.
879
880              [--id=@name] create table column[:key]=value...
881                     Creates a new record in table and sets the initial values
882                     of  each  column. Columns not explicitly set will receive
883                     their default values. Outputs the UUID of the new row.
884
885                     If @name is specified, then the UUID for the new row  may
886                     be  referred  to by that name elsewhere in the same \*(PN
887                     invocation in contexts where a  UUID  is  expected.  Such
888                     references may precede or follow the create command.
889
890                     Caution (ovs-vsctl as example)
891                            Records  in the Open vSwitch database are signifi‐
892                            cant only when they can be reached directly or in‐
893                            directly  from  the Open_vSwitch table. Except for
894                            records in the QoS or Queue tables,  records  that
895                            are  not reachable from the Open_vSwitch table are
896                            automatically  deleted  from  the  database.  This
897                            deletion  happens immediately, without waiting for
898                            additional ovs-vsctl commands  or  other  database
899                            activity. Thus, a create command must generally be
900                            accompanied by additional commands within the same
901                            ovs-vsctl  invocation to add a chain of references
902                            to the newly created  record  from  the  top-level
903                            Open_vSwitch  record.  The  EXAMPLES section gives
904                            some examples that show how to do this.
905
906              [--if-exists] destroy table record...
907                     Deletes each specified record from table. Unless --if-ex‐
908                     ists is specified, each records must exist.
909
910              --all destroy table
911                     Deletes all records from the table.
912
913                     Caution (ovs-vsctl as example)
914                            The  destroy command is only useful for records in
915                            the QoS or Queue tables. Records in  other  tables
916                            are  automatically  deleted from the database when
917                            they become unreachable from the Open_vSwitch  ta‐
918                            ble.  This  means that deleting the last reference
919                            to a record is sufficient for deleting the  record
920                            itself.  For  records  in these tables, destroy is
921                            silently ignored. See the EXAMPLES  section  below
922                            for more information.
923
924              wait-until table record [column[:key]=value]...
925                     Waits  until  table  contains a record named record whose
926                     column equals value or, if key is specified, whose column
927                     contains  a  key  with  the specified value. This command
928                     supports the same operators and semantics  described  for
929                     the find command above.
930
931                     If  no  column[:key]=value arguments are given, this com‐
932                     mand waits only until record exists.  If  more  than  one
933                     such  argument  is  given, the command waits until all of
934                     them are satisfied.
935
936                     Caution (ovs-vsctl as example)
937                            Usually wait-until should be placed at the  begin‐
938                            ning  of a set of ovs-vsctl commands. For example,
939                            wait-until bridge br0  --  get  bridge  br0  data‐
940                            path_id waits until a bridge named br0 is created,
941                            then prints its datapath_id  column,  whereas  get
942                            bridge  br0  datapath_id  -- wait-until bridge br0
943                            will abort if no  bridge  named  br0  exists  when
944                            ovs-vsctl initially connects to the database.
945
946                     Consider  specifying --timeout=0 along with --wait-until,
947                     to prevent ovs-vsctl from terminating after waiting  only
948                     at most 5 seconds.
949
950              comment [arg]...
951                     This  command has no effect on behavior, but any database
952                     log record created by the command will include  the  com‐
953                     mand and its arguments.
954

ENVIRONMENT

956       OVN_SB_DAEMON
957              If set, this should name the Unix domain socket for an ovn-sbctl
958              server process. See Daemon Mode, above, for more information.
959
960       OVN_SBCTL_OPTIONS
961              If set, a set of options for ovn-sbctl to  apply  automatically,
962              in the same form as on the command line.
963
964       OVN_SB_DB
965              If  set, the default database to contact when the --db option is
966              not used.
967

EXIT STATUS

969       0      Successful program execution.
970
971       1      Usage, syntax, or network error.
972

SEE ALSO

974       ovn-sb(5), ovn-appctl(8).
975
976
977
978OVN 21.09.0                        ovn-sbctl                      ovn-sbctl(8)
Impressum