1vtep-ctl(8)                   Open vSwitch Manual                  vtep-ctl(8)
2
3
4

NAME

6       vtep-ctl - utility for querying and configuring a VTEP database
7

SYNOPSIS

9       vtep-ctl  [options]  --  [options] command [args] [-- [options] command
10       [args]]...
11

DESCRIPTION

13       The vtep-ctl program configures a VTEP database.  See vtep(5) for  com‐
14       prehensive documentation of the database schema.
15
16       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
20       vtep-ctl  can  perform  any  number of commands in a single run, imple‐
21       mented as a single atomic transaction against the database.
22
23       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

OPTIONS

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
38       --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
44       --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
49              This option is equivalent to --verbose=vtep_ctl:syslog:warn.
50
51       --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
60       --dry-run
61              Prevents vtep-ctl from actually modifying the database.
62
63       -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
72   Table Formatting Options
73       These options control the format of output from the list and find  com‐
74       mands.
75
76       -f format
77       --format=format
78              Sets  the type of table formatting.  The following types of for‐
79              mat are available:
80
81              table  2-D text tables with aligned columns.
82
83              list (default)
84                     A list with one column per line and rows separated  by  a
85                     blank line.
86
87              html   HTML tables.
88
89              csv    Comma-separated values as defined in RFC 4180.
90
91              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
96                     caption
97                            The table's caption.  This member  is  omitted  if
98                            the table has no caption.
99
100                     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
105                     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
114       -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
121              string (default)
122                     The  simple  format described in the Database Values sec‐
123                     tion of ovs-vsctl(8).
124
125              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
131              json   The RFC 4627 JSON format as described above.
132
133       --no-headings
134              This option suppresses the heading row that otherwise appears in
135              the first row of table output.
136
137       --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
143              This option does not affect JSON  in  tables,  which  is  always
144              printed compactly.
145
146       --bare Equivalent to --format=list --data=bare --no-headings.
147
148       --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
154   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
160       -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
167       -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
175       -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
181       --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
190              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
194              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
198              This option is mutually exclusive with -C and --ca-cert.
199
200       --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
208              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
214       -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
221              •      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
225syslog, 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
231                     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
235off, 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
241              Case is not significant within spec.
242
243              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
247              For compatibility with older versions of OVS, any is accepted as
248              a word but has no effect.
249
250       -v
251       --verbose
252              Sets  the  maximum logging verbosity level, equivalent to --ver‐
253              bose=dbg.
254
255       -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
260       -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
270       --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
276       --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
281       --syslog-method=method
282              Specify method how syslog messages should be sent to syslog dae‐
283              mon.  Following forms are supported:
284
285libc, 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
290unix: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
298udp: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
308null, discards all messages logged to syslog.
309
310              The default is  taken  from  the  OVS_SYSLOG_METHOD  environment
311              variable; if it is unset, the default is libc.
312
313       -h
314       --help Prints a brief help message to the console.
315
316       -V
317       --version
318              Prints version information to the console.
319

COMMANDS

321       The  commands implemented by vtep-ctl are described in the sections be‐
322       low.
323
324   Physical Switch Commands
325       These commands examine and manipulate physical switches.
326
327       [--may-exist] add-ps pswitch
328              Creates a new physical  switch  named  pswitch.   Initially  the
329              switch will have no ports.
330
331              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
335       [--if-exists] del-ps pswitch
336              Deletes pswitch and all of its ports.
337
338              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
342       list-ps
343              Lists all existing physical switches on standard output, one per
344              line.
345
346       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
351   Port Commands
352       These commands examine and manipulate VTEP physical ports.
353
354       list-ports pswitch
355              Lists all of the ports within pswitch on  standard  output,  one
356              per line.
357
358       [--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
362              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
366       [--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
371              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
375   Logical Switch Commands
376       These commands examine and manipulate logical switches.
377
378       [--may-exist] add-ls lswitch
379              Creates a new  logical  switch  named  lswitch.   Initially  the
380              switch will have no locator bindings.
381
382              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
386       [--if-exists] del-ls lswitch
387              Deletes lswitch.
388
389              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
393       list-ls
394              Lists  all existing logical switches on standard output, one per
395              line.
396
397       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
402       bind-ls pswitch port vlan lswitch
403              Bind logical switch lswitch to the port/vlan combination on  the
404              physical switch pswitch.
405
406       unbind-ls pswitch port vlan
407              Remove the logical switch binding from the port/vlan combination
408              on the physical switch pswitch.
409
410       list-bindings pswitch port
411              List the logical switch bindings for port on the physical switch
412              pswitch.
413
414       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
434       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
440   Logical Router Commands
441       These commands examine and manipulate logical routers.
442
443       [--may-exist] add-lr lrouter
444              Creates a new logical router named lrouter.
445
446              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
450       [--if-exists] del-lr lrouter
451              Deletes lrouter.
452
453              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
457       list-lr
458              Lists  all  existing logical routers on standard output, one per
459              line.
460
461       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
466
467   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
472       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
478       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
483       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
490       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
497       clear-local-macs lswitch
498              Clear the local MAC bindings for lswitch.
499
500       list-local-macs lswitch
501              List the local MAC bindings for lswitch, one per line.
502
503   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
508       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
515       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
520       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
527       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
534       clear-remote-macs lswitch
535              Clear the remote MAC bindings for lswitch.
536
537       list-remote-macs lswitch
538              List the remote MAC bindings for lswitch, one per line.
539
540   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
547       get-manager
548              Prints the configured manager(s).
549
550       del-manager
551              Deletes the configured manager(s).
552
553       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
558   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
563     Identifying Tables, Records, and Columns
564
565       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
572       The following tables are currently defined:
573
574       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
578       Manager
579              Configuration for an OVSDB connection.  Records may  be  identi‐
580              fied by target (e.g. tcp:1.2.3.4).
581
582       Physical_Switch
583              A  physical switch that implements a VTEP.  Records may be iden‐
584              tified by physical switch name.
585
586       Physical_Port
587              A port within a physical switch.
588
589       Logical_Binding_Stats
590              Reports statistics for the logical switch with which a VLAN on a
591              physical port is associated.
592
593       Logical_Switch
594              A logical Ethernet switch.  Records may be identified by logical
595              switch name.
596
597       Ucast_Macs_Local
598              Mapping of locally discovered unicast MAC addresses to tunnels.
599
600       Ucast_Macs_Remote
601              Mapping of remotely programmed unicast MAC addresses to tunnels.
602
603       Mcast_Macs_Local
604              Mapping of locally discovered multicast MAC  addresses  to  tun‐
605              nels.
606
607       Mcast_Macs_Remote
608              Mapping  of  remotely programmed multicast MAC addresses to tun‐
609              nels.
610
611       Physical_Locator_Set
612              A set of one or more physical locators.
613
614       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
619       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
626     Database Values
627
628       Each  column  in  the  database accepts a fixed type of data.  The cur‐
629       rently defined basic types, and their representations, are:
630
631       integer
632              A decimal integer in the range -2**63 to 2**63-1, inclusive.
633
634       real   A floating-point number.
635
636       Boolean
637              True or false, written true or false, respectively.
638
639       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
650       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
654       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
664       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
675     Database Command Syntax
676
677       [--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
681              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
685              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
689       [--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
695              = != < > <= >=
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
701                     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
712              {=} {!=}
713                     Test for set equality or inequality, respectively.
714
715              {<=}   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
720              {<}    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
725              {>=} {>}
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
731              The  following operators are available only in Open vSwitch 2.16
732              and later:
733
734              {in}   Selects records in which every element in column[:key] is
735                     also in value.  (This is the same as {<=}.)
736
737              {not-in}
738                     Selects records in which every element in column[:key] is
739                     not in value.
740
741              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
747              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
753              Don't forget to escape < or > from interpretation by the shell.
754
755              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
759              The UUIDs shown for rows created in the same vtep-ctl invocation
760              will be wrong.
761
762       [--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
768              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
773              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
777              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
782              --id and --if-exists cannot be used together.
783
784       [--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
791              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
795       [--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
802              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
806       [--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
817              It is not an error if the column does not contain the  specified
818              key or value or pair.
819
820              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
824       [--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
829              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
833       [--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
838              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
843              If a valid uuid is specified, then it is used as the UUID of the
844              new row.
845
846              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
861       [--if-exists] destroy table record...
862              Deletes each specified record from table.  Unless --if-exists is
863              specified, each records must exist.
864
865       --all destroy table
866              Deletes all records from the table.
867
868              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
878       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
884              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
888              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
897              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
901       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

EXIT STATUS

907       0      Successful program execution.
908
909       1      Usage, syntax, or configuration file error.
910
911       2      The switch argument to ps-exists specified the name of a  physi‐
912              cal switch that does not exist.
913

SEE ALSO

915       ovsdb-server(1), vtep(5).
916
917
918
919Open vSwitch                      March 2013                       vtep-ctl(8)
Impressum