1ovs-vsctl(8)                  Open vSwitch Manual                 ovs-vsctl(8)
2
3
4

NAME

6       ovs-vsctl - utility for querying and configuring ovs-vswitchd
7

SYNOPSIS

9       ovs-vsctl  [options]  -- [options] command [args] [-- [options] command
10       [args]]...
11

DESCRIPTION

13       The  ovs-vsctl  program  configures  ovs-vswitchd(8)  by  providing   a
14       high-level    interface    to    its   configuration   database.    See
15       ovs-vswitchd.conf.db(5) for comprehensive documentation of the database
16       schema.
17
18       ovs-vsctl  connects  to  an ovsdb-server process that maintains an Open
19       vSwitch configuration database.  Using this connection, it queries  and
20       possibly  applies  changes  to  the database, depending on the supplied
21       commands.  Then, if it applied any changes, by default it  waits  until
22       ovs-vswitchd  has  finished  reconfiguring itself before it exits.  (If
23       you use ovs-vsctl when ovs-vswitchd is not running, use --no-wait.)
24
25       ovs-vsctl can perform any number of commands in a  single  run,  imple‐
26       mented as a single atomic transaction against the database.
27
28       The  ovs-vsctl  command  line  begins  with global options (see OPTIONS
29       below for details).  The global options are followed  by  one  or  more
30       commands.   Each  command  should begin with -- by itself as a command-
31       line argument, to separate it from the  following  commands.   (The  --
32       before  the first command is optional.)  The command itself starts with
33       command-specific options, if any, followed by the command name and  any
34       arguments.  See EXAMPLES below for syntax examples.
35
36   Linux VLAN Bridging Compatibility
37       The  ovs-vsctl  program  supports  the model of a bridge implemented by
38       Open vSwitch, in which a  single  bridge  supports  ports  on  multiple
39       VLANs.   In  this  model,  each port on a bridge is either a trunk port
40       that potentially passes packets tagged with 802.1Q headers that  desig‐
41       nate  VLANs  or  it  is  assigned  a single implicit VLAN that is never
42       tagged with an 802.1Q header.
43
44       For  compatibility  with  software  designed  for  the  Linux   bridge,
45       ovs-vsctl  also  supports  a  model  in which traffic associated with a
46       given 802.1Q VLAN is segregated into a separate bridge.  A special form
47       of  the  add-br command (see below) creates a ``fake bridge'' within an
48       Open vSwitch bridge to simulate this  behavior.   When  such  a  ``fake
49       bridge'' is active, ovs-vsctl will treat it much like a bridge separate
50       from its ``parent bridge,''  but  the  actual  implementation  in  Open
51       vSwitch  uses  only  a  single  bridge,  with  ports on the fake bridge
52       assigned the implicit VLAN of the fake bridge of which  they  are  mem‐
53       bers.   (A  fake bridge for VLAN 0 receives packets that have no 802.1Q
54       tag or a tag with VLAN 0.)
55

OPTIONS

57       The following options affect the behavior ovs-vsctl as a  whole.   Some
58       individual commands also accept their own options, which are given just
59       before the command name.  If the first command on the command line  has
60       options,  then  those options must be separated from the global options
61       by --.
62
63       --db=server
64              Sets server as the database server that  ovs-vsctl  contacts  to
65              query    or    modify    configuration.     The    default    is
66              unix:/var/run/openvswitch/db.sock.  server must take one of  the
67              following forms:
68
69              ssl:ip:port
70                     The specified SSL port on the host at the given ip, which
71                     must be expressed as an IP address (not a DNS name).  The
72                     --private-key,  --certificate,  and --ca-cert options are
73                     mandatory when this form is used.
74
75              tcp:ip:port
76                     Connect to the given TCP port on ip.
77
78              unix:file
79                     Connect to the Unix domain server socket named file.
80
81              pssl:port[:ip]
82                     Listen on the  given  SSL  port  for  a  connection.   By
83                     default,  connections are not bound to a particular local
84                     IP address, but specifying ip limits connections to those
85                     from the given ip.  The --private-key, --certificate, and
86                     --ca-cert options are mandatory when this form is used.
87
88              ptcp:port[:ip]
89                     Listen on the  given  TCP  port  for  a  connection.   By
90                     default,  connections are not bound to a particular local
91                     IP address, but ip may be specified to  listen  only  for
92                     connections to the given ip.
93
94              punix:file
95                     Listen  on the Unix domain server socket named file for a
96                     connection.
97
98       --no-wait
99              Prevents ovs-vsctl from waiting for ovs-vswitchd to  reconfigure
100              itself  according  to  the  the  modified database.  This option
101              should be  used  if  ovs-vswitchd  is  not  running;  otherwise,
102              ovs-vsctl will not exit until ovs-vswitchd starts.
103
104              This  option  has  no  effect  if  the commands specified do not
105              change the database.
106
107       --no-syslog
108              By default, ovs-vsctl logs its arguments and the details of  any
109              changes  that  it makes to the system log.  This option disables
110              this logging.
111
112              This option is equivalent to --verbose=vsctl:syslog:warn.
113
114       --oneline
115              Modifies the output format so that the output for  each  command
116              is  printed  on  a  single line.  New-line characters that would
117              otherwise separate lines are printed as \n, and any instances of
118              \ that would otherwise appear in the output are doubled.  Prints
119              a blank line for each command that has no output.   This  option
120              does  not  affect the formatting of output from the list or find
121              commands; see Table Formatting Options below.
122
123       --dry-run
124              Prevents ovs-vsctl from actually modifying the database.
125
126       -t secs
127       --timeout=secs
128              By default, or with a secs of 0, ovs-vsctl waits forever  for  a
129              response  from  the  database.   This  option  limits runtime to
130              approximately secs seconds.  If the timeout  expires,  ovs-vsctl
131              will exit with a SIGALRM signal.  (A timeout would normally hap‐
132              pen only if the database cannot be contacted, or if  the  system
133              is overloaded.)
134
135       --retry
136              Without  this option, if ovs-vsctl connects outward to the data‐
137              base server (the default) then ovs-vsctl  will  try  to  connect
138              once  and exit with an error if the connection fails (which usu‐
139              ally means that ovsdb-server is not running).
140
141              With this option, or if --db  specifies  that  ovs-vsctl  should
142              listen for an incoming connection from the database server, then
143              ovs-vsctl will wait for a connection to the database forever.
144
145              Regardless of this setting, --timeout  always  limits  how  long
146              ovs-vsctl will wait.
147
148   Table Formatting Options
149       These  options control the format of output from the list and find com‐
150       mands.
151
152       -f format
153       --format=format
154              Sets the type of table formatting.  The following types of  for‐
155              mat are available:
156
157              table  2-D text tables with aligned columns.
158
159              list (default)
160                     A  list  with one column per line and rows separated by a
161                     blank line.
162
163              html   HTML tables.
164
165              csv    Comma-separated values as defined in RFC 4180.
166
167              json   JSON format as defined in RFC  4627.   The  output  is  a
168                     sequence  of  JSON  objects, each of which corresponds to
169                     one table.  Each JSON object has  the  following  members
170                     with the noted values:
171
172                     caption
173                            The  table's  caption.   This member is omitted if
174                            the table has no caption.
175
176                     headings
177                            An array with one element per table column.   Each
178                            array element is a string giving the corresponding
179                            column's heading.
180
181                     data   An array with one element  per  table  row.   Each
182                            element  is also an array with one element per ta‐
183                            ble column.  The  elements  of  this  second-level
184                            array  are  the  cells  that constitute the table.
185                            Cells that represent OVSDB data or data types  are
186                            expressed  in  the  format  described in the OVSDB
187                            specification; other cells are simply expressed as
188                            text strings.
189
190       -d format
191       --data=format
192              Sets the formatting for cells within output tables.  The follow‐
193              ing types of format are available:
194
195              string (default)
196                     The simple format described in the Database  Values  sec‐
197                     tion below.
198
199              bare   The  simple  format with punctuation stripped off: [] and
200                     {} are omitted around  sets,  maps,  and  empty  columns,
201                     items  within  sets  and  maps  are  space-separated, and
202                     strings are never quoted.  This format may be easier  for
203                     scripts to parse.
204
205              json   JSON.
206
207              The  json  output  format  always  outputs cells in JSON format,
208              ignoring this option.
209
210       --no-heading
211              This option suppresses the heading row that otherwise appears in
212              the first row of table output.
213
214       --pretty
215              By  default, JSON in output is printed as compactly as possible.
216              This option causes JSON in output to be printed in a more  read‐
217              able  fashion.   Members  of  objects and elements of arrays are
218              printed one per line, with indentation.
219
220              This option does not affect JSON  in  tables,  which  is  always
221              printed compactly.
222
223       --bare Equivalent to --format=list --data=bare --no-headings.
224
225   Public Key Infrastructure Options
226       -p privkey.pem
227       --private-key=privkey.pem
228              Specifies  a  PEM  file  containing  the  private  key  used  as
229              ovs-vsctl's identity for outgoing SSL connections.
230
231       -c cert.pem
232       --certificate=cert.pem
233              Specifies a PEM file containing a certificate that certifies the
234              private  key specified on -p or --private-key to be trustworthy.
235              The certificate must be signed by the certificate authority (CA)
236              that the peer in SSL connections will use to verify it.
237
238       -C cacert.pem
239       --ca-cert=cacert.pem
240              Specifies   a  PEM  file  containing  the  CA  certificate  that
241              ovs-vsctl should use to verify certificates presented to  it  by
242              SSL peers.  (This may be the same certificate that SSL peers use
243              to verify the certificate specified on -c or  --certificate,  or
244              it may be a different one, depending on the PKI design in use.)
245
246       -C none
247       --ca-cert=none
248              Disables  verification  of  certificates presented by SSL peers.
249              This introduces a security risk, because it means that  certifi‐
250              cates cannot be verified to be those of known trusted hosts.
251
252       --bootstrap-ca-cert=cacert.pem
253              When cacert.pem exists, this option has the same effect as -C or
254              --ca-cert.  If it does not exist, then ovs-vsctl will attempt to
255              obtain  the  CA  certificate  from the SSL peer on its first SSL
256              connection and save it to the named PEM file.  If it is success‐
257              ful,  it will immediately drop the connection and reconnect, and
258              from then on all SSL connections must be authenticated by a cer‐
259              tificate signed by the CA certificate thus obtained.
260
261              This  option  exposes  the SSL connection to a man-in-the-middle
262              attack obtaining the initial CA certificate, but it may be  use‐
263              ful for bootstrapping.
264
265              This option is only useful if the SSL peer sends its CA certifi‐
266              cate as part of the SSL certificate  chain.   The  SSL  protocol
267              does  not  require  the  server  to send the CA certificate, but
268              ovsdb-server(8)  can  be  configured   to   do   so   with   the
269              --peer-ca-cert option.
270
271              This option is mutually exclusive with -C and --ca-cert.
272
273       --peer-ca-cert=peer-cacert.pem
274              Specifies  a  PEM file that contains one or more additional cer‐
275              tificates to send to SSL peers.  peer-cacert.pem should  be  the
276              CA  certificate  used  to sign ovs-vsctl's own certificate, that
277              is, the  certificate  specified  on  -c  or  --certificate.   If
278              ovs-vsctl's  certificate  is self-signed, then --certificate and
279              --peer-ca-cert should specify the same file.
280
281              This option is not useful in normal operation, because  the  SSL
282              peer  must  already have the CA certificate for the peer to have
283              any confidence in ovs-vsctl's identity.  However, this offers  a
284              way  for  a  new installation to bootstrap the CA certificate on
285              its first SSL connection.
286
287       -v[spec]
288       --verbose=[spec]
289              Sets logging levels.  Without any spec, sets the log  level  for
290              every  module and facility to dbg.  Otherwise, spec is a list of
291              words separated by spaces or commas or colons, up  to  one  from
292              each category below:
293
294              ·      A  valid  module name, as displayed by the vlog/list com‐
295                     mand on ovs-appctl(8), limits the log level change to the
296                     specified module.
297
298              ·      syslog,  console,  or file, to limit the log level change
299                     to only to the system log, to the console, or to a  file,
300                     respectively.
301
302              ·      off,  emer,  err,  warn, info, or dbg, to control the log
303                     level.  Messages of the given severity or higher will  be
304                     logged,  and  messages of lower severity will be filtered
305                     out.  off filters out all  messages.   See  ovs-appctl(8)
306                     for a definition of each log level.
307
308              Case is not significant within spec.
309
310              Regardless  of  the  log  levels set for file, logging to a file
311              will not take place unless --log-file  is  also  specified  (see
312              below).
313
314              For compatibility with older versions of OVS, any is accepted as
315              a word but has no effect.
316
317       -v
318       --verbose
319              Sets the maximum logging verbosity level, equivalent  to  --ver‐
320              bose=dbg.
321
322       --log-file[=file]
323              Enables  logging  to  a  file.  If file is specified, then it is
324              used as the exact name for the log file.  The default  log  file
325              name    used    if    file    is   omitted   is   /var/log/open‐
326              vswitch/ovs-vsctl.log.
327

COMMANDS

329       The commands implemented by ovs-vsctl are  described  in  the  sections
330       below.
331
332   Open vSwitch Commands
333       These commands work with an Open vSwitch as a whole.
334
335       init   Initializes  the  Open vSwitch database, if it is empty.  If the
336              database has already  been  initialized,  this  command  has  no
337              effect.
338
339              Any  successful  ovs-vsctl command automatically initializes the
340              Open vSwitch database if it is empty.  This command is  provided
341              to initialize the database without executing any other command.
342
343       show   Prints a brief overview of the database contents.
344
345       emer-reset
346              Reset  the  configuration  into  a clean state.  It deconfigures
347              OpenFlow controllers, OVSDB servers, and SSL, and  deletes  port
348              mirroring,  fail_mode,  NetFlow, sFlow, and IPFIX configuration.
349              This command also removes all other-config keys from  all  data‐
350              base records, except that other-config:hwaddr is preserved if it
351              is present in a Bridge record.  Other  networking  configuration
352              is left as-is.
353
354   Bridge Commands
355       These commands examine and manipulate Open vSwitch bridges.
356
357       [--may-exist] add-br bridge
358              Creates  a  new  bridge named bridge.  Initially the bridge will
359              have no ports (other than bridge itself).
360
361              Without --may-exist, attempting to create a bridge  that  exists
362              is  an  error.   With  --may-exist, this command does nothing if
363              bridge already exists as a real bridge.
364
365       [--may-exist] add-br bridge parent vlan
366              Creates a ``fake bridge'' named bridge within the existing  Open
367              vSwitch  bridge  parent,  which  must already exist and must not
368              itself be a fake bridge.  The new fake bridge will be on  802.1Q
369              VLAN  vlan,  which  must be an integer between 0 and 4095.  Ini‐
370              tially bridge will have no ports (other than bridge itself).
371
372              Without --may-exist, attempting to create a bridge  that  exists
373              is  an  error.   With  --may-exist, this command does nothing if
374              bridge already exists as a VLAN bridge under parent for vlan.
375
376       [--if-exists] del-br bridge
377              Deletes bridge and all of  its  ports.   If  bridge  is  a  real
378              bridge,  this  command  also  deletes any fake bridges that were
379              created with bridge as parent, including all of their ports.
380
381              Without --if-exists, attempting to delete a bridge that does not
382              exist  is  an  error.   With --if-exists, attempting to delete a
383              bridge that does not exist has no effect.
384
385       [--real|--fake] list-br
386              Lists all existing real and fake bridges on standard output, one
387              per  line.  With --real or --fake, only bridges of that type are
388              returned.
389
390       br-exists bridge
391              Tests whether bridge exists as a real or fake  bridge.   If  so,
392              ovs-vsctl   exits  successfully  with  exit  code  0.   If  not,
393              ovs-vsctl exits unsuccessfully with exit code 2.
394
395       br-to-vlan bridge
396              If bridge is a fake bridge, prints the bridge's 802.1Q VLAN as a
397              decimal integer.  If bridge is a real bridge, prints 0.
398
399       br-to-parent bridge
400              If  bridge  is  a  fake  bridge,  prints  the name of its parent
401              bridge.  If bridge is a real bridge, print bridge.
402
403       br-set-external-id bridge key [value]
404              Sets or clears an ``external ID'' value on bridge.  These values
405              are  intended to identify entities external to Open vSwitch with
406              which bridge is associated, e.g. the bridge's  identifier  in  a
407              virtualization  management  platform.  The Open vSwitch database
408              schema specifies well-known key values, but key  and  value  are
409              otherwise arbitrary strings.
410
411              If  value  is  specified,  then  key is set to value for bridge,
412              overwriting any previous value.  If value is omitted,  then  key
413              is  removed  from  bridge's  set  of  external  IDs  (if  it was
414              present).
415
416              For real bridges, the effect of this command is similar to  that
417              of  a  set  or  remove command in the external-ids column of the
418              Bridge table.  For fake bridges, it actually modifies keys  with
419              names prefixed by fake-bridge- in the Port table.
420
421       br-get-external-id bridge [key]
422              Queries  the  external  IDs on bridge.  If key is specified, the
423              output is the value for that key or the empty string if  key  is
424              unset.   If  key  is  omitted,  the output is key=value, one per
425              line, for each key-value pair.
426
427              For real bridges, the effect of this command is similar to  that
428              of a get command in the external-ids column of the Bridge table.
429              For fake  bridges,  it  queries  keys  with  names  prefixed  by
430              fake-bridge- in the Port table.
431
432   Port Commands
433       These  commands  examine and manipulate Open vSwitch ports.  These com‐
434       mands treat a bonded port as a single entity.
435
436       list-ports bridge
437              Lists all of the ports within bridge on standard output, one per
438              line.  The local port bridge is not included in the list.
439
440       [--may-exist] add-port bridge port [column[:key]=value]...
441              Creates  on bridge a new port named port from the network device
442              of the same name.
443
444              Optional arguments set values of column in the Port record  cre‐
445              ated  by the command.  For example, tag=9 would make the port an
446              access port for VLAN 9.  The syntax is the same as that for  the
447              set command (see Database Commands below).
448
449              Without  --may-exist, attempting to create a port that exists is
450              an error.  With --may-exist, this command does nothing  if  port
451              already exists on bridge and is not a bonded port.
452
453       [--fake-iface] add-bond bridge port iface... [column[:key]=value]...
454              Creates  on bridge a new port named port that bonds together the
455              network devices given as each iface.  At  least  two  interfaces
456              must be named.
457
458              Optional  arguments set values of column in the Port record cre‐
459              ated by the command.  The syntax is the same as that for the set
460              command (see Database Commands below).
461
462              With  --fake-iface,  a fake interface with the name port is cre‐
463              ated.  This should only be used for  compatibility  with  legacy
464              software that requires it.
465
466              Without  --may-exist, attempting to create a port that exists is
467              an error.  With --may-exist, this command does nothing  if  port
468              already  exists  on bridge and bonds together exactly the speci‐
469              fied interfaces.
470
471       [--if-exists] del-port [bridge] port
472              Deletes port.  If bridge is omitted, port is removed from  what‐
473              ever  bridge contains it; if bridge is specified, it must be the
474              real or fake bridge that contains port.
475
476              Without --if-exists, attempting to delete a port that  does  not
477              exist  is  an  error.   With --if-exists, attempting to delete a
478              port that does not exist has no effect.
479
480       [--if-exists] --with-iface del-port [bridge] iface
481              Deletes the port named iface or  that  has  an  interface  named
482              iface.   If bridge is omitted, the port is removed from whatever
483              bridge contains it; if bridge is specified, it must be the  real
484              or fake bridge that contains the port.
485
486              Without --if-exists, attempting to delete the port for an inter‐
487              face that  does  not  exist  is  an  error.   With  --if-exists,
488              attempting  to  delete  the  port for an interface that does not
489              exist has no effect.
490
491       port-to-br port
492              Prints the name of the bridge that  contains  port  on  standard
493              output.
494
495   Interface Commands
496       These  commands  examine  the  interfaces  attached  to an Open vSwitch
497       bridge.  These commands treat a bonded port as a collection of  two  or
498       more interfaces, rather than as a single port.
499
500       list-ifaces bridge
501              Lists  all  of  the interfaces within bridge on standard output,
502              one per line.  The local port bridge  is  not  included  in  the
503              list.
504
505       iface-to-br iface
506              Prints  the  name  of the bridge that contains iface on standard
507              output.
508
509   OpenFlow Controller Connectivity
510       ovs-vswitchd can perform all configured bridging and switching locally,
511       or  it can be configured to communicate with one or more external Open‐
512       Flow controllers.  The switch is typically configured to connect  to  a
513       primary  controller  that  takes  charge  of the bridge's flow table to
514       implement a network policy.  In addition, the switch can be  configured
515       to listen to connections from service controllers.  Service controllers
516       are typically used for occasional support and  maintenance,  e.g.  with
517       ovs-ofctl.
518
519       get-controller bridge
520              Prints the configured controller target.
521
522       del-controller bridge
523              Deletes the configured controller target.
524
525       set-controller bridge target...
526              Sets  the  configured controller target or targets.  Each target
527              may use any of the following forms:
528
529              ssl:ip[:port]
530                     The specified SSL port (default: 6633) on the host at the
531                     given ip, which must be expressed as an IP address (not a
532                     DNS  name).   The   --private-key,   --certificate,   and
533                     --ca-cert options are mandatory when this form is used.
534
535              tcp:ip[:port]
536                     The specified TCP port (default: 6633) on the host at the
537                     given ip, which must be expressed as an IP address (not a
538                     DNS name).
539
540              unix:file
541                     The Unix domain server socket named file.
542
543              pssl:[port][:ip]
544                     Listens  for  OpenFlow  SSL connections on port (default:
545                     6633).  The --private-key, --certificate,  and  --ca-cert
546                     options  are  mandatory  when  this  form  is  used.   By
547                     default, connections are not bound to a particular  local
548                     IP  address,  but  ip may be specified to listen only for
549                     connections to the given ip.
550
551              ptcp:[port][:ip]
552                     Listens for OpenFlow TCP connections  on  port  (default:
553                     6633).   By  default, connections are not bound to a par‐
554                     ticular local IP address, but ip may be specified to lis‐
555                     ten only for connections to the given ip.
556
557              punix:file
558                     Listens  for  OpenFlow  connections  on  the  Unix domain
559                     server socket named file.
560
561     Controller Failure Settings
562
563       When a controller is configured, it  is,  ordinarily,  responsible  for
564       setting  up  all  flows  on the switch.  Thus, if the connection to the
565       controller fails, no new network connections can be  set  up.   If  the
566       connection  to  the  controller  stays down long enough, no packets can
567       pass through the switch at all.
568
569       If the value is standalone, or if neither of  these  settings  is  set,
570       ovs-vswitchd will take over responsibility for setting up flows when no
571       message has been received from the controller for three times the inac‐
572       tivity  probe interval.  In this mode, ovs-vswitchd causes the datapath
573       to act like an ordinary MAC-learning switch.   ovs-vswitchd  will  con‐
574       tinue to retry connecting to the controller in the background and, when
575       the connection succeeds, it discontinues its standalone behavior.
576
577       If this option is set to secure, ovs-vswitchd will not set up flows  on
578       its own when the controller connection fails.
579
580       get-fail-mode bridge
581              Prints the configured failure mode.
582
583       del-fail-mode bridge
584              Deletes the configured failure mode.
585
586       set-fail-mode bridge standalone|secure
587              Sets the configured failure mode.
588
589   Manager Connectivity
590       These   commands   manipulate   the   manager_options   column  in  the
591       Open_vSwitch table and rows in the Managers table.   When  ovsdb-server
592       is  configured  to use the manager_options column for OVSDB connections
593       (as described in INSTALL.Linux and in the startup scripts provided with
594       Open  vSwitch),  this allows the administrator to use ovs-vsctl to con‐
595       figure database connections.
596
597       get-manager
598              Prints the configured manager(s).
599
600       del-manager
601              Deletes the configured manager(s).
602
603       set-manager target...
604              Sets the configured manager target or targets.  Each target  may
605              use any of the following forms:
606
607              ssl:ip:port
608                     The specified SSL port on the host at the given ip, which
609                     must be expressed as an IP address (not a DNS name).  The
610                     --private-key,  --certificate,  and --ca-cert options are
611                     mandatory when this form is used.
612
613              tcp:ip:port
614                     Connect to the given TCP port on ip.
615
616              unix:file
617                     Connect to the Unix domain server socket named file.
618
619              pssl:port[:ip]
620                     Listen on the  given  SSL  port  for  a  connection.   By
621                     default,  connections are not bound to a particular local
622                     IP address, but specifying ip limits connections to those
623                     from the given ip.  The --private-key, --certificate, and
624                     --ca-cert options are mandatory when this form is used.
625
626              ptcp:port[:ip]
627                     Listen on the  given  TCP  port  for  a  connection.   By
628                     default,  connections are not bound to a particular local
629                     IP address, but ip may be specified to  listen  only  for
630                     connections to the given ip.
631
632              punix:file
633                     Listen  on the Unix domain server socket named file for a
634                     connection.
635
636   SSL Configuration
637       When ovs-vswitchd is configured to connect over SSL for  management  or
638       controller connectivity, the following parameters are required:
639
640       private-key
641              Specifies a PEM file containing the private key used as the vir‐
642              tual switch's identity for SSL connections to the controller.
643
644       certificate
645              Specifies a PEM file containing a  certificate,  signed  by  the
646              certificate  authority  (CA) used by the controller and manager,
647              that certifies the virtual switch's private key,  identifying  a
648              trustworthy switch.
649
650       ca-cert
651              Specifies  a PEM file containing the CA certificate used to ver‐
652              ify that the virtual switch is connected to a  trustworthy  con‐
653              troller.
654
655       These files are read only once, at ovs-vswitchd startup time.  If their
656       contents change, ovs-vswitchd must be killed and restarted.
657
658       These SSL settings apply to all SSL connections  made  by  the  virtual
659       switch.
660
661       get-ssl
662              Prints the SSL configuration.
663
664       del-ssl
665              Deletes the current SSL configuration.
666
667       [--bootstrap] set-ssl private-key certificate ca-cert
668              Sets the SSL configuration.  The --bootstrap option is described
669              below.
670
671     CA Certificate Bootstrap
672
673       Ordinarily, all of the files named in the SSL configuration must  exist
674       when  ovs-vswitchd starts.  However, if the ca-cert file does not exist
675       and the --bootstrap option is given, then ovs-vswitchd will attempt  to
676       obtain  the CA certificate from the controller on its first SSL connec‐
677       tion and save it to the named PEM file.  If it is successful,  it  will
678       immediately drop the connection and reconnect, and from then on all SSL
679       connections must be authenticated by a certificate  signed  by  the  CA
680       certificate thus obtained.
681
682       This  option  exposes  the SSL connection to a man-in-the-middle attack
683       obtaining the initial CA certificate, but it may be  useful  for  boot‐
684       strapping.
685
686       This  option  is only useful if the controller sends its CA certificate
687       as part of the SSL  certificate  chain.   The  SSL  protocol  does  not
688       require  the  controller  to  send  the  CA  certificate,  but ovs-con‐
689       troller(8) can be configured to do so with the --peer-ca-cert option.
690
691   Database Commands
692       These commands query and modify the contents of ovsdb tables.  They are
693       a slight abstraction of the ovsdb interface and as such they operate at
694       a lower level than other ovs-vsctl commands.
695
696     Identifying Tables, Records, and Columns
697
698       Each of these commands has a table parameter to identify a table within
699       the  database.   Many of them also take a record parameter that identi‐
700       fies a particular record within a table.  The record parameter  may  be
701       the  UUID  for a record, and many tables offer additional ways to iden‐
702       tify records.  Some commands also take column parameters that  identify
703       a particular field within the records in a table.
704
705       The following tables are currently defined:
706
707       Open_vSwitch
708              Global  configuration  for an ovs-vswitchd.  This table contains
709              exactly one record, identified by specifying  .  as  the  record
710              name.
711
712       Bridge Configuration  for a bridge within an Open vSwitch.  Records may
713              be identified by bridge name.
714
715       Port   A bridge port.  Records may be identified by port name.
716
717       Interface
718              A network device attached to a port.  Records may be  identified
719              by name.
720
721       Flow_Table
722              Configuration for a particular OpenFlow flow table.  Records may
723              be identified by name.
724
725       QoS    Quality-of-service configuration for a  Port.   Records  may  be
726              identified by port name.
727
728       Queue  Configuration for one queue within a QoS configuration.  Records
729              may only be identified by UUID.
730
731       Mirror A port mirroring configuration attached to  a  bridge.   Records
732              may be identified by mirror name.
733
734       Controller
735              Configuration for an OpenFlow controller.  A controller attached
736              to a particular bridge may be identified by the bridge's name.
737
738       Manager
739              Configuration for an OVSDB connection.  Records may  be  identi‐
740              fied by target (e.g. tcp:1.2.3.4).
741
742       NetFlow
743              A  NetFlow  configuration  attached to a bridge.  Records may be
744              identified by bridge name.
745
746       SSL    The global  SSL  configuration  for  ovs-vswitchd.   The  record
747              attached to the Open_vSwitch table may be identified by specify‐
748              ing . as the record name.
749
750       sFlow  An sFlow exporter configuration attached to a  bridge.   Records
751              may be identified by bridge name.
752
753       IPFIX  An  IPFIX  exporter configuration attached to a bridge.  Records
754              may be identified by bridge name.
755
756       Flow_Sample_Collector_Set
757              An IPFIX exporter configuration attached to a  bridge  for  sam‐
758              pling packets on a per-flow basis using OpenFlow sample actions.
759
760       Record names must be specified in full and with correct capitalization.
761       Names of tables and columns are not case-sensitive, and --  and  _  are
762       treated interchangeably.  Unique abbreviations are acceptable, e.g. net
763       or n is sufficient to identify the NetFlow table.
764
765     Database Values
766
767       Each column in the database accepts a fixed type  of  data.   The  cur‐
768       rently defined basic types, and their representations, are:
769
770       integer
771              A decimal integer in the range -2**63 to 2**63-1, inclusive.
772
773       real   A floating-point number.
774
775       Boolean
776              True or false, written true or false, respectively.
777
778       string An  arbitrary  Unicode  string,  except  that null bytes are not
779              allowed.  Quotes are optional for most strings that  begin  with
780              an  English  letter  or  underscore and consist only of letters,
781              underscores, hyphens, and periods.  However, true and false  and
782              strings  that  match  the  syntax  of  UUIDs (see below) must be
783              enclosed in double quotes to distinguish them from  other  basic
784              types.   When  double  quotes  are  used,  the syntax is that of
785              strings in JSON, e.g. backslashes may be used to escape  special
786              characters.   The  empty string must be represented as a pair of
787              double quotes ("").
788
789       UUID   Either a universally unique identifier in the style of RFC 4122,
790              e.g.  f81d4fae-7dec-11d0-a765-00a0c91e6bf6,  or an @name defined
791              by a get or create command within the same ovs-vsctl invocation.
792
793       Multiple values in a single column may be separated by spaces or a sin‐
794       gle  comma.   When  multiple  values  are  present,  duplicates are not
795       allowed, and order is not important.  Conversely, some database columns
796       can have an empty set of values, represented as [], and square brackets
797       may optionally enclose other non-empty sets or single values as well.
798
799       A few database columns are ``maps'' of key-value pairs, where  the  key
800       and  the  value are each some fixed database type.  These are specified
801       in the form key=value, where key and value follow the  syntax  for  the
802       column's  key  type  and value type, respectively.  When multiple pairs
803       are present (separated by spaces or a comma), duplicate  keys  are  not
804       allowed,  and  again  the order is not important.  Duplicate values are
805       allowed.  An empty map is represented as {}.  Curly braces may  option‐
806       ally  enclose  non-empty  maps  as  well (but use quotes to prevent the
807       shell  from  expanding  other-config={0=x,1=y}  into   other-config=0=x
808       other-config=1=y, which may not have the desired effect).
809
810     Database Command Syntax
811
812       [--if-exists] [--columns=column[,column]...] list table [record]...
813              Lists  the  data  in  each  specified record.  If no records are
814              specified, lists all the records in table.
815
816              If --columns  is  specified,  only  the  requested  columns  are
817              listed,  in  the  specified  order.   Otherwise, all columns are
818              listed, in alphabetical order by column name.
819
820              Without --if-exists, it is an error if any specified record does
821              not  exist.   With  --if-exists,  the command ignores any record
822              that does not exist, without producing any output.
823
824       [--columns=column[,column]...] find table [column[:key]=value]...
825              Lists the data in each record in table whose column equals value
826              or,  if  key  is specified, whose column contains a key with the
827              specified value.  The following operators may be used where = is
828              written in the syntax summary:
829
830              = != < > <= >=
831                     Selects  records  in  which column[:key] equals, does not
832                     equal, is less than, is greater than,  is  less  than  or
833                     equal  to,  or is greater than or equal to value, respec‐
834                     tively.
835
836                     Consider column[:key] and  value  as  sets  of  elements.
837                     Identical  sets  are considered equal.  Otherwise, if the
838                     sets have different numbers of  elements,  then  the  set
839                     with  more  elements  is considered to be larger.  Other‐
840                     wise, consider a  element  from  each  set  pairwise,  in
841                     increasing  order  within  each set.  The first pair that
842                     differs determines the result.  (For a column  that  con‐
843                     tains  key-value  pairs, first all the keys are compared,
844                     and values are considered only if the  two  sets  contain
845                     identical keys.)
846
847              {=} {!=}
848                     Test for set equality or inequality, respectively.
849
850              {<=}   Selects  records  in  which  column[:key]  is a subset of
851                     value.  For example, flood-vlans{<=}1,2  selects  records
852                     in  which the flood-vlans column is the empty set or con‐
853                     tains 1 or 2 or both.
854
855              {<}    Selects records in which column[:key] is a proper  subset
856                     of value.  For example, flood-vlans{<}1,2 selects records
857                     in which the flood-vlans column is the empty set or  con‐
858                     tains 1 or 2 but not both.
859
860              {>=} {>}
861                     Same as {<=} and {<}, respectively, except that the rela‐
862                     tionship is reversed.   For  example,  flood-vlans{>=}1,2
863                     selects  records in which the flood-vlans column contains
864                     both 1 and 2.
865
866              For arithmetic operators (= != < > <= >=), when key is specified
867              but  a  particular  record's  column  does  not contain key, the
868              record is always omitted from the results.  Thus, the  condition
869              other-config:mtu!=1500 matches records that have a mtu key whose
870              value is not 1500, but not those that lack an mtu key.
871
872              For the set operators, when key is specified  but  a  particular
873              record's  column  does  not  contain key, the comparison is done
874              against  an  empty  set.    Thus,   the   condition   other-con‐
875              fig:mtu{!=}1500  matches records that have a mtu key whose value
876              is not 1500 and those that lack an mtu key.
877
878              Don't forget to escape < or > from interpretation by the shell.
879
880              If --columns  is  specified,  only  the  requested  columns  are
881              listed,  in  the  specified  order.   Otherwise  all columns are
882              listed, in alphabetical order by column name.
883
884              The UUIDs shown for rows created in the same  ovs-vsctl  invoca‐
885              tion will be wrong.
886
887       [--if-exists] [--id=@name] get table record [column[:key]]...
888              Prints the value of each specified column in the given record in
889              table.  For map columns, a key may optionally be  specified,  in
890              which  case  the  value  associated  with  key  in the column is
891              printed, instead of the entire map.
892
893              Without --if-exists, it is an error if record does not exist  or
894              key  is  specified,  if  key  does  not  exist  in record.  With
895              --if-exists, a missing record yields no output and a missing key
896              prints a blank line.
897
898              If  @name is specified, then the UUID for record may be referred
899              to by that name later in the same ovs-vsctl invocation  in  con‐
900              texts where a UUID is expected.
901
902              Both  --id and the column arguments are optional, but usually at
903              least one or the other should be specified.  If both  are  omit‐
904              ted,  then get has no effect except to verify that record exists
905              in table.
906
907              --id and --if-exists cannot be used together.
908
909       [--if-exists] set table record column[:key]=value...
910              Sets the value of each specified column in the given  record  in
911              table to value.  For map columns, a key may optionally be speci‐
912              fied, in which case the value associated with key in that column
913              is  changed  (or  added,  if none exists), instead of the entire
914              map.
915
916              Without --if-exists, it is an error if record  does  not  exist.
917              With  --if-exists,  this command does nothing if record does not
918              exist.
919
920       [--if-exists] add table record column [key=]value...
921              Adds the specified value or key-value pair to column  in  record
922              in  table.   If column is a map, then key is required, otherwise
923              it is prohibited.  If key already exists in a map  column,  then
924              the  current  value  is  not  replaced  (use  the set command to
925              replace an existing value).
926
927              Without --if-exists, it is an error if record  does  not  exist.
928              With  --if-exists,  this command does nothing if record does not
929              exist.
930
931       [--if-exists] remove table record column value...
932       [--if-exists] remove table record column key...
933       [--if-exists] remove table record column key=value...
934              Removes the specified values or key-value pairs from  column  in
935              record in table.  The first form applies to columns that are not
936              maps: each specified value is removed from the column.  The sec‐
937              ond and third forms apply to map columns: if only a key is spec‐
938              ified, then any key-value pair with the given  key  is  removed,
939              regardless  of  its  value;  if  a value is given then a pair is
940              removed only if both key and value match.
941
942              It is not an error if the column does not contain the  specified
943              key or value or pair.
944
945              Without  --if-exists,  it  is an error if record does not exist.
946              With --if-exists, this command does nothing if record  does  not
947              exist.
948
949       [--if-exists] clear table record column...
950              Sets  each  column  in record in table to the empty set or empty
951              map, as appropriate.  This command applies only to columns  that
952              are allowed to be empty.
953
954              Without  --if-exists,  it  is an error if record does not exist.
955              With --if-exists, this command does nothing if record  does  not
956              exist.
957
958       [--id=@name] create table column[:key]=value...
959              Creates  a  new  record  in table and sets the initial values of
960              each column.  Columns not  explicitly  set  will  receive  their
961              default values.  Outputs the UUID of the new row.
962
963              If  @name  is  specified,  then  the UUID for the new row may be
964              referred to by that name elsewhere in the same ovs-vsctl invoca‐
965              tion  in contexts where a UUID is expected.  Such references may
966              precede or follow the create command.
967
968              Records in the Open vSwitch database are significant  only  when
969              they can be reached directly or indirectly from the Open_vSwitch
970              table.  Except for records in the QoS or Queue  tables,  records
971              that are not reachable from the Open_vSwitch table are automati‐
972              cally deleted from the database.  This deletion happens  immedi‐
973              ately,  without  waiting  for  additional  ovs-vsctl commands or
974              other database activity.  Thus, a create command must  generally
975              be  accompanied by additional commands within the same ovs-vsctl
976              invocation to add a chain of references  to  the  newly  created
977              record  from  the  top-level  Open_vSwitch record.  The EXAMPLES
978              section gives some examples that show how to do this.
979
980       [--if-exists] destroy table record...
981              Deletes each specified record from table.  Unless --if-exists is
982              specified, each records must exist.
983
984       --all destroy table
985              Deletes all records from the table.
986
987              The  destroy  command  is  only useful for records in the QoS or
988              Queue tables.  Records in other tables are automatically deleted
989              from   the  database  when  they  become  unreachable  from  the
990              Open_vSwitch table.  This means that deleting the last reference
991              to  a  record is sufficient for deleting the record itself.  For
992              records in these tables, destroy is silently ignored.   See  the
993              EXAMPLES section below for more information.
994
995       wait-until table record [column[:key]=value]...
996              Waits  until  table  contains a record named record whose column
997              equals value or, if key is specified, whose  column  contains  a
998              key  with  the  specified value.  Any of the operators !=, <, >,
999              <=, or >= may be substituted for = to test for inequality,  less
1000              than,  greater  than,  less than or equal to, or greater than or
1001              equal to, respectively.  (Don't forget to escape  <  or  >  from
1002              interpretation by the shell.)
1003
1004              If no column[:key]=value arguments are given, this command waits
1005              only until record exists.  If more than  one  such  argument  is
1006              given, the command waits until all of them are satisfied.
1007
1008              Usually wait-until should be placed at the beginning of a set of
1009              ovs-vsctl commands.  For example, wait-until bridge br0  --  get
1010              bridge  br0  datapath_id  waits until a bridge named br0 is cre‐
1011              ated, then prints its datapath_id column, whereas get bridge br0
1012              datapath_id  --  wait-until  bridge  br0 will abort if no bridge
1013              named br0 exists when ovs-vsctl initially connects to the  data‐
1014              base.
1015
1016              Consider specifying --timeout=0 along with --wait-until, to pre‐
1017              vent ovs-vsctl from terminating after waiting  only  at  most  5
1018              seconds.
1019
1020       comment [arg]...
1021              This  command  has  no  effect on behavior, but any database log
1022              record created by the command will include the command  and  its
1023              arguments.
1024

EXAMPLES

1026       Create a new bridge named br0 and add port eth0 to it:
1027
1028              ovs-vsctl add-br br0
1029              ovs-vsctl add-port br0 eth0
1030
1031       Alternatively, perform both operations in a single atomic transaction:
1032
1033              ovs-vsctl add-br br0 -- add-port br0 eth0
1034
1035       Delete bridge br0, reporting an error if it does not exist:
1036
1037              ovs-vsctl del-br br0
1038
1039       Delete bridge br0 if it exists:
1040
1041              ovs-vsctl --if-exists del-br br0
1042
1043       Set  the  qos  column of the Port record for eth0 to point to a new QoS
1044       record, which in turn points with its queue 0 to a new Queue record:
1045
1046              ovs-vsctl -- set port eth0 qos=@newqos  --  --id=@newqos  create
1047              qos         type=linux-htb         other-config:max-rate=1000000
1048              queues:0=@newqueue --  --id=@newqueue  create  queue  other-con‐
1049              fig:min-rate=1000000 other-config:max-rate=1000000
1050

CONFIGURATION COOKBOOK

1052   Port Configuration
1053       Add an ``internal port'' vlan10 to bridge br0 as a VLAN access port for
1054       VLAN 10, and configure it with an IP address:
1055
1056              ovs-vsctl add-port br0 vlan10 tag=10  --  set  Interface  vlan10
1057              type=internal
1058
1059              ifconfig vlan10 192.168.0.123
1060
1061       Add a GRE tunnel port gre0 to remote IP address 1.2.3.4 to bridge br0:
1062
1063              ovs-vsctl  add-port  br0  gre0  --  set  Interface gre0 type=gre
1064              options:remote_ip=1.2.3.4
1065
1066   Port Mirroring
1067       Mirror all packets received or sent on eth0 or eth1 onto eth2, assuming
1068       that  all  of  those  ports  exist on bridge br0 (as a side-effect this
1069       causes any packets received on eth2 to be ignored):
1070
1071              ovs-vsctl -- set Bridge br0 mirrors=@m \
1072
1073              -- --id=@eth0 get Port eth0 \
1074
1075              -- --id=@eth1 get Port eth1 \
1076
1077              -- --id=@eth2 get Port eth2 \
1078
1079              --   --id=@m    create    Mirror    name=mymirror    select-dst-
1080              port=@eth0,@eth1 select-src-port=@eth0,@eth1 output-port=@eth2
1081
1082       Remove  the mirror created above from br0, which also destroys the Mir‐
1083       ror record (since it is now unreferenced):
1084
1085              ovs-vsctl -- --id=@rec get Mirror mymirror \
1086
1087              -- remove Bridge br0 mirrors @rec
1088
1089       The following simpler command also works:
1090
1091              ovs-vsctl clear Bridge br0 mirrors
1092
1093   Quality of Service (QoS)
1094       Create a linux-htb QoS record that points to a few queues and use it on
1095       eth0 and eth1:
1096
1097              ovs-vsctl -- set Port eth0 qos=@newqos \
1098
1099              -- set Port eth1 qos=@newqos \
1100
1101              --    --id=@newqos    create   QoS   type=linux-htb   other-con‐
1102              fig:max-rate=1000000000 queues=0=@q0,1=@q1 \
1103
1104              --   --id=@q0   create   Queue   other-config:min-rate=100000000
1105              other-config:max-rate=100000000 \
1106
1107              -- --id=@q1 create Queue other-config:min-rate=500000000
1108
1109       Deconfigure the QoS record above from eth1 only:
1110
1111              ovs-vsctl clear Port eth1 qos
1112
1113       To  deconfigure  the QoS record from both eth0 and eth1 and then delete
1114       the QoS record (which must be done explicitly because unreferenced  QoS
1115       records are not automatically destroyed):
1116
1117              ovs-vsctl  --  destroy  QoS eth0 -- clear Port eth0 qos -- clear
1118              Port eth1 qos
1119
1120       (This command will leave two unreferenced Queue records  in  the  data‐
1121       base.   To delete them, use "ovs-vsctl list Queue" to find their UUIDs,
1122       then "ovs-vsctl destroy Queue uuid1 uuid2" to destroy each of  them  or
1123       use "ovs-vsctl -- --all destroy Queue" to delete all records.)
1124
1125   Connectivity Monitoring
1126       Monitor connectivity to a remote maintenance point on eth0.
1127
1128              ovs-vsctl set Interface eth0 cfm_mpid=1
1129
1130       Deconfigure connectivity monitoring from above:
1131
1132              ovs-vsctl clear Interface eth0 cfm_mpid
1133
1134   NetFlow
1135       Configure  bridge  br0 to send NetFlow records to UDP port 5566 on host
1136       192.168.0.34, with an active timeout of 30 seconds:
1137
1138              ovs-vsctl -- set Bridge br0 netflow=@nf \
1139
1140              --   --id=@nf   create   NetFlow   targets=\"192.168.0.34:5566\"
1141              active-timeout=30
1142
1143       Update  the  NetFlow  configuration  created by the previous command to
1144       instead use an active timeout of 60 seconds:
1145
1146              ovs-vsctl set NetFlow br0 active_timeout=60
1147
1148       Deconfigure the NetFlow settings from br0, which also destroys the Net‐
1149       Flow record (since it is now unreferenced):
1150
1151              ovs-vsctl clear Bridge br0 netflow
1152
1153   sFlow
1154       Configure  bridge  br0 to send sFlow records to a collector on 10.0.0.1
1155       at port 6343, using eth1´s IP address as the source, with specific sam‐
1156       pling parameters:
1157
1158              ovs-vsctl    --    --id=@s    create   sFlow   agent=eth1   tar‐
1159              get=\"10.0.0.1:6343\" header=128 sampling=64 polling=10 \
1160
1161              -- set Bridge br0 sflow=@s
1162
1163       Deconfigure sFlow from br0, which also destroys the sFlow record (since
1164       it is now unreferenced):
1165
1166              ovs-vsctl -- clear Bridge br0 sflow
1167
1168   IPFIX
1169       Configure bridge br0 to send one IPFIX flow record per packet sample to
1170       UDP port 4739 on host 192.168.0.34, with Observation Domain ID 123  and
1171       Observation  Point  ID 456, a flow cache active timeout of 1 minute (60
1172       seconds), and a maximum flow cache size of 13 flows:
1173
1174              ovs-vsctl -- set Bridge br0 ipfix=@i \
1175
1176              --   --id=@i    create    IPFIX    targets=\"192.168.0.34:4739\"
1177              obs_domain_id=123    obs_point_id=456    cache_active_timeout=60
1178              cache_max_flows=13
1179
1180       Deconfigure the IPFIX settings from br0, which also destroys the  IPFIX
1181       record (since it is now unreferenced):
1182
1183              ovs-vsctl clear Bridge br0 ipfix
1184
1185   802.1D Spanning Tree Protocol (STP)
1186       Configure bridge br0 to participate in an 802.1D spanning tree:
1187
1188              ovs-vsctl set Bridge br0 stp_enable=true
1189
1190       Set the bridge priority of br0 to 0x7800:
1191
1192              ovs-vsctl set Bridge br0 other_config:stp-priority=0x7800
1193
1194       Set the path cost of port eth0 to 10:
1195
1196              ovs-vsctl set Port eth0 other_config:stp-path-cost=10
1197
1198       Deconfigure STP from above:
1199
1200              ovs-vsctl clear Bridge br0 stp_enable
1201
1202   OpenFlow Version
1203       Configure bridge br0 to support OpenFlow versions 1.0, 1.2, and 1.3:
1204
1205              ovs-vsctl  set  bridge br0 protocols=openflow10,openflow12,open‐
1206              flow13
1207

EXIT STATUS

1209       0      Successful program execution.
1210
1211       1      Usage, syntax, or configuration file error.
1212
1213       2      The bridge argument to br-exists specified the name of a  bridge
1214              that does not exist.
1215

SEE ALSO

1217       ovsdb-server(1), ovs-vswitchd(8), ovs-vswitchd.conf.db(5).
1218
1219
1220
1221Open vSwitch                         2.0.0                        ovs-vsctl(8)
Impressum