1vtep-ctl(8) Open vSwitch Manual vtep-ctl(8)
2
6 vtep-ctl - utility for querying and configuring a VTEP database
7
9 vtep-ctl [options] -- [options] command [args] [-- [options] command
10 [args]]...
11
13 The vtep-ctl program configures a VTEP database. See vtep(5) for com‐
14 prehensive documentation of the database schema.
15 vtep-ctl connects to an ovsdb-server process that maintains a VTEP con‐
17 figuration database. Using this connection, it queries and possibly
18 applies changes to the database, depending on the supplied commands.
19 vtep-ctl can perform any number of commands in a single run, imple‐
21 mented as a single atomic transaction against the database.
22 The vtep-ctl command line begins with global options (see OPTIONS below
24 for details). The global options are followed by one or more commands.
25 Each command should begin with -- by itself as a command-line argument,
26 to separate it from the following commands. (The -- before the first
27 command is optional.) The command itself starts with command-specific
28 options, if any, followed by the command name and any arguments. See
29 EXAMPLES below for syntax examples.
30
32 The following options affect the behavior vtep-ctl as a whole. Some
33 individual commands also accept their own options, which are given just
34 before the command name. If the first command on the command line has
35 options, then those options must be separated from the global options
36 by --.
37 --db=server
39 Sets server as the database server that vtep-ctl contacts to
40 query or modify configuration. server may be an OVSDB active or
41 passive connection method, as described in ovsdb(7). The de‐
42 fault is unix:/var/run/openvswitch/db.sock.
43 --no-syslog
45 By default, vtep-ctl logs its arguments and the details of any
46 changes that it makes to the system log. This option disables
47 this logging.
48 This option is equivalent to --verbose=vtep_ctl:syslog:warn.
50 --oneline
52 Modifies the output format so that the output for each command
53 is printed on a single line. New-line characters that would
54 otherwise separate lines are printed as \n, and any instances of
55 \ that would otherwise appear in the output are doubled. Prints
56 a blank line for each command that has no output. This option
57 does not affect the formatting of output from the list or find
58 commands; see Table Formatting Options below.
59 --dry-run
61 Prevents vtep-ctl from actually modifying the database.
62 -t secs
64 --timeout=secs
65 By default, or with a secs of 0, vtep-ctl waits forever for a
66 response from the database. This option limits runtime to ap‐
67 proximately secs seconds. If the timeout expires, vtep-ctl will
68 exit with a SIGALRM signal. (A timeout would normally happen
69 only if the database cannot be contacted, or if the system is
70 overloaded.)
71 Table Formatting Options
73 These options control the format of output from the list and find com‐
74 mands.
75 -f format
77 --format=format
78 Sets the type of table formatting. The following types of for‐
79 mat are available:
80 table 2-D text tables with aligned columns.
82 list (default)
84 A list with one column per line and rows separated by a
85 blank line.
86 html HTML tables.
88 csv Comma-separated values as defined in RFC 4180.
90 json JSON format as defined in RFC 4627. The output is a se‐
92 quence of JSON objects, each of which corresponds to one
93 table. Each JSON object has the following members with
94 the noted values:
95 caption
97 The table's caption. This member is omitted if
98 the table has no caption.
99 headings
101 An array with one element per table column. Each
102 array element is a string giving the corresponding
103 column's heading.
104 data An array with one element per table row. Each el‐
106 ement is also an array with one element per table
107 column. The elements of this second-level array
108 are the cells that constitute the table. Cells
109 that represent OVSDB data or data types are ex‐
110 pressed in the format described in the OVSDB spec‐
111 ification; other cells are simply expressed as
112 text strings.
113 -d format
115 --data=format
116 Sets the formatting for cells within output tables unless the
117 table format is set to json, in which case json formatting is
118 always used when formatting cells. The following types of for‐
119 mat are available:
120 string (default)
122 The simple format described in the Database Values sec‐
123 tion of ovs-vsctl(8).
124 bare The simple format with punctuation stripped off: [] and
126 {} are omitted around sets, maps, and empty columns,
127 items within sets and maps are space-separated, and
128 strings are never quoted. This format may be easier for
129 scripts to parse.
130 json The RFC 4627 JSON format as described above.
132 --no-headings
134 This option suppresses the heading row that otherwise appears in
135 the first row of table output.
136 --pretty
138 By default, JSON in output is printed as compactly as possible.
139 This option causes JSON in output to be printed in a more read‐
140 able fashion. Members of objects and elements of arrays are
141 printed one per line, with indentation.
142 This option does not affect JSON in tables, which is always
144 printed compactly.
145 --bare Equivalent to --format=list --data=bare --no-headings.
147 --max-column-width=n
149 For table output only, limits the width of any column in the
150 output to n columns. Longer cell data is truncated to fit, as
151 necessary. Columns are always wide enough to display the column
152 names, if the heading row is printed.
153 Public Key Infrastructure Options
155 -p privkey.pem
156 --private-key=privkey.pem
157 Specifies a PEM file containing the private key used as
158 vtep-ctl's identity for outgoing SSL connections.
159 -c cert.pem
161 --certificate=cert.pem
162 Specifies a PEM file containing a certificate that certifies the
163 private key specified on -p or --private-key to be trustworthy.
164 The certificate must be signed by the certificate authority (CA)
165 that the peer in SSL connections will use to verify it.
166 -C cacert.pem
168 --ca-cert=cacert.pem
169 Specifies a PEM file containing the CA certificate that vtep-ctl
170 should use to verify certificates presented to it by SSL peers.
171 (This may be the same certificate that SSL peers use to verify
172 the certificate specified on -c or --certificate, or it may be a
173 different one, depending on the PKI design in use.)
174 -C none
176 --ca-cert=none
177 Disables verification of certificates presented by SSL peers.
178 This introduces a security risk, because it means that certifi‐
179 cates cannot be verified to be those of known trusted hosts.
180 --bootstrap-ca-cert=cacert.pem
182 When cacert.pem exists, this option has the same effect as -C or
183 --ca-cert. If it does not exist, then vtep-ctl will attempt to
184 obtain the CA certificate from the SSL peer on its first SSL
185 connection and save it to the named PEM file. If it is success‐
186 ful, it will immediately drop the connection and reconnect, and
187 from then on all SSL connections must be authenticated by a cer‐
188 tificate signed by the CA certificate thus obtained.
189 This option exposes the SSL connection to a man-in-the-middle
191 attack obtaining the initial CA certificate, but it may be use‐
192 ful for bootstrapping.
193 This option is only useful if the SSL peer sends its CA certifi‐
195 cate as part of the SSL certificate chain. The SSL protocol
196 does not require the server to send the CA certificate.
197 This option is mutually exclusive with -C and --ca-cert.
199 --peer-ca-cert=peer-cacert.pem
201 Specifies a PEM file that contains one or more additional cer‐
202 tificates to send to SSL peers. peer-cacert.pem should be the
203 CA certificate used to sign vtep-ctl's own certificate, that is,
204 the certificate specified on -c or --certificate. If vtep-ctl's
205 certificate is self-signed, then --certificate and
206 --peer-ca-cert should specify the same file.
207 This option is not useful in normal operation, because the SSL
209 peer must already have the CA certificate for the peer to have
210 any confidence in vtep-ctl's identity. However, this offers a
211 way for a new installation to bootstrap the CA certificate on
212 its first SSL connection.
213 -v[spec]
215 --verbose=[spec]
216 Sets logging levels. Without any spec, sets the log level for
217 every module and destination to dbg. Otherwise, spec is a list
218 of words separated by spaces or commas or colons, up to one from
219 each category below:
220 • A valid module name, as displayed by the vlog/list com‐
222 mand on ovs-appctl(8), limits the log level change to the
223 specified module.
224 • syslog, console, or file, to limit the log level change
226 to only to the system log, to the console, or to a file,
227 respectively. (If --detach is specified, vtep-ctl closes
228 its standard file descriptors, so logging to the console
229 will have no effect.)
230 On Windows platform, syslog is accepted as a word and is
232 only useful along with the --syslog-target option (the
233 word has no effect otherwise).
234 • off, emer, err, warn, info, or dbg, to control the log
236 level. Messages of the given severity or higher will be
237 logged, and messages of lower severity will be filtered
238 out. off filters out all messages. See ovs-appctl(8)
239 for a definition of each log level.
240 Case is not significant within spec.
242 Regardless of the log levels set for file, logging to a file
244 will not take place unless --log-file is also specified (see be‐
245 low).
246 For compatibility with older versions of OVS, any is accepted as
248 a word but has no effect.
249 -v
251 --verbose
252 Sets the maximum logging verbosity level, equivalent to --ver‐
253 bose=dbg.
254 -vPATTERN:destination:pattern
256 --verbose=PATTERN:destination:pattern
257 Sets the log pattern for destination to pattern. Refer to
258 ovs-appctl(8) for a description of the valid syntax for pattern.
259 -vFACILITY:facility
261 --verbose=FACILITY:facility
262 Sets the RFC5424 facility of the log message. facility can be
263 one of kern, user, mail, daemon, auth, syslog, lpr, news, uucp,
264 clock, ftp, ntp, audit, alert, clock2, local0, local1, local2,
265 local3, local4, local5, local6 or local7. If this option is not
266 specified, daemon is used as the default for the local system
267 syslog and local0 is used while sending a message to the target
268 provided via the --syslog-target option.
269 --log-file[=file]
271 Enables logging to a file. If file is specified, then it is
272 used as the exact name for the log file. The default log file
273 name used if file is omitted is /var/log/open‐
274 vswitch/vtep-ctl.log.
275 --syslog-target=host:port
277 Send syslog messages to UDP port on host, in addition to the
278 system syslog. The host must be a numerical IP address, not a
279 hostname.
280 --syslog-method=method
282 Specify method how syslog messages should be sent to syslog dae‐
283 mon. Following forms are supported:
284 • libc, use libc syslog() function. Downside of using this
286 options is that libc adds fixed prefix to every message
287 before it is actually sent to the syslog daemon over
288 /dev/log UNIX domain socket.
289 • unix:file, use UNIX domain socket directly. It is possi‐
291 ble to specify arbitrary message format with this option.
292 However, rsyslogd 8.9 and older versions use hard coded
293 parser function anyway that limits UNIX domain socket
294 use. If you want to use arbitrary message format with
295 older rsyslogd versions, then use UDP socket to localhost
296 IP address instead.
297 • udp:ip:port, use UDP socket. With this method it is pos‐
299 sible to use arbitrary message format also with older
300 rsyslogd. When sending syslog messages over UDP socket
301 extra precaution needs to be taken into account, for ex‐
302 ample, syslog daemon needs to be configured to listen on
303 the specified UDP port, accidental iptables rules could
304 be interfering with local syslog traffic and there are
305 some security considerations that apply to UDP sockets,
306 but do not apply to UNIX domain sockets.
307 • null, discards all messages logged to syslog.
309 The default is taken from the OVS_SYSLOG_METHOD environment
311 variable; if it is unset, the default is libc.
312 -h
314 --help Prints a brief help message to the console.
315 -V
317 --version
318 Prints version information to the console.
319
321 The commands implemented by vtep-ctl are described in the sections be‐
322 low.
323 Physical Switch Commands
325 These commands examine and manipulate physical switches.
326 [--may-exist] add-ps pswitch
328 Creates a new physical switch named pswitch. Initially the
329 switch will have no ports.
330 Without --may-exist, attempting to create a switch that exists
332 is an error. With --may-exist, this command does nothing if
333 pswitch already exists.
334 [--if-exists] del-ps pswitch
336 Deletes pswitch and all of its ports.
337 Without --if-exists, attempting to delete a switch that does not
339 exist is an error. With --if-exists, attempting to delete a
340 switch that does not exist has no effect.
341 list-ps
343 Lists all existing physical switches on standard output, one per
344 line.
345 ps-exists pswitch
347 Tests whether pswitch exists. If so, vtep-ctl exits success‐
348 fully with exit code 0. If not, vtep-ctl exits unsuccessfully
349 with exit code 2.
350 Port Commands
352 These commands examine and manipulate VTEP physical ports.
353 list-ports pswitch
355 Lists all of the ports within pswitch on standard output, one
356 per line.
357 [--may-exist] add-port pswitch port
359 Creates on pswitch a new port named port from the network device
360 of the same name.
361 Without --may-exist, attempting to create a port that exists is
363 an error. With --may-exist, this command does nothing if port
364 already exists on pswitch.
365 [--if-exists] del-port [pswitch] port
367 Deletes port. If pswitch is omitted, port is removed from what‐
368 ever switch contains it; if pswitch is specified, it must be the
369 switch that contains port.
370 Without --if-exists, attempting to delete a port that does not
372 exist is an error. With --if-exists, attempting to delete a
373 port that does not exist has no effect.
374 Logical Switch Commands
376 These commands examine and manipulate logical switches.
377 [--may-exist] add-ls lswitch
379 Creates a new logical switch named lswitch. Initially the
380 switch will have no locator bindings.
381 Without --may-exist, attempting to create a switch that exists
383 is an error. With --may-exist, this command does nothing if
384 lswitch already exists.
385 [--if-exists] del-ls lswitch
387 Deletes lswitch.
388 Without --if-exists, attempting to delete a switch that does not
390 exist is an error. With --if-exists, attempting to delete a
391 switch that does not exist has no effect.
392 list-ls
394 Lists all existing logical switches on standard output, one per
395 line.
396 ls-exists lswitch
398 Tests whether lswitch exists. If so, vtep-ctl exits success‐
399 fully with exit code 0. If not, vtep-ctl exits unsuccessfully
400 with exit code 2.
401 bind-ls pswitch port vlan lswitch
403 Bind logical switch lswitch to the port/vlan combination on the
404 physical switch pswitch.
405 unbind-ls pswitch port vlan
407 Remove the logical switch binding from the port/vlan combination
408 on the physical switch pswitch.
409 list-bindings pswitch port
411 List the logical switch bindings for port on the physical switch
412 pswitch.
413 set-replication-mode lswitch replication-mode
415 Set logical switch lswitch replication mode to replication-mode;
416 the only valid values for replication mode are "service_node"
417 and "source_node". For handling L2 broadcast, multicast and un‐
418 known unicast traffic, packets can be sent to all members of a
419 logical switch referenced by a physical switch. There are dif‐
420 ferent modes to replicate the packets. The default mode of
421 replication is to send the traffic to a service node, which can
422 be a hypervisor, server or appliance, and let the service node
423 handle replication to other transport nodes (hypervisors or
424 other VTEP physical switches). This mode is called service node
425 replication. An alternate mode of replication, called source
426 node replication involves the source node sending to all other
427 transport nodes. Hypervisors are always responsible for doing
428 their own replication for locally attached VMs in both modes.
429 Service node mode is the default, if the replication mode is not
430 explicitly set. Service node replication mode is considered a
431 basic requirement because it only requires sending the packet to
432 a single transport node.
433 get-replication-mode lswitch
435 Get logical switch lswitch replication mode. The only valid
436 values for replication mode are "service_node" and
437 "source_node". An empty reply for replication mode implies a
438 default of "service_node".
439 Logical Router Commands
441 These commands examine and manipulate logical routers.
442 [--may-exist] add-lr lrouter
444 Creates a new logical router named lrouter.
445 Without --may-exist, attempting to create a router that exists
447 is an error. With --may-exist, this command does nothing if
448 lrouter already exists.
449 [--if-exists] del-lr lrouter
451 Deletes lrouter.
452 Without --if-exists, attempting to delete a router that does not
454 exist is an error. With --if-exists, attempting to delete a
455 router that does not exist has no effect.
456 list-lr
458 Lists all existing logical routers on standard output, one per
459 line.
460 lr-exists lrouter
462 Tests whether lrouter exists. If so, vtep-ctl exits success‐
463 fully with exit code 0. If not, vtep-ctl exits unsuccessfully
464 with exit code 2.
465 Local MAC Binding Commands
468 These commands examine and manipulate local MAC bindings for the logi‐
469 cal switch. The local maps are written by the VTEP to refer to MACs it
470 has learned on its physical ports.
471 add-ucast-local lswitch mac [encap] ip
473 Map the unicast Ethernet address mac to the physical location ip
474 using encapsulation encap on lswitch. If encap is not speci‐
475 fied, the default is "vxlan_over_ipv4". The local mappings are
476 used by the VTEP to refer to MACs learned on its physical ports.
477 del-ucast-local lswitch mac
479 Remove the local unicast Ethernet address mac map from lswitch.
480 The local mappings are used by the VTEP to refer to MACs learned
481 on its physical ports.
482 add-mcast-local lswitch mac [encap] ip
484 Add physical location ip using encapsulation encap to the local
485 mac binding table for multicast Ethernet address mac on lswitch.
486 If encap is not specified, the default is "vxlan_over_ipv4".
487 The local mappings are used by the VTEP to refer to MACs learned
488 on its physical ports.
489 del-mcast-local lswitch mac [encap] ip
491 Remove physical location ip using encapsulation encap from the
492 local mac binding table for multicast Ethernet address mac on
493 lswitch. If encap is not specified, the default is
494 "vxlan_over_ipv4". The local mappings are used by the VTEP to
495 refer to MACs learned on its physical ports.
496 clear-local-macs lswitch
498 Clear the local MAC bindings for lswitch.
499 list-local-macs lswitch
501 List the local MAC bindings for lswitch, one per line.
502 Remote MAC Binding Commands
504 These commands examine and manipulate local and remote MAC bindings for
505 the logical switch. The remote maps are written by the network virtu‐
506 alization controller to refer to MACs that it has learned.
507 add-ucast-remote lswitch mac [encap] ip
509 Map the unicast Ethernet address mac to the physical location ip
510 using encapsulation encap on lswitch. If encap is not speci‐
511 fied, the default is "vxlan_over_ipv4". The remote mappings are
512 used by the network virtualization platform to refer to MACs
513 that it has learned.
514 del-ucast-remote lswitch mac
516 Remove the remote unicast Ethernet address mac map from lswitch.
517 The remote mappings are used by the network virtualization plat‐
518 form to refer to MACs that it has learned.
519 add-mcast-remote lswitch mac [encap] ip
521 Add physical location ip using encapsulation encap to the remote
522 mac binding table for multicast Ethernet address mac on lswitch.
523 If encap is not specified, the default is "vxlan_over_ipv4".
524 The remote mappings are used by the network virtualization plat‐
525 form to refer to MACs that it has learned.
526 del-mcast-remote lswitch mac [encap] ip
528 Remove physical location ip using encapsulation encap from the
529 remote mac binding table for multicast Ethernet address mac on
530 lswitch. If encap is not specified, the default is
531 "vxlan_over_ipv4". The remote mappings are used by the network
532 virtualization platform to refer to MACs that it has learned.
533 clear-remote-macs lswitch
535 Clear the remote MAC bindings for lswitch.
536 list-remote-macs lswitch
538 List the remote MAC bindings for lswitch, one per line.
539 Manager Connectivity
541 These commands manipulate the managers column in the Global table and
542 rows in the Managers table. When ovsdb-server is configured to use the
543 managers column for OVSDB connections (as described in the startup
544 scripts provided with Open vSwitch), this allows the administrator to
545 use vtep-ctl to configure database connections.
546 get-manager
548 Prints the configured manager(s).
549 del-manager
551 Deletes the configured manager(s).
552 set-manager target...
554 Sets the configured manager target or targets. Each target may
555 be an OVSDB active or passive connection method, e.g. pssl:6640,
556 as described in ovsdb(7).
557 Database Commands
559 These commands query and modify the contents of ovsdb tables. They are
560 a slight abstraction of the ovsdb interface and as such they operate at
561 a lower level than other vtep-ctl commands.
562 Identifying Tables, Records, and Columns
564 Each of these commands has a table parameter to identify a table within
566 the database. Many of them also take a record parameter that identi‐
567 fies a particular record within a table. The record parameter may be
568 the UUID for a record, and many tables offer additional ways to iden‐
569 tify records. Some commands also take column parameters that identify
570 a particular field within the records in a table.
571 The following tables are currently defined:
573 Global Top-level configuration for a hardware VTEP. This table con‐
575 tains exactly one record, identified by specifying . as the
576 record name.
577 Manager
579 Configuration for an OVSDB connection. Records may be identi‐
580 fied by target (e.g. tcp:1.2.3.4).
581 Physical_Switch
583 A physical switch that implements a VTEP. Records may be iden‐
584 tified by physical switch name.
585 Physical_Port
587 A port within a physical switch.
588 Logical_Binding_Stats
590 Reports statistics for the logical switch with which a VLAN on a
591 physical port is associated.
592 Logical_Switch
594 A logical Ethernet switch. Records may be identified by logical
595 switch name.
596 Ucast_Macs_Local
598 Mapping of locally discovered unicast MAC addresses to tunnels.
599 Ucast_Macs_Remote
601 Mapping of remotely programmed unicast MAC addresses to tunnels.
602 Mcast_Macs_Local
604 Mapping of locally discovered multicast MAC addresses to tun‐
605 nels.
606 Mcast_Macs_Remote
608 Mapping of remotely programmed multicast MAC addresses to tun‐
609 nels.
610 Physical_Locator_Set
612 A set of one or more physical locators.
613 Physical_Locator
615 Identifies an endpoint to which logical switch traffic may be
616 encapsulated and forwarded. Records may be identified by physi‐
617 cal locator name.
618 Record names must be specified in full and with correct capitalization,
620 except that UUIDs may be abbreviated to their first 4 (or more) hex
621 digits, as long as that is unique within the table. Names of tables
622 and columns are not case-sensitive, and - and _ are treated inter‐
623 changeably. Unique abbreviations of table and column names are accept‐
624 able, e.g. man or m is sufficient to identify the Manager table.
625 Database Values
627 Each column in the database accepts a fixed type of data. The cur‐
629 rently defined basic types, and their representations, are:
630 integer
632 A decimal integer in the range -2**63 to 2**63-1, inclusive.
633 real A floating-point number.
635 Boolean
637 True or false, written true or false, respectively.
638 string An arbitrary Unicode string, except that null bytes are not al‐
640 lowed. Quotes are optional for most strings that begin with an
641 English letter or underscore and consist only of letters, under‐
642 scores, hyphens, and periods. However, true and false and
643 strings that match the syntax of UUIDs (see below) must be en‐
644 closed in double quotes to distinguish them from other basic
645 types. When double quotes are used, the syntax is that of
646 strings in JSON, e.g. backslashes may be used to escape special
647 characters. The empty string must be represented as a pair of
648 double quotes ("").
649 UUID Either a universally unique identifier in the style of RFC 4122,
651 e.g. f81d4fae-7dec-11d0-a765-00a0c91e6bf6, or an @name defined
652 by a get or create command within the same vtep-ctl invocation.
653 Multiple values in a single column may be separated by spaces or a sin‐
655 gle comma. When multiple values are present, duplicates are not al‐
656 lowed, and order is not important. Conversely, some database columns
657 can have an empty set of values, represented as [], and square brackets
658 may optionally enclose other non-empty sets or single values as well.
659 For a column accepting a set of integers, database commands accept a
660 range. A range is represented by two integers separated by -. A range
661 is inclusive. A range has a maximum size of 4096 elements. If more ele‐
662 ments are needed, they can be specified in separate ranges.
663 A few database columns are ``maps'' of key-value pairs, where the key
665 and the value are each some fixed database type. These are specified
666 in the form key=value, where key and value follow the syntax for the
667 column's key type and value type, respectively. When multiple pairs
668 are present (separated by spaces or a comma), duplicate keys are not
669 allowed, and again the order is not important. Duplicate values are
670 allowed. An empty map is represented as {}. Curly braces may option‐
671 ally enclose non-empty maps as well (but use quotes to prevent the
672 shell from expanding other-config={0=x,1=y} into other-config=0=x
673 other-config=1=y, which may not have the desired effect).
674 Database Command Syntax
676 [--if-exists] [--columns=column[,column]...] list table [record]...
678 Lists the data in each specified record. If no records are
679 specified, lists all the records in table.
680 If --columns is specified, only the requested columns are
682 listed, in the specified order. Otherwise, all columns are
683 listed, in alphabetical order by column name.
684 Without --if-exists, it is an error if any specified record does
686 not exist. With --if-exists, the command ignores any record
687 that does not exist, without producing any output.
688 [--columns=column[,column]...] find table [column[:key]=value]...
690 Lists the data in each record in table whose column equals value
691 or, if key is specified, whose column contains a key with the
692 specified value. The following operators may be used where = is
693 written in the syntax summary:
694 = != < > <= >=
696 Selects records in which column[:key] equals, does not
697 equal, is less than, is greater than, is less than or
698 equal to, or is greater than or equal to value, respec‐
699 tively.
700 Consider column[:key] and value as sets of elements.
702 Identical sets are considered equal. Otherwise, if the
703 sets have different numbers of elements, then the set
704 with more elements is considered to be larger. Other‐
705 wise, consider a element from each set pairwise, in in‐
706 creasing order within each set. The first pair that dif‐
707 fers determines the result. (For a column that contains
708 key-value pairs, first all the keys are compared, and
709 values are considered only if the two sets contain iden‐
710 tical keys.)
711 {=} {!=}
713 Test for set equality or inequality, respectively.
714 {<=} Selects records in which column[:key] is a subset of
716 value. For example, flood-vlans{<=}1,2 selects records
717 in which the flood-vlans column is the empty set or con‐
718 tains 1 or 2 or both.
719 {<} Selects records in which column[:key] is a proper subset
721 of value. For example, flood-vlans{<}1,2 selects records
722 in which the flood-vlans column is the empty set or con‐
723 tains 1 or 2 but not both.
724 {>=} {>}
726 Same as {<=} and {<}, respectively, except that the rela‐
727 tionship is reversed. For example, flood-vlans{>=}1,2
728 selects records in which the flood-vlans column contains
729 both 1 and 2.
730 The following operators are available only in Open vSwitch 2.16
732 and later:
733 {in} Selects records in which every element in column[:key] is
735 also in value. (This is the same as {<=}.)
736 {not-in}
738 Selects records in which every element in column[:key] is
739 not in value.
740 For arithmetic operators (= != < > <= >=), when key is specified
742 but a particular record's column does not contain key, the
743 record is always omitted from the results. Thus, the condition
744 other-config:mtu!=1500 matches records that have a mtu key whose
745 value is not 1500, but not those that lack an mtu key.
746 For the set operators, when key is specified but a particular
748 record's column does not contain key, the comparison is done
749 against an empty set. Thus, the condition other-con‐
750 fig:mtu{!=}1500 matches records that have a mtu key whose value
751 is not 1500 and those that lack an mtu key.
752 Don't forget to escape < or > from interpretation by the shell.
754 If --columns is specified, only the requested columns are
756 listed, in the specified order. Otherwise all columns are
757 listed, in alphabetical order by column name.
758 The UUIDs shown for rows created in the same vtep-ctl invocation
760 will be wrong.
761 [--if-exists] [--id=@name] get table record [column[:key]]...
763 Prints the value of each specified column in the given record in
764 table. For map columns, a key may optionally be specified, in
765 which case the value associated with key in the column is
766 printed, instead of the entire map.
767 Without --if-exists, it is an error if record does not exist or
769 key is specified, if key does not exist in record. With
770 --if-exists, a missing record yields no output and a missing key
771 prints a blank line.
772 If @name is specified, then the UUID for record may be referred
774 to by that name later in the same vtep-ctl invocation in con‐
775 texts where a UUID is expected.
776 Both --id and the column arguments are optional, but usually at
778 least one or the other should be specified. If both are omit‐
779 ted, then get has no effect except to verify that record exists
780 in table.
781 --id and --if-exists cannot be used together.
783 [--if-exists] set table record column[:key]=value...
785 Sets the value of each specified column in the given record in
786 table to value. For map columns, a key may optionally be speci‐
787 fied, in which case the value associated with key in that column
788 is changed (or added, if none exists), instead of the entire
789 map.
790 Without --if-exists, it is an error if record does not exist.
792 With --if-exists, this command does nothing if record does not
793 exist.
794 [--if-exists] add table record column [key=]value...
796 Adds the specified value or key-value pair to column in record
797 in table. If column is a map, then key is required, otherwise
798 it is prohibited. If key already exists in a map column, then
799 the current value is not replaced (use the set command to re‐
800 place an existing value).
801 Without --if-exists, it is an error if record does not exist.
803 With --if-exists, this command does nothing if record does not
804 exist.
805 [--if-exists] remove table record column value...
807 [--if-exists] remove table record column key...
808 [--if-exists] remove table record column key=value...
809 Removes the specified values or key-value pairs from column in
810 record in table. The first form applies to columns that are not
811 maps: each specified value is removed from the column. The sec‐
812 ond and third forms apply to map columns: if only a key is spec‐
813 ified, then any key-value pair with the given key is removed,
814 regardless of its value; if a value is given then a pair is re‐
815 moved only if both key and value match.
816 It is not an error if the column does not contain the specified
818 key or value or pair.
819 Without --if-exists, it is an error if record does not exist.
821 With --if-exists, this command does nothing if record does not
822 exist.
823 [--if-exists] clear table record column...
825 Sets each column in record in table to the empty set or empty
826 map, as appropriate. This command applies only to columns that
827 are allowed to be empty.
828 Without --if-exists, it is an error if record does not exist.
830 With --if-exists, this command does nothing if record does not
831 exist.
832 [--id=(@name | uuid] create table column[:key]=value...
834 Creates a new record in table and sets the initial values of
835 each column. Columns not explicitly set will receive their de‐
836 fault values. Outputs the UUID of the new row.
837 If @name is specified, then the UUID for the new row may be re‐
839 ferred to by that name elsewhere in the same vtep-ctl invocation
840 in contexts where a UUID is expected. Such references may pre‐
841 cede or follow the create command.
842 If a valid uuid is specified, then it is used as the UUID of the
844 new row.
845 Caution (ovs-vsctl as example)
847 Records in the Open vSwitch database are significant only
848 when they can be reached directly or indirectly from the
849 Open_vSwitch table. Except for records in the QoS or
850 Queue tables, records that are not reachable from the
851 Open_vSwitch table are automatically deleted from the
852 database. This deletion happens immediately, without
853 waiting for additional ovs-vsctl commands or other data‐
854 base activity. Thus, a create command must generally be
855 accompanied by additional commands within the same
856 ovs-vsctl invocation to add a chain of references to the
857 newly created record from the top-level Open_vSwitch
858 record. The EXAMPLES section gives some examples that
859 show how to do this.
860 [--if-exists] destroy table record...
862 Deletes each specified record from table. Unless --if-exists is
863 specified, each records must exist.
864 --all destroy table
866 Deletes all records from the table.
867 Caution (ovs-vsctl as example)
869 The destroy command is only useful for records in the QoS
870 or Queue tables. Records in other tables are automati‐
871 cally deleted from the database when they become unreach‐
872 able from the Open_vSwitch table. This means that delet‐
873 ing the last reference to a record is sufficient for
874 deleting the record itself. For records in these tables,
875 destroy is silently ignored. See the EXAMPLES section
876 below for more information.
877 wait-until table record [column[:key]=value]...
879 Waits until table contains a record named record whose column
880 equals value or, if key is specified, whose column contains a
881 key with the specified value. This command supports the same
882 operators and semantics described for the find command above.
883 If no column[:key]=value arguments are given, this command waits
885 only until record exists. If more than one such argument is
886 given, the command waits until all of them are satisfied.
887 Caution (ovs-vsctl as example)
889 Usually wait-until should be placed at the beginning of a
890 set of ovs-vsctl commands. For example, wait-until
891 bridge br0 -- get bridge br0 datapath_id waits until a
892 bridge named br0 is created, then prints its datapath_id
893 column, whereas get bridge br0 datapath_id -- wait-until
894 bridge br0 will abort if no bridge named br0 exists when
895 ovs-vsctl initially connects to the database.
896 Consider specifying --timeout=0 along with --wait-until, to pre‐
898 vent vtep-ctl from terminating after waiting only at most 5 sec‐
899 onds.
900 comment [arg]...
902 This command has no effect on behavior, but any database log
903 record created by the command will include the command and its
904 arguments.
905
907 0 Successful program execution.
908 1 Usage, syntax, or configuration file error.
910 2 The switch argument to ps-exists specified the name of a physi‐
912 cal switch that does not exist.
913
915 ovsdb-server(1), vtep(5).
916Open vSwitch March 2013 vtep-ctl(8)