]>
Commit | Line | Data |
---|---|---|
43bb5f82 BP |
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 | |
b3a375f2 | 20 | \fBovs\-ctl\fR \fB\-\-system\-id=random\fR|\fIuuid\fR |
43bb5f82 BP |
21 | [\fIoptions\fR] \fBstart |
22 | .br | |
23 | \fBovs\-ctl stop | |
24 | .br | |
25 | \fBovs\-ctl status | |
26 | .br | |
27 | \fBovs\-ctl version | |
28 | .br | |
b3a375f2 | 29 | \fBovs\-ctl |
da3db88f SH |
30 | [\fIoptions\fR] |
31 | \fBload\-kmod\fR | |
32 | .br | |
33 | \fBovs\-ctl | |
b3a375f2 BP |
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 | |
43bb5f82 BP |
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 | . | |
9fc47ed7 BP |
72 | .IP 2. |
73 | If \fB\-\-brcompat\fR was specified, loads the Open vSwitch bridge | |
74 | compatibility module. | |
75 | . | |
43bb5f82 BP |
76 | .PP |
77 | The \fBstart\fR command skips the following steps if | |
78 | \fBovsdb\-server\fR is already running: | |
9fc47ed7 | 79 | .IP 3. |
43bb5f82 BP |
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 | . | |
9fc47ed7 | 84 | .IP 4. |
43bb5f82 BP |
85 | Starts \fBovsdb-server\fR. |
86 | . | |
9fc47ed7 | 87 | .IP 5. |
43bb5f82 BP |
88 | Initializes a few values inside the database. |
89 | . | |
9fc47ed7 | 90 | .IP 6. |
43bb5f82 BP |
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: | |
9fc47ed7 | 97 | .IP 7. |
43bb5f82 BP |
98 | Starts \fBovs\-vswitchd\fR. |
99 | . | |
9fc47ed7 BP |
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 | . | |
43bb5f82 BP |
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 | |
a685eb5a GS |
127 | The following options should be specified if the defaults are not |
128 | suitable: | |
43bb5f82 BP |
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). | |
a685eb5a GS |
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. | |
43bb5f82 BP |
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" | |
7bb8f953 BP |
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. | |
43bb5f82 | 185 | . |
d0c06099 BP |
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. | |
37368939 BP |
201 | . |
202 | .IP "\fBglibc\fR" | |
203 | Enable GNU C library features designed to find memory errors. | |
d0c06099 BP |
204 | .RE |
205 | . | |
206 | .IP | |
207 | By default, no wrapper is used. | |
208 | . | |
209 | .IP | |
37368939 BP |
210 | Each of the wrappers can expose bugs in Open vSwitch that lead to |
211 | incorrect operation, including crashes. The \fBvalgring\fR and | |
212 | \fBstrace\fR wrappers greatly slow daemon operations so they should | |
213 | not be used in production. They also produce voluminous logs that can | |
214 | quickly fill small disk partitions. The \fBglibc\fR wrapper is less | |
215 | resource-intensive but still somewhat slows the daemons. | |
d0c06099 | 216 | . |
43bb5f82 BP |
217 | .PP |
218 | The following options control file locations. They should only be | |
219 | used if the default locations cannot be used. See \fBFILES\fR, below, | |
220 | for more information. | |
221 | . | |
222 | .IP "\fB\-\-db\-file=\fIfile\fR" | |
223 | Overrides the file name for the OVS database. | |
224 | . | |
225 | .IP "\fB\-\-db\-sock=\fIsocket\fR" | |
226 | Overrides the file name for the Unix domain socket used to connect to | |
227 | \fBovsdb\-server\fR. | |
228 | . | |
229 | .IP "\fB\-\-db\-schema=\fIschema\fR" | |
230 | Overrides the file name for the OVS database schema. | |
231 | . | |
b4e8d170 BP |
232 | .IP "\fB\-\-extra-dbs=\fIfile\fR" |
233 | Adds \fIfile\fR as an extra database for \fBovsdb\-server\fR to serve | |
234 | out. Multiple space-separated file names may also be specified. | |
235 | \fIfile\fR should begin with \fB/\fR; if it does not, then it will be | |
236 | taken as relative to \fIdbdir\fR. | |
237 | . | |
43bb5f82 BP |
238 | .SH "The ``stop'' command" |
239 | . | |
240 | .PP | |
9fc47ed7 BP |
241 | The \fBstop\fR command shuts down Open vSwitch. It kills any running |
242 | \fBovs\-brcompatd\fR, \fBovs\-vswitchd\fR, or \fBovsdb\-server\fR | |
243 | daemons and waits for them to terminate. | |
244 | . | |
245 | .PP | |
246 | The \fBstop\fR command does not unload the Open vSwitch kernel | |
247 | modules. | |
43bb5f82 BP |
248 | . |
249 | .PP | |
250 | This command does nothing and finishes successfully if the OVS daemons | |
251 | aren't running. | |
252 | . | |
253 | .SH "The ``status'' command" | |
254 | . | |
255 | .PP | |
9fc47ed7 BP |
256 | The \fBstatus\fR command checks whether the OVS daemons |
257 | \fBovs-vswitchd\fR and \fBovsdb\-server\fR are running and prints | |
258 | messages with that information. If \fB\-\-brcompat\fR is specified, | |
259 | it also checks for \fBovs\-brcompatd\fR. It exits with status 0 if | |
43bb5f82 BP |
260 | the daemons are running, 1 otherwise. |
261 | . | |
262 | .SH "The ``version'' command" | |
263 | . | |
264 | .PP | |
265 | The \fBversion\fR command runs \fBovsdb\-server \-\-version\fR and | |
9fc47ed7 BP |
266 | \fBovs\-vswitchd \-\-version\fR. If \fB\-\-brcompat\fR is specified, |
267 | it also runs \fBovs\-brcompatd \-\-version\fR. | |
43bb5f82 BP |
268 | . |
269 | .SH "The ``force\-reload\-kmod'' command" | |
270 | . | |
271 | .PP | |
272 | The \fBforce\-reload\-kmod\fR command allows upgrading the Open | |
273 | vSwitch kernel module without rebooting. It performs the following | |
274 | tasks: | |
275 | . | |
276 | .IP 1. | |
277 | Gets a list of OVS ``internal'' interfaces, that is, network devices | |
278 | implemented by Open vSwitch. The most common examples of these are | |
279 | bridge ``local ports''. | |
280 | . | |
281 | .IP 2. | |
282 | Stops the Open vSwitch daemons, as if by a call to \fBovs\-ctl | |
283 | stop\fR. | |
284 | . | |
285 | .IP 3. | |
286 | Saves the kernel configuration state of the OVS internal interfaces | |
287 | listed in step 1, including IP and IPv6 addresses and routing table | |
288 | entries. | |
289 | . | |
290 | .IP 4. | |
9fc47ed7 BP |
291 | Unloads the Open vSwitch kernel module (including the bridge |
292 | compatibility module if it is loaded). | |
43bb5f82 BP |
293 | . |
294 | .IP 5. | |
295 | Starts OVS back up, as if by a call to \fBovs\-ctl start\fR. This | |
9fc47ed7 BP |
296 | reloads the kernel module and restarts the OVS daemons (including |
297 | \fBovs\-brcompatd\fR, if \fB\-\-brcompat\fR is specified). | |
43bb5f82 BP |
298 | . |
299 | .IP 6. | |
300 | Restores the kernel configuration state that was saved in step 3. | |
301 | . | |
2dc7590d BP |
302 | .IP 7. |
303 | Checks for daemons that may need to be restarted because they have | |
304 | packet sockets that are listening on old instances of Open vSwitch | |
305 | kernel interfaces and, if it finds any, prints a warning on stdout. | |
306 | DHCP is a common example: if the ISC DHCP client is running on an OVS | |
307 | internal interface, then it will have to be restarted after completing | |
308 | the above procedure. (It would be nice if \fBovs\-ctl\fR could restart | |
309 | daemons automatically, but the details are far too specific to a | |
310 | particular distribution and installation.) | |
43bb5f82 BP |
311 | . |
312 | .PP | |
b3a375f2 | 313 | \fBforce\-kmod\-reload\fR internally stops and starts OVS, so it |
43bb5f82 BP |
314 | accepts all of the options accepted by the \fBstart\fR command. |
315 | . | |
da3db88f SH |
316 | .SH "The ``load\-kmod'' command" |
317 | . | |
318 | .PP | |
319 | The \fBload\-kmod\fR command loads the openvswitch kernel modules if | |
320 | they are not already loaded. This operation also occurs as part of | |
321 | the \fBstart\fR command. The motivation for providing the \fBload\-kmod\fR | |
322 | command is to allow errors when loading modules to be handled separatetly | |
323 | from other errors that may occur when running the \fBstart\fR command. | |
324 | . | |
325 | .PP | |
326 | By default the \fBload\-kmod\fR command attempts to load the | |
9b80f761 CW |
327 | openvswitch kernel module. If the \fB\-\-brcompat\fR option is |
328 | specified then the brcompat kernel module is also loaded. | |
da3db88f | 329 | . |
2bed68ff | 330 | .SH "The ``enable\-protocol'' command" |
b3a375f2 BP |
331 | . |
332 | .PP | |
333 | The \fBenable\-protocol\fR command checks for rules related to a | |
334 | specified protocol in the system's \fBiptables\fR(8) configuration. If there | |
335 | are no rules specifically related to that protocol, then it inserts a | |
336 | rule to accept the specified protocol. | |
337 | . | |
338 | .PP | |
339 | More specifically: | |
340 | . | |
341 | .IP \(bu | |
342 | If \fBiptables\fR is not installed or not enabled, this command does | |
343 | nothing, assuming that lack of filtering means that the protocol is | |
344 | enabled. | |
345 | . | |
346 | .IP \(bu | |
347 | If the \fBINPUT\fR chain has a rule that matches the specified | |
348 | protocol, then this command does nothing, assuming that whatever rule | |
349 | is installed reflects the system administrator's decisions. | |
350 | . | |
351 | .IP \(bu | |
352 | Otherwise, this command installs a rule that accepts traffic of the | |
353 | specified protocol. | |
354 | . | |
355 | .PP | |
356 | This command normally completes successfully, even if it does | |
357 | nothing. Only the failure of an attempt to insert a rule normally | |
358 | causes it to return an exit code other than 0. | |
359 | . | |
360 | The following options control the protocol to be enabled: | |
361 | . | |
362 | .IP "\fB\-\-protocol=\fIprotocol\fR" | |
363 | The name of the IP protocol to be enabled, such as \fBgre\fR or | |
364 | \fBtcp\fR. The default is \fBgre\fR. | |
365 | . | |
366 | .IP "\fB\-\-sport=\fIsport\fR" | |
367 | .IQ "\fB\-\-dport=\fIdport\fR" | |
368 | TCP or UDP source or destination port to match. These are optional | |
369 | and allowed only with \fB\-\-protocol=tcp\fR or | |
370 | \fB\-\-protocol=udp\fR. | |
371 | . | |
2bed68ff | 372 | .SH "The ``help'' command" |
43bb5f82 BP |
373 | . |
374 | Prints a usage message and exits successfully. | |
375 | . | |
9fc47ed7 BP |
376 | .SH "OPTIONS" |
377 | .PP | |
378 | In addition to the options listed for each command above, this option | |
379 | controls the behavior of several of \fBovs\-ctl\fR's commands. | |
380 | . | |
381 | .IP "\fB\-\-brcompat\fR" | |
382 | By default, \fBovs\-ctl\fR does not load the Open vSwitch bridge | |
383 | compatibility module and does not start or check the status or report | |
384 | the version of the \fBovs\-brcompatd\fR daemon. This option enables | |
385 | all of those behaviors. | |
386 | . | |
387 | .IP | |
388 | The \fBstop\fR command always stops \fBovs\-brcompatd\fR, if it is | |
389 | running, regardless of this option. | |
390 | . | |
43bb5f82 BP |
391 | .SH "EXIT STATUS" |
392 | . | |
393 | \fBovs\-ctl\fR exits with status 0 on success and nonzero on failure. | |
394 | The \fBstart\fR command is considered to succeed if OVS is already | |
395 | started; the \fBstop\fR command is considered to succeed if OVS is | |
396 | already stopped. | |
397 | . | |
398 | .SH "ENVIRONMENT" | |
399 | . | |
400 | The following environment variables affect \fBovs\-ctl\fR: | |
401 | . | |
402 | .IP "\fBPATH\fR" | |
403 | \fBovs\-ctl\fR does not hardcode the location of any of the programs | |
404 | that it runs. \fBovs\-ctl\fR will add the \fIsbindir\fR and | |
405 | \fIbindir\fR that were specified at \fBconfigure\fR time to | |
406 | \fBPATH\fR, if they are not already present. | |
407 | . | |
408 | .IP "\fBOVS_LOGDIR\fR" | |
409 | .IQ "\fBOVS_RUNDIR\fR" | |
f973f2af | 410 | .IQ "\fBOVS_DBDIR\fR" |
43bb5f82 BP |
411 | .IQ "\fBOVS_SYSCONFDIR\fR" |
412 | .IQ "\fBOVS_PKGDATADIR\fR" | |
413 | .IQ "\fBOVS_BINDIR\fR" | |
414 | .IQ "\fBOVS_SBINDIR\fR" | |
415 | Setting one of these variables in the environment overrides the | |
416 | respective \fBconfigure\fR option, both for \fBovs\-ctl\fR itself and | |
417 | for the other Open vSwitch programs that it runs. | |
418 | . | |
419 | .SH "FILES" | |
420 | . | |
421 | \fBovs\-ctl\fR uses the following files: | |
422 | . | |
423 | .IP "\fBovs\-lib.sh" | |
424 | Shell function library used internally by \fBovs\-ctl\fR. It must be | |
425 | installed in the same directory as \fBovs\-ctl\fR. | |
426 | . | |
427 | .IP "\fIlogdir\fB/\fIdaemon\fB.log\fR" | |
428 | Per-daemon logfiles. | |
429 | . | |
430 | .IP "\fIrundir\fB/\fIdaemon\fB.pid\fR" | |
431 | Per-daemon pidfiles to track whether a daemon is running and with what | |
432 | process ID. | |
433 | . | |
434 | .IP "\fIpkgdatadir\fB/vswitch.ovsschema\fR" | |
435 | The OVS database schema used to initialize the database (use | |
436 | \fB\-\-db\-schema to override this location). | |
437 | . | |
f973f2af | 438 | .IP "\fIdbdir\fB/conf.db\fR" |
43bb5f82 BP |
439 | The OVS database (use \fB\-\-db\-file\fR to override this location). |
440 | . | |
441 | .IP "\fIrundir\fB/openvswitch/db.sock\fR" | |
442 | The Unix domain socket used for local communication with | |
443 | \fBovsdb\-server\fR (use \fB\-\-db\-sock\fR to override this | |
444 | location). | |
445 | . | |
446 | .IP "\fIsysconfdir\fB/openvswitch/system-id.conf\fR" | |
447 | The persistent system UUID created and read by | |
448 | \fB\-\-system\-id=random\fR. | |
449 | . | |
a685eb5a GS |
450 | .IP "\fIsysconfdir\fB/openvswitch/system\-type.conf\fR" |
451 | .IQ "\fIsysconfdir\fB/openvswitch/system\-version.conf\fR" | |
452 | The \fBsystem\-type\fR and \fBsystem\-version\fR values stored in the database's | |
453 | \fBOpen_vSwitch\fR table when not specified as a command-line option. | |
454 | . | |
43bb5f82 BP |
455 | .SH "EXAMPLE" |
456 | . | |
457 | .PP | |
458 | The files \fBdebian/openvswitch\-switch.init\fR and | |
459 | \fBxenserver/etc_init.d_openvswitch\fR in the Open vSwitch source | |
460 | distribution are good examples of how to use \fBovs\-ctl\fR. | |
461 | . | |
462 | .SH "SEE ALSO" | |
463 | . | |
9fc47ed7 | 464 | \fBREADME\fR, \fBINSTALL.Linux\fR, \fBovsdb\-server\fR(8), |
43bb5f82 | 465 | \fBovs\-vswitchd\fR(8). |