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