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