utilities/ovs-ctl.8

   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 ovs\-ctl 8 "June 2011" "Open vSwitch" "Open vSwitch Manual"
  14 .ds PN ovs\-ctl
  15 .
  16 .SH NAME
  17 ovs\-ctl \- OVS startup helper script
  18 .
  19 .SH SYNOPSIS
  20 \fBovs\-ctl\fR \fB\-\-system\-id=random\fR|\fIuuid\fR
  21 [\fIoptions\fR] \fBstart
  22 .br
  23 \fBovs\-ctl stop
  24 .br
  25 \fBovs\-ctl status
  26 .br
  27 \fBovs\-ctl version
  28 .br
  29 \fBovs\-ctl
  30 \fB\-\-system\-id=random\fR|\fIuuid\fR
  31 [\fIoptions\fR]
  32 \fBforce\-reload\-kmod\fR
  33 .br
  34 \fBovs\-ctl
  35 \fR[\fB\-\-protocol=\fIprotocol\fR]
  36 [\fB\-\-sport=\fIsport\fR]
  37 [\fB\-\-dport=\fIdport\fR]
  38 \fBenable\-protocol\fR
  39 .br
  40 \fBovs\-ctl help \fR| \fB\-h \fR| \fB\-\-help
  41 .br
  42 \fBovs\-ctl \-\-version
  43 .
  44 .SH DESCRIPTION
  45 .
  46 .PP
  47 The \fBovs\-ctl\fR program starts, stops, and checks the status of
  48 Open vSwitch daemons.  It is not meant to be invoked directly by
  49 system administrators but to be called internally by system startup
  50 scripts.
  51 .
  52 .PP
  53 Each of \fBovs\-ctl\fR's commands is described separately below.
  54 .
  55 .SH "The ``start'' command"
  56 .
  57 .PP
  58 The \fBstart\fR command starts Open vSwitch.  It performs the
  59 following tasks:
  60 .
  61 .IP 1.
  62 Loads the Open vSwitch kernel module.  If this fails, and the Linux
  63 bridge module is loaded but no bridges exist, it tries to unload the
  64 bridge module and tries loading the Open vSwitch kernel module again.
  65 (This is because the Open vSwitch kernel module cannot coexist with
  66 the Linux bridge module before 2.6.37.)
  67 .
  68 .IP 2.
  69 If \fB\-\-brcompat\fR was specified, loads the Open vSwitch bridge
  70 compatibility module.
  71 .
  72 .PP
  73 The \fBstart\fR command skips the following steps if
  74 \fBovsdb\-server\fR is already running:
  75 .IP 3.
  76 If the Open vSwitch database file does not exist, it creates it.
  77 If the database does exist, but it has an obsolete version, it
  78 upgrades it to the latest schema.
  79 .
  80 .IP 4.
  81 Starts \fBovsdb-server\fR.
  82 .
  83 .IP 5.
  84 Initializes a few values inside the database.
  85 .
  86 .IP 6.
  87 If the \fB\-\-delete\-bridges\fR option was used, deletes all of the
  88 bridges from the database.
  89 .
  90 .PP
  91 The \fBstart\fR command skips the following step if
  92 \fBovs\-vswitchd\fR is already running:
  93 .IP 7.
  94 Starts \fBovs\-vswitchd\fR.
  95 .
  96 .PP
  97 The \fBstart\fR command skips the following step if
  98 \fBovs\-brcompatd\fR is already running or if \fB\-\-brcompat\fR is
  99 not specified:
 100 .IP 8.
 101 Starts \fBovs\-brcompatd\fR.
 102 .
 103 .SS "Options"
 104 .PP
 105 Several command-line options influence the \fBstart\fR command's
 106 behavior.  Some form of the following option should ordinarily be
 107 specified:
 108 .
 109 .IP "\fB\-\-system\-id=\fIuuid\fR"
 110 .IQ "\fB\-\-system\-id=random\fR"
 111 This specifies a unique system identifier to store into
 112 \fBexternal-ids:system-id\fR in the database's \fBOpen_vSwitch\fR
 113 table.  Remote managers that talk to the Open vSwitch database server
 114 over network protocols use this value to identify and distinguish Open
 115 vSwitch instances, so it should be unique (at least) within OVS
 116 instances that will connect to a single controller.
 117 .IP
 118 When \fBrandom\fR is specified, \fBovs\-ctl\fR will generate a random
 119 ID that persists from one run to another (stored in a file).  When
 120 another string is specified \fBovs\-ctl\fR uses it literally.
 121 .
 122 .PP
 123 On systems that have the \fBlsb_release\fR program, \fBovs\-ctl\fR
 124 chooses reasonable defaults for the following options.  Other systems
 125 should specify values:
 126 .
 127 .IP "\fB\-\-system\-type=\fItype\fR"
 128 .IQ "\fB\-\-system\-version=\fIversion\fR"
 129 Sets the value to store in the \fBsystem-type\fR and
 130 \fBsystem-version\fR columns, respectively, in the database's
 131 \fBOpen_vSwitch\fR table.  Remote managers may use these values to
 132 determine the kind of system to which they are connected (primarily
 133 for display to human administrators).
 134 .
 135 .PP
 136 The following options are also likely to be useful:
 137 .
 138 .IP "\fB\-\-external\-id=\(dq\fIname\fB=\fIvalue\fB\(dq"
 139 Sets \fBexternal-ids:\fIname\fR to \fIvalue\fR in the database's
 140 \fBOpen_vSwitch\fR table.  Specifying this option multiple times adds
 141 multiple key-value pairs.
 142 .
 143 .IP "\fB\-\-delete\-bridges\fR"
 144 Ordinarily Open vSwitch bridges persist from one system boot to the
 145 next, as long as the database is preserved.  Some environments instead
 146 expect to re-create all of the bridges and other configuration state
 147 on every boot.  This option supports that, by deleting all Open
 148 vSwitch bridges after starting \fBovsdb\-server\fR but before starting
 149 \fBovs\-vswitchd\fR.
 150 .
 151 .PP
 152 The following options are less important:
 153 .
 154 .IP "\fB\-\-daemon-cwd=\fIdirectory\fR"
 155 Specifies the current working directory that the OVS daemons should
 156 run from.  The default is \fB/\fR (the root directory) if this option
 157 is not specified.  (This option is useful because most systems create
 158 core files in a process's current working directory and because a file
 159 system that is in use as a process's current working directory cannot
 160 be unmounted.)
 161 .
 162 .IP "\fB\-\-no\-force\-corefiles\fR"
 163 By default, \fBovs\-ctl\fR enables core dumps for the OVS daemons.
 164 This option disables that behavior.
 165 .
 166 .IP "\fB\-\-no\-mlockall\fR"
 167 By default \fBovs\-ctl\fR passes \fB\-\-mlockall\fR to
 168 \fBovs\-vswitchd\fR, requesting that it lock all of its virtual
 169 memory, preventing it from being paged to disk.  This option
 170 suppresses that behavior.
 171 .
 172 .IP "\fB\-\-ovsdb\-server\-priority=\fIniceness\fR"
 173 .IQ "\fB\-\-ovs\-vswitchd\-priority=\fIniceness\fR"
 174 Sets the \fBnice\fR(1) level used for \fBovsdb\-server\fR and
 175 \fBovs\-vswitchd\fR, respectively.  Both default to \fB\-10\fR.
 176 .
 177 .PP
 178 The following options control file locations.  They should only be
 179 used if the default locations cannot be used.  See \fBFILES\fR, below,
 180 for more information.
 181 .
 182 .IP "\fB\-\-db\-file=\fIfile\fR"
 183 Overrides the file name for the OVS database.
 184 .
 185 .IP "\fB\-\-db\-sock=\fIsocket\fR"
 186 Overrides the file name for the Unix domain socket used to connect to
 187 \fBovsdb\-server\fR.
 188 .
 189 .IP "\fB\-\-db\-schema=\fIschema\fR"
 190 Overrides the file name for the OVS database schema.
 191 .
 192 .SH "The ``stop'' command"
 193 .
 194 .PP
 195 The \fBstop\fR command shuts down Open vSwitch.  It kills any running
 196 \fBovs\-brcompatd\fR, \fBovs\-vswitchd\fR, or \fBovsdb\-server\fR
 197 daemons and waits for them to terminate.
 198 .
 199 .PP
 200 The \fBstop\fR command does not unload the Open vSwitch kernel
 201 modules.
 202 .
 203 .PP
 204 This command does nothing and finishes successfully if the OVS daemons
 205 aren't running.
 206 .
 207 .SH "The ``status'' command"
 208 .
 209 .PP
 210 The \fBstatus\fR command checks whether the OVS daemons
 211 \fBovs-vswitchd\fR and \fBovsdb\-server\fR are running and prints
 212 messages with that information.  If \fB\-\-brcompat\fR is specified,
 213 it also checks for \fBovs\-brcompatd\fR.  It exits with status 0 if
 214 the daemons are running, 1 otherwise.
 215 .
 216 .SH "The ``version'' command"
 217 .
 218 .PP
 219 The \fBversion\fR command runs \fBovsdb\-server \-\-version\fR and
 220 \fBovs\-vswitchd \-\-version\fR.  If \fB\-\-brcompat\fR is specified,
 221 it also runs \fBovs\-brcompatd \-\-version\fR.
 222 .
 223 .SH "The ``force\-reload\-kmod'' command"
 224 .
 225 .PP
 226 The \fBforce\-reload\-kmod\fR command allows upgrading the Open
 227 vSwitch kernel module without rebooting.  It performs the following
 228 tasks:
 229 .
 230 .IP 1.
 231 Gets a list of OVS ``internal'' interfaces, that is, network devices
 232 implemented by Open vSwitch.  The most common examples of these are
 233 bridge ``local ports''.
 234 .
 235 .IP 2.
 236 Stops the Open vSwitch daemons, as if by a call to \fBovs\-ctl
 237 stop\fR.
 238 .
 239 .IP 3.
 240 Saves the kernel configuration state of the OVS internal interfaces
 241 listed in step 1, including IP and IPv6 addresses and routing table
 242 entries.
 243 .
 244 .IP 4.
 245 Unloads the Open vSwitch kernel module (including the bridge
 246 compatibility module if it is loaded).
 247 .
 248 .IP 5.
 249 Starts OVS back up, as if by a call to \fBovs\-ctl start\fR.  This
 250 reloads the kernel module and restarts the OVS daemons (including
 251 \fBovs\-brcompatd\fR, if \fB\-\-brcompat\fR is specified).
 252 .
 253 .IP 6.
 254 Restores the kernel configuration state that was saved in step 3.
 255 .
 256 .PP
 257 The steps above are often enough to hot-upgrade a new kernel module
 258 with only a few seconds of downtime.  DHCP is a common problem: if the
 259 ISC DHCP client is running on an OVS internal interface, then it will
 260 have to be restarted after completing the above procedure.
 261 .
 262 .PP
 263 \fBforce\-kmod\-reload\fR internally stops and starts OVS, so it
 264 accepts all of the options accepted by the \fBstart\fR command.
 265 .
 266 .SH "The ``enable\-protocol'' command"
 267 .
 268 .PP
 269 The \fBenable\-protocol\fR command checks for rules related to a
 270 specified protocol in the system's \fBiptables\fR(8) configuration.  If there
 271 are no rules specifically related to that protocol, then it inserts a
 272 rule to accept the specified protocol.
 273 .
 274 .PP
 275 More specifically:
 276 .
 277 .IP \(bu
 278 If \fBiptables\fR is not installed or not enabled, this command does
 279 nothing, assuming that lack of filtering means that the protocol is
 280 enabled.
 281 .
 282 .IP \(bu
 283 If the \fBINPUT\fR chain has a rule that matches the specified
 284 protocol, then this command does nothing, assuming that whatever rule
 285 is installed reflects the system administrator's decisions.
 286 .
 287 .IP \(bu
 288 Otherwise, this command installs a rule that accepts traffic of the
 289 specified protocol.
 290 .
 291 .PP
 292 This command normally completes successfully, even if it does
 293 nothing.  Only the failure of an attempt to insert a rule normally
 294 causes it to return an exit code other than 0.
 295 .
 296 The following options control the protocol to be enabled:
 297 .
 298 .IP "\fB\-\-protocol=\fIprotocol\fR"
 299 The name of the IP protocol to be enabled, such as \fBgre\fR or
 300 \fBtcp\fR.  The default is \fBgre\fR.
 301 .
 302 .IP "\fB\-\-sport=\fIsport\fR"
 303 .IQ "\fB\-\-dport=\fIdport\fR"
 304 TCP or UDP source or destination port to match.  These are optional
 305 and allowed only with \fB\-\-protocol=tcp\fR or
 306 \fB\-\-protocol=udp\fR.
 307 .
 308 .SH "The ``help'' command"
 309 .
 310 Prints a usage message and exits successfully.
 311 .
 312 .SH "OPTIONS"
 313 .PP
 314 In addition to the options listed for each command above, this option
 315 controls the behavior of several of \fBovs\-ctl\fR's commands.
 316 .
 317 .IP "\fB\-\-brcompat\fR"
 318 By default, \fBovs\-ctl\fR does not load the Open vSwitch bridge
 319 compatibility module and does not start or check the status or report
 320 the version of the \fBovs\-brcompatd\fR daemon.  This option enables
 321 all of those behaviors.
 322 .
 323 .IP
 324 The \fBstop\fR command always stops \fBovs\-brcompatd\fR, if it is
 325 running, regardless of this option.
 326 .
 327 .SH "EXIT STATUS"
 328 .
 329 \fBovs\-ctl\fR exits with status 0 on success and nonzero on failure.
 330 The \fBstart\fR command is considered to succeed if OVS is already
 331 started; the \fBstop\fR command is considered to succeed if OVS is
 332 already stopped.
 333 .
 334 .SH "ENVIRONMENT"
 335 .
 336 The following environment variables affect \fBovs\-ctl\fR:
 337 .
 338 .IP "\fBPATH\fR"
 339 \fBovs\-ctl\fR does not hardcode the location of any of the programs
 340 that it runs.  \fBovs\-ctl\fR will add the \fIsbindir\fR and
 341 \fIbindir\fR that were specified at \fBconfigure\fR time to
 342 \fBPATH\fR, if they are not already present.
 343 .
 344 .IP "\fBOVS_LOGDIR\fR"
 345 .IQ "\fBOVS_RUNDIR\fR"
 346 .IQ "\fBOVS_SYSCONFDIR\fR"
 347 .IQ "\fBOVS_PKGDATADIR\fR"
 348 .IQ "\fBOVS_BINDIR\fR"
 349 .IQ "\fBOVS_SBINDIR\fR"
 350 Setting one of these variables in the environment overrides the
 351 respective \fBconfigure\fR option, both for \fBovs\-ctl\fR itself and
 352 for the other Open vSwitch programs that it runs.
 353 .
 354 .SH "FILES"
 355 .
 356 \fBovs\-ctl\fR uses the following files:
 357 .
 358 .IP "\fBovs\-lib.sh"
 359 Shell function library used internally by \fBovs\-ctl\fR.  It must be
 360 installed in the same directory as \fBovs\-ctl\fR.
 361 .
 362 .IP "\fIlogdir\fB/\fIdaemon\fB.log\fR"
 363 Per-daemon logfiles.
 364 .
 365 .IP "\fIrundir\fB/\fIdaemon\fB.pid\fR"
 366 Per-daemon pidfiles to track whether a daemon is running and with what
 367 process ID.
 368 .
 369 .IP "\fIpkgdatadir\fB/vswitch.ovsschema\fR"
 370 The OVS database schema used to initialize the database (use
 371 \fB\-\-db\-schema to override this location).
 372 .
 373 .IP "\fIsysconfdir\fB/openvswitch/conf.db\fR"
 374 The OVS database (use \fB\-\-db\-file\fR to override this location).
 375 .
 376 .IP "\fIrundir\fB/openvswitch/db.sock\fR"
 377 The Unix domain socket used for local communication with
 378 \fBovsdb\-server\fR (use \fB\-\-db\-sock\fR to override this
 379 location).
 380 .
 381 .IP "\fIsysconfdir\fB/openvswitch/system-id.conf\fR"
 382 The persistent system UUID created and read by
 383 \fB\-\-system\-id=random\fR.
 384 .
 385 .SH "EXAMPLE"
 386 .
 387 .PP
 388 The files \fBdebian/openvswitch\-switch.init\fR and
 389 \fBxenserver/etc_init.d_openvswitch\fR in the Open vSwitch source
 390 distribution are good examples of how to use \fBovs\-ctl\fR.
 391 .
 392 .SH "SEE ALSO"
 393 .
 394 \fBREADME\fR, \fBINSTALL.Linux\fR, \fBovsdb\-server\fR(8),
 395 \fBovs\-vswitchd\fR(8).