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