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