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 \fB\-\-system\-id=random\fR|\fIuuid\fR
  31 [\fIoptions\fR]
  32 \fBforce\-reload\-kmod\fR
  33 .br
  34 \fBovs\-ctl
  35 \fR[\fB\-\-protocol=\fIprotocol\fR]
  36 [\fB\-\-sport=\fIsport\fR]
  37 [\fB\-\-dport=\fIdport\fR]
  38 \fBenable\-protocol\fR
  39 .br
  40 \fBovs\-ctl help \fR| \fB\-h \fR| \fB\-\-help
  41 .br
  42 \fBovs\-ctl \-\-version
  43 .
  44 .SH DESCRIPTION
  45 .
  46 .PP
  47 The \fBovs\-ctl\fR program starts, stops, and checks the status of
  48 Open vSwitch daemons.  It is not meant to be invoked directly by
  49 system administrators but to be called internally by system startup
  50 scripts.
  51 .
  52 .PP
  53 Each of \fBovs\-ctl\fR's commands is described separately below.
  54 .
  55 .SH "The ``start'' command"
  56 .
  57 .PP
  58 The \fBstart\fR command starts Open vSwitch.  It performs the
  59 following tasks:
  60 .
  61 .IP 1.
  62 Loads the Open vSwitch kernel module.  If this fails, and the Linux
  63 bridge module is loaded but no bridges exist, it tries to unload the
  64 bridge module and tries loading the Open vSwitch kernel module again.
  65 (This is because the Open vSwitch kernel module cannot coexist with
  66 the Linux bridge module before 2.6.37.)
  67 .
  68 .PP
  69 The \fBstart\fR command skips the following steps if
  70 \fBovsdb\-server\fR is already running:
  71 .IP 2.
  72 If the Open vSwitch database file does not exist, it creates it.
  73 If the database does exist, but it has an obsolete version, it
  74 upgrades it to the latest schema.
  75 .
  76 .IP 3.
  77 Starts \fBovsdb-server\fR.
  78 .
  79 .IP 4.
  80 Initializes a few values inside the database.
  81 .
  82 .IP 5.
  83 If the \fB\-\-delete\-bridges\fR option was used, deletes all of the
  84 bridges from the database.
  85 .
  86 .PP
  87 The \fBstart\fR command skips the following step if
  88 \fBovs\-vswitchd\fR is already running:
  89 .IP 6.
  90 Starts \fBovs\-vswitchd\fR.
  91 .
  92 .SS "Options"
  93 .PP
  94 Several command-line options influence the \fBstart\fR command's
  95 behavior.  Some form of the following option should ordinarily be
  96 specified:
  97 .
  98 .IP "\fB\-\-system\-id=\fIuuid\fR"
  99 .IQ "\fB\-\-system\-id=random\fR"
 100 This specifies a unique system identifier to store into
 101 \fBexternal-ids:system-id\fR in the database's \fBOpen_vSwitch\fR
 102 table.  Remote managers that talk to the Open vSwitch database server
 103 over network protocols use this value to identify and distinguish Open
 104 vSwitch instances, so it should be unique (at least) within OVS
 105 instances that will connect to a single controller.
 106 .IP
 107 When \fBrandom\fR is specified, \fBovs\-ctl\fR will generate a random
 108 ID that persists from one run to another (stored in a file).  When
 109 another string is specified \fBovs\-ctl\fR uses it literally.
 110 .
 111 .PP
 112 On systems that have the \fBlsb_release\fR program, \fBovs\-ctl\fR
 113 chooses reasonable defaults for the following options.  Other systems
 114 should specify values:
 115 .
 116 .IP "\fB\-\-system\-type=\fItype\fR"
 117 .IQ "\fB\-\-system\-version=\fIversion\fR"
 118 Sets the value to store in the \fBsystem-type\fR and
 119 \fBsystem-version\fR columns, respectively, in the database's
 120 \fBOpen_vSwitch\fR table.  Remote managers may use these values to
 121 determine the kind of system to which they are connected (primarily
 122 for display to human administrators).
 123 .
 124 .PP
 125 The following options are also likely to be useful:
 126 .
 127 .IP "\fB\-\-external\-id=\(dq\fIname\fB=\fIvalue\fB\(dq"
 128 Sets \fBexternal-ids:\fIname\fR to \fIvalue\fR in the database's
 129 \fBOpen_vSwitch\fR table.  Specifying this option multiple times adds
 130 multiple key-value pairs.
 131 .
 132 .IP "\fB\-\-delete\-bridges\fR"
 133 Ordinarily Open vSwitch bridges persist from one system boot to the
 134 next, as long as the database is preserved.  Some environments instead
 135 expect to re-create all of the bridges and other configuration state
 136 on every boot.  This option supports that, by deleting all Open
 137 vSwitch bridges after starting \fBovsdb\-server\fR but before starting
 138 \fBovs\-vswitchd\fR.
 139 .
 140 .PP
 141 The following options are less important:
 142 .
 143 .IP "\fB\-\-daemon-cwd=\fIdirectory\fR"
 144 Specifies the current working directory that the OVS daemons should
 145 run from.  The default is \fB/\fR (the root directory) if this option
 146 is not specified.  (This option is useful because most systems create
 147 core files in a process's current working directory and because a file
 148 system that is in use as a process's current working directory cannot
 149 be unmounted.)
 150 .
 151 .IP "\fB\-\-no\-force\-corefiles\fR"
 152 By default, \fBovs\-ctl\fR enables core dumps for the OVS daemons.
 153 This option disables that behavior.
 154 .
 155 .IP "\fB\-\-no\-mlockall\fR"
 156 By default \fBovs\-ctl\fR passes \fB\-\-mlockall\fR to
 157 \fBovs\-vswitchd\fR, requesting that it lock all of its virtual
 158 memory, preventing it from being paged to disk.  This option
 159 suppresses that behavior.
 160 .
 161 .IP "\fB\-\-ovsdb\-server\-priority=\fIniceness\fR"
 162 .IQ "\fB\-\-ovs\-vswitchd\-priority=\fIniceness\fR"
 163 Sets the \fBnice\fR(1) level used for \fBovsdb\-server\fR and
 164 \fBovs\-vswitchd\fR, respectively.  Both default to \fB\-10\fR.
 165 .
 166 .PP
 167 The following options control file locations.  They should only be
 168 used if the default locations cannot be used.  See \fBFILES\fR, below,
 169 for more information.
 170 .
 171 .IP "\fB\-\-db\-file=\fIfile\fR"
 172 Overrides the file name for the OVS database.
 173 .
 174 .IP "\fB\-\-db\-sock=\fIsocket\fR"
 175 Overrides the file name for the Unix domain socket used to connect to
 176 \fBovsdb\-server\fR.
 177 .
 178 .IP "\fB\-\-db\-schema=\fIschema\fR"
 179 Overrides the file name for the OVS database schema.
 180 .
 181 .SH "The ``stop'' command"
 182 .
 183 .PP
 184 The \fBstart\fR command shuts down Open vSwitch.  If
 185 \fBovs\-vswitchd\fR is running, kills it and waits for it to
 186 terminate, then it does the same for \fBovsdb\-server\fR.
 187 .
 188 .PP
 189 This command does nothing and finishes successfully if the OVS daemons
 190 aren't running.
 191 .
 192 .SH "The ``status'' command"
 193 .
 194 .PP
 195 The \fBstatus\fR command checks whether the OVS daemons are running
 196 and prints messages with that information.  It exits with status 0 if
 197 the daemons are running, 1 otherwise.
 198 .
 199 .SH "The ``version'' command"
 200 .
 201 .PP
 202 The \fBversion\fR command runs \fBovsdb\-server \-\-version\fR and
 203 \fBovs\-vswitchd \-\-version\fR.
 204 .
 205 .SH "The ``force\-reload\-kmod'' command"
 206 .
 207 .PP
 208 The \fBforce\-reload\-kmod\fR command allows upgrading the Open
 209 vSwitch kernel module without rebooting.  It performs the following
 210 tasks:
 211 .
 212 .IP 1.
 213 Gets a list of OVS ``internal'' interfaces, that is, network devices
 214 implemented by Open vSwitch.  The most common examples of these are
 215 bridge ``local ports''.
 216 .
 217 .IP 2.
 218 Stops the Open vSwitch daemons, as if by a call to \fBovs\-ctl
 219 stop\fR.
 220 .
 221 .IP 3.
 222 Saves the kernel configuration state of the OVS internal interfaces
 223 listed in step 1, including IP and IPv6 addresses and routing table
 224 entries.
 225 .
 226 .IP 4.
 227 Unloads the Open vSwitch kernel module.
 228 .
 229 .IP 5.
 230 Starts OVS back up, as if by a call to \fBovs\-ctl start\fR.  This
 231 reloads the kernel module and restarts the OVS daemons.
 232 .
 233 .IP 6.
 234 Restores the kernel configuration state that was saved in step 3.
 235 .
 236 .PP
 237 The steps above are often enough to hot-upgrade a new kernel module
 238 with only a few seconds of downtime.  DHCP is a common problem: if the
 239 ISC DHCP client is running on an OVS internal interface, then it will
 240 have to be restarted after completing the above procedure.
 241 .
 242 .PP
 243 \fBforce\-kmod\-reload\fR internally stops and starts OVS, so it
 244 accepts all of the options accepted by the \fBstart\fR command.
 245 .
 246 .SS "The ``enable\-protocol'' command"
 247 .
 248 .PP
 249 The \fBenable\-protocol\fR command checks for rules related to a
 250 specified protocol in the system's \fBiptables\fR(8) configuration.  If there
 251 are no rules specifically related to that protocol, then it inserts a
 252 rule to accept the specified protocol.
 253 .
 254 .PP
 255 More specifically:
 256 .
 257 .IP \(bu
 258 If \fBiptables\fR is not installed or not enabled, this command does
 259 nothing, assuming that lack of filtering means that the protocol is
 260 enabled.
 261 .
 262 .IP \(bu
 263 If the \fBINPUT\fR chain has a rule that matches the specified
 264 protocol, then this command does nothing, assuming that whatever rule
 265 is installed reflects the system administrator's decisions.
 266 .
 267 .IP \(bu
 268 Otherwise, this command installs a rule that accepts traffic of the
 269 specified protocol.
 270 .
 271 .PP
 272 This command normally completes successfully, even if it does
 273 nothing.  Only the failure of an attempt to insert a rule normally
 274 causes it to return an exit code other than 0.
 275 .
 276 The following options control the protocol to be enabled:
 277 .
 278 .IP "\fB\-\-protocol=\fIprotocol\fR"
 279 The name of the IP protocol to be enabled, such as \fBgre\fR or
 280 \fBtcp\fR.  The default is \fBgre\fR.
 281 .
 282 .IP "\fB\-\-sport=\fIsport\fR"
 283 .IQ "\fB\-\-dport=\fIdport\fR"
 284 TCP or UDP source or destination port to match.  These are optional
 285 and allowed only with \fB\-\-protocol=tcp\fR or
 286 \fB\-\-protocol=udp\fR.
 287 .
 288 .SS "The ``help'' command"
 289 .
 290 Prints a usage message and exits successfully.
 291 .
 292 .SH "EXIT STATUS"
 293 .
 294 \fBovs\-ctl\fR exits with status 0 on success and nonzero on failure.
 295 The \fBstart\fR command is considered to succeed if OVS is already
 296 started; the \fBstop\fR command is considered to succeed if OVS is
 297 already stopped.
 298 .
 299 .SH "ENVIRONMENT"
 300 .
 301 The following environment variables affect \fBovs\-ctl\fR:
 302 .
 303 .IP "\fBPATH\fR"
 304 \fBovs\-ctl\fR does not hardcode the location of any of the programs
 305 that it runs.  \fBovs\-ctl\fR will add the \fIsbindir\fR and
 306 \fIbindir\fR that were specified at \fBconfigure\fR time to
 307 \fBPATH\fR, if they are not already present.
 308 .
 309 .IP "\fBOVS_LOGDIR\fR"
 310 .IQ "\fBOVS_RUNDIR\fR"
 311 .IQ "\fBOVS_SYSCONFDIR\fR"
 312 .IQ "\fBOVS_PKGDATADIR\fR"
 313 .IQ "\fBOVS_BINDIR\fR"
 314 .IQ "\fBOVS_SBINDIR\fR"
 315 Setting one of these variables in the environment overrides the
 316 respective \fBconfigure\fR option, both for \fBovs\-ctl\fR itself and
 317 for the other Open vSwitch programs that it runs.
 318 .
 319 .SH "FILES"
 320 .
 321 \fBovs\-ctl\fR uses the following files:
 322 .
 323 .IP "\fBovs\-lib.sh"
 324 Shell function library used internally by \fBovs\-ctl\fR.  It must be
 325 installed in the same directory as \fBovs\-ctl\fR.
 326 .
 327 .IP "\fIlogdir\fB/\fIdaemon\fB.log\fR"
 328 Per-daemon logfiles.
 329 .
 330 .IP "\fIrundir\fB/\fIdaemon\fB.pid\fR"
 331 Per-daemon pidfiles to track whether a daemon is running and with what
 332 process ID.
 333 .
 334 .IP "\fIpkgdatadir\fB/vswitch.ovsschema\fR"
 335 The OVS database schema used to initialize the database (use
 336 \fB\-\-db\-schema to override this location).
 337 .
 338 .IP "\fIsysconfdir\fB/openvswitch/conf.db\fR"
 339 The OVS database (use \fB\-\-db\-file\fR to override this location).
 340 .
 341 .IP "\fIrundir\fB/openvswitch/db.sock\fR"
 342 The Unix domain socket used for local communication with
 343 \fBovsdb\-server\fR (use \fB\-\-db\-sock\fR to override this
 344 location).
 345 .
 346 .IP "\fIsysconfdir\fB/openvswitch/system-id.conf\fR"
 347 The persistent system UUID created and read by
 348 \fB\-\-system\-id=random\fR.
 349 .
 350 .SH "EXAMPLE"
 351 .
 352 .PP
 353 The files \fBdebian/openvswitch\-switch.init\fR and
 354 \fBxenserver/etc_init.d_openvswitch\fR in the Open vSwitch source
 355 distribution are good examples of how to use \fBovs\-ctl\fR.
 356 .
 357 .SH "SEE ALSO"
 358 .
 359 \fBREADME\fR, \fBINSTALL.LINUX\fR, \fBovsdb\-server\fR(8),
 360 \fBovs\-vswitchd\fR(8).