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