.\" -*- 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 command should only be used for advanced debugging and troubleshooting
of the \fBOVN_Southbound\fR database; and should never be used in normal
operation.
.PP
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.)
.
.SS "Table Formatting Options"
These options control the format of output from the \fBlist\fR and
\fBfind\fR commands.
.so lib/table.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 "\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] \fBlport\-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] \fBlport\-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 "\fBlflow\-list\fR [\fIlogical\-datapath\fR]"
List logical flows. If \fIlogical\-datapath\fR is specified, only list flows for
that logical datapath.
.
.IP "\fBdump\-flows\fR [\fIlogical\-datapath\fR]"
Alias for \fBlflow\-list\fB.
.
.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).