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 .IP 2.
  73 If \fB\-\-brcompat\fR was specified, loads the Open vSwitch bridge
  74 compatibility module.
  75 .
  76 .PP
  77 The \fBstart\fR command skips the following steps if
  78 \fBovsdb\-server\fR is already running:
  79 .IP 3.
  80 If the Open vSwitch database file does not exist, it creates it.
  81 If the database does exist, but it has an obsolete version, it
  82 upgrades it to the latest schema.
  83 .
  84 .IP 4.
  85 Starts \fBovsdb-server\fR.
  86 .
  87 .IP 5.
  88 Initializes a few values inside the database.
  89 .
  90 .IP 6.
  91 If the \fB\-\-delete\-bridges\fR option was used, deletes all of the
  92 bridges from the database.
  93 .
  94 .PP
  95 The \fBstart\fR command skips the following step if
  96 \fBovs\-vswitchd\fR is already running:
  97 .IP 7.
  98 Starts \fBovs\-vswitchd\fR.
  99 .
 100 .PP
 101 The \fBstart\fR command skips the following step if
 102 \fBovs\-brcompatd\fR is already running or if \fB\-\-brcompat\fR is
 103 not specified:
 104 .IP 8.
 105 Starts \fBovs\-brcompatd\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 On systems that have the \fBlsb_release\fR program, \fBovs\-ctl\fR
 128 chooses reasonable defaults for the following options.  Other systems
 129 should specify values:
 130 .
 131 .IP "\fB\-\-system\-type=\fItype\fR"
 132 .IQ "\fB\-\-system\-version=\fIversion\fR"
 133 Sets the value to store in the \fBsystem-type\fR and
 134 \fBsystem-version\fR columns, respectively, in the database's
 135 \fBOpen_vSwitch\fR table.  Remote managers may use these values to
 136 determine the kind of system to which they are connected (primarily
 137 for display to human administrators).
 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 .PP
 156 The following options are less important:
 157 .
 158 .IP "\fB\-\-daemon-cwd=\fIdirectory\fR"
 159 Specifies the current working directory that the OVS daemons should
 160 run from.  The default is \fB/\fR (the root directory) if this option
 161 is not specified.  (This option is useful because most systems create
 162 core files in a process's current working directory and because a file
 163 system that is in use as a process's current working directory cannot
 164 be unmounted.)
 165 .
 166 .IP "\fB\-\-no\-force\-corefiles\fR"
 167 By default, \fBovs\-ctl\fR enables core dumps for the OVS daemons.
 168 This option disables that behavior.
 169 .
 170 .IP "\fB\-\-no\-mlockall\fR"
 171 By default \fBovs\-ctl\fR passes \fB\-\-mlockall\fR to
 172 \fBovs\-vswitchd\fR, requesting that it lock all of its virtual
 173 memory, preventing it from being paged to disk.  This option
 174 suppresses that behavior.
 175 .
 176 .IP "\fB\-\-ovsdb\-server\-priority=\fIniceness\fR"
 177 .IQ "\fB\-\-ovs\-vswitchd\-priority=\fIniceness\fR"
 178 Sets the \fBnice\fR(1) level used for \fBovsdb\-server\fR and
 179 \fBovs\-vswitchd\fR, respectively.  Both default to \fB\-10\fR.
 180 .
 181 .PP
 182 The following options control file locations.  They should only be
 183 used if the default locations cannot be used.  See \fBFILES\fR, below,
 184 for more information.
 185 .
 186 .IP "\fB\-\-db\-file=\fIfile\fR"
 187 Overrides the file name for the OVS database.
 188 .
 189 .IP "\fB\-\-db\-sock=\fIsocket\fR"
 190 Overrides the file name for the Unix domain socket used to connect to
 191 \fBovsdb\-server\fR.
 192 .
 193 .IP "\fB\-\-db\-schema=\fIschema\fR"
 194 Overrides the file name for the OVS database schema.
 195 .
 196 .SH "The ``stop'' command"
 197 .
 198 .PP
 199 The \fBstop\fR command shuts down Open vSwitch.  It kills any running
 200 \fBovs\-brcompatd\fR, \fBovs\-vswitchd\fR, or \fBovsdb\-server\fR
 201 daemons and waits for them to terminate.
 202 .
 203 .PP
 204 The \fBstop\fR command does not unload the Open vSwitch kernel
 205 modules.
 206 .
 207 .PP
 208 This command does nothing and finishes successfully if the OVS daemons
 209 aren't running.
 210 .
 211 .SH "The ``status'' command"
 212 .
 213 .PP
 214 The \fBstatus\fR command checks whether the OVS daemons
 215 \fBovs-vswitchd\fR and \fBovsdb\-server\fR are running and prints
 216 messages with that information.  If \fB\-\-brcompat\fR is specified,
 217 it also checks for \fBovs\-brcompatd\fR.  It exits with status 0 if
 218 the daemons are running, 1 otherwise.
 219 .
 220 .SH "The ``version'' command"
 221 .
 222 .PP
 223 The \fBversion\fR command runs \fBovsdb\-server \-\-version\fR and
 224 \fBovs\-vswitchd \-\-version\fR.  If \fB\-\-brcompat\fR is specified,
 225 it also runs \fBovs\-brcompatd \-\-version\fR.
 226 .
 227 .SH "The ``force\-reload\-kmod'' command"
 228 .
 229 .PP
 230 The \fBforce\-reload\-kmod\fR command allows upgrading the Open
 231 vSwitch kernel module without rebooting.  It performs the following
 232 tasks:
 233 .
 234 .IP 1.
 235 Gets a list of OVS ``internal'' interfaces, that is, network devices
 236 implemented by Open vSwitch.  The most common examples of these are
 237 bridge ``local ports''.
 238 .
 239 .IP 2.
 240 Stops the Open vSwitch daemons, as if by a call to \fBovs\-ctl
 241 stop\fR.
 242 .
 243 .IP 3.
 244 Saves the kernel configuration state of the OVS internal interfaces
 245 listed in step 1, including IP and IPv6 addresses and routing table
 246 entries.
 247 .
 248 .IP 4.
 249 Unloads the Open vSwitch kernel module (including the bridge
 250 compatibility module if it is loaded).
 251 .
 252 .IP 5.
 253 Starts OVS back up, as if by a call to \fBovs\-ctl start\fR.  This
 254 reloads the kernel module and restarts the OVS daemons (including
 255 \fBovs\-brcompatd\fR, if \fB\-\-brcompat\fR is specified).
 256 .
 257 .IP 6.
 258 Restores the kernel configuration state that was saved in step 3.
 259 .
 260 .PP
 261 The steps above are often enough to hot-upgrade a new kernel module
 262 with only a few seconds of downtime.  DHCP is a common problem: if the
 263 ISC DHCP client is running on an OVS internal interface, then it will
 264 have to be restarted after completing the above procedure.
 265 .
 266 .PP
 267 \fBforce\-kmod\-reload\fR internally stops and starts OVS, so it
 268 accepts all of the options accepted by the \fBstart\fR command.
 269 .
 270 .SH "The ``load\-kmod'' command"
 271 .
 272 .PP
 273 The \fBload\-kmod\fR command loads the openvswitch kernel modules if
 274 they are not already loaded. This operation also occurs as part of
 275 the \fBstart\fR command. The motivation for providing the \fBload\-kmod\fR
 276 command is to allow errors when loading modules to be handled separatetly
 277 from other errors that may occur when running the \fBstart\fR command.
 278 .
 279 .PP
 280 By default the \fBload\-kmod\fR command attempts to load the
 281 openvswitch_mod kernel module. If the \fB\-\-brcompat\fR option is
 282 specified then the brcompat_mod kernel module is also loaded.
 283 .
 284 .SH "The ``enable\-protocol'' command"
 285 .
 286 .PP
 287 The \fBenable\-protocol\fR command checks for rules related to a
 288 specified protocol in the system's \fBiptables\fR(8) configuration.  If there
 289 are no rules specifically related to that protocol, then it inserts a
 290 rule to accept the specified protocol.
 291 .
 292 .PP
 293 More specifically:
 294 .
 295 .IP \(bu
 296 If \fBiptables\fR is not installed or not enabled, this command does
 297 nothing, assuming that lack of filtering means that the protocol is
 298 enabled.
 299 .
 300 .IP \(bu
 301 If the \fBINPUT\fR chain has a rule that matches the specified
 302 protocol, then this command does nothing, assuming that whatever rule
 303 is installed reflects the system administrator's decisions.
 304 .
 305 .IP \(bu
 306 Otherwise, this command installs a rule that accepts traffic of the
 307 specified protocol.
 308 .
 309 .PP
 310 This command normally completes successfully, even if it does
 311 nothing.  Only the failure of an attempt to insert a rule normally
 312 causes it to return an exit code other than 0.
 313 .
 314 The following options control the protocol to be enabled:
 315 .
 316 .IP "\fB\-\-protocol=\fIprotocol\fR"
 317 The name of the IP protocol to be enabled, such as \fBgre\fR or
 318 \fBtcp\fR.  The default is \fBgre\fR.
 319 .
 320 .IP "\fB\-\-sport=\fIsport\fR"
 321 .IQ "\fB\-\-dport=\fIdport\fR"
 322 TCP or UDP source or destination port to match.  These are optional
 323 and allowed only with \fB\-\-protocol=tcp\fR or
 324 \fB\-\-protocol=udp\fR.
 325 .
 326 .SH "The ``help'' command"
 327 .
 328 Prints a usage message and exits successfully.
 329 .
 330 .SH "OPTIONS"
 331 .PP
 332 In addition to the options listed for each command above, this option
 333 controls the behavior of several of \fBovs\-ctl\fR's commands.
 334 .
 335 .IP "\fB\-\-brcompat\fR"
 336 By default, \fBovs\-ctl\fR does not load the Open vSwitch bridge
 337 compatibility module and does not start or check the status or report
 338 the version of the \fBovs\-brcompatd\fR daemon.  This option enables
 339 all of those behaviors.
 340 .
 341 .IP
 342 The \fBstop\fR command always stops \fBovs\-brcompatd\fR, if it is
 343 running, regardless of this option.
 344 .
 345 .SH "EXIT STATUS"
 346 .
 347 \fBovs\-ctl\fR exits with status 0 on success and nonzero on failure.
 348 The \fBstart\fR command is considered to succeed if OVS is already
 349 started; the \fBstop\fR command is considered to succeed if OVS is
 350 already stopped.
 351 .
 352 .SH "ENVIRONMENT"
 353 .
 354 The following environment variables affect \fBovs\-ctl\fR:
 355 .
 356 .IP "\fBPATH\fR"
 357 \fBovs\-ctl\fR does not hardcode the location of any of the programs
 358 that it runs.  \fBovs\-ctl\fR will add the \fIsbindir\fR and
 359 \fIbindir\fR that were specified at \fBconfigure\fR time to
 360 \fBPATH\fR, if they are not already present.
 361 .
 362 .IP "\fBOVS_LOGDIR\fR"
 363 .IQ "\fBOVS_RUNDIR\fR"
 364 .IQ "\fBOVS_SYSCONFDIR\fR"
 365 .IQ "\fBOVS_PKGDATADIR\fR"
 366 .IQ "\fBOVS_BINDIR\fR"
 367 .IQ "\fBOVS_SBINDIR\fR"
 368 Setting one of these variables in the environment overrides the
 369 respective \fBconfigure\fR option, both for \fBovs\-ctl\fR itself and
 370 for the other Open vSwitch programs that it runs.
 371 .
 372 .SH "FILES"
 373 .
 374 \fBovs\-ctl\fR uses the following files:
 375 .
 376 .IP "\fBovs\-lib.sh"
 377 Shell function library used internally by \fBovs\-ctl\fR.  It must be
 378 installed in the same directory as \fBovs\-ctl\fR.
 379 .
 380 .IP "\fIlogdir\fB/\fIdaemon\fB.log\fR"
 381 Per-daemon logfiles.
 382 .
 383 .IP "\fIrundir\fB/\fIdaemon\fB.pid\fR"
 384 Per-daemon pidfiles to track whether a daemon is running and with what
 385 process ID.
 386 .
 387 .IP "\fIpkgdatadir\fB/vswitch.ovsschema\fR"
 388 The OVS database schema used to initialize the database (use
 389 \fB\-\-db\-schema to override this location).
 390 .
 391 .IP "\fIsysconfdir\fB/openvswitch/conf.db\fR"
 392 The OVS database (use \fB\-\-db\-file\fR to override this location).
 393 .
 394 .IP "\fIrundir\fB/openvswitch/db.sock\fR"
 395 The Unix domain socket used for local communication with
 396 \fBovsdb\-server\fR (use \fB\-\-db\-sock\fR to override this
 397 location).
 398 .
 399 .IP "\fIsysconfdir\fB/openvswitch/system-id.conf\fR"
 400 The persistent system UUID created and read by
 401 \fB\-\-system\-id=random\fR.
 402 .
 403 .SH "EXAMPLE"
 404 .
 405 .PP
 406 The files \fBdebian/openvswitch\-switch.init\fR and
 407 \fBxenserver/etc_init.d_openvswitch\fR in the Open vSwitch source
 408 distribution are good examples of how to use \fBovs\-ctl\fR.
 409 .
 410 .SH "SEE ALSO"
 411 .
 412 \fBREADME\fR, \fBINSTALL.Linux\fR, \fBovsdb\-server\fR(8),
 413 \fBovs\-vswitchd\fR(8).