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