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 "\fBshow\fR"
 112 Prints a brief overview of the database contents.
 113 .
 114 .SS "Chassis Commands"
 115 These commands manipulate \fBOVN_Southbound\fR chassis.
 116 .
 117 .IP "[\fB\-\-may\-exist\fR] \fBchassis\-add \fIchassis\fR \fIencap\-type\fR \fIencap-ip\fR"
 118 Creates a new chassis named \fIchassis\fR.  \fIencap\-type\fR is a
 119 comma-separated list of tunnel types.  The chassis will have
 120 one encap entry for each specified tunnel type with \fIencap-ip\fR
 121 as the destination IP for each.
 122 .IP
 123 Without \fB\-\-may\-exist\fR, attempting to create a chassis that
 124 exists is an error.  With \fB\-\-may\-exist\fR, this command does
 125 nothing if \fIchassis\fR already exists.
 126 .
 127 .IP "[\fB\-\-if\-exists\fR] \fBchassis\-del \fIchassis\fR"
 128 Deletes \fIchassis\fR and its \fIencaps\fR and \fIgateway_ports\fR.
 129 .IP
 130 Without \fB\-\-if\-exists\fR, attempting to delete a chassis that does
 131 not exist is an error.  With \fB\-\-if\-exists\fR, attempting to
 132 delete a chassis that does not exist has no effect.
 133 .
 134 .SS "Port binding Commands"
 135 .
 136 These commands manipulate \fBOVN_Southbound\fR port bindings.
 137 .
 138 .IP "[\fB\-\-may\-exist\fR] \fBlport\-bind \fIlogical\-port\fR \fIchassis\fR"
 139 Binds the logical port named \fIlogical\-port\fR to \fIchassis\fR.
 140 .IP
 141 Without \fB\-\-may\-exist\fR, attempting to bind a logical port that
 142 has already been bound is an error.  With \fB\-\-may\-exist\fR, this
 143 command does nothing if \fIlogical\-port\fR has already been bound to
 144 a chassis.
 145 .
 146 .IP "[\fB\-\-if\-exists\fR] \fBlport\-unbind\fR \fIlogical\-port\fR"
 147 Resets the binding of \fIlogical\-port\fR to \fINULL\fR.
 148 .IP
 149 Without \fB\-\-if\-exists\fR, attempting to unbind a logical port
 150 that is not bound is an error.  With \fB\-\-if\-exists\fR, attempting
 151 to unbind logical port that is not bound has no effect.
 152 .
 153 .SS "Logical Flow Commands"
 154 .
 155 .IP "\fBlflow\-list\fR [\fIlogical\-datapath\fR]"
 156 List logical flows. If \fIlogical\-datapath\fR is specified, only list flows for
 157 that logical datapath.
 158 .
 159 .IP "\fBdump\-flows\fR [\fIlogical\-datapath\fR]"
 160 Alias for \fBlflow\-list\fB.
 161 .
 162 .so lib/db-ctl-base.man
 163 .SH "EXIT STATUS"
 164 .IP "0"
 165 Successful program execution.
 166 .IP "1"
 167 Usage, syntax, or configuration file error.
 168 .SH "SEE ALSO"
 169 .
 170 .BR ovn\-sb (5).