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 [\fIoptions\fR]
  31 \fBload\-kmod\fR
  32 .br
  33 \fBovs\-ctl
  34 \fB\-\-system\-id=random\fR|\fIuuid\fR
  35 [\fIoptions\fR]
  36 \fBforce\-reload\-kmod\fR
  37 .br
  38 \fBovs\-ctl
  39 \fR[\fB\-\-protocol=\fIprotocol\fR]
  40 [\fB\-\-sport=\fIsport\fR]
  41 [\fB\-\-dport=\fIdport\fR]
  42 \fBenable\-protocol\fR
  43 .br
  44 \fBovs\-ctl help \fR| \fB\-h \fR| \fB\-\-help
  45 .br
  46 \fBovs\-ctl \-\-version
  47 .
  48 .SH DESCRIPTION
  49 .
  50 .PP
  51 The \fBovs\-ctl\fR program starts, stops, and checks the status of
  52 Open vSwitch daemons.  It is not meant to be invoked directly by
  53 system administrators but to be called internally by system startup
  54 scripts.
  55 .
  56 .PP
  57 Each of \fBovs\-ctl\fR's commands is described separately below.
  58 .
  59 .SH "The ``start'' command"
  60 .
  61 .PP
  62 The \fBstart\fR command starts Open vSwitch.  It performs the
  63 following tasks:
  64 .
  65 .IP 1.
  66 Loads the Open vSwitch kernel module.  If this fails, and the Linux
  67 bridge module is loaded but no bridges exist, it tries to unload the
  68 bridge module and tries loading the Open vSwitch kernel module again.
  69 (This is because the Open vSwitch kernel module cannot coexist with
  70 the Linux bridge module before 2.6.37.)
  71 .
  72 .IP 2.
  73 If \fB\-\-brcompat\fR was specified, loads the Open vSwitch bridge
  74 compatibility module.
  75 .
  76 .PP
  77 The \fBstart\fR command skips the following steps if
  78 \fBovsdb\-server\fR is already running:
  79 .IP 3.
  80 If the Open vSwitch database file does not exist, it creates it.
  81 If the database does exist, but it has an obsolete version, it
  82 upgrades it to the latest schema.
  83 .
  84 .IP 4.
  85 Starts \fBovsdb-server\fR.
  86 .
  87 .IP 5.
  88 Initializes a few values inside the database.
  89 .
  90 .IP 6.
  91 If the \fB\-\-delete\-bridges\fR option was used, deletes all of the
  92 bridges from the database.
  93 .
  94 .PP
  95 The \fBstart\fR command skips the following step if
  96 \fBovs\-vswitchd\fR is already running:
  97 .IP 7.
  98 Starts \fBovs\-vswitchd\fR.
  99 .
 100 .PP
 101 The \fBstart\fR command skips the following step if
 102 \fBovs\-brcompatd\fR is already running or if \fB\-\-brcompat\fR is
 103 not specified:
 104 .IP 8.
 105 Starts \fBovs\-brcompatd\fR.
 106 .
 107 .SS "Options"
 108 .PP
 109 Several command-line options influence the \fBstart\fR command's
 110 behavior.  Some form of the following option should ordinarily be
 111 specified:
 112 .
 113 .IP "\fB\-\-system\-id=\fIuuid\fR"
 114 .IQ "\fB\-\-system\-id=random\fR"
 115 This specifies a unique system identifier to store into
 116 \fBexternal-ids:system-id\fR in the database's \fBOpen_vSwitch\fR
 117 table.  Remote managers that talk to the Open vSwitch database server
 118 over network protocols use this value to identify and distinguish Open
 119 vSwitch instances, so it should be unique (at least) within OVS
 120 instances that will connect to a single controller.
 121 .IP
 122 When \fBrandom\fR is specified, \fBovs\-ctl\fR will generate a random
 123 ID that persists from one run to another (stored in a file).  When
 124 another string is specified \fBovs\-ctl\fR uses it literally.
 125 .
 126 .PP
 127 The following options should be specified if the defaults are not
 128 suitable:
 129 .
 130 .IP "\fB\-\-system\-type=\fItype\fR"
 131 .IQ "\fB\-\-system\-version=\fIversion\fR"
 132 Sets the value to store in the \fBsystem-type\fR and
 133 \fBsystem-version\fR columns, respectively, in the database's
 134 \fBOpen_vSwitch\fR table.  Remote managers may use these values to
 135 determine the kind of system to which they are connected (primarily
 136 for display to human administrators).
 137 .IP
 138 When not specified, \fBovs\-ctl\fR uses values from the optional
 139 \fBsystem\-type.conf\fR and \fBsystem\-version.conf\fR files(see section
 140 \fBFILES\fR) or it uses the \fBlsb_release\fR program, if present, to
 141 provide reasonable defaults.
 142 .
 143 .PP
 144 The following options are also likely to be useful:
 145 .
 146 .IP "\fB\-\-external\-id=\(dq\fIname\fB=\fIvalue\fB\(dq"
 147 Sets \fBexternal-ids:\fIname\fR to \fIvalue\fR in the database's
 148 \fBOpen_vSwitch\fR table.  Specifying this option multiple times adds
 149 multiple key-value pairs.
 150 .
 151 .IP "\fB\-\-delete\-bridges\fR"
 152 Ordinarily Open vSwitch bridges persist from one system boot to the
 153 next, as long as the database is preserved.  Some environments instead
 154 expect to re-create all of the bridges and other configuration state
 155 on every boot.  This option supports that, by deleting all Open
 156 vSwitch bridges after starting \fBovsdb\-server\fR but before starting
 157 \fBovs\-vswitchd\fR.
 158 .
 159 .PP
 160 The following options are less important:
 161 .
 162 .IP "\fB\-\-daemon-cwd=\fIdirectory\fR"
 163 Specifies the current working directory that the OVS daemons should
 164 run from.  The default is \fB/\fR (the root directory) if this option
 165 is not specified.  (This option is useful because most systems create
 166 core files in a process's current working directory and because a file
 167 system that is in use as a process's current working directory cannot
 168 be unmounted.)
 169 .
 170 .IP "\fB\-\-no\-force\-corefiles\fR"
 171 By default, \fBovs\-ctl\fR enables core dumps for the OVS daemons.
 172 This option disables that behavior.
 173 .
 174 .IP "\fB\-\-no\-mlockall\fR"
 175 By default \fBovs\-ctl\fR passes \fB\-\-mlockall\fR to
 176 \fBovs\-vswitchd\fR, requesting that it lock all of its virtual
 177 memory, preventing it from being paged to disk.  This option
 178 suppresses that behavior.
 179 .
 180 .IP "\fB\-\-ovsdb\-server\-priority=\fIniceness\fR"
 181 .IQ "\fB\-\-ovs\-vswitchd\-priority=\fIniceness\fR"
 182 .IQ "\fB\-\-ovs\-brcompatd\-priority=\fIniceness\fR"
 183 Sets the \fBnice\fR(1) level used for each daemon.  All of them
 184 default to \fB\-10\fR.
 185 .
 186 .IP "\fB\-\-ovsdb\-server\-wrapper=\fIwrapper\fR"
 187 .IQ "\fB\-\-ovs\-vswitchd\-wrapper=\fIwrapper\fR"
 188 .IQ "\fB\-\-ovs\-brcompatd\-wrapper=\fIwrapper\fR"
 189 .
 190 Configures the specified daemon to run under \fIwrapper\fR, which is
 191 one of the following:
 192 .
 193 .RS
 194 .IP "\fBvalgrind\fR"
 195 Run the daemon under \fBvalgrind\fR(1), if it is installed, logging to
 196 \fIdaemon\fB.valgrind.log.\fIpid\fR in the log directory.
 197 .
 198 .IP "\fBstrace\fR"
 199 Run the daemon under \fBstrace\fR(1), if it is installed, logging to
 200 \fIdaemon\fB.strace.log.\fIpid\fR in the log directory.
 201 .
 202 .IP "\fBglibc\fR"
 203 Enable GNU C library features designed to find memory errors.
 204 .RE
 205 .
 206 .IP
 207 By default, no wrapper is used.
 208 .
 209 .IP
 210 Each of the wrappers can expose bugs in Open vSwitch that lead to
 211 incorrect operation, including crashes.  The \fBvalgring\fR and
 212 \fBstrace\fR wrappers greatly slow daemon operations so they should
 213 not be used in production.  They also produce voluminous logs that can
 214 quickly fill small disk partitions.  The \fBglibc\fR wrapper is less
 215 resource-intensive but still somewhat slows the daemons.
 216 .
 217 .PP
 218 The following options control file locations.  They should only be
 219 used if the default locations cannot be used.  See \fBFILES\fR, below,
 220 for more information.
 221 .
 222 .IP "\fB\-\-db\-file=\fIfile\fR"
 223 Overrides the file name for the OVS database.
 224 .
 225 .IP "\fB\-\-db\-sock=\fIsocket\fR"
 226 Overrides the file name for the Unix domain socket used to connect to
 227 \fBovsdb\-server\fR.
 228 .
 229 .IP "\fB\-\-db\-schema=\fIschema\fR"
 230 Overrides the file name for the OVS database schema.
 231 .
 232 .IP "\fB\-\-extra-dbs=\fIfile\fR"
 233 Adds \fIfile\fR as an extra database for \fBovsdb\-server\fR to serve
 234 out.  Multiple space-separated file names may also be specified.
 235 \fIfile\fR should begin with \fB/\fR; if it does not, then it will be
 236 taken as relative to \fIdbdir\fR.
 237 .
 238 .SH "The ``stop'' command"
 239 .
 240 .PP
 241 The \fBstop\fR command shuts down Open vSwitch.  It kills any running
 242 \fBovs\-brcompatd\fR, \fBovs\-vswitchd\fR, or \fBovsdb\-server\fR
 243 daemons and waits for them to terminate.
 244 .
 245 .PP
 246 The \fBstop\fR command does not unload the Open vSwitch kernel
 247 modules.
 248 .
 249 .PP
 250 This command does nothing and finishes successfully if the OVS daemons
 251 aren't running.
 252 .
 253 .SH "The ``restart'' command"
 254 .
 255 .PP
 256 The \fBrestart\fR command performs a \fBstop\fR followed by a \fBstart\fR
 257 command.  The command can take the same options as that of the \fBstart\fR
 258 command. In addition, it saves and restores Openflow flows for each
 259 individual bridge.
 260 .
 261 .SH "The ``status'' command"
 262 .
 263 .PP
 264 The \fBstatus\fR command checks whether the OVS daemons
 265 \fBovs-vswitchd\fR and \fBovsdb\-server\fR are running and prints
 266 messages with that information.  If \fB\-\-brcompat\fR is specified,
 267 it also checks for \fBovs\-brcompatd\fR.  It exits with status 0 if
 268 the daemons are running, 1 otherwise.
 269 .
 270 .SH "The ``version'' command"
 271 .
 272 .PP
 273 The \fBversion\fR command runs \fBovsdb\-server \-\-version\fR and
 274 \fBovs\-vswitchd \-\-version\fR.  If \fB\-\-brcompat\fR is specified,
 275 it also runs \fBovs\-brcompatd \-\-version\fR.
 276 .
 277 .SH "The ``force\-reload\-kmod'' command"
 278 .
 279 .PP
 280 The \fBforce\-reload\-kmod\fR command allows upgrading the Open
 281 vSwitch kernel module without rebooting.  It performs the following
 282 tasks:
 283 .
 284 .IP 1.
 285 Gets a list of OVS ``internal'' interfaces, that is, network devices
 286 implemented by Open vSwitch.  The most common examples of these are
 287 bridge ``local ports''.
 288 .
 289 .IP 2.
 290 Saves the Openflow flows of each bridge.
 291 .
 292 .IP 3.
 293 Stops the Open vSwitch daemons, as if by a call to \fBovs\-ctl
 294 stop\fR.
 295 .
 296 .IP 4.
 297 Saves the kernel configuration state of the OVS internal interfaces
 298 listed in step 1, including IP and IPv6 addresses and routing table
 299 entries.
 300 .
 301 .IP 5.
 302 Unloads the Open vSwitch kernel module (including the bridge
 303 compatibility module if it is loaded).
 304 .
 305 .IP 6.
 306 Starts OVS back up, as if by a call to \fBovs\-ctl start\fR.  This
 307 reloads the kernel module, restarts the OVS daemons (including
 308 \fBovs\-brcompatd\fR, if \fB\-\-brcompat\fR is specified) and finally
 309 restores the saved Openflow flows.
 310 .
 311 .IP 7.
 312 Restores the kernel configuration state that was saved in step 4.
 313 .
 314 .IP 8.
 315 Checks for daemons that may need to be restarted because they have
 316 packet sockets that are listening on old instances of Open vSwitch
 317 kernel interfaces and, if it finds any, prints a warning on stdout.
 318 DHCP is a common example: if the ISC DHCP client is running on an OVS
 319 internal interface, then it will have to be restarted after completing
 320 the above procedure.  (It would be nice if \fBovs\-ctl\fR could restart
 321 daemons automatically, but the details are far too specific to a
 322 particular distribution and installation.)
 323 .
 324 .PP
 325 \fBforce\-kmod\-reload\fR internally stops and starts OVS, so it
 326 accepts all of the options accepted by the \fBstart\fR command.
 327 .
 328 .SH "The ``load\-kmod'' command"
 329 .
 330 .PP
 331 The \fBload\-kmod\fR command loads the openvswitch kernel modules if
 332 they are not already loaded. This operation also occurs as part of
 333 the \fBstart\fR command. The motivation for providing the \fBload\-kmod\fR
 334 command is to allow errors when loading modules to be handled separatetly
 335 from other errors that may occur when running the \fBstart\fR command.
 336 .
 337 .PP
 338 By default the \fBload\-kmod\fR command attempts to load the
 339 openvswitch kernel module. If the \fB\-\-brcompat\fR option is
 340 specified then the brcompat kernel module is also loaded.
 341 .
 342 .SH "The ``enable\-protocol'' command"
 343 .
 344 .PP
 345 The \fBenable\-protocol\fR command checks for rules related to a
 346 specified protocol in the system's \fBiptables\fR(8) configuration.  If there
 347 are no rules specifically related to that protocol, then it inserts a
 348 rule to accept the specified protocol.
 349 .
 350 .PP
 351 More specifically:
 352 .
 353 .IP \(bu
 354 If \fBiptables\fR is not installed or not enabled, this command does
 355 nothing, assuming that lack of filtering means that the protocol is
 356 enabled.
 357 .
 358 .IP \(bu
 359 If the \fBINPUT\fR chain has a rule that matches the specified
 360 protocol, then this command does nothing, assuming that whatever rule
 361 is installed reflects the system administrator's decisions.
 362 .
 363 .IP \(bu
 364 Otherwise, this command installs a rule that accepts traffic of the
 365 specified protocol.
 366 .
 367 .PP
 368 This command normally completes successfully, even if it does
 369 nothing.  Only the failure of an attempt to insert a rule normally
 370 causes it to return an exit code other than 0.
 371 .
 372 The following options control the protocol to be enabled:
 373 .
 374 .IP "\fB\-\-protocol=\fIprotocol\fR"
 375 The name of the IP protocol to be enabled, such as \fBgre\fR or
 376 \fBtcp\fR.  The default is \fBgre\fR.
 377 .
 378 .IP "\fB\-\-sport=\fIsport\fR"
 379 .IQ "\fB\-\-dport=\fIdport\fR"
 380 TCP or UDP source or destination port to match.  These are optional
 381 and allowed only with \fB\-\-protocol=tcp\fR or
 382 \fB\-\-protocol=udp\fR.
 383 .
 384 .SH "The ``help'' command"
 385 .
 386 Prints a usage message and exits successfully.
 387 .
 388 .SH "OPTIONS"
 389 .PP
 390 In addition to the options listed for each command above, this option
 391 controls the behavior of several of \fBovs\-ctl\fR's commands.
 392 .
 393 .IP "\fB\-\-brcompat\fR"
 394 By default, \fBovs\-ctl\fR does not load the Open vSwitch bridge
 395 compatibility module and does not start or check the status or report
 396 the version of the \fBovs\-brcompatd\fR daemon.  This option enables
 397 all of those behaviors.
 398 .
 399 .IP
 400 The \fBstop\fR command always stops \fBovs\-brcompatd\fR, if it is
 401 running, regardless of this option.
 402 .
 403 .SH "EXIT STATUS"
 404 .
 405 \fBovs\-ctl\fR exits with status 0 on success and nonzero on failure.
 406 The \fBstart\fR command is considered to succeed if OVS is already
 407 started; the \fBstop\fR command is considered to succeed if OVS is
 408 already stopped.
 409 .
 410 .SH "ENVIRONMENT"
 411 .
 412 The following environment variables affect \fBovs\-ctl\fR:
 413 .
 414 .IP "\fBPATH\fR"
 415 \fBovs\-ctl\fR does not hardcode the location of any of the programs
 416 that it runs.  \fBovs\-ctl\fR will add the \fIsbindir\fR and
 417 \fIbindir\fR that were specified at \fBconfigure\fR time to
 418 \fBPATH\fR, if they are not already present.
 419 .
 420 .IP "\fBOVS_LOGDIR\fR"
 421 .IQ "\fBOVS_RUNDIR\fR"
 422 .IQ "\fBOVS_DBDIR\fR"
 423 .IQ "\fBOVS_SYSCONFDIR\fR"
 424 .IQ "\fBOVS_PKGDATADIR\fR"
 425 .IQ "\fBOVS_BINDIR\fR"
 426 .IQ "\fBOVS_SBINDIR\fR"
 427 Setting one of these variables in the environment overrides the
 428 respective \fBconfigure\fR option, both for \fBovs\-ctl\fR itself and
 429 for the other Open vSwitch programs that it runs.
 430 .
 431 .SH "FILES"
 432 .
 433 \fBovs\-ctl\fR uses the following files:
 434 .
 435 .IP "\fBovs\-lib.sh"
 436 Shell function library used internally by \fBovs\-ctl\fR.  It must be
 437 installed in the same directory as \fBovs\-ctl\fR.
 438 .
 439 .IP "\fIlogdir\fB/\fIdaemon\fB.log\fR"
 440 Per-daemon logfiles.
 441 .
 442 .IP "\fIrundir\fB/\fIdaemon\fB.pid\fR"
 443 Per-daemon pidfiles to track whether a daemon is running and with what
 444 process ID.
 445 .
 446 .IP "\fIpkgdatadir\fB/vswitch.ovsschema\fR"
 447 The OVS database schema used to initialize the database (use
 448 \fB\-\-db\-schema to override this location).
 449 .
 450 .IP "\fIdbdir\fB/conf.db\fR"
 451 The OVS database (use \fB\-\-db\-file\fR to override this location).
 452 .
 453 .IP "\fIrundir\fB/openvswitch/db.sock\fR"
 454 The Unix domain socket used for local communication with
 455 \fBovsdb\-server\fR (use \fB\-\-db\-sock\fR to override this
 456 location).
 457 .
 458 .IP "\fIsysconfdir\fB/openvswitch/system-id.conf\fR"
 459 The persistent system UUID created and read by
 460 \fB\-\-system\-id=random\fR.
 461 .
 462 .IP "\fIsysconfdir\fB/openvswitch/system\-type.conf\fR"
 463 .IQ "\fIsysconfdir\fB/openvswitch/system\-version.conf\fR"
 464 The \fBsystem\-type\fR  and \fBsystem\-version\fR values stored in the database's
 465 \fBOpen_vSwitch\fR table when not specified as a command-line option.
 466 .
 467 .SH "EXAMPLE"
 468 .
 469 .PP
 470 The files \fBdebian/openvswitch\-switch.init\fR and
 471 \fBxenserver/etc_init.d_openvswitch\fR in the Open vSwitch source
 472 distribution are good examples of how to use \fBovs\-ctl\fR.
 473 .
 474 .SH "SEE ALSO"
 475 .
 476 \fBREADME\fR, \fBINSTALL.Linux\fR, \fBovsdb\-server\fR(8),
 477 \fBovs\-vswitchd\fR(8).