ovn/utilities/ovn-sbctl.8.in

   1 .\" -*- nroff -*-
   2 .de IQ
   3 .  br
   4 .  ns
   5 .  IP "\\$1"
   6 ..
   7 .de ST
   8 .  PP
   9 .  RS -0.15in
  10 .  I "\\$1"
  11 .  RE
  12 ..
  13 .TH ovn\-sbctl 8 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
  14 .\" This program's name:
  15 .ds PN ovn\-sbctl
  16 .
  17 .SH NAME
  18 ovn\-sbctl \- utility for querying and configuring \fBOVN_Southbound\fR database
  19 .
  20 .SH SYNOPSIS
  21 \fBovn\-sbctl\fR [\fIoptions\fR] \fB\-\-\fR [\fIoptions\fR] \fIcommand
  22 \fR[\fIargs\fR] [\fB\-\-\fR [\fIoptions\fR] \fIcommand \fR[\fIargs\fR]]...
  23 .
  24 .SH DESCRIPTION
  25 The command should only be used for advanced debugging and troubleshooting
  26 of the \fBOVN_Southbound\fR database; and should never be used in normal
  27 operation.
  28 .PP
  29 The \fBovn\-sbctl\fR program configures the \fBOVN_Southbound\fR database
  30 by providing a high\-level interface to its configuration database.  See
  31 \fBovn\-sb\fR(5) for comprehensive documentation of the database schema.
  32 .PP
  33 \fBovn\-sbctl\fR connects to an \fBovsdb\-server\fR process that
  34 maintains an OVN_Southbound configuration database.  Using this
  35 connection, it queries and possibly applies changes to the database,
  36 depending on the supplied commands.
  37 .PP
  38 \fBovn\-sbctl\fR can perform any number of commands in a single run,
  39 implemented as a single atomic transaction against the database.
  40 .PP
  41 The \fBovn\-sbctl\fR command line begins with global options (see
  42 \fBOPTIONS\fR below for details).  The global options are followed by
  43 one or more commands.  Each command should begin with \fB\-\-\fR by
  44 itself as a command-line argument, to separate it from the following
  45 commands.  (The \fB\-\-\fR before the first command is optional.)  The
  46 command
  47 itself starts with command-specific options, if any, followed by the
  48 command name and any arguments.
  49 .
  50 .SH OPTIONS
  51 .
  52 The following options affect the behavior of \fBovn\-sbctl\fR as a
  53 whole.  Some individual commands also accept their own options, which
  54 are given just before the command name.  If the first command on the
  55 command line has options, then those options must be separated from
  56 the global options by \fB\-\-\fR.
  57 .
  58 .IP "\fB\-\-db=\fIserver\fR"
  59 The OVSDB database remote to contact.  If the \fBOVN_SB_DB\fR
  60 environment variable is set, its value is used as the default.
  61 Otherwise, the default is \fBunix:@RUNDIR@/db.sock\fR, but this
  62 default is unlikely to be useful outside of single-machine OVN test
  63 environments.
  64 .IP
  65 \fIserver\fR must take one of the following forms:
  66 .RS
  67 .so ovsdb/remote-active.man
  68 .so ovsdb/remote-passive.man
  69 .RE
  70 .
  71 .IP "\fB\-\-no\-syslog\fR"
  72 By default, \fBovn\-sbctl\fR logs its arguments and the details of any
  73 changes that it makes to the system log.  This option disables this
  74 logging.
  75 .IP
  76 This option is equivalent to \fB\-\-verbose=sbctl:syslog:warn\fR.
  77 .
  78 .IP "\fB\-\-oneline\fR"
  79 Modifies the output format so that the output for each command is printed
  80 on a single line.  New-line characters that would otherwise separate
  81 lines are printed as \fB\\n\fR, and any instances of \fB\\\fR that
  82 would otherwise appear in the output are doubled.
  83 Prints a blank line for each command that has no output.
  84 This option does not affect the formatting of output from the
  85 \fBlist\fR or \fBfind\fR commands; see \fBTable Formatting Options\fR
  86 below.
  87 .
  88 .IP "\fB\-\-dry\-run\fR"
  89 Prevents \fBovn\-sbctl\fR from actually modifying the database.
  90 .
  91 .IP "\fB\-t \fIsecs\fR"
  92 .IQ "\fB\-\-timeout=\fIsecs\fR"
  93 By default, or with a \fIsecs\fR of \fB0\fR, \fBovn\-sbctl\fR waits
  94 forever for a response from the database.  This option limits runtime
  95 to approximately \fIsecs\fR seconds.  If the timeout expires,
  96 \fBovn\-sbctl\fR will exit with a \fBSIGALRM\fR signal.  (A timeout
  97 would normally happen only if the database cannot be contacted, or if
  98 the system is overloaded.)
  99 .
 100 .SS "Table Formatting Options"
 101 These options control the format of output from the \fBlist\fR and
 102 \fBfind\fR commands.
 103 .so lib/table.man
 104 .
 105 .SH COMMANDS
 106 The commands implemented by \fBovn\-sbctl\fR are described in the
 107 sections below.
 108 .SS "OVN_Southbound Commands"
 109 These commands work with an \fBOVN_Southbound\fR database as a whole.
 110 .
 111 .IP "\fBinit\fR"
 112 Initializes the database, if it is empty.  If the database has already
 113 been initialized, this command has no effect.
 114 .
 115 .IP "\fBshow\fR"
 116 Prints a brief overview of the database contents.
 117 .
 118 .SS "Chassis Commands"
 119 These commands manipulate \fBOVN_Southbound\fR chassis.
 120 .
 121 .IP "[\fB\-\-may\-exist\fR] \fBchassis\-add \fIchassis\fR \fIencap\-type\fR \fIencap-ip\fR"
 122 Creates a new chassis named \fIchassis\fR.  \fIencap\-type\fR is a
 123 comma-separated list of tunnel types.  The chassis will have
 124 one encap entry for each specified tunnel type with \fIencap-ip\fR
 125 as the destination IP for each.
 126 .IP
 127 Without \fB\-\-may\-exist\fR, attempting to create a chassis that
 128 exists is an error.  With \fB\-\-may\-exist\fR, this command does
 129 nothing if \fIchassis\fR already exists.
 130 .
 131 .IP "[\fB\-\-if\-exists\fR] \fBchassis\-del \fIchassis\fR"
 132 Deletes \fIchassis\fR and its \fIencaps\fR and \fIgateway_ports\fR.
 133 .IP
 134 Without \fB\-\-if\-exists\fR, attempting to delete a chassis that does
 135 not exist is an error.  With \fB\-\-if\-exists\fR, attempting to
 136 delete a chassis that does not exist has no effect.
 137 .
 138 .SS "Port binding Commands"
 139 .
 140 These commands manipulate \fBOVN_Southbound\fR port bindings.
 141 .
 142 .IP "[\fB\-\-may\-exist\fR] \fBlsp\-bind \fIlogical\-port\fR \fIchassis\fR"
 143 Binds the logical port named \fIlogical\-port\fR to \fIchassis\fR.
 144 .IP
 145 Without \fB\-\-may\-exist\fR, attempting to bind a logical port that
 146 has already been bound is an error.  With \fB\-\-may\-exist\fR, this
 147 command does nothing if \fIlogical\-port\fR has already been bound to
 148 a chassis.
 149 .
 150 .IP "[\fB\-\-if\-exists\fR] \fBlsp\-unbind\fR \fIlogical\-port\fR"
 151 Resets the binding of \fIlogical\-port\fR to \fINULL\fR.
 152 .IP
 153 Without \fB\-\-if\-exists\fR, attempting to unbind a logical port
 154 that is not bound is an error.  With \fB\-\-if\-exists\fR, attempting
 155 to unbind logical port that is not bound has no effect.
 156 .
 157 .SS "Logical Flow Commands"
 158 .
 159 .IP "\fBlflow\-list\fR [\fIlogical\-datapath\fR]"
 160 List logical flows. If \fIlogical\-datapath\fR is specified, only list flows for
 161 that logical datapath.
 162 .
 163 .IP "\fBdump\-flows\fR [\fIlogical\-datapath\fR]"
 164 Alias for \fBlflow\-list\fB.
 165 .
 166 .so lib/db-ctl-base.man
 167 .SH "EXIT STATUS"
 168 .IP "0"
 169 Successful program execution.
 170 .IP "1"
 171 Usage, syntax, or configuration file error.
 172 .SH "SEE ALSO"
 173 .
 174 .BR ovn\-sb (5).