]>
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 | . | |
351 | .ST "Database Values" | |
352 | .PP | |
353 | Each column in the database accepts a fixed type of data. The | |
354 | currently defined basic types, and their representations, are: | |
355 | .IP "integer" | |
356 | A decimal integer in the range \-2**63 to 2**63\-1, inclusive. | |
357 | .IP "real" | |
358 | A floating-point number. | |
359 | .IP "Boolean" | |
360 | True or false, written \fBtrue\fR or \fBfalse\fR, respectively. | |
361 | .IP "string" | |
362 | An arbitrary Unicode string, except that null bytes are not allowed. | |
363 | Quotes are optional for most strings that begin with an English letter | |
364 | or underscore and consist only of letters, underscores, hyphens, and | |
365 | periods. However, \fBtrue\fR and \fBfalse\fR and strings that match | |
366 | the syntax of UUIDs (see below) must be enclosed in double quotes to | |
367 | distinguish them from other basic types. When double quotes are used, | |
368 | the syntax is that of strings in JSON, e.g. backslashes may be used to | |
369 | escape special characters. The empty string must be represented as a | |
370 | pair of double quotes (\fB""\fR). | |
371 | .IP "UUID" | |
372 | Either a universally unique identifier in the style of RFC 4122, | |
373 | e.g. \fBf81d4fae\-7dec\-11d0\-a765\-00a0c91e6bf6\fR, or an \fB@\fIname\fR | |
374 | defined by a \fBget\fR or \fBcreate\fR command within the same \fBvtep\-ctl\fR | |
375 | invocation. | |
376 | .PP | |
377 | Multiple values in a single column may be separated by spaces or a | |
378 | single comma. When multiple values are present, duplicates are not | |
379 | allowed, and order is not important. Conversely, some database | |
380 | columns can have an empty set of values, represented as \fB[]\fR, and | |
381 | square brackets may optionally enclose other non-empty sets or single | |
382 | values as well. | |
383 | .PP | |
384 | A few database columns are ``maps'' of key-value pairs, where the key | |
385 | and the value are each some fixed database type. These are specified | |
386 | in the form \fIkey\fB=\fIvalue\fR, where \fIkey\fR and \fIvalue\fR | |
387 | follow the syntax for the column's key type and value type, | |
388 | respectively. When multiple pairs are present (separated by spaces or | |
389 | a comma), duplicate keys are not allowed, and again the order is not | |
390 | important. Duplicate values are allowed. An empty map is represented | |
391 | as \fB{}\fR. Curly braces may optionally enclose non-empty maps as | |
392 | well (but use quotes to prevent the shell from expanding | |
393 | \fBother-config={0=x,1=y}\fR into \fBother-config=0=x | |
394 | other-config=1=y\fR, which may not have the desired effect). | |
395 | . | |
396 | .ST "Database Command Syntax" | |
397 | .IP "[\fB\-\-columns=\fIcolumn\fR[\fB,\fIcolumn\fR]...] \fBlist \fItable \fR[\fIrecord\fR]..." | |
398 | Lists the data in each specified \fIrecord\fR. If no | |
399 | records are specified, lists all the records in \fItable\fR. | |
400 | .IP | |
401 | If \fB\-\-columns\fR is specified, only the requested columns are | |
402 | listed, in the specified order. Otherwise, all columns are listed, in | |
403 | alphabetical order by column name. | |
404 | . | |
405 | .IP "[\fB\-\-columns=\fIcolumn\fR[\fB,\fIcolumn\fR]...] \fBfind \fItable \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR]..." | |
406 | Lists the data in each record in \fItable\fR whose \fIcolumn\fR equals | |
407 | \fIvalue\fR or, if \fIkey\fR is specified, whose \fIcolumn\fR contains | |
408 | a \fIkey\fR with the specified \fIvalue\fR. The following operators | |
409 | may be used where \fB=\fR is written in the syntax summary: | |
410 | .RS | |
411 | .IP "\fB= != < > <= >=\fR" | |
412 | Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] equals, does not | |
413 | equal, is less than, is greater than, is less than or equal to, or is | |
414 | greater than or equal to \fIvalue\fR, respectively. | |
415 | .IP | |
416 | Consider \fIcolumn\fR[\fB:\fIkey\fR] and \fIvalue\fR as sets of | |
417 | elements. Identical sets are considered equal. Otherwise, if the | |
418 | sets have different numbers of elements, then the set with more | |
419 | elements is considered to be larger. Otherwise, consider a element | |
420 | from each set pairwise, in increasing order within each set. The | |
421 | first pair that differs determines the result. (For a column that | |
422 | contains key-value pairs, first all the keys are compared, and values | |
423 | are considered only if the two sets contain identical keys.) | |
424 | .IP "\fB{=} {!=}\fR" | |
425 | Test for set equality or inequality, respectively. | |
426 | .IP "\fB{<=}\fR" | |
427 | Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] is a subset of | |
428 | \fIvalue\fR. For example, \fBflood-vlans{<=}1,2\fR selects records in | |
429 | which the \fBflood-vlans\fR column is the empty set or contains 1 or 2 | |
430 | or both. | |
431 | .IP "\fB{<}\fR" | |
432 | Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] is a proper | |
433 | subset of \fIvalue\fR. For example, \fBflood-vlans{<}1,2\fR selects | |
434 | records in which the \fBflood-vlans\fR column is the empty set or | |
435 | contains 1 or 2 but not both. | |
436 | .IP "\fB{>=} {>}\fR" | |
437 | Same as \fB{<=}\fR and \fB{<}\fR, respectively, except that the | |
438 | relationship is reversed. For example, \fBflood-vlans{>=}1,2\fR | |
439 | selects records in which the \fBflood-vlans\fR column contains both 1 | |
440 | and 2. | |
441 | .RE | |
442 | .IP | |
443 | For arithmetic operators (\fB= != < > <= >=\fR), when \fIkey\fR is | |
444 | specified but a particular record's \fIcolumn\fR does not contain | |
445 | \fIkey\fR, the record is always omitted from the results. Thus, the | |
446 | condition \fBother-config:mtu!=1500\fR matches records that have a | |
447 | \fBmtu\fR key whose value is not 1500, but not those that lack an | |
448 | \fBmtu\fR key. | |
449 | .IP | |
450 | For the set operators, when \fIkey\fR is specified but a particular | |
451 | record's \fIcolumn\fR does not contain \fIkey\fR, the comparison is | |
452 | done against an empty set. Thus, the condition | |
453 | \fBother-config:mtu{!=}1500\fR matches records that have a \fBmtu\fR | |
454 | key whose value is not 1500 and those that lack an \fBmtu\fR key. | |
455 | .IP | |
456 | Don't forget to escape \fB<\fR or \fB>\fR from interpretation by the | |
457 | shell. | |
458 | .IP | |
459 | If \fB\-\-columns\fR is specified, only the requested columns are | |
460 | listed, in the specified order. Otherwise all columns are listed, in | |
461 | alphabetical order by column name. | |
462 | .IP | |
463 | The UUIDs shown for rows created in the same \fBvtep\-ctl\fR | |
464 | invocation will be wrong. | |
465 | . | |
466 | .IP "[\fB\-\-id=@\fIname\fR] [\fB\-\-if\-exists\fR] \fBget \fItable record \fR[\fIcolumn\fR[\fB:\fIkey\fR]]..." | |
467 | Prints the value of each specified \fIcolumn\fR in the given | |
468 | \fIrecord\fR in \fItable\fR. For map columns, a \fIkey\fR may | |
469 | optionally be specified, in which case the value associated with | |
470 | \fIkey\fR in the column is printed, instead of the entire map. | |
471 | .IP | |
472 | For a map column, without \fB\-\-if\-exists\fR it is an error if | |
473 | \fIkey\fR does not exist; with it, a blank line is printed. If | |
474 | \fIcolumn\fR is not a map column or if \fIkey\fR is not specified, | |
475 | \fB\-\-if\-exists\fR has no effect. | |
476 | .IP | |
477 | If \fB@\fIname\fR is specified, then the UUID for \fIrecord\fR may be | |
478 | referred to by that name later in the same \fBvtep\-ctl\fR | |
479 | invocation in contexts where a UUID is expected. | |
480 | .IP | |
481 | Both \fB\-\-id\fR and the \fIcolumn\fR arguments are optional, but | |
482 | usually at least one or the other should be specified. If both are | |
483 | omitted, then \fBget\fR has no effect except to verify that | |
484 | \fIrecord\fR exists in \fItable\fR. | |
485 | . | |
486 | .IP "\fBset \fItable record column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..." | |
487 | Sets the value of each specified \fIcolumn\fR in the given | |
488 | \fIrecord\fR in \fItable\fR to \fIvalue\fR. For map columns, a | |
489 | \fIkey\fR may optionally be specified, in which case the value | |
490 | associated with \fIkey\fR in that column is changed (or added, if none | |
491 | exists), instead of the entire map. | |
492 | . | |
493 | .IP "\fBadd \fItable record column \fR[\fIkey\fB=\fR]\fIvalue\fR..." | |
494 | Adds the specified value or key-value pair to \fIcolumn\fR in | |
495 | \fIrecord\fR in \fItable\fR. If \fIcolumn\fR is a map, then \fIkey\fR | |
496 | is required, otherwise it is prohibited. If \fIkey\fR already exists | |
497 | in a map column, then the current \fIvalue\fR is not replaced (use the | |
498 | \fBset\fR command to replace an existing value). | |
499 | . | |
500 | .IP "\fBremove \fItable record column \fR\fIvalue\fR..." | |
501 | .IQ "\fBremove \fItable record column \fR\fIkey\fR..." | |
502 | .IQ "\fBremove \fItable record column \fR\fIkey\fB=\fR\fIvalue\fR..." | |
503 | Removes the specified values or key-value pairs from \fIcolumn\fR in | |
504 | \fIrecord\fR in \fItable\fR. The first form applies to columns that | |
505 | are not maps: each specified \fIvalue\fR is removed from the column. | |
506 | The second and third forms apply to map columns: if only a \fIkey\fR | |
507 | is specified, then any key-value pair with the given \fIkey\fR is | |
508 | removed, regardless of its value; if a \fIvalue\fR is given then a | |
509 | pair is removed only if both key and value match. | |
510 | .IP | |
511 | It is not an error if the column does not contain the specified key or | |
512 | value or pair. | |
513 | . | |
514 | .IP "\fBclear\fR \fItable record column\fR..." | |
515 | Sets each \fIcolumn\fR in \fIrecord\fR in \fItable\fR to the empty set | |
516 | or empty map, as appropriate. This command applies only to columns | |
517 | that are allowed to be empty. | |
518 | . | |
519 | .IP "[\fB\-\-id=@\fIname\fR] \fBcreate\fR \fItable column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..." | |
520 | Creates a new record in \fItable\fR and sets the initial values of | |
521 | each \fIcolumn\fR. Columns not explicitly set will receive their | |
522 | default values. Outputs the UUID of the new row. | |
523 | .IP | |
524 | If \fB@\fIname\fR is specified, then the UUID for the new row may be | |
525 | referred to by that name elsewhere in the same \fBvtep\-ctl\fR | |
526 | invocation in contexts where a UUID is expected. Such references may | |
527 | precede or follow the \fBcreate\fR command. | |
528 | .IP | |
529 | Records in the Open vSwitch database are significant only when they | |
530 | can be reached directly or indirectly from the \fBOpen_vSwitch\fR | |
531 | table. Except for records in the \fBQoS\fR or \fBQueue\fR tables, | |
532 | records that are not reachable from the \fBOpen_vSwitch\fR table are | |
533 | automatically deleted from the database. This deletion happens | |
534 | immediately, without waiting for additional \fBvtep\-ctl\fR commands | |
535 | or other database activity. Thus, a \fBcreate\fR command must | |
536 | generally be accompanied by additional commands \fIwithin the same | |
537 | \fBvtep\-ctl\fI invocation\fR to add a chain of references to the | |
538 | newly created record from the top-level \fBOpen_vSwitch\fR record. | |
539 | The \fBEXAMPLES\fR section gives some examples that show how to do | |
540 | this. | |
541 | . | |
542 | .IP "\fR[\fB\-\-if\-exists\fR] \fBdestroy \fItable record\fR..." | |
543 | Deletes each specified \fIrecord\fR from \fItable\fR. Unless | |
544 | \fB\-\-if\-exists\fR is specified, each \fIrecord\fRs must exist. | |
545 | .IP "\fB\-\-all destroy \fItable\fR" | |
546 | Deletes all records from the \fItable\fR. | |
547 | .IP | |
548 | The \fBdestroy\fR command is only useful for records in the \fBQoS\fR | |
549 | or \fBQueue\fR tables. Records in other tables are automatically | |
550 | deleted from the database when they become unreachable from the | |
551 | \fBOpen_vSwitch\fR table. This means that deleting the last reference | |
552 | to a record is sufficient for deleting the record itself. For records | |
553 | in these tables, \fBdestroy\fR is silently ignored. See the | |
554 | \fBEXAMPLES\fR section below for more information. | |
555 | . | |
556 | .IP "\fBwait\-until \fItable record \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR]..." | |
557 | Waits until \fItable\fR contains a record named \fIrecord\fR whose | |
558 | \fIcolumn\fR equals \fIvalue\fR or, if \fIkey\fR is specified, whose | |
559 | \fIcolumn\fR contains a \fIkey\fR with the specified \fIvalue\fR. Any | |
560 | of the operators \fB!=\fR, \fB<\fR, \fB>\fR, \fB<=\fR, or \fB>=\fR may | |
561 | be substituted for \fB=\fR to test for inequality, less than, greater | |
562 | than, less than or equal to, or greater than or equal to, | |
563 | respectively. (Don't forget to escape \fB<\fR or \fB>\fR from | |
564 | interpretation by the shell.) | |
565 | .IP | |
566 | If no \fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR arguments are given, | |
567 | this command waits only until \fIrecord\fR exists. If more than one | |
568 | such argument is given, the command waits until all of them are | |
569 | satisfied. | |
570 | .IP | |
571 | Consider specifying \fB\-\-timeout=0\fR along with | |
572 | \fB\-\-wait\-until\fR, to prevent \fBvtep\-ctl\fR from terminating | |
573 | after waiting only at most 5 seconds. | |
574 | .IP "\fBcomment \fR[\fIarg\fR]..." | |
575 | This command has no effect on behavior, but any database log record | |
576 | created by the command will include the command and its arguments. | |
577 | .PP | |
578 | .SH "EXIT STATUS" | |
579 | .IP "0" | |
580 | Successful program execution. | |
581 | .IP "1" | |
582 | Usage, syntax, or configuration file error. | |
583 | .IP "2" | |
584 | The \fIswitch\fR argument to \fBps\-exists\fR specified the name of a | |
585 | physical switch that does not exist. | |
586 | .SH "SEE ALSO" | |
587 | . | |
588 | .BR ovsdb\-server (1), | |
589 | .BR vtep (5). |