]>
Commit | Line | Data |
---|---|---|
ffc759c6 JP |
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 vtep\-ctl 8 "March 2013" "Open vSwitch" "Open vSwitch Manual" | |
14 | .\" This program's name: | |
15 | .ds PN vtep\-ctl | |
ffc759c6 JP |
16 | . |
17 | .SH NAME | |
18 | vtep\-ctl \- utility for querying and configuring a VTEP database | |
19 | . | |
20 | .SH SYNOPSIS | |
21 | \fBvtep\-ctl\fR [\fIoptions\fR] \fB\-\-\fR [\fIoptions\fR] \fIcommand | |
22 | \fR[\fIargs\fR] [\fB\-\-\fR [\fIoptions\fR] \fIcommand \fR[\fIargs\fR]]... | |
23 | . | |
24 | .SH DESCRIPTION | |
25 | The \fBvtep\-ctl\fR program configures a VTEP database. | |
26 | See \fBvtep\fR(5) for comprehensive documentation of | |
27 | the database schema. | |
28 | .PP | |
29 | \fBvtep\-ctl\fR connects to an \fBovsdb\-server\fR process that | |
30 | maintains a VTEP configuration database. Using this connection, it | |
31 | queries and possibly applies changes to the database, depending on the | |
32 | supplied commands. | |
33 | .PP | |
34 | \fBvtep\-ctl\fR can perform any number of commands in a single run, | |
35 | implemented as a single atomic transaction against the database. | |
36 | .PP | |
37 | The \fBvtep\-ctl\fR command line begins with global options (see | |
38 | \fBOPTIONS\fR below for details). The global options are followed by | |
39 | one or more commands. Each command should begin with \fB\-\-\fR by | |
40 | itself as a command-line argument, to separate it from the following | |
41 | commands. (The \fB\-\-\fR before the first command is optional.) The | |
42 | command itself starts with command-specific options, if any, followed by | |
43 | the command name and any arguments. See \fBEXAMPLES\fR below for syntax | |
44 | examples. | |
45 | . | |
46 | .SH OPTIONS | |
47 | . | |
48 | The following options affect the behavior \fBvtep\-ctl\fR as a whole. | |
49 | Some individual commands also accept their own options, which are | |
50 | given just before the command name. If the first command on the | |
51 | command line has options, then those options must be separated from | |
52 | the global options by \fB\-\-\fR. | |
53 | . | |
54 | .IP "\fB\-\-db=\fIserver\fR" | |
55 | Sets \fIserver\fR as the database server that \fBvtep\-ctl\fR | |
56 | contacts to query or modify configuration. The default is | |
57 | \fBunix:@RUNDIR@/db.sock\fR. \fIserver\fR must take one of the | |
58 | following forms: | |
59 | .RS | |
60 | .so ovsdb/remote-active.man | |
61 | .so ovsdb/remote-passive.man | |
62 | .RE | |
63 | . | |
64 | .IP "\fB\-\-no\-syslog\fR" | |
65 | By default, \fBvtep\-ctl\fR logs its arguments and the details of any | |
66 | changes that it makes to the system log. This option disables this | |
67 | logging. | |
68 | .IP | |
69 | This option is equivalent to \fB\-\-verbose=vtep_ctl:syslog:warn\fR. | |
70 | . | |
71 | .IP "\fB\-\-oneline\fR" | |
72 | Modifies the output format so that the output for each command is printed | |
73 | on a single line. New-line characters that would otherwise separate | |
74 | lines are printed as \fB\\n\fR, and any instances of \fB\\\fR that | |
75 | would otherwise appear in the output are doubled. | |
76 | Prints a blank line for each command that has no output. | |
77 | This option does not affect the formatting of output from the | |
78 | \fBlist\fR or \fBfind\fR commands; see \fBTable Formatting Options\fR | |
79 | below. | |
80 | . | |
81 | .IP "\fB\-\-dry\-run\fR" | |
82 | Prevents \fBvtep\-ctl\fR from actually modifying the database. | |
83 | . | |
84 | .IP "\fB\-t \fIsecs\fR" | |
85 | .IQ "\fB\-\-timeout=\fIsecs\fR" | |
86 | By default, or with a \fIsecs\fR of \fB0\fR, \fBvtep\-ctl\fR waits | |
87 | forever for a response from the database. This option limits runtime | |
88 | to approximately \fIsecs\fR seconds. If the timeout expires, | |
89 | \fBvtep\-ctl\fR will exit with a \fBSIGALRM\fR signal. (A timeout | |
90 | would normally happen only if the database cannot be contacted, or if | |
91 | the system is overloaded.) | |
92 | . | |
93 | .SS "Table Formatting Options" | |
94 | These options control the format of output from the \fBlist\fR and | |
95 | \fBfind\fR commands. | |
96 | .so lib/table.man | |
97 | . | |
98 | .SS "Public Key Infrastructure Options" | |
99 | .so lib/ssl.man | |
100 | .so lib/ssl-bootstrap.man | |
101 | .so lib/ssl-peer-ca-cert.man | |
102 | .so lib/vlog.man | |
77d9e0eb | 103 | .so lib/common.man |
ffc759c6 JP |
104 | . |
105 | .SH COMMANDS | |
106 | The commands implemented by \fBvtep\-ctl\fR are described in the | |
107 | sections below. | |
108 | . | |
109 | .SS "Physical Switch Commands" | |
110 | These commands examine and manipulate physical switches. | |
111 | . | |
112 | .IP "[\fB\-\-may\-exist\fR] \fBadd\-ps \fIpswitch\fR" | |
113 | Creates a new physical switch named \fIpswitch\fR. Initially the switch | |
114 | will have no ports. | |
115 | .IP | |
116 | Without \fB\-\-may\-exist\fR, attempting to create a switch that | |
117 | exists is an error. With \fB\-\-may\-exist\fR, this command does | |
118 | nothing if \fIpswitch\fR already exists. | |
119 | . | |
120 | .IP "[\fB\-\-if\-exists\fR] \fBdel\-ps \fIpswitch\fR" | |
121 | Deletes \fIpswitch\fR and all of its ports. | |
122 | .IP | |
123 | Without \fB\-\-if\-exists\fR, attempting to delete a switch that does | |
124 | not exist is an error. With \fB\-\-if\-exists\fR, attempting to | |
125 | delete a switch that does not exist has no effect. | |
126 | . | |
127 | .IP "\fBlist\-ps\fR" | |
128 | Lists all existing physical switches on standard output, one per line. | |
129 | . | |
130 | .IP "\fBps\-exists \fIpswitch\fR" | |
131 | Tests whether \fIpswitch\fR exists. If so, \fBvtep\-ctl\fR exits | |
132 | successfully with exit code 0. If not, \fBvtep\-ctl\fR exits | |
133 | unsuccessfully with exit code 2. | |
134 | . | |
135 | .SS "Port Commands" | |
136 | . | |
137 | These commands examine and manipulate VTEP physical ports. | |
138 | . | |
139 | .IP "\fBlist\-ports \fIpswitch\fR" | |
140 | Lists all of the ports within \fIpswitch\fR on standard output, one per | |
141 | line. | |
142 | . | |
143 | .IP "[\fB\-\-may\-exist\fR] \fBadd\-port \fIpswitch port\fR" | |
144 | Creates on \fIpswitch\fR a new port named \fIport\fR from the network | |
145 | device of the same name. | |
146 | .IP | |
147 | Without \fB\-\-may\-exist\fR, attempting to create a port that exists | |
148 | is an error. With \fB\-\-may\-exist\fR, this command does nothing if | |
149 | \fIport\fR already exists on \fIpswitch\fR. | |
150 | . | |
151 | .IP "[\fB\-\-if\-exists\fR] \fBdel\-port \fR[\fIpswitch\fR] \fIport\fR" | |
152 | Deletes \fIport\fR. If \fIpswitch\fR is omitted, \fIport\fR is removed | |
153 | from whatever switch contains it; if \fIpswitch\fR is specified, it | |
154 | must be the switch that contains \fIport\fR. | |
155 | .IP | |
156 | Without \fB\-\-if\-exists\fR, attempting to delete a port that does | |
157 | not exist is an error. With \fB\-\-if\-exists\fR, attempting to | |
158 | delete a port that does not exist has no effect. | |
159 | . | |
160 | .SS "Logical Switch Commands" | |
161 | These commands examine and manipulate logical switches. | |
162 | . | |
163 | .IP "[\fB\-\-may\-exist\fR] \fBadd\-ls \fIlswitch\fR" | |
164 | Creates a new logical switch named \fIlswitch\fR. Initially the switch | |
165 | will have no locator bindings. | |
166 | .IP | |
167 | Without \fB\-\-may\-exist\fR, attempting to create a switch that | |
168 | exists is an error. With \fB\-\-may\-exist\fR, this command does | |
169 | nothing if \fIlswitch\fR already exists. | |
170 | . | |
171 | .IP "[\fB\-\-if\-exists\fR] \fBdel\-ls \fIlswitch\fR" | |
172 | Deletes \fIlswitch\fR. | |
173 | .IP | |
174 | Without \fB\-\-if\-exists\fR, attempting to delete a switch that does | |
175 | not exist is an error. With \fB\-\-if\-exists\fR, attempting to | |
176 | delete a switch that does not exist has no effect. | |
177 | . | |
178 | .IP "\fBlist\-ls\fR" | |
179 | Lists all existing logical switches on standard output, one per line. | |
180 | . | |
181 | .IP "\fBls\-exists \fIlswitch\fR" | |
182 | Tests whether \fIlswitch\fR exists. If so, \fBvtep\-ctl\fR exits | |
183 | successfully with exit code 0. If not, \fBvtep\-ctl\fR exits | |
184 | unsuccessfully with exit code 2. | |
185 | . | |
186 | .IP "\fBbind\-ls \fIpswitch port vlan lswitch\fR" | |
187 | Bind logical switch \fIlswitch\fR to the \fIport\fR/\fIvlan\fR | |
188 | combination on the physical switch \fIpswitch\fR. | |
189 | . | |
190 | .IP "\fBunbind\-ls \fIpswitch port vlan\fR" | |
191 | Remove the logical switch binding from the \fIport\fR/\fIvlan\fR | |
192 | combination on the physical switch \fIpswitch\fR. | |
193 | . | |
194 | .IP "\fBlist\-bindings \fIpswitch port\fR" | |
195 | List the logical switch bindings for \fIport\fR on the physical switch | |
196 | \fIpswitch\fR. | |
197 | . | |
b351ac0c DB |
198 | .IP "\fBset\-replication\-mode \fIlswitch replication\-mode\fR" |
199 | Set logical switch \fIlswitch\fR replication mode to | |
200 | \fIreplication\-mode\fR; the only valid values for replication mode | |
201 | are "service_node" and "source_node". | |
202 | . | |
203 | For handling L2 broadcast, multicast and unknown unicast traffic, | |
204 | packets can be sent to all members of a logical switch referenced by | |
205 | a physical switch. There are different modes to replicate the | |
206 | packets. The default mode of replication is to send the traffic to | |
207 | a service node, which can be a hypervisor, server or appliance, and | |
208 | let the service node handle replication to other transport nodes | |
209 | (hypervisors or other VTEP physical switches). This mode is called | |
210 | service node replication. An alternate mode of replication, called | |
211 | source node replication involves the source node sending to all | |
212 | other transport nodes. Hypervisors are always responsible for doing | |
213 | their own replication for locally attached VMs in both modes. | |
214 | Service node mode is the default, if the replication mode is not | |
215 | explicitly set. Service node replication mode is considered a basic | |
216 | requirement because it only requires sending the packet to a single | |
217 | transport node. | |
218 | . | |
219 | .IP "\fBget\-replication\-mode \fIlswitch\fR" | |
220 | Get logical switch \fIlswitch\fR replication mode. The only valid values | |
221 | for replication mode are "service_node" and "source_node". An empty reply | |
222 | for replication mode implies a default of "service_node". | |
223 | . | |
993225bd WZ |
224 | .SS "Logical Router Commands" |
225 | These commands examine and manipulate logical routers. | |
226 | . | |
227 | .IP "[\fB\-\-may\-exist\fR] \fBadd\-lr \fIlrouter\fR" | |
228 | Creates a new logical router named \fIlrouter\fR. | |
229 | .IP | |
230 | Without \fB\-\-may\-exist\fR, attempting to create a router that | |
231 | exists is an error. With \fB\-\-may\-exist\fR, this command does | |
232 | nothing if \fIlrouter\fR already exists. | |
233 | . | |
234 | .IP "[\fB\-\-if\-exists\fR] \fBdel\-lr \fIlrouter\fR" | |
235 | Deletes \fIlrouter\fR. | |
236 | .IP | |
237 | Without \fB\-\-if\-exists\fR, attempting to delete a router that does | |
238 | not exist is an error. With \fB\-\-if\-exists\fR, attempting to | |
239 | delete a router that does not exist has no effect. | |
240 | . | |
241 | .IP "\fBlist\-lr\fR" | |
242 | Lists all existing logical routers on standard output, one per line. | |
243 | . | |
244 | .IP "\fBlr\-exists \fIlrouter\fR" | |
245 | Tests whether \fIlrouter\fR exists. If so, \fBvtep\-ctl\fR exits | |
246 | successfully with exit code 0. If not, \fBvtep\-ctl\fR exits | |
247 | unsuccessfully with exit code 2. | |
248 | ||
ffc759c6 JP |
249 | .SS "Local MAC Binding Commands" |
250 | These commands examine and manipulate local MAC bindings for the logical | |
251 | switch. The local maps are written by the VTEP to refer to MACs it has | |
252 | learned on its physical ports. | |
253 | . | |
254 | .IP "\fBadd\-ucast\-local \fIlswitch mac\fR [\fIencap\fR] \fIip\fR" | |
255 | Map the unicast Ethernet address \fImac\fR to the physical location | |
256 | \fIip\fR using encapsulation \fIencap\fR on \fIlswitch\fR. If | |
257 | \fIencap\fR is not specified, the default is "vxlan_over_ipv4". The | |
258 | local mappings are used by the VTEP to refer to MACs learned on its | |
259 | physical ports. | |
260 | . | |
261 | .IP "\fBdel\-ucast\-local \fIlswitch mac\fR" | |
262 | Remove the local unicast Ethernet address \fImac\fR map from | |
263 | \fIlswitch\fR. The local mappings are used by the VTEP to refer to MACs | |
264 | learned on its physical ports. | |
265 | . | |
266 | .IP "\fBadd\-mcast\-local \fIlswitch mac\fR [\fIencap\fR] \fIip\fR" | |
267 | Add physical location \fIip\fR using encapsulation \fIencap\fR to the | |
268 | local mac binding table for multicast Ethernet address \fImac\fR on | |
269 | \fIlswitch\fR. If \fIencap\fR is not specified, the default is | |
270 | "vxlan_over_ipv4". The local mappings are used by the VTEP to refer to | |
271 | MACs learned on its physical ports. | |
272 | . | |
273 | .IP "\fBdel\-mcast\-local \fIlswitch mac\fR [\fIencap\fR] \fIip\fR" | |
274 | Remove physical location \fIip\fR using encapsulation \fIencap\fR from | |
275 | the local mac binding table for multicast Ethernet address \fImac\fR on | |
276 | \fIlswitch\fR. If \fIencap\fR is not specified, the default is | |
277 | "vxlan_over_ipv4". The local mappings are used by the VTEP to refer to | |
278 | MACs learned on its physical ports. | |
279 | . | |
280 | .IP "\fBclear\-local\-macs \fIlswitch\fR" | |
281 | Clear the local MAC bindings for \fIlswitch\fR. | |
282 | . | |
283 | .IP "\fBlist\-local\-macs \fIlswitch\fR" | |
284 | List the local MAC bindings for \fIlswitch\fR, one per line. | |
285 | . | |
286 | .SS "Remote MAC Binding Commands" | |
287 | These commands examine and manipulate local and remote MAC bindings for | |
288 | the logical switch. The remote maps are written by the network | |
289 | virtualization controller to refer to MACs that it has learned. | |
290 | . | |
291 | .IP "\fBadd\-ucast\-remote \fIlswitch mac\fR [\fIencap\fR] \fIip\fR" | |
292 | Map the unicast Ethernet address \fImac\fR to the physical location | |
293 | \fIip\fR using encapsulation \fIencap\fR on \fIlswitch\fR. If | |
294 | \fIencap\fR is not specified, the default is "vxlan_over_ipv4". The | |
295 | remote mappings are used by the network virtualization platform to refer | |
296 | to MACs that it has learned. | |
297 | . | |
298 | .IP "\fBdel\-ucast\-remote \fIlswitch mac\fR" | |
299 | Remove the remote unicast Ethernet address \fImac\fR map from | |
300 | \fIlswitch\fR. The remote mappings are used by the network | |
301 | virtualization platform to refer to MACs that it has learned. | |
302 | . | |
303 | .IP "\fBadd\-mcast\-remote \fIlswitch mac\fR [\fIencap\fR] \fIip\fR" | |
304 | Add physical location \fIip\fR using encapsulation \fIencap\fR to the | |
305 | remote mac binding table for multicast Ethernet address \fImac\fR on | |
306 | \fIlswitch\fR. If \fIencap\fR is not specified, the default is | |
307 | "vxlan_over_ipv4". The remote mappings are used by the network | |
308 | virtualization platform to refer to MACs that it has learned. | |
309 | . | |
310 | .IP "\fBdel\-mcast\-remote \fIlswitch mac\fR [\fIencap\fR] \fIip\fR" | |
311 | Remove physical location \fIip\fR using encapsulation \fIencap\fR from | |
312 | the remote mac binding table for multicast Ethernet address \fImac\fR on | |
313 | \fIlswitch\fR. If \fIencap\fR is not specified, the default is | |
314 | "vxlan_over_ipv4". The remote mappings are used by the network | |
315 | virtualization platform to refer to MACs that it has learned. | |
316 | . | |
317 | .IP "\fBclear\-remote\-macs \fIlswitch\fR" | |
318 | Clear the remote MAC bindings for \fIlswitch\fR. | |
319 | . | |
320 | .IP "\fBlist\-remote\-macs \fIlswitch\fR" | |
321 | List the remote MAC bindings for \fIlswitch\fR, one per line. | |
322 | . | |
323 | .SS "Manager Connectivity" | |
324 | . | |
325 | These commands manipulate the \fBmanagers\fR column in the \fBGlobal\fR | |
326 | table and rows in the \fBManagers\fR table. When \fBovsdb\-server\fR is | |
327 | configured to use the \fBmanagers\fR column for OVSDB connections (as | |
795752a3 SF |
328 | described in the startup scripts provided with Open vSwitch), this |
329 | allows the administrator to use \fBvtep\-ctl\fR to configure database | |
330 | connections. | |
ffc759c6 JP |
331 | . |
332 | .IP "\fBget\-manager\fR" | |
333 | Prints the configured manager(s). | |
334 | . | |
335 | .IP "\fBdel\-manager\fR" | |
336 | Deletes the configured manager(s). | |
337 | . | |
338 | .IP "\fBset\-manager\fR \fItarget\fR\&..." | |
339 | Sets the configured manager target or targets. Each \fItarget\fR may | |
340 | use any of the following forms: | |
341 | . | |
342 | .RS | |
343 | .so ovsdb/remote-active.man | |
344 | .so ovsdb/remote-passive.man | |
345 | .RE | |
346 | . | |
347 | .SS "Database Commands" | |
348 | . | |
349 | These commands query and modify the contents of \fBovsdb\fR tables. | |
350 | They are a slight abstraction of the \fBovsdb\fR interface and as such | |
351 | they operate at a lower level than other \fBvtep\-ctl\fR commands. | |
352 | .PP | |
353 | .ST "Identifying Tables, Records, and Columns" | |
354 | .PP | |
355 | Each of these commands has a \fItable\fR parameter to identify a table | |
356 | within the database. Many of them also take a \fIrecord\fR parameter | |
357 | that identifies a particular record within a table. The \fIrecord\fR | |
358 | parameter may be the UUID for a record, and many tables offer | |
359 | additional ways to identify records. Some commands also take | |
360 | \fIcolumn\fR parameters that identify a particular field within the | |
361 | records in a table. | |
362 | .PP | |
363 | The following tables are currently defined: | |
364 | .IP "\fBGlobal\fR" | |
365 | Top-level configuration for a hardware VTEP. This table contains | |
366 | exactly one record, identified by specifying \fB.\fR as the record name. | |
367 | .IP "\fBManager\fR" | |
368 | Configuration for an OVSDB connection. Records may be identified | |
369 | by target (e.g. \fBtcp:1.2.3.4\fR). | |
370 | .IP "\fBPhysical_Switch\fR" | |
371 | A physical switch that implements a VTEP. Records may be identified by | |
372 | physical switch name. | |
373 | .IP "\fBPhysical_Port\fR" | |
374 | A port within a physical switch. | |
375 | .IP "\fBLogical_Binding_Stats\fR" | |
376 | Reports statistics for the logical switch with which a VLAN on a | |
377 | physical port is associated. | |
378 | .IP "\fBLogical_Switch\fR" | |
379 | A logical Ethernet switch. Records may be identified by logical switch | |
380 | name. | |
381 | .IP "\fBUcast_Macs_Local\fR" | |
382 | Mapping of locally discovered unicast MAC addresses to tunnels. | |
383 | .IP "\fBUcast_Macs_Remote\fR" | |
384 | Mapping of remotely programmed unicast MAC addresses to tunnels. | |
385 | .IP "\fBMcast_Macs_Local\fR" | |
386 | Mapping of locally discovered multicast MAC addresses to tunnels. | |
387 | .IP "\fBMcast_Macs_Remote\fR" | |
388 | Mapping of remotely programmed multicast MAC addresses to tunnels. | |
389 | .IP "\fBPhysical_Locator_Set\fR" | |
390 | A set of one or more physical locators. | |
391 | .IP "\fBPhysical_Locator\fR" | |
392 | Identifies an endpoint to which logical switch traffic may be | |
393 | encapsulated and forwarded. Records may be identified by physical | |
394 | locator name. | |
395 | .PP | |
396 | Record names must be specified in full and with correct | |
4e3000a0 BP |
397 | capitalization, except that UUIDs may be abbreviated to their first 4 |
398 | (or more) hex digits, as long as that is unique within the table. | |
399 | Names of tables and columns are not case-sensitive, and \fB\-\fR and | |
400 | \fB_\fR are treated interchangeably. Unique abbreviations of table | |
401 | and column names are acceptable, e.g. \fBman\fR or \fBm\fR is | |
402 | sufficient to identify the \fBManager\fR table. | |
ffc759c6 | 403 | . |
3935f67d | 404 | .so lib/db-ctl-base.man |
ffc759c6 JP |
405 | .PP |
406 | .SH "EXIT STATUS" | |
407 | .IP "0" | |
408 | Successful program execution. | |
409 | .IP "1" | |
410 | Usage, syntax, or configuration file error. | |
411 | .IP "2" | |
412 | The \fIswitch\fR argument to \fBps\-exists\fR specified the name of a | |
413 | physical switch that does not exist. | |
414 | .SH "SEE ALSO" | |
415 | . | |
416 | .BR ovsdb\-server (1), | |
417 | .BR vtep (5). |