ovn-sbctl(8)

NAME
ovn-sbctl - utility for querying and configuring OVN_Southbound database

SYNOPSIS
ovn-sbctl [options] -- [options] command [args] [-- [options] command [args]]...

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.

OPTIONS
The following options 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 --.

--db=server
    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:@RUNDIR@/ovnsb_db.sock, but this default is unlikely to be useful outside of single-machine OVN test environments.

    server may be an OVSDB active or passive connection method, e.g. ssl:192.168.10.5:6640, as described in ovsdb(7).

--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.

--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 \n, and any instances of \ 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
    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.)

OVN_SBCTL_OPTIONS
    User can set one or more options using OVN_SBCTL_OPTIONS environment variable. Under the Bourne shell this might be done like this: export OVN_SBCTL_OPTIONS"="--db=unix:sb1.ovsdb --no-leader-only". However user can still over-ride environment options by passing different options in cli. When the environment variable is no longer needed, unset it, e.g.: unset OVN_SBCTL_OPTIONS"

  Table Formatting Options
These options control the format of output from the list and find commands.

  Public Key Infrastructure Options

COMMANDS
The commands implemented by ovn-sbctl are described in the sections below.

  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
    Resets the binding of logical-port to NULL.

    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:@RUNDIR@/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.

  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 ovn-sbctl to configure database connections.

get-connection
    Prints the configured connection(s).

del-connection
    Deletes the configured connection(s).

set-connection [access-specifier] target...
    Sets the configured manager target or targets. Each target may may be an OVSDB active or passive connection method, e.g. pssl:6640, as described in ovsdb(7), optionally preceded by an optional access-specifier (read-only or read-write). If provided, the effect of the access specifier persists for subsequent targets until changed by another access specifier.

  SSL Configuration
When ovsdb-server is configured to connect using SSL, the following parameters are required:

private-key
    Specifies a PEM file containing the private key used for SSL 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 settings apply to all SSL connections made by the southbound database server.

get-ssl
    Prints the SSL configuration.

del-ssl
    Deletes the current SSL configuration.

[--bootstrap] set-ssl private-key certificate ca-cert [ssl-protocol-list [ssl-cipher-list]]
    Sets the SSL configuration. The --bootstrap option is described below.

Ordinarily, all of the files named in the SSL configuration must exist before SSL connectivity can be used. However, if the ca-cert file does not exist and the --bootstrap option is given, then ovsdb-server will attempt to obtain the CA certificate from the target 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 controller to send the CA certificate.

  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 ovs-sbctl commands.

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, and 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. addr or a is sufficient to identify the Address_Set table.

EXIT STATUS

0   Successful program execution.

1   Usage, syntax, or configuration file error.

SEE ALSO
ovn-sb(5).