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