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