]>
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 BP |
29 | \fBovs\-ctl |
30 | \fB\-\-system\-id=random\fR|\fIuuid\fR | |
31 | [\fIoptions\fR] | |
32 | \fBforce\-reload\-kmod\fR | |
33 | .br | |
34 | \fBovs\-ctl | |
35 | \fR[\fB\-\-protocol=\fIprotocol\fR] | |
36 | [\fB\-\-sport=\fIsport\fR] | |
37 | [\fB\-\-dport=\fIdport\fR] | |
38 | \fBenable\-protocol\fR | |
43bb5f82 BP |
39 | .br |
40 | \fBovs\-ctl help \fR| \fB\-h \fR| \fB\-\-help | |
41 | .br | |
42 | \fBovs\-ctl \-\-version | |
43 | . | |
44 | .SH DESCRIPTION | |
45 | . | |
46 | .PP | |
47 | The \fBovs\-ctl\fR program starts, stops, and checks the status of | |
48 | Open vSwitch daemons. It is not meant to be invoked directly by | |
49 | system administrators but to be called internally by system startup | |
50 | scripts. | |
51 | . | |
52 | .PP | |
53 | Each of \fBovs\-ctl\fR's commands is described separately below. | |
54 | . | |
55 | .SH "The ``start'' command" | |
56 | . | |
57 | .PP | |
58 | The \fBstart\fR command starts Open vSwitch. It performs the | |
59 | following tasks: | |
60 | . | |
61 | .IP 1. | |
62 | Loads the Open vSwitch kernel module. If this fails, and the Linux | |
63 | bridge module is loaded but no bridges exist, it tries to unload the | |
64 | bridge module and tries loading the Open vSwitch kernel module again. | |
65 | (This is because the Open vSwitch kernel module cannot coexist with | |
66 | the Linux bridge module before 2.6.37.) | |
67 | . | |
9fc47ed7 BP |
68 | .IP 2. |
69 | If \fB\-\-brcompat\fR was specified, loads the Open vSwitch bridge | |
70 | compatibility module. | |
71 | . | |
43bb5f82 BP |
72 | .PP |
73 | The \fBstart\fR command skips the following steps if | |
74 | \fBovsdb\-server\fR is already running: | |
9fc47ed7 | 75 | .IP 3. |
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 | . | |
9fc47ed7 | 80 | .IP 4. |
43bb5f82 BP |
81 | Starts \fBovsdb-server\fR. |
82 | . | |
9fc47ed7 | 83 | .IP 5. |
43bb5f82 BP |
84 | Initializes a few values inside the database. |
85 | . | |
9fc47ed7 | 86 | .IP 6. |
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: | |
9fc47ed7 | 93 | .IP 7. |
43bb5f82 BP |
94 | Starts \fBovs\-vswitchd\fR. |
95 | . | |
9fc47ed7 BP |
96 | .PP |
97 | The \fBstart\fR command skips the following step if | |
98 | \fBovs\-brcompatd\fR is already running or if \fB\-\-brcompat\fR is | |
99 | not specified: | |
100 | .IP 8. | |
101 | Starts \fBovs\-brcompatd\fR. | |
102 | . | |
43bb5f82 BP |
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 | |
123 | On systems that have the \fBlsb_release\fR program, \fBovs\-ctl\fR | |
124 | chooses reasonable defaults for the following options. Other systems | |
125 | should specify values: | |
126 | . | |
127 | .IP "\fB\-\-system\-type=\fItype\fR" | |
128 | .IQ "\fB\-\-system\-version=\fIversion\fR" | |
129 | Sets the value to store in the \fBsystem-type\fR and | |
130 | \fBsystem-version\fR columns, respectively, in the database's | |
131 | \fBOpen_vSwitch\fR table. Remote managers may use these values to | |
132 | determine the kind of system to which they are connected (primarily | |
133 | for display to human administrators). | |
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" | |
174 | Sets the \fBnice\fR(1) level used for \fBovsdb\-server\fR and | |
175 | \fBovs\-vswitchd\fR, respectively. Both default to \fB\-10\fR. | |
176 | . | |
177 | .PP | |
178 | The following options control file locations. They should only be | |
179 | used if the default locations cannot be used. See \fBFILES\fR, below, | |
180 | for more information. | |
181 | . | |
182 | .IP "\fB\-\-db\-file=\fIfile\fR" | |
183 | Overrides the file name for the OVS database. | |
184 | . | |
185 | .IP "\fB\-\-db\-sock=\fIsocket\fR" | |
186 | Overrides the file name for the Unix domain socket used to connect to | |
187 | \fBovsdb\-server\fR. | |
188 | . | |
189 | .IP "\fB\-\-db\-schema=\fIschema\fR" | |
190 | Overrides the file name for the OVS database schema. | |
191 | . | |
192 | .SH "The ``stop'' command" | |
193 | . | |
194 | .PP | |
9fc47ed7 BP |
195 | The \fBstop\fR command shuts down Open vSwitch. It kills any running |
196 | \fBovs\-brcompatd\fR, \fBovs\-vswitchd\fR, or \fBovsdb\-server\fR | |
197 | daemons and waits for them to terminate. | |
198 | . | |
199 | .PP | |
200 | The \fBstop\fR command does not unload the Open vSwitch kernel | |
201 | modules. | |
43bb5f82 BP |
202 | . |
203 | .PP | |
204 | This command does nothing and finishes successfully if the OVS daemons | |
205 | aren't running. | |
206 | . | |
207 | .SH "The ``status'' command" | |
208 | . | |
209 | .PP | |
9fc47ed7 BP |
210 | The \fBstatus\fR command checks whether the OVS daemons |
211 | \fBovs-vswitchd\fR and \fBovsdb\-server\fR are running and prints | |
212 | messages with that information. If \fB\-\-brcompat\fR is specified, | |
213 | it also checks for \fBovs\-brcompatd\fR. It exits with status 0 if | |
43bb5f82 BP |
214 | the daemons are running, 1 otherwise. |
215 | . | |
216 | .SH "The ``version'' command" | |
217 | . | |
218 | .PP | |
219 | The \fBversion\fR command runs \fBovsdb\-server \-\-version\fR and | |
9fc47ed7 BP |
220 | \fBovs\-vswitchd \-\-version\fR. If \fB\-\-brcompat\fR is specified, |
221 | it also runs \fBovs\-brcompatd \-\-version\fR. | |
43bb5f82 BP |
222 | . |
223 | .SH "The ``force\-reload\-kmod'' command" | |
224 | . | |
225 | .PP | |
226 | The \fBforce\-reload\-kmod\fR command allows upgrading the Open | |
227 | vSwitch kernel module without rebooting. It performs the following | |
228 | tasks: | |
229 | . | |
230 | .IP 1. | |
231 | Gets a list of OVS ``internal'' interfaces, that is, network devices | |
232 | implemented by Open vSwitch. The most common examples of these are | |
233 | bridge ``local ports''. | |
234 | . | |
235 | .IP 2. | |
236 | Stops the Open vSwitch daemons, as if by a call to \fBovs\-ctl | |
237 | stop\fR. | |
238 | . | |
239 | .IP 3. | |
240 | Saves the kernel configuration state of the OVS internal interfaces | |
241 | listed in step 1, including IP and IPv6 addresses and routing table | |
242 | entries. | |
243 | . | |
244 | .IP 4. | |
9fc47ed7 BP |
245 | Unloads the Open vSwitch kernel module (including the bridge |
246 | compatibility module if it is loaded). | |
43bb5f82 BP |
247 | . |
248 | .IP 5. | |
249 | Starts OVS back up, as if by a call to \fBovs\-ctl start\fR. This | |
9fc47ed7 BP |
250 | reloads the kernel module and restarts the OVS daemons (including |
251 | \fBovs\-brcompatd\fR, if \fB\-\-brcompat\fR is specified). | |
43bb5f82 BP |
252 | . |
253 | .IP 6. | |
254 | Restores the kernel configuration state that was saved in step 3. | |
255 | . | |
256 | .PP | |
257 | The steps above are often enough to hot-upgrade a new kernel module | |
258 | with only a few seconds of downtime. DHCP is a common problem: if the | |
259 | ISC DHCP client is running on an OVS internal interface, then it will | |
260 | have to be restarted after completing the above procedure. | |
261 | . | |
262 | .PP | |
b3a375f2 | 263 | \fBforce\-kmod\-reload\fR internally stops and starts OVS, so it |
43bb5f82 BP |
264 | accepts all of the options accepted by the \fBstart\fR command. |
265 | . | |
2bed68ff | 266 | .SH "The ``enable\-protocol'' command" |
b3a375f2 BP |
267 | . |
268 | .PP | |
269 | The \fBenable\-protocol\fR command checks for rules related to a | |
270 | specified protocol in the system's \fBiptables\fR(8) configuration. If there | |
271 | are no rules specifically related to that protocol, then it inserts a | |
272 | rule to accept the specified protocol. | |
273 | . | |
274 | .PP | |
275 | More specifically: | |
276 | . | |
277 | .IP \(bu | |
278 | If \fBiptables\fR is not installed or not enabled, this command does | |
279 | nothing, assuming that lack of filtering means that the protocol is | |
280 | enabled. | |
281 | . | |
282 | .IP \(bu | |
283 | If the \fBINPUT\fR chain has a rule that matches the specified | |
284 | protocol, then this command does nothing, assuming that whatever rule | |
285 | is installed reflects the system administrator's decisions. | |
286 | . | |
287 | .IP \(bu | |
288 | Otherwise, this command installs a rule that accepts traffic of the | |
289 | specified protocol. | |
290 | . | |
291 | .PP | |
292 | This command normally completes successfully, even if it does | |
293 | nothing. Only the failure of an attempt to insert a rule normally | |
294 | causes it to return an exit code other than 0. | |
295 | . | |
296 | The following options control the protocol to be enabled: | |
297 | . | |
298 | .IP "\fB\-\-protocol=\fIprotocol\fR" | |
299 | The name of the IP protocol to be enabled, such as \fBgre\fR or | |
300 | \fBtcp\fR. The default is \fBgre\fR. | |
301 | . | |
302 | .IP "\fB\-\-sport=\fIsport\fR" | |
303 | .IQ "\fB\-\-dport=\fIdport\fR" | |
304 | TCP or UDP source or destination port to match. These are optional | |
305 | and allowed only with \fB\-\-protocol=tcp\fR or | |
306 | \fB\-\-protocol=udp\fR. | |
307 | . | |
2bed68ff | 308 | .SH "The ``help'' command" |
43bb5f82 BP |
309 | . |
310 | Prints a usage message and exits successfully. | |
311 | . | |
9fc47ed7 BP |
312 | .SH "OPTIONS" |
313 | .PP | |
314 | In addition to the options listed for each command above, this option | |
315 | controls the behavior of several of \fBovs\-ctl\fR's commands. | |
316 | . | |
317 | .IP "\fB\-\-brcompat\fR" | |
318 | By default, \fBovs\-ctl\fR does not load the Open vSwitch bridge | |
319 | compatibility module and does not start or check the status or report | |
320 | the version of the \fBovs\-brcompatd\fR daemon. This option enables | |
321 | all of those behaviors. | |
322 | . | |
323 | .IP | |
324 | The \fBstop\fR command always stops \fBovs\-brcompatd\fR, if it is | |
325 | running, regardless of this option. | |
326 | . | |
43bb5f82 BP |
327 | .SH "EXIT STATUS" |
328 | . | |
329 | \fBovs\-ctl\fR exits with status 0 on success and nonzero on failure. | |
330 | The \fBstart\fR command is considered to succeed if OVS is already | |
331 | started; the \fBstop\fR command is considered to succeed if OVS is | |
332 | already stopped. | |
333 | . | |
334 | .SH "ENVIRONMENT" | |
335 | . | |
336 | The following environment variables affect \fBovs\-ctl\fR: | |
337 | . | |
338 | .IP "\fBPATH\fR" | |
339 | \fBovs\-ctl\fR does not hardcode the location of any of the programs | |
340 | that it runs. \fBovs\-ctl\fR will add the \fIsbindir\fR and | |
341 | \fIbindir\fR that were specified at \fBconfigure\fR time to | |
342 | \fBPATH\fR, if they are not already present. | |
343 | . | |
344 | .IP "\fBOVS_LOGDIR\fR" | |
345 | .IQ "\fBOVS_RUNDIR\fR" | |
346 | .IQ "\fBOVS_SYSCONFDIR\fR" | |
347 | .IQ "\fBOVS_PKGDATADIR\fR" | |
348 | .IQ "\fBOVS_BINDIR\fR" | |
349 | .IQ "\fBOVS_SBINDIR\fR" | |
350 | Setting one of these variables in the environment overrides the | |
351 | respective \fBconfigure\fR option, both for \fBovs\-ctl\fR itself and | |
352 | for the other Open vSwitch programs that it runs. | |
353 | . | |
354 | .SH "FILES" | |
355 | . | |
356 | \fBovs\-ctl\fR uses the following files: | |
357 | . | |
358 | .IP "\fBovs\-lib.sh" | |
359 | Shell function library used internally by \fBovs\-ctl\fR. It must be | |
360 | installed in the same directory as \fBovs\-ctl\fR. | |
361 | . | |
362 | .IP "\fIlogdir\fB/\fIdaemon\fB.log\fR" | |
363 | Per-daemon logfiles. | |
364 | . | |
365 | .IP "\fIrundir\fB/\fIdaemon\fB.pid\fR" | |
366 | Per-daemon pidfiles to track whether a daemon is running and with what | |
367 | process ID. | |
368 | . | |
369 | .IP "\fIpkgdatadir\fB/vswitch.ovsschema\fR" | |
370 | The OVS database schema used to initialize the database (use | |
371 | \fB\-\-db\-schema to override this location). | |
372 | . | |
373 | .IP "\fIsysconfdir\fB/openvswitch/conf.db\fR" | |
374 | The OVS database (use \fB\-\-db\-file\fR to override this location). | |
375 | . | |
376 | .IP "\fIrundir\fB/openvswitch/db.sock\fR" | |
377 | The Unix domain socket used for local communication with | |
378 | \fBovsdb\-server\fR (use \fB\-\-db\-sock\fR to override this | |
379 | location). | |
380 | . | |
381 | .IP "\fIsysconfdir\fB/openvswitch/system-id.conf\fR" | |
382 | The persistent system UUID created and read by | |
383 | \fB\-\-system\-id=random\fR. | |
384 | . | |
385 | .SH "EXAMPLE" | |
386 | . | |
387 | .PP | |
388 | The files \fBdebian/openvswitch\-switch.init\fR and | |
389 | \fBxenserver/etc_init.d_openvswitch\fR in the Open vSwitch source | |
390 | distribution are good examples of how to use \fBovs\-ctl\fR. | |
391 | . | |
392 | .SH "SEE ALSO" | |
393 | . | |
9fc47ed7 | 394 | \fBREADME\fR, \fBINSTALL.Linux\fR, \fBovsdb\-server\fR(8), |
43bb5f82 | 395 | \fBovs\-vswitchd\fR(8). |