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