]>
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 | . | |
198 | .SS "Local MAC Binding Commands" | |
199 | These commands examine and manipulate local MAC bindings for the logical | |
200 | switch. The local maps are written by the VTEP to refer to MACs it has | |
201 | learned on its physical ports. | |
202 | . | |
203 | .IP "\fBadd\-ucast\-local \fIlswitch mac\fR [\fIencap\fR] \fIip\fR" | |
204 | Map the unicast Ethernet address \fImac\fR to the physical location | |
205 | \fIip\fR using encapsulation \fIencap\fR on \fIlswitch\fR. If | |
206 | \fIencap\fR is not specified, the default is "vxlan_over_ipv4". The | |
207 | local mappings are used by the VTEP to refer to MACs learned on its | |
208 | physical ports. | |
209 | . | |
210 | .IP "\fBdel\-ucast\-local \fIlswitch mac\fR" | |
211 | Remove the local unicast Ethernet address \fImac\fR map from | |
212 | \fIlswitch\fR. The local mappings are used by the VTEP to refer to MACs | |
213 | learned on its physical ports. | |
214 | . | |
215 | .IP "\fBadd\-mcast\-local \fIlswitch mac\fR [\fIencap\fR] \fIip\fR" | |
216 | Add physical location \fIip\fR using encapsulation \fIencap\fR to the | |
217 | local mac binding table for multicast Ethernet address \fImac\fR on | |
218 | \fIlswitch\fR. If \fIencap\fR is not specified, the default is | |
219 | "vxlan_over_ipv4". The local mappings are used by the VTEP to refer to | |
220 | MACs learned on its physical ports. | |
221 | . | |
222 | .IP "\fBdel\-mcast\-local \fIlswitch mac\fR [\fIencap\fR] \fIip\fR" | |
223 | Remove physical location \fIip\fR using encapsulation \fIencap\fR from | |
224 | the local mac binding table for multicast Ethernet address \fImac\fR on | |
225 | \fIlswitch\fR. If \fIencap\fR is not specified, the default is | |
226 | "vxlan_over_ipv4". The local mappings are used by the VTEP to refer to | |
227 | MACs learned on its physical ports. | |
228 | . | |
229 | .IP "\fBclear\-local\-macs \fIlswitch\fR" | |
230 | Clear the local MAC bindings for \fIlswitch\fR. | |
231 | . | |
232 | .IP "\fBlist\-local\-macs \fIlswitch\fR" | |
233 | List the local MAC bindings for \fIlswitch\fR, one per line. | |
234 | . | |
235 | .SS "Remote MAC Binding Commands" | |
236 | These commands examine and manipulate local and remote MAC bindings for | |
237 | the logical switch. The remote maps are written by the network | |
238 | virtualization controller to refer to MACs that it has learned. | |
239 | . | |
240 | .IP "\fBadd\-ucast\-remote \fIlswitch mac\fR [\fIencap\fR] \fIip\fR" | |
241 | Map the unicast Ethernet address \fImac\fR to the physical location | |
242 | \fIip\fR using encapsulation \fIencap\fR on \fIlswitch\fR. If | |
243 | \fIencap\fR is not specified, the default is "vxlan_over_ipv4". The | |
244 | remote mappings are used by the network virtualization platform to refer | |
245 | to MACs that it has learned. | |
246 | . | |
247 | .IP "\fBdel\-ucast\-remote \fIlswitch mac\fR" | |
248 | Remove the remote unicast Ethernet address \fImac\fR map from | |
249 | \fIlswitch\fR. The remote mappings are used by the network | |
250 | virtualization platform to refer to MACs that it has learned. | |
251 | . | |
252 | .IP "\fBadd\-mcast\-remote \fIlswitch mac\fR [\fIencap\fR] \fIip\fR" | |
253 | Add physical location \fIip\fR using encapsulation \fIencap\fR to the | |
254 | remote mac binding table for multicast Ethernet address \fImac\fR on | |
255 | \fIlswitch\fR. If \fIencap\fR is not specified, the default is | |
256 | "vxlan_over_ipv4". The remote mappings are used by the network | |
257 | virtualization platform to refer to MACs that it has learned. | |
258 | . | |
259 | .IP "\fBdel\-mcast\-remote \fIlswitch mac\fR [\fIencap\fR] \fIip\fR" | |
260 | Remove physical location \fIip\fR using encapsulation \fIencap\fR from | |
261 | the remote mac binding table for multicast Ethernet address \fImac\fR on | |
262 | \fIlswitch\fR. If \fIencap\fR is not specified, the default is | |
263 | "vxlan_over_ipv4". The remote mappings are used by the network | |
264 | virtualization platform to refer to MACs that it has learned. | |
265 | . | |
266 | .IP "\fBclear\-remote\-macs \fIlswitch\fR" | |
267 | Clear the remote MAC bindings for \fIlswitch\fR. | |
268 | . | |
269 | .IP "\fBlist\-remote\-macs \fIlswitch\fR" | |
270 | List the remote MAC bindings for \fIlswitch\fR, one per line. | |
271 | . | |
272 | .SS "Manager Connectivity" | |
273 | . | |
274 | These commands manipulate the \fBmanagers\fR column in the \fBGlobal\fR | |
275 | table and rows in the \fBManagers\fR table. When \fBovsdb\-server\fR is | |
276 | configured to use the \fBmanagers\fR column for OVSDB connections (as | |
277 | described in \fBINSTALL.Linux\fR and in the startup scripts provided | |
278 | with Open vSwitch), this allows the administrator to use \fBvtep\-ctl\fR | |
279 | to configure database connections. | |
280 | . | |
281 | .IP "\fBget\-manager\fR" | |
282 | Prints the configured manager(s). | |
283 | . | |
284 | .IP "\fBdel\-manager\fR" | |
285 | Deletes the configured manager(s). | |
286 | . | |
287 | .IP "\fBset\-manager\fR \fItarget\fR\&..." | |
288 | Sets the configured manager target or targets. Each \fItarget\fR may | |
289 | use any of the following forms: | |
290 | . | |
291 | .RS | |
292 | .so ovsdb/remote-active.man | |
293 | .so ovsdb/remote-passive.man | |
294 | .RE | |
295 | . | |
296 | .SS "Database Commands" | |
297 | . | |
298 | These commands query and modify the contents of \fBovsdb\fR tables. | |
299 | They are a slight abstraction of the \fBovsdb\fR interface and as such | |
300 | they operate at a lower level than other \fBvtep\-ctl\fR commands. | |
301 | .PP | |
302 | .ST "Identifying Tables, Records, and Columns" | |
303 | .PP | |
304 | Each of these commands has a \fItable\fR parameter to identify a table | |
305 | within the database. Many of them also take a \fIrecord\fR parameter | |
306 | that identifies a particular record within a table. The \fIrecord\fR | |
307 | parameter may be the UUID for a record, and many tables offer | |
308 | additional ways to identify records. Some commands also take | |
309 | \fIcolumn\fR parameters that identify a particular field within the | |
310 | records in a table. | |
311 | .PP | |
312 | The following tables are currently defined: | |
313 | .IP "\fBGlobal\fR" | |
314 | Top-level configuration for a hardware VTEP. This table contains | |
315 | exactly one record, identified by specifying \fB.\fR as the record name. | |
316 | .IP "\fBManager\fR" | |
317 | Configuration for an OVSDB connection. Records may be identified | |
318 | by target (e.g. \fBtcp:1.2.3.4\fR). | |
319 | .IP "\fBPhysical_Switch\fR" | |
320 | A physical switch that implements a VTEP. Records may be identified by | |
321 | physical switch name. | |
322 | .IP "\fBPhysical_Port\fR" | |
323 | A port within a physical switch. | |
324 | .IP "\fBLogical_Binding_Stats\fR" | |
325 | Reports statistics for the logical switch with which a VLAN on a | |
326 | physical port is associated. | |
327 | .IP "\fBLogical_Switch\fR" | |
328 | A logical Ethernet switch. Records may be identified by logical switch | |
329 | name. | |
330 | .IP "\fBUcast_Macs_Local\fR" | |
331 | Mapping of locally discovered unicast MAC addresses to tunnels. | |
332 | .IP "\fBUcast_Macs_Remote\fR" | |
333 | Mapping of remotely programmed unicast MAC addresses to tunnels. | |
334 | .IP "\fBMcast_Macs_Local\fR" | |
335 | Mapping of locally discovered multicast MAC addresses to tunnels. | |
336 | .IP "\fBMcast_Macs_Remote\fR" | |
337 | Mapping of remotely programmed multicast MAC addresses to tunnels. | |
338 | .IP "\fBPhysical_Locator_Set\fR" | |
339 | A set of one or more physical locators. | |
340 | .IP "\fBPhysical_Locator\fR" | |
341 | Identifies an endpoint to which logical switch traffic may be | |
342 | encapsulated and forwarded. Records may be identified by physical | |
343 | locator name. | |
344 | .PP | |
345 | Record names must be specified in full and with correct | |
346 | capitalization. Names of tables and columns are not case-sensitive, | |
347 | and \fB\-\-\fR and \fB_\fR are treated interchangeably. Unique | |
348 | abbreviations are acceptable, e.g. \fBman\fR or \fBm\fR is sufficient | |
349 | to identify the \fBManager\fR table. | |
350 | . | |
3935f67d | 351 | .so lib/db-ctl-base.man |
ffc759c6 JP |
352 | .PP |
353 | .SH "EXIT STATUS" | |
354 | .IP "0" | |
355 | Successful program execution. | |
356 | .IP "1" | |
357 | Usage, syntax, or configuration file error. | |
358 | .IP "2" | |
359 | The \fIswitch\fR argument to \fBps\-exists\fR specified the name of a | |
360 | physical switch that does not exist. | |
361 | .SH "SEE ALSO" | |
362 | . | |
363 | .BR ovsdb\-server (1), | |
364 | .BR vtep (5). |