.\" -*- nroff -*-
.de IQ
.  br
.  ns
.  IP "\\$1"
..
.de ST
.  PP
.  RS -0.15in
.  I "\\$1"
.  RE
..
.TH ovn\-sbctl 8 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
.\" This program's name:
.ds PN ovn\-sbctl
.
.SH NAME
ovn\-sbctl \- utility for querying and configuring \fBOVN_Southbound\fR database
.
.SH SYNOPSIS
\fBovn\-sbctl\fR [\fIoptions\fR] \fB\-\-\fR [\fIoptions\fR] \fIcommand
\fR[\fIargs\fR] [\fB\-\-\fR [\fIoptions\fR] \fIcommand \fR[\fIargs\fR]]...
.
.SH DESCRIPTION
The \fBovn\-sbctl\fR program configures the \fBOVN_Southbound\fR database
by providing a high\-level interface to its configuration database.  See
\fBovn\-sb\fR(5) for comprehensive documentation of the database schema.
.PP
\fBovn\-sbctl\fR connects to an \fBovsdb\-server\fR 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.
.PP
\fBovn\-sbctl\fR can perform any number of commands in a single run,
implemented as a single atomic transaction against the database.
.PP
The \fBovn\-sbctl\fR command line begins with global options (see
\fBOPTIONS\fR below for details).  The global options are followed by
one or more commands.  Each command should begin with \fB\-\-\fR by
itself as a command-line argument, to separate it from the following
commands.  (The \fB\-\-\fR before the first command is optional.)  The
command
itself starts with command-specific options, if any, followed by the
command name and any arguments.
.
.SH OPTIONS
.
The following options affect the behavior of \fBovn\-sbctl\fR 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 \fB\-\-\fR.
.
.IP "\fB\-\-db=\fIserver\fR"
The OVSDB database remote to contact.  If the \fBOVN_SB_DB\fR
environment variable is set, its value is used as the default.
Otherwise, the default is \fBunix:@RUNDIR@/db.sock\fR, but this
default is unlikely to be useful outside of single-machine OVN test
environments.
.IP
\fIserver\fR must take one of the following forms:
.RS
.so ovsdb/remote-active.man
.so ovsdb/remote-passive.man
.RE
.
.IP "\fB\-\-no\-syslog\fR"
By default, \fBovn\-sbctl\fR logs its arguments and the details of any
changes that it makes to the system log.  This option disables this
logging.
.IP
This option is equivalent to \fB\-\-verbose=sbctl:syslog:warn\fR.
.
.IP "\fB\-\-oneline\fR"
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
\fBlist\fR or \fBfind\fR commands; see \fBTable Formatting Options\fR
below.
.
.IP "\fB\-\-dry\-run\fR"
Prevents \fBovn\-sbctl\fR from actually modifying the database.
.
.IP "\fB\-t \fIsecs\fR"
.IQ "\fB\-\-timeout=\fIsecs\fR"
By default, or with a \fIsecs\fR of \fB0\fR, \fBovn\-sbctl\fR waits
forever for a response from the database.  This option limits runtime
to approximately \fIsecs\fR seconds.  If the timeout expires,
\fBovn\-sbctl\fR will exit with a \fBSIGALRM\fR signal.  (A timeout
would normally happen only if the database cannot be contacted, or if
the system is overloaded.)
.
.so lib/vlog.man
.so lib/common.man
.
.SS "Table Formatting Options"
These options control the format of output from the \fBlist\fR and
\fBfind\fR commands.
.so lib/table.man
.
.SS "Public Key Infrastructure Options"
.so lib/ssl.man
.so lib/ssl-bootstrap.man
.so lib/ssl-peer-ca-cert.man
.
.SH COMMANDS
The commands implemented by \fBovn\-sbctl\fR are described in the
sections below.
.SS "OVN_Southbound Commands"
These commands work with an \fBOVN_Southbound\fR database as a whole.
.
.IP "\fBinit\fR"
Initializes the database, if it is empty.  If the database has already
been initialized, this command has no effect.
.
.IP "\fBshow\fR"
Prints a brief overview of the database contents.
.
.SS "Chassis Commands"
These commands manipulate \fBOVN_Southbound\fR chassis.
.
.IP "[\fB\-\-may\-exist\fR] \fBchassis\-add \fIchassis\fR \fIencap-type\fR \fIencap-ip\fR"
Creates a new chassis named \fIchassis\fR.  \fIencap-type\fR is a
comma-separated list of tunnel types.  The chassis will have
one encap entry for each specified tunnel type with \fIencap-ip\fR
as the destination IP for each.
.IP
Without \fB\-\-may\-exist\fR, attempting to create a chassis that
exists is an error.  With \fB\-\-may\-exist\fR, this command does
nothing if \fIchassis\fR already exists.
.
.IP "[\fB\-\-if\-exists\fR] \fBchassis\-del \fIchassis\fR"
Deletes \fIchassis\fR and its \fIencaps\fR and \fIgateway_ports\fR.
.IP
Without \fB\-\-if\-exists\fR, attempting to delete a chassis that does
not exist is an error.  With \fB\-\-if\-exists\fR, attempting to
delete a chassis that does not exist has no effect.
.
.SS "Port binding Commands"
.
These commands manipulate \fBOVN_Southbound\fR port bindings.
.
.IP "[\fB\-\-may\-exist\fR] \fBlsp\-bind \fIlogical-port\fR \fIchassis\fR"
Binds the logical port named \fIlogical-port\fR to \fIchassis\fR.
.IP
Without \fB\-\-may\-exist\fR, attempting to bind a logical port that
has already been bound is an error.  With \fB\-\-may\-exist\fR, this
command does nothing if \fIlogical-port\fR has already been bound to
a chassis.
.
.IP "[\fB\-\-if\-exists\fR] \fBlsp\-unbind\fR \fIlogical-port\fR"
Resets the binding of \fIlogical-port\fR to \fINULL\fR.
.IP
Without \fB\-\-if\-exists\fR, attempting to unbind a logical port
that is not bound is an error.  With \fB\-\-if\-exists\fR, attempting
to unbind logical port that is not bound has no effect.
.
.SS "Logical Flow Commands"
.
.IP "[\fB\-\-uuid\fR] \fBlflow\-list\fR [\fIlogical-datapath\fR] [\fIlflow\fR...]"
List logical flows.  If \fIlogical-datapath\fR is specified, only list
flows for that logical datapath.  The \fIlogical-datapath\fR may be
given as a UUID or as a datapath name (reporting an error if multiple
datapaths have the same name).
.IP
If at least one \fIlflow\fR is given, only matching logical flows, if
any, are listed.  Each \fIlflow\fR may be specified as a UUID or the
first few characters of a UUID, optionally prefixed by \fB0x\fR.
(Because \fBovn\-controller\fR 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.)
.IP
If \fB\-\-uuid\fR 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.
.
.IP "[\fB\-\-uuid\fR] \fBdump\-flows\fR [\fIlogical-datapath\fR]"
Alias for \fBlflow\-list\fB.
.
.SS "Remote Connectivity Commands"
.
These commands manipulate the \fBconnections\fR column in the \fBSB_Global\fR
table and rows in the \fBConnection\fR table.  When \fBovsdb\-server\fR
is configured to use the \fBconnections\fR column for OVSDB connections,
this allows the administrator to use \fBovn\-sbctl\fR to configure database
connections.
.
.IP "\fBget\-connection\fR"
Prints the configured connection(s).
.
.IP "\fBdel\-connection\fR"
Deletes the configured connection(s).
.
.IP "\fBset\-connection\fR [\fIaccess\-specifier\fR] \fItarget\fR\&..."
Sets the configured manager target or targets.  Each \fItarget\fR may
be preceded by an optional access-specifier (\fBread\-only\fR or
\fBread\-write\fR) and may use any of the following forms:
.
.RS
.so ovsdb/remote-active.man
.so ovsdb/remote-passive.man
.RE

If provided, the effect of the access specifier persists for subsequent
targets until changed by another access specifier.
.
.SS "SSL Configuration"
When \fBovsdb\-server\fR is configured to connect using SSL, the
following parameters are required:
.TP
\fIprivate-key\fR
Specifies a PEM file containing the private key used for SSL connections.
.TP
\fIcertificate\fR
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.
.TP
\fIca-cert\fR
Specifies a PEM file containing the CA certificate used to verify that
the connection peers are trustworthy.
.PP
These SSL settings apply to all SSL connections made by the southbound
database server.
.
.IP "\fBget\-ssl\fR"
Prints the SSL configuration.
.
.IP "\fBdel\-ssl\fR"
Deletes the current SSL configuration.
.
.IP "[\fB\-\-bootstrap\fR] \fBset\-ssl\fR \fIprivate-key\fR \fIcertificate\fR \fIca-cert\fR"
Sets the SSL configuration.  The \fB\-\-bootstrap\fR option is described
below.
.
.ST "CA Certificate Bootstrap"
.PP
Ordinarily, all of the files named in the SSL configuration must exist
before SSL connectivity can be used.  However, if the \fIca-cert\fR file
does not exist and the \fB\-\-bootstrap\fR
option is given, then \fBovsdb\-server\fR 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.
.PP
\fBThis option exposes the SSL connection to a man-in-the-middle
attack obtaining the initial CA certificate\fR, but it may be useful
for bootstrapping.
.PP
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.
.
.so lib/db-ctl-base.man
.SH "EXIT STATUS"
.IP "0"
Successful program execution.
.IP "1"
Usage, syntax, or configuration file error.
.SH "SEE ALSO"
.
.BR ovn\-sb (5).