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 \fBovn\-sbctl\fR program configures the \fBOVN_Southbound\fR database
  26 by providing a high\-level interface to its configuration database.  See
  27 \fBovn\-sb\fR(5) for comprehensive documentation of the database schema.
  28 .PP
  29 \fBovn\-sbctl\fR connects to an \fBovsdb\-server\fR process that
  30 maintains an OVN_Southbound configuration database.  Using this
  31 connection, it queries and possibly applies changes to the database,
  32 depending on the supplied commands.
  33 .PP
  34 \fBovn\-sbctl\fR can perform any number of commands in a single run,
  35 implemented as a single atomic transaction against the database.
  36 .PP
  37 The \fBovn\-sbctl\fR command line begins with global options (see
  38 \fBOPTIONS\fR below for details).  The global options are followed by
  39 one or more commands.  Each command should begin with \fB\-\-\fR by
  40 itself as a command-line argument, to separate it from the following
  41 commands.  (The \fB\-\-\fR before the first command is optional.)  The
  42 command
  43 itself starts with command-specific options, if any, followed by the
  44 command name and any arguments.
  45 .
  46 .SH OPTIONS
  47 .
  48 The following options affect the behavior of \fBovn\-sbctl\fR as a
  49 whole.  Some individual commands also accept their own options, which
  50 are given just before the command name.  If the first command on the
  51 command line has options, then those options must be separated from
  52 the global options by \fB\-\-\fR.
  53 .
  54 .IP "\fB\-\-db=\fIserver\fR"
  55 The OVSDB database remote to contact.  If the \fBOVN_SB_DB\fR
  56 environment variable is set, its value is used as the default.
  57 Otherwise, the default is \fBunix:@RUNDIR@/ovnsb_db.sock\fR, but this
  58 default is unlikely to be useful outside of single-machine OVN test
  59 environments.
  60 .IP
  61 \fIserver\fR must take one of the following forms:
  62 .RS
  63 .so ovsdb/remote-active.man
  64 .so ovsdb/remote-passive.man
  65 .RE
  66 .
  67 .IP "\fB\-\-no\-syslog\fR"
  68 By default, \fBovn\-sbctl\fR logs its arguments and the details of any
  69 changes that it makes to the system log.  This option disables this
  70 logging.
  71 .IP
  72 This option is equivalent to \fB\-\-verbose=sbctl:syslog:warn\fR.
  73 .
  74 .IP "\fB\-\-oneline\fR"
  75 Modifies the output format so that the output for each command is printed
  76 on a single line.  New-line characters that would otherwise separate
  77 lines are printed as \fB\\n\fR, and any instances of \fB\\\fR that
  78 would otherwise appear in the output are doubled.
  79 Prints a blank line for each command that has no output.
  80 This option does not affect the formatting of output from the
  81 \fBlist\fR or \fBfind\fR commands; see \fBTable Formatting Options\fR
  82 below.
  83 .
  84 .IP "\fB\-\-dry\-run\fR"
  85 Prevents \fBovn\-sbctl\fR from actually modifying the database.
  86 .
  87 .IP "\fB\-t \fIsecs\fR"
  88 .IQ "\fB\-\-timeout=\fIsecs\fR"
  89 By default, or with a \fIsecs\fR of \fB0\fR, \fBovn\-sbctl\fR waits
  90 forever for a response from the database.  This option limits runtime
  91 to approximately \fIsecs\fR seconds.  If the timeout expires,
  92 \fBovn\-sbctl\fR will exit with a \fBSIGALRM\fR signal.  (A timeout
  93 would normally happen only if the database cannot be contacted, or if
  94 the system is overloaded.)
  95 .
  96 .so lib/vlog.man
  97 .so lib/common.man
  98 .
  99 .SS "Table Formatting Options"
 100 These options control the format of output from the \fBlist\fR and
 101 \fBfind\fR commands.
 102 .so lib/table.man
 103 .
 104 .SS "Public Key Infrastructure Options"
 105 .so lib/ssl.man
 106 .so lib/ssl-bootstrap.man
 107 .so lib/ssl-peer-ca-cert.man
 108 .
 109 .SH COMMANDS
 110 The commands implemented by \fBovn\-sbctl\fR are described in the
 111 sections below.
 112 .SS "OVN_Southbound Commands"
 113 These commands work with an \fBOVN_Southbound\fR database as a whole.
 114 .
 115 .IP "\fBinit\fR"
 116 Initializes the database, if it is empty.  If the database has already
 117 been initialized, this command has no effect.
 118 .
 119 .IP "\fBshow\fR"
 120 Prints a brief overview of the database contents.
 121 .
 122 .SS "Chassis Commands"
 123 These commands manipulate \fBOVN_Southbound\fR chassis.
 124 .
 125 .IP "[\fB\-\-may\-exist\fR] \fBchassis\-add \fIchassis\fR \fIencap-type\fR \fIencap-ip\fR"
 126 Creates a new chassis named \fIchassis\fR.  \fIencap-type\fR is a
 127 comma-separated list of tunnel types.  The chassis will have
 128 one encap entry for each specified tunnel type with \fIencap-ip\fR
 129 as the destination IP for each.
 130 .IP
 131 Without \fB\-\-may\-exist\fR, attempting to create a chassis that
 132 exists is an error.  With \fB\-\-may\-exist\fR, this command does
 133 nothing if \fIchassis\fR already exists.
 134 .
 135 .IP "[\fB\-\-if\-exists\fR] \fBchassis\-del \fIchassis\fR"
 136 Deletes \fIchassis\fR and its \fIencaps\fR and \fIgateway_ports\fR.
 137 .IP
 138 Without \fB\-\-if\-exists\fR, attempting to delete a chassis that does
 139 not exist is an error.  With \fB\-\-if\-exists\fR, attempting to
 140 delete a chassis that does not exist has no effect.
 141 .
 142 .SS "Port binding Commands"
 143 .
 144 These commands manipulate \fBOVN_Southbound\fR port bindings.
 145 .
 146 .IP "[\fB\-\-may\-exist\fR] \fBlsp\-bind \fIlogical-port\fR \fIchassis\fR"
 147 Binds the logical port named \fIlogical-port\fR to \fIchassis\fR.
 148 .IP
 149 Without \fB\-\-may\-exist\fR, attempting to bind a logical port that
 150 has already been bound is an error.  With \fB\-\-may\-exist\fR, this
 151 command does nothing if \fIlogical-port\fR has already been bound to
 152 a chassis.
 153 .
 154 .IP "[\fB\-\-if\-exists\fR] \fBlsp\-unbind\fR \fIlogical-port\fR"
 155 Resets the binding of \fIlogical-port\fR to \fINULL\fR.
 156 .IP
 157 Without \fB\-\-if\-exists\fR, attempting to unbind a logical port
 158 that is not bound is an error.  With \fB\-\-if\-exists\fR, attempting
 159 to unbind logical port that is not bound has no effect.
 160 .
 161 .SS "Logical Flow Commands"
 162 .
 163 .IP "[\fB\-\-uuid\fR] [\fB\-\-ovs\fR[\fB=\fIremote\fR]] [\fB\-\-stats\fR] \fBlflow\-list\fR [\fIlogical-datapath\fR] [\fIlflow\fR...]"
 164 List logical flows.  If \fIlogical-datapath\fR is specified, only list
 165 flows for that logical datapath.  The \fIlogical-datapath\fR may be
 166 given as a UUID or as a datapath name (reporting an error if multiple
 167 datapaths have the same name).
 168 .IP
 169 If at least one \fIlflow\fR is given, only matching logical flows, if
 170 any, are listed.  Each \fIlflow\fR may be specified as a UUID or the
 171 first few characters of a UUID, optionally prefixed by \fB0x\fR.
 172 (Because \fBovn\-controller\fR sets OpenFlow flow cookies to the first
 173 32 bits of the corresponding logical flow's UUID, this makes it easy
 174 to look up the logical flow that generated a particular OpenFlow
 175 flow.)
 176 .IP
 177 If \fB\-\-uuid\fR is specified, the output includes the first 32 bits
 178 of each logical flow's UUID.  This makes it easier to find the
 179 OpenFlow flows that correspond to a given logical flow.
 180 .IP
 181 If \fB\-\-ovs\fR is included, \fBovn\-sbctl\fR attempts to obtain and
 182 display the OpenFlow flows that correspond to each OVN logical flow.
 183 To do so, \fBovn\-sbctl\fR connects to \fIremote\fR (by default,
 184 \fBunix:@RUNDIR@/br-int.mgmt\fR) over OpenFlow and retrieves the
 185 flows.  If \fIremote\fR is specified, it must be an active OpenFlow
 186 connection method described in \fBovs\-ofctl\fR(8).  Please see the
 187 discussion of the similar \fB\-\-ovs\fR option in \fBovn-trace\fR(8)
 188 for more information about the OpenFlow flow output.
 189 .IP
 190 By default, OpenFlow flow output includes only match and actions.  Add
 191 \fB\-\-stats\fR to include all OpenFlow information, such as packet
 192 and byte counters, duration, and timeouts.
 193 .
 194 .IP "[\fB\-\-uuid\fR] \fBdump\-flows\fR [\fIlogical-datapath\fR]"
 195 Alias for \fBlflow\-list\fB.
 196 .
 197 .SS "Remote Connectivity Commands"
 198 .
 199 These commands manipulate the \fBconnections\fR column in the \fBSB_Global\fR
 200 table and rows in the \fBConnection\fR table.  When \fBovsdb\-server\fR
 201 is configured to use the \fBconnections\fR column for OVSDB connections,
 202 this allows the administrator to use \fBovn\-sbctl\fR to configure database
 203 connections.
 204 .
 205 .IP "\fBget\-connection\fR"
 206 Prints the configured connection(s).
 207 .
 208 .IP "\fBdel\-connection\fR"
 209 Deletes the configured connection(s).
 210 .
 211 .IP "\fBset\-connection\fR [\fIaccess\-specifier\fR] \fItarget\fR\&..."
 212 Sets the configured manager target or targets.  Each \fItarget\fR may
 213 be preceded by an optional access-specifier (\fBread\-only\fR or
 214 \fBread\-write\fR) and may use any of the following forms:
 215 .
 216 .RS
 217 .so ovsdb/remote-active.man
 218 .so ovsdb/remote-passive.man
 219 .RE
 220
 221 If provided, the effect of the access specifier persists for subsequent
 222 targets until changed by another access specifier.
 223 .
 224 .SS "SSL Configuration"
 225 When \fBovsdb\-server\fR is configured to connect using SSL, the
 226 following parameters are required:
 227 .TP
 228 \fIprivate-key\fR
 229 Specifies a PEM file containing the private key used for SSL connections.
 230 .TP
 231 \fIcertificate\fR
 232 Specifies a PEM file containing a certificate, signed by the
 233 certificate authority (CA) used by the connection peers, that
 234 certifies the private key, identifying a trustworthy peer.
 235 .TP
 236 \fIca-cert\fR
 237 Specifies a PEM file containing the CA certificate used to verify that
 238 the connection peers are trustworthy.
 239 .PP
 240 These SSL settings apply to all SSL connections made by the southbound
 241 database server.
 242 .
 243 .IP "\fBget\-ssl\fR"
 244 Prints the SSL configuration.
 245 .
 246 .IP "\fBdel\-ssl\fR"
 247 Deletes the current SSL configuration.
 248 .
 249 .IP "[\fB\-\-bootstrap\fR] \fBset\-ssl\fR \fIprivate-key\fR \fIcertificate\fR \fIca-cert\fR"
 250 Sets the SSL configuration.  The \fB\-\-bootstrap\fR option is described
 251 below.
 252 .
 253 .ST "CA Certificate Bootstrap"
 254 .PP
 255 Ordinarily, all of the files named in the SSL configuration must exist
 256 before SSL connectivity can be used.  However, if the \fIca-cert\fR file
 257 does not exist and the \fB\-\-bootstrap\fR
 258 option is given, then \fBovsdb\-server\fR will attempt to obtain the
 259 CA certificate from the target on its first SSL connection and
 260 save it to the named PEM file.  If it is successful, it will
 261 immediately drop the connection and reconnect, and from then on all
 262 SSL connections must be authenticated by a certificate signed by the
 263 CA certificate thus obtained.
 264 .PP
 265 \fBThis option exposes the SSL connection to a man-in-the-middle
 266 attack obtaining the initial CA certificate\fR, but it may be useful
 267 for bootstrapping.
 268 .PP
 269 This option is only useful if the SSL peer sends its CA certificate
 270 as part of the SSL certificate chain.  The SSL protocol does not
 271 require the controller to send the CA certificate.
 272 .
 273 .SS "Database Commands"
 274 .
 275 These commands query and modify the contents of \fBovsdb\fR tables.
 276 They are a slight abstraction of the \fBovsdb\fR interface and as such
 277 they operate at a lower level than other \fBovs\-sbctl\fR commands.
 278 .PP
 279 .ST "Identifying Tables, Records, and Columns"
 280 .PP
 281 Each of these commands has a \fItable\fR parameter to identify a table
 282 within the database.  Many of them also take a \fIrecord\fR parameter
 283 that identifies a particular record within a table.  The \fIrecord\fR
 284 parameter may be the UUID for a record, and many tables offer
 285 additional ways to identify records.  Some commands also take
 286 \fIcolumn\fR parameters that identify a particular field within the
 287 records in a table.
 288 .\" It would be kind to list all the tables and their supported identifiers
 289 .\" here.
 290 .PP
 291 Record names must be specified in full and with correct
 292 capitalization, except that UUIDs may be abbreviated to their first 4
 293 (or more) hex digits, as long as that is unique within the table.
 294 Names of tables and columns are not case-sensitive, and \fB\-\fR and
 295 \fB_\fR are treated interchangeably.  Unique abbreviations of table
 296 and column names are acceptable, e.g. \fBaddr\fR or \fBa\fR is
 297 sufficient to identify the \fBAddress_Set\fR table.
 298 .
 299 .so lib/db-ctl-base.man
 300 .SH "EXIT STATUS"
 301 .IP "0"
 302 Successful program execution.
 303 .IP "1"
 304 Usage, syntax, or configuration file error.
 305 .SH "SEE ALSO"
 306 .
 307 .BR ovn\-sb (5).