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