# ovn-sbctl

## NAME



           ovn-sbctl - Open Virtual Network southbound db management utility
    


## SYNOPSIS



           **ovn-sbctl**[_options_] _command_ [_arg_...]
    


## DESCRIPTION



           The **ovn-sbctl** program configures the **OVN_Southbound** database by
           providing a high-level interface to its configuration database.
           See ovn-sb(5) for comprehensive documentation of the database
           schema.
    
           **ovn-sbctl** connects to an **ovsdb-server** process that maintains an
           OVN_Southbound configuration database. Using this connection, it
           queries and possibly applies changes to the database, depending on
           the supplied commands.
    
           **ovn-sbctl** can perform any number of commands in a single run,
           implemented as a single atomic transaction against the database.
    
           The **ovn-sbctl** command line begins with global options (see **OPTIONS**
           below for details). The global options are followed by one or more
           commands. Each command should begin with **--** by itself as a
           command-line argument, to separate it from the following commands.
           (The **--** before the first command is optional.) The command itself
           starts with command-specific options, if any, followed by the
           command name and any arguments.
    


## DAEMON MODE



           When it is invoked in the most ordinary way, **ovn-sbctl** connects to
           an OVSDB server that hosts the southbound database, retrieves a
           partial copy of the database that is complete enough to do its
           work, sends a transaction request to the server, and receives and
           processes the server’s reply. In common interactive use, this is
           fine, but if the database is large, the step in which **ovn-sbctl**
           retrieves a partial copy of the database can take a long time,
           which yields poor performance overall.
    
           To improve performance in such a case, **ovn-sbctl** offers a "daemon
           mode," in which the user first starts **ovn-sbctl** running in the
           background and afterward uses the daemon to execute operations.
           Over several **ovn-sbctl** command invocations, this performs better
           overall because it retrieves a copy of the database only once at
           the beginning, not once per program run.
    
           Use the **--detach** option to start an **ovn-sbctl** daemon. With this
           option, **ovn-sbctl** prints the name of a control socket to stdout.
           The client should save this name in environment variable
           **OVN_SB_DAEMON**. Under the Bourne shell this might be done like
           this:
    
                 export OVN_SB_DAEMON=$(ovn-sbctl --pidfile --detach)
    
           When **OVN_SB_DAEMON** is set, **ovn-sbctl** automatically and
           transparently uses the daemon to execute its commands.
    
           When the daemon is no longer needed, kill it and unset the
           environment variable, e.g.:
    
                 kill $(cat $OVN_RUNDIR/ovn-sbctl.pid)
                 unset OVN_SB_DAEMON
    
           When using daemon mode, an alternative to the **OVN_SB_DAEMON**
           environment variable is to specify a path for the Unix socket.
           When starting the ovn-sbctl daemon, specify the **-u** option with a
           full path to the location of the socket file. Here is an exmple:
    
                 ovn-sbctl --detach -u /tmp/mysock.ctl
    
           Then to connect to the running daemon, use the **-u** option with the
           full path to the socket created when the daemon was started:
    
                 ovn-sbctl -u /tmp/mysock.ctl show
    
         _Daemon Commands_
    
           Daemon mode is internally implemented using the same mechanism
           used by **ovn-appctl**. One may also use **ovn-appctl** directly with the
           following commands:
    
                  **run**[_options_] _command_ [_arg_...] [**--**[_options_] _command_
                  [_arg_...] ...]
                         Instructs the daemon process to run one or more
                         **ovn-sbctl** commands described above and reply with
                         the results of running these commands. Accepts the
                         **--timeout** , **--dry-run** , **--oneline** , and the options
                         described under **Table Formatting Options** in addition
                         to the the command-specific options.
    
                  **exit** Causes **ovn-sbctl** to gracefully terminate.
    


## OPTIONS



           The options listed below affect the behavior of **ovn-sbctl** as a
           whole. Some individual commands also accept their own options,
           which are given just before the command name. If the first command
           on the command line has options, then those options must be
           separated from the global options by **--**.
    
           **ovn-sbctl** also accepts options from the **OVN_SBCTL_OPTIONS**
           environment variable, in the same format as on the command line.
           Options from the command line override those in the environment.
    
                  **--db** _database_
                         The OVSDB database remote to contact. If the
                         **OVN_SB_DB** environment variable is set, its value is
                         used as the default. Otherwise, the default is
                         **unix:/ovnsb_db.sock** , but this default is unlikely to
                         be useful outside of single-machine OVN test
                         environments.
    
                  **--leader-only**
                  **--no-leader-only**
                       By default, or with **--leader-only** , when the database
                       server is a clustered database, **ovn-sbctl** will avoid
                       servers other than the cluster leader. This ensures
                       that any data that **ovn-sbctl** reads and reports is up-
                       to-date. With **--no-leader-only** , **ovn-sbctl** will use any
                       server in the cluster, which means that for read-only
                       transactions it can report and act on stale data
                       (transactions that modify the database are always
                       serialized even with **--no-leader-only**). Refer to
                       **Understanding Cluster Consistency** in ovsdb(7) for more
                       information.
    
                  **--shuffle-remotes**
                  **--no-shuffle-remotes**
                       By default, or with **--shuffle-remotes** , when there are
                       multiple remotes specified in the OVSDB connection
                       string specified by **--db** or the **OVN_SB_DB** environment
                       variable, the order of the remotes will be shuffled
                       before the client tries to connect. The remotes will
                       be shuffled only once to a new order before the first
                       connection attempt. The following retries, if any,
                       will follow the same new order. The default behavior
                       is to make sure clients of a clustered database can
                       distribute evenly to all members of the cluster. With
                       **--no-shuffle-remotes** , **ovn-sbctl** will use the original
                       order specified in the connection string to connect.
                       This allows user to specify the preferred order, which
                       is particularly useful for testing.
    
                  **--no-syslog**
                       By default, **ovn-sbctl** logs its arguments and the
                       details of any changes that it makes to the system
                       log. This option disables this logging.
    
                       This option is equivalent to
                       **--verbose=sbctl:syslog:warn**.
    
                  **--oneline**
                       Modifies the output format so that the output for each
                       command is printed on a single line. New-line
                       characters that would otherwise separate lines are
                       printed as \fB\\n\fR, and any instances of \fB\\\fR
                       that would otherwise appear in the output are doubled.
                       Prints a blank line for each command that has no
                       output. This option does not affect the formatting of
                       output from the **list** or **find** commands; see **Table**
                       **Formatting Options** below.
    
                  **--dry-run**
                       Prevents **ovn-sbctl** from actually modifying the
                       database.
    
                  **-t** _secs_
                  **--timeout=**_secs_
                       By default, or with a _secs_ of **0** , **ovn-sbctl** waits
                       forever for a response from the database. This option
                       limits runtime to approximately _secs_ seconds. If the
                       timeout expires, **ovn-sbctl** will exit with a **SIGALRM**
                       signal. (A timeout would normally happen only if the
                       database cannot be contacted, or if the system is
                       overloaded.)
    
       **Daemon Options**
           **--pidfile**[**=**_pidfile_]
                  Causes a file (by default, _program_**.pid**) to be created
                  indicating the PID of the running process. If the _pidfile_
                  argument is not specified, or if it does not begin with **/** ,
                  then it is created in .
    
                  If **--pidfile** is not specified, no pidfile is created.
    
           **--overwrite-pidfile**
                  By default, when **--pidfile** is specified and the specified
                  pidfile already exists and is locked by a running process,
                  the daemon refuses to start. Specify **--overwrite-pidfile** to
                  cause it to instead overwrite the pidfile.
    
                  When **--pidfile** is not specified, this option has no effect.
    
           **--detach**
                  Runs this program as a background process. The process
                  forks, and in the child it starts a new session, closes the
                  standard file descriptors (which has the side effect of
                  disabling logging to the console), and changes its current
                  directory to the root (unless **--no-chdir** is specified).
                  After the child completes its initialization, the parent
                  exits.
    
           **--monitor**
                  Creates an additional process to monitor this program. If
                  it dies due to a signal that indicates a programming error
                  (**SIGABRT** , **SIGALRM** , **SIGBUS** , **SIGFPE** , **SIGILL** , **SIGPIPE** ,
                  **SIGSEGV** , **SIGXCPU** , or **SIGXFSZ**) then the monitor process
                  starts a new copy of it. If the daemon dies or exits for
                  another reason, the monitor process exits.
    
                  This option is normally used with **--detach** , but it also
                  functions without it.
    
           **--no-chdir**
                  By default, when **--detach** is specified, the daemon changes
                  its current working directory to the root directory after
                  it detaches. Otherwise, invoking the daemon from a
                  carelessly chosen directory would prevent the administrator
                  from unmounting the file system that holds that directory.
    
                  Specifying **--no-chdir** suppresses this behavior, preventing
                  the daemon from changing its current working directory.
                  This may be useful for collecting core files, since it is
                  common behavior to write core dumps into the current
                  working directory and the root directory is not a good
                  directory to use.
    
                  This option has no effect when **--detach** is not specified.
    
           **--no-self-confinement**
                  By default this daemon will try to self-confine itself to
                  work with files under well-known directories determined at
                  build time. It is better to stick with this default
                  behavior and not to use this flag unless some other Access
                  Control is used to confine daemon. Note that in contrast to
                  other access control implementations that are typically
                  enforced from kernel-space (e.g. DAC or MAC), self-
                  confinement is imposed from the user-space daemon itself
                  and hence should not be considered as a full confinement
                  strategy, but instead should be viewed as an additional
                  layer of security.
    
           **--user=**_user_**:**_group_
                  Causes this program to run as a different user specified in
                  _user_**:**_group_ , thus dropping most of the root privileges.
                  Short forms _user_ and **:**_group_ are also allowed, with current
                  user or group assumed, respectively. Only daemons started
                  by the root user accepts this argument.
    
                  On Linux, daemons will be granted **CAP_IPC_LOCK** and
                  **CAP_NET_BIND_SERVICES** before dropping root privileges.
                  Daemons that interact with a datapath, such as
                  **ovs-vswitchd** , will be granted three additional
                  capabilities, namely **CAP_NET_ADMIN** , **CAP_NET_BROADCAST** and
                  **CAP_NET_RAW**. The capability change will apply even if the
                  new user is root.
    
                  On Windows, this option is not currently supported. For
                  security reasons, specifying this option will cause the
                  daemon process not to start.
    
       **Logging options**
           **-v**[_spec_]
           **--verbose=**[_spec_]
                Sets logging levels. Without any _spec_ , sets the log level for
                every module and destination to **dbg**. Otherwise, _spec_ is a
                list of words separated by spaces or commas or colons, up to
                one from each category below:
    
                •      A valid module name, as displayed by the **vlog/list**
                       command on ovs-appctl(8), limits the log level change
                       to the specified module.
    
                •      **syslog** , **console** , or **file** , to limit the log level
                       change to only to the system log, to the console, or
                       to a file, respectively. (If **--detach** is specified,
                       the daemon closes its standard file descriptors, so
                       logging to the console will have no effect.)
    
                       On Windows platform, **syslog** is accepted as a word and
                       is only useful along with the **--syslog-target** option
                       (the word has no effect otherwise).
    
                •      **off** , **emer** , **err** , **warn** , **info** , or **dbg** , to control the log
                       level. Messages of the given severity or higher will
                       be logged, and messages of lower severity will be
                       filtered out. **off** filters out all messages. See
                       ovs-appctl(8) for a definition of each log level.
    
                Case is not significant within _spec_.
    
                Regardless of the log levels set for **file** , logging to a file
                will not take place unless **--log-file** is also specified (see
                below).
    
                For compatibility with older versions of OVS, **any** is accepted
                as a word but has no effect.
    
           **-v**
           **--verbose**
                Sets the maximum logging verbosity level, equivalent to
                **--verbose=dbg**.
    
           **-vPATTERN:**_destination_**:**_pattern_
           **--verbose=PATTERN:**_destination_**:**_pattern_
                Sets the log pattern for _destination_ to _pattern_. Refer to
                ovs-appctl(8) for a description of the valid syntax for
                _pattern_.
    
           **-vFACILITY:**_facility_
           **--verbose=FACILITY:**_facility_
                Sets the RFC5424 facility of the log message. _facility_ can be
                one of **kern** , **user** , **mail** , **daemon** , **auth** , **syslog** , **lpr** , **news** ,
                **uucp** , **clock** , **ftp** , **ntp** , **audit** , **alert** , **clock2** , **local0** , **local1** ,
                **local2** , **local3** , **local4** , **local5** , **local6** or **local7**. If this
                option is not specified, **daemon** is used as the default for
                the local system syslog and **local0** is used while sending a
                message to the target provided via the **--syslog-target**
                option.
    
           **--log-file**[**=**_file_]
                Enables logging to a file. If _file_ is specified, then it is
                used as the exact name for the log file. The default log file
                name used if _file_ is omitted is
                **/usr/local/var/log/ovn/**_program_**.log**.
    
           **--syslog-target=**_host_**:**_port_
                Send syslog messages to UDP _port_ on _host_ , in addition to the
                system syslog. The _host_ must be a numerical IP address, not a
                hostname.
    
           **--syslog-method=**_method_
                Specify _method_ as how syslog messages should be sent to
                syslog daemon. The following forms are supported:
    
                •      **libc** , to use the libc **syslog()** function. Downside of
                       using this options is that libc adds fixed prefix to
                       every message before it is actually sent to the syslog
                       daemon over **/dev/log** UNIX domain socket.
    
                •      **unix:**_file_ , to use a UNIX domain socket directly. It is
                       possible to specify arbitrary message format with this
                       option. However, **rsyslogd 8.9** and older versions use
                       hard coded parser function anyway that limits UNIX
                       domain socket use. If you want to use arbitrary
                       message format with older **rsyslogd** versions, then use
                       UDP socket to localhost IP address instead.
    
                •      **udp:**_ip_**:**_port_ , to use a UDP socket. With this method it
                       is possible to use arbitrary message format also with
                       older **rsyslogd**. When sending syslog messages over UDP
                       socket extra precaution needs to be taken into
                       account, for example, syslog daemon needs to be
                       configured to listen on the specified UDP port,
                       accidental iptables rules could be interfering with
                       local syslog traffic and there are some security
                       considerations that apply to UDP sockets, but do not
                       apply to UNIX domain sockets.
    
                •      **null** , to discard all messages logged to syslog.
    
                The default is taken from the **OVS_SYSLOG_METHOD** environment
                variable; if it is unset, the default is **libc**.
    
       **Table Formatting Options**
           These options control the format of output from the **list** and **find**
           commands.
    
                  **-f** _format_
                  **--format=**_format_
                       Sets the type of table formatting. The following types
                       of _format_ are available:
    
                       **table** 2-D text tables with aligned columns.
    
                       **list**(default)
                              A list with one column per line and rows
                              separated by a blank line.
    
                       **html** HTML tables.
    
                       **csv** Comma-separated values as defined in RFC 4180.
    
                       **json** JSON format as defined in RFC 4627. The output
                              is a sequence of JSON objects, each of which
                              corresponds to one table. Each JSON object has
                              the following members with the noted values:
    
                              **caption**
                                     The table’s caption. This member is
                                     omitted if the table has no caption.
    
                              **headings**
                                     An array with one element per table
                                     column. Each array element is a string
                                     giving the corresponding column’s
                                     heading.
    
                              **data** An array with one element per table row.
                                     Each element is also an array with one
                                     element per table column. The elements
                                     of this second-level array are the cells
                                     that constitute the table. Cells that
                                     represent OVSDB data or data types are
                                     expressed in the format described in the
                                     OVSDB specification; other cells are
                                     simply expressed as text strings.
    
                  **-d** _format_
                  **--data=**_format_
                       Sets the formatting for cells within output tables
                       unless the table format is set to **json** , in which case
                       **json** formatting is always used when formatting cells.
                       The following types of _format_ are available:
    
                       **string**(default)
                              The simple format described in the **Database**
                              **Values** section of ovs-vsctl(8).
    
                       **bare** The simple format with punctuation stripped
                              off: **[]** and **{}** are omitted around sets, maps,
                              and empty columns, items within sets and maps
                              are space-separated, and strings are never
                              quoted. This format may be easier for scripts
                              to parse.
    
                       **json** The RFC 4627 JSON format as described above.
    
                  **--no-headings**
                       This option suppresses the heading row that otherwise
                       appears in the first row of table output.
    
                  **--pretty**
                       By default, JSON in output is printed as compactly as
                       possible. This option causes JSON in output to be
                       printed in a more readable fashion. Members of objects
                       and elements of arrays are printed one per line, with
                       indentation.
    
                       This option does not affect JSON in tables, which is
                       always printed compactly.
    
                  **--bare**
                       Equivalent to **--format=list --data=bare --no-headings**.
    
       **PKI Options**
           PKI configuration is required to use SSL/TLS for the connection to
           the database.
    
                  **-p** _privkey.pem_
                  **--private-key=**_privkey.pem_
                       Specifies a PEM file containing the private key used
                       as identity for outgoing SSL connections.
    
                  **-c** _cert.pem_
                  **--certificate=**_cert.pem_
                       Specifies a PEM file containing a certificate that
                       certifies the private key specified on **-p** or
                       **--private-key** to be trustworthy. The certificate must
                       be signed by the certificate authority (CA) that the
                       peer in SSL connections will use to verify it.
    
                  **-C** _cacert.pem_
                  **--ca-cert=**_cacert.pem_
                       Specifies a PEM file containing the CA certificate for
                       verifying certificates presented to this program by
                       SSL peers. (This may be the same certificate that SSL
                       peers use to verify the certificate specified on **-c** or
                       **--certificate** , or it may be a different one, depending
                       on the PKI design in use.)
    
                  **-C none**
                  **--ca-cert=none**
                       Disables verification of certificates presented by SSL
                       peers. This introduces a security risk, because it
                       means that certificates cannot be verified to be those
                       of known trusted hosts.
    
                  **--bootstrap-ca-cert=**_cacert.pem_
                         When _cacert.pem_ exists, this option has the same
                         effect as **-C** or **--ca-cert**. If it does not exist,
                         then the executable will attempt to obtain the CA
                         certificate from the SSL peer on its first SSL
                         connection and save it to the named PEM file. If it
                         is successful, it will immediately drop the
                         connection and reconnect, and from then on all SSL
                         connections must be authenticated by a certificate
                         signed by the CA certificate thus obtained.
    
                         This option exposes the SSL connection to a man-in-
                         the-middle attack obtaining the initial CA
                         certificate, but it may be useful for bootstrapping.
    
                         This option is only useful if the SSL peer sends its
                         CA certificate as part of the SSL certificate chain.
                         The SSL protocol does not require the server to send
                         the CA certificate.
    
                         This option is mutually exclusive with **-C** and
                         **--ca-cert**.
    
       **Other Options**
           **-h**
           **--help**
                Prints a brief help message to the console.
    
           **-V**
           **--version**
                Prints version information to the console.
    


## COMMANDS



           The following sections describe the commands that **ovn-sbctl**
           supports.
    
       **OVN_Southbound Commands**
           These commands work with an **OVN_Southbound** database as a whole.
    
                  **init** Initializes the database, if it is empty. If the
                         database has already been initialized, this command
                         has no effect.
    
                  **show** Prints a brief overview of the database contents.
    
       **Chassis Commands**
           These commands manipulate **OVN_Southbound** chassis.
    
                  [**--may-exist**] **chassis-add** _chassis encap-type encap-ip_
                         Creates a new chassis named _chassis_. _encap-type_ is a
                         comma-separated list of tunnel types. The chassis
                         will have one encap entry for each specified tunnel
                         type with _encap-ip_ as the destination IP for each.
    
                         Without **--may-exist** , attempting to create a chassis
                         that exists is an error. With **--may-exist** , this
                         command does nothing if _chassis_ already exists.
    
                  [**--if-exists**] _chassis-del chassis_
                         Deletes _chassis_ and its _encaps_ and _gateway_ports_.
    
                         Without **--if-exists** , attempting to delete a chassis
                         that does not exist is an error. With **--if-exists**
                         attempting to delete a chassis that does not exist
                         has no effect.
    
       **Port Binding Commands**
           These commands manipulate **OVN_Southbound** port bindings.
    
                  [**--may-exist**] **lsp-bind** _logical-port chassis_
                         Binds the logical port named _logical-port_ to
                         _chassis_.
    
                         Without **--may-exist** , attempting to bind a logical
                         port that has already been bound is an error. With
                         **--may-exist** , this command does nothing if _logical-_
                         _port_ has already been bound to a chassis.
    
                  [**--if-exists**] **lsp-unbind** _logical-port_
                         Removes the binding of _logical-port_.
    
                         Without **--if-exists** , attempting to unbind a logical
                         port that is not bound is an error. With
                         **--if-exists** , attempting to unbind logical port that
                         is not bound has no effect.
    
       **Logical Flow Commands**
           [**--uuid**] [**--ovs**[**=**_remote_**]**] [**--stats**] [**--vflows**] **lflow-list**
           [_logical-datapath_] [_lflow_...]
                  List logical flows. If _logical-datapath_ is specified, only
                  list flows for that logical datapath. The _logical-datapath_
                  may be given as a UUID or as a datapath name (reporting an
                  error if multiple datapaths have the same name).
    
                  If at least one _lflow_ is given, only matching logical
                  flows, if any, are listed. Each _lflow_ may be specified as a
                  UUID or the first few characters of a UUID, optionally
                  prefixed by **0x**. (Because **ovn-controller** sets OpenFlow flow
                  cookies to the first 32 bits of the corresponding logical
                  flow’s UUID, this makes it easy to look up the logical flow
                  that generated a particular OpenFlow flow.)
    
                  If **--uuid** is specified, the output includes the first 32
                  bits of each logical flow’s UUID. This makes it easier to
                  find the OpenFlow flows that correspond to a given logical
                  flow.
    
                  If **--ovs** is included, **ovn-sbctl** attempts to obtain and
                  display the OpenFlow flows that correspond to each OVN
                  logical flow. To do so, **ovn-sbctl** connects to _remote_ (by
                  default, **unix:/br-int.mgmt**) over OpenFlow and retrieves the
                  flows. If _remote_ is specified, it must be an active
                  OpenFlow connection method described in ovsdb(7). Please
                  see the discussion of the similar **--ovs** option in
                  ovn-trace(8) for more information about the OpenFlow flow
                  output.
    
                  By default, OpenFlow flow output includes only match and
                  actions. Add **--stats** to include all OpenFlow information,
                  such as packet and byte counters, duration, and timeouts.
    
                  If **--vflows** is included, other southbound database records
                  directly used for generating OpenFlow flows are also
                  listed. This includes: _port-bindings_ , _mac-bindings_ ,
                  _multicast-groups_ , _chassis_. The **--ovs** and **--stats** can also
                  be used in conjunction with **--vflows**.
    
           [**--uuid**] **dump-flows**[_logical-datapath_]
                  Alias for **lflow-list**.
    
           **count-flows**[_logical-datapath_]
                  prints numbers of logical flows per table and per datapath.
    
       **Remote Connectivity Commands**
           These commands manipulate the **connections** column in the **SB_Global**
           table and rows in the **Connection** table. When **ovsdb-server** is
           configured to use the **connections** column for OVSDB connections,
           this allows the administrator to use \fBovn\-sbctl\fR to configure
           database connections.
    
                  **get-connection**
                         Prints the configured connection(s).
    
                  **del-connection**
                         Deletes the configured connection(s).
    
                  [**--inactivity-probe=**_msecs_] **set-connection** _target_...
                         Sets the configured manager target or targets. Use
                         **--inactivity-probe=**_msecs_ to override the default
                         idle connection inactivity probe time. Use 0 to
                         disable inactivity probes.
    
       **SSL/TLS Configuration Commands**
           When **ovsdb-server** is configured to connect using SSL/TLS, the
           following parameters are required:
    
                  _private-key_
                         Specifies a PEM file containing the private key used
                         for SSL/TLS connections.
    
                  _certificate_
                         Specifies a PEM file containing a certificate,
                         signed by the certificate authority (CA) used by the
                         connection peers, that certifies the private key,
                         identifying a trustworthy peer.
    
                  _ca-cert_
                         Specifies a PEM file containing the CA certificate
                         used to verify that the connection peers are
                         trustworthy.
    
           These SSL/TLS settings apply to all SSL/TLS connections made by
           the southbound database server.
    
                  **get-ssl**
                         Prints the SSL/TLS configuration.
    
                  **del-ssl**
                         Deletes the current SSL/TLS configuration.
    
                  [**--bootstrap**] **set-ssl** _private-key certificate ca-cert_ [_ssl-_
                  _protocol-list_ [_ssl-cipher-list_ [_ssl-ciphersuites_]]]
                         Sets the SSL/TLS configuration.
    
       **Database Commands**
           These commands query and modify the contents of **ovsdb** tables. They
           are a slight abstraction of the **ovsdb** interface and as such they
           operate at a lower level than other **ovn-sbctl** commands.
    
           _Identifying Tables, Records, and Columns_
    
           Each of these commands has a _table_ parameter to identify a table
           within the database. Many of them also take a _record_ parameter
           that identifies a particular record within a table. The _record_
           parameter may be the UUID for a record, which may be abbreviated
           to its first 4 (or more) hex digits, as long as that is unique.
           Many tables offer additional ways to identify records. Some
           commands also take _column_ parameters that identify a particular
           field within the records in a table.
    
           For a list of tables and their columns, see ovn-sb(5) or see the
           table listing from the **--help** option.
    
           Record names must be specified in full and with correct
           capitalization, except that UUIDs may be abbreviated to their
           first 4 (or more) hex digits, as long as that is unique within the
           table. Names of tables and columns are not case-sensitive, and **-**
           and **_** are treated interchangeably. Unique abbreviations of table
           and column names are acceptable, e.g. **d** or **dhcp** is sufficient to
           identify the **DHCP_Options** table.
    
           _Database Values_
    
           Each column in the database accepts a fixed type of data. The
           currently defined basic types, and their representations, are:
    
                  integer
                         A decimal integer in the range -2**63 to 2**63-1,
                         inclusive.
    
                  real   A floating-point number.
    
                  Boolean
                         True or false, written **true** or **false** , respectively.
    
                  string An arbitrary Unicode string, except that null bytes
                         are not allowed. Quotes are optional for most
                         strings that begin with an English letter or
                         underscore and consist only of letters, underscores,
                         hyphens, and periods. However, **true** and **false** and
                         strings that match the syntax of UUIDs (see below)
                         must be enclosed in double quotes to distinguish
                         them from other basic types. When double quotes are
                         used, the syntax is that of strings in JSON, e.g.
                         backslashes may be used to escape special
                         characters. The empty string must be represented as
                         a pair of double quotes (**""**).
    
                  UUID   Either a universally unique identifier in the style
                         of RFC 4122, e.g.
                         **f81d4fae-7dec-11d0-a765-00a0c91e6bf6** , or an **@**_name_
                         defined by a **get** or **create** command within the same
                         **ovs-vsctl** invocation.
    
           Multiple values in a single column may be separated by spaces or a
           single comma. When multiple values are present, duplicates are not
           allowed, and order is not important. Conversely, some database
           columns can have an empty set of values, represented as **[]** , and
           square brackets may optionally enclose other non-empty sets or
           single values as well.
    
           A few database columns are ``maps’’ of key-value pairs, where the
           key and the value are each some fixed database type. These are
           specified in the form _key_**=**_value_ , where _key_ and _value_ follow the
           syntax for the column’s key type and value type, respectively.
           When multiple pairs are present (separated by spaces or a comma),
           duplicate keys are not allowed, and again the order is not
           important. Duplicate values are allowed. An empty map is
           represented as **{}**. Curly braces may optionally enclose non-empty
           maps as well (but use quotes to prevent the shell from expanding
           **other-config={0=x,1=y}** into **other-config=0=x other-config=1=y** ,
           which may not have the desired effect).
    
           _Database Command Syntax_
    
                  [**--if-exists**] [**--columns=**_column_[**,**_column_]...] **list** _table_
                  [_record_]...
                         Lists the data in each specified _record_. If no
                         records are specified, lists all the records in
                         _table_.
    
                         If **--columns** is specified, only the requested
                         columns are listed, in the specified order.
                         Otherwise, all columns are listed, in alphabetical
                         order by column name.
    
                         Without **--if-exists** , it is an error if any specified
                         _record_ does not exist. With **--if-exists** , the command
                         ignores any _record_ that does not exist, without
                         producing any output.
    
                  [**--columns=**_column_[**,**_column_]...] **find** _table_
                  [_column_[**:**_key_]**=**_value_]...
                         Lists the data in each record in _table_ whose _column_
                         equals _value_ or, if _key_ is specified, whose _column_
                         contains a _key_ with the specified _value_. The
                         following operators may be used where **=** is written
                         in the syntax summary:
    
                         **= != < > <= >=**
                                Selects records in which _column_[**:**_key_] equals,
                                does not equal, is less than, is greater
                                than, is less than or equal to, or is greater
                                than or equal to _value_ , respectively.
    
                                Consider _column_[**:**_key_] and _value_ as sets of
                                elements. Identical sets are considered
                                equal. Otherwise, if the sets have different
                                numbers of elements, then the set with more
                                elements is considered to be larger.
                                Otherwise, consider a element from each set
                                pairwise, in increasing order within each
                                set. The first pair that differs determines
                                the result. (For a column that contains key-
                                value pairs, first all the keys are compared,
                                and values are considered only if the two
                                sets contain identical keys.)
    
                         **{=} {!=}**
                                Test for set equality or inequality,
                                respectively.
    
                         **{ <=}   **Selects records in which _column_[**:**_key_] is a
                                subset of _value_. For example,
                                **flood-vlans{ <=}1,2 **selects records in which
                                the **flood-vlans** column is the empty set or
                                contains 1 or 2 or both.
    
                         **{ <}    **Selects records in which _column_[**:**_key_] is a
                                proper subset of _value_. For example,
                                **flood-vlans{ <}1,2 **selects records in which
                                the **flood-vlans** column is the empty set or
                                contains 1 or 2 but not both.
    
                         **{ >=} {>}**
                                Same as **{ <=} **and **{ <}**, respectively, except
                                that the relationship is reversed. For
                                example, **flood-vlans{ >=}1,2 **selects records
                                in which the **flood-vlans** column contains both
                                1 and 2.
    
                         The following operators are available only in Open
                         vSwitch 2.16 and later:
    
                         **{in}** Selects records in which every element in
                                _column_[**:**_key_] is also in _value_. (This is the
                                same as **{ <=}**.)
    
                         **{not-in}**
                                Selects records in which every element in
                                _column_[**:**_key_] is not in _value_.
    
                         For arithmetic operators (**= != < > <= >=**), when _key_
                         is specified but a particular record’s _column_ does
                         not contain _key_ , the record is always omitted from
                         the results. Thus, the condition
                         **other-config:mtu!=1500** matches records that have a
                         **mtu** key whose value is not 1500, but not those that
                         lack an **mtu** key.
    
                         For the set operators, when _key_ is specified but a
                         particular record’s _column_ does not contain _key_ , the
                         comparison is done against an empty set. Thus, the
                         condition **other-config:mtu{!=}1500** matches records
                         that have a **mtu** key whose value is not 1500 and
                         those that lack an **mtu** key.
    
                         Don’t forget to escape **< **or **> **from interpretation by
                         the shell.
    
                         If **--columns** is specified, only the requested
                         columns are listed, in the specified order.
                         Otherwise all columns are listed, in alphabetical
                         order by column name.
    
                         The UUIDs shown for rows created in the same
                         **ovs-vsctl** invocation will be wrong.
    
                  [**--if-exists**] [**--id=@**_name_] **get** _table record_
                  [_column_[**:**_key_]]...
                         Prints the value of each specified _column_ in the
                         given _record_ in _table_. For map columns, a _key_ may
                         optionally be specified, in which case the value
                         associated with _key_ in the column is printed,
                         instead of the entire map.
    
                         Without **--if-exists** , it is an error if _record_ does
                         not exist or _key_ is specified, if _key_ does not exist
                         in _record_. With **--if-exists** , a missing _record_ yields
                         no output and a missing _key_ prints a blank line.
    
                         If **@**_name_ is specified, then the UUID for _record_ may
                         be referred to by that name later in the same
                         **ovs-vsctl** invocation in contexts where a UUID is
                         expected.
    
                         Both **--id** and the _column_ arguments are optional, but
                         usually at least one or the other should be
                         specified. If both are omitted, then **get** has no
                         effect except to verify that _record_ exists in _table_.
    
                         **--id** and **--if-exists** cannot be used together.
    
                  [**--if-exists**] **set** _table record column_[**:**_key_]**=**_value_...
                         Sets the value of each specified _column_ in the given
                         _record_ in _table_ to _value_. For map columns, a _key_ may
                         optionally be specified, in which case the value
                         associated with _key_ in that column is changed (or
                         added, if none exists), instead of the entire map.
    
                         Without **--if-exists** , it is an error if _record_ does
                         not exist. With **--if-exists** , this command does
                         nothing if _record_ does not exist.
    
                  [**--if-exists**] **add** _table record column_ [_key_**=**]_value_...
                         Adds the specified value or key-value pair to _column_
                         in _record_ in _table_. If _column_ is a map, then _key_ is
                         required, otherwise it is prohibited. If _key_ already
                         exists in a map column, then the current _value_ is
                         not replaced (use the **set** command to replace an
                         existing value).
    
                         Without **--if-exists** , it is an error if _record_ does
                         not exist. With **--if-exists** , this command does
                         nothing if _record_ does not exist.
    
                  [**--if-exists**] **remove** _table record column value_...
    
                         [**--if-exists**] **remove** _table record column key_...
    
                         [**--if-exists**] **remove** _table record column_
                         _key_**=**_value_...  Removes the specified values or key-
                         value pairs from _column_ in _record_ in _table_. The
                         first form applies to columns that are not maps:
                         each specified _value_ is removed from the column. The
                         second and third forms apply to map columns: if only
                         a _key_ is specified, then any key-value pair with the
                         given _key_ is removed, regardless of its value; if a
                         _value_ is given then a pair is removed only if both
                         key and value match.
    
                         It is not an error if the column does not contain
                         the specified key or value or pair.
    
                         Without **--if-exists** , it is an error if _record_ does
                         not exist. With **--if-exists** , this command does
                         nothing if _record_ does not exist.
    
                  [**--if-exists**] **clear** _table record column_...
                         Sets each _column_ in _record_ in _table_ to the empty set
                         or empty map, as appropriate. This command applies
                         only to columns that are allowed to be empty.
    
                         Without **--if-exists** , it is an error if _record_ does
                         not exist. With **--if-exists** , this command does
                         nothing if _record_ does not exist.
    
                  [**--id=(@**_name_ |_uuid_)] **create** _table column_[**:**_key_]**=**_value_...
                         Creates a new record in _table_ and sets the initial
                         values of each _column_. Columns not explicitly set
                         will receive their default values. Outputs the UUID
                         of the new row.
    
                         If **@**_name_ is specified, then the UUID for the new row
                         may be referred to by that name elsewhere in the
                         same **\*(PN** invocation in contexts where a UUID is
                         expected. Such references may precede or follow the
                         **create** command.
    
                         If a valid _uuid_ is specified, then it is used as the
                         UUID of the new row.
    
                         Caution (ovs-vsctl as example)
                                Records in the Open vSwitch database are
                                significant only when they can be reached
                                directly or indirectly from the **Open_vSwitch**
                                table. Except for records in the **QoS** or **Queue**
                                tables, records that are not reachable from
                                the **Open_vSwitch** table are automatically
                                deleted from the database. This deletion
                                happens immediately, without waiting for
                                additional **ovs-vsctl** commands or other
                                database activity. Thus, a **create** command
                                must generally be accompanied by additional
                                commands _within the same_ **ovs-vsctl** _invocation_
                                to add a chain of references to the newly
                                created record from the top-level
                                **Open_vSwitch** record. The **EXAMPLES** section
                                gives some examples that show how to do this.
    
                  [**--if-exists**] **destroy** _table record_...
                         Deletes each specified _record_ from _table_. Unless
                         **--if-exists** is specified, each _record_ s must exist.
    
                  **--all destroy** _table_
                         Deletes all records from the _table_.
    
                         Caution (ovs-vsctl as example)
                                The **destroy** command is only useful for
                                records in the **QoS** or **Queue** tables. Records
                                in other tables are automatically deleted
                                from the database when they become
                                unreachable from the **Open_vSwitch** table. This
                                means that deleting the last reference to a
                                record is sufficient for deleting the record
                                itself. For records in these tables, **destroy**
                                is silently ignored. See the **EXAMPLES** section
                                below for more information.
    
                  **wait-until** _table record_ [_column_[**:**_key_]**=**_value_]...
                         Waits until _table_ contains a record named _record_
                         whose _column_ equals _value_ or, if _key_ is specified,
                         whose _column_ contains a _key_ with the specified
                         _value_. This command supports the same operators and
                         semantics described for the **find** command above.
    
                         If no _column_[**:**_key_]**=**_value_ arguments are given, this
                         command waits only until _record_ exists. If more than
                         one such argument is given, the command waits until
                         all of them are satisfied.
    
                         Caution (ovs-vsctl as example)
                                Usually **wait-until** should be placed at the
                                beginning of a set of **ovs-vsctl** commands. For
                                example, **wait-until bridge br0 -- get bridge**
                                **br0 datapath_id** waits until a bridge named
                                **br0** is created, then prints its **datapath_id**
                                column, whereas **get bridge br0 datapath_id --**
                                **wait-until bridge br0** will abort if no bridge
                                named **br0** exists when **ovs-vsctl** initially
                                connects to the database.
    
                         Consider specifying **--timeout=0** along with
                         **--wait-until** , to prevent **ovs-vsctl** from terminating
                         after waiting only at most 5 seconds.
    
                  **comment**[_arg_]...
                         This command has no effect on behavior, but any
                         database log record created by the command will
                         include the command and its arguments.
    


## ENVIRONMENT



           **OVN_SB_DAEMON**
                  If set, this should name the Unix domain socket for an
                  **ovn-sbctl** server process. See **Daemon Mode** , above, for more
                  information.
    
           **OVN_SBCTL_OPTIONS**
                  If set, a set of options for **ovn-sbctl** to apply
                  automatically, in the same form as on the command line.
    
           **OVN_SB_DB**
                  If set, the default database to contact when the **--db**
                  option is not used.
    


## EXIT STATUS



           0      Successful program execution.
    
           1      Usage, syntax, or network error.
    


* * *