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