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

NAME

6       ovs-vswitchd - Open vSwitch daemon
7

SYNOPSIS

9       ovs-vswitchd [database]
10

DESCRIPTION

12       A  daemon that manages and controls any number of Open vSwitch switches
13       on the local machine.
14
15       The  database  argument  specifies   how   ovs-vswitchd   connects   to
16       ovsdb-server.   database  may  be an OVSDB active or passive connection
17       method, as described in ovsdb(7).  The default  is  unix:/var/run/open‐
18       vswitch/db.sock.
19
20       ovs-vswitchd  retrieves its configuration from database at startup.  It
21       sets up Open vSwitch datapaths and then operates switching across  each
22       bridge  described in its configuration files.  As the database changes,
23       ovs-vswitchd automatically updates its configuration to match.
24
25       ovs-vswitchd switches may be configured with any of the following  fea‐
26       tures:
27
28       ·      L2 switching with MAC learning.
29
30       ·      NIC  bonding  with  automatic  fail-over and source MAC-based TX
31              load balancing ("SLB").
32
33       ·      802.1Q VLAN support.
34
35       ·      Port mirroring, with optional VLAN tagging.
36
37       ·      NetFlow v5 flow logging.
38
39       ·      sFlow(R) monitoring.
40
41       ·      Connectivity to an external OpenFlow controller, such as NOX.
42
43       Only a single instance of ovs-vswitchd is intended to run at a time.  A
44       single  ovs-vswitchd  can  manage any number of switch instances, up to
45       the maximum number of supported Open vSwitch datapaths.
46
47       ovs-vswitchd does all the necessary management of  Open  vSwitch  data‐
48       paths  itself.  Thus, ovs-dpctl(8) (and its userspace datapath counter‐
49       parts accessible via ovs-appctl  dpctl/command)  are  not  needed  with
50       ovs-vswitchd and should not be used because they can interfere with its
51       operation.  These tools are still useful for diagnostics.
52
53       An Open vSwitch datapath kernel module must be loaded for  ovs-vswitchd
54       to  be  useful.   Refer to the documentation for instructions on how to
55       build and load the Open vSwitch kernel module.
56

OPTIONS

58       --mlockall
59              Causes ovs-vswitchd to call the mlockall() function, to  attempt
60              to  lock all of its process memory into physical RAM, preventing
61              the kernel from paging any of its memory to disk.  This helps to
62              avoid networking interruptions due to system memory pressure.
63
64              Some systems do not support mlockall() at all, and other systems
65              only allow privileged users, such as the superuser, to  use  it.
66              ovs-vswitchd emits a log message if mlockall() is unavailable or
67              unsuccessful.
68
69   DPDK Options
70       For details on initializing the ovs-vswitchd DPDK  datapath,  refer  to
71       the documentation or ovs-vswitchd.conf.db(5) for details.
72
73   Daemon Options
74       The following options are valid on POSIX based platforms.
75
76       --pidfile[=pidfile]
77              Causes a file (by default, ovs-vswitchd.pid) to be created indi‐
78              cating the PID of the running process.  If the pidfile  argument
79              is  not  specified,  or  if it does not begin with /, then it is
80              created in /var/run/openvswitch.
81
82              If --pidfile is not specified, no pidfile is created.
83
84       --overwrite-pidfile
85              By default, when --pidfile is specified and the  specified  pid‐
86              file  already  exists  and  is  locked  by  a  running  process,
87              ovs-vswitchd refuses to start.  Specify  --overwrite-pidfile  to
88              cause it to instead overwrite the pidfile.
89
90              When --pidfile is not specified, this option has no effect.
91
92       --detach
93              Runs  ovs-vswitchd  as a background process.  The process forks,
94              and in the child it starts a new session,  closes  the  standard
95              file descriptors (which has the side effect of disabling logging
96              to the console), and changes its current directory to  the  root
97              (unless --no-chdir is specified).  After the child completes its
98              initialization, the parent exits.   ovs-vswitchd  detaches  only
99              after  it  has  connected to the database, retrieved the initial
100              configuration, and set up that configuration.
101
102       --monitor
103              Creates an additional process to monitor the  ovs-vswitchd  dae‐
104              mon.   If  the daemon dies due to a signal that indicates a pro‐
105              gramming error (SIGABRT, SIGALRM, SIGBUS, SIGFPE,  SIGILL,  SIG‐
106              PIPE,  SIGSEGV,  SIGXCPU,  or  SIGXFSZ) then the monitor process
107              starts a new copy of it.   If  the  daemon  dies  or  exits  for
108              another reason, the monitor process exits.
109
110              This  option  is  normally used with --detach, but it also func‐
111              tions without it.
112
113       --no-chdir
114              By default, when --detach is specified, ovs-vswitchd changes its
115              current  working  directory  to  the  root  directory  after  it
116              detaches.  Otherwise, invoking ovs-vswitchd  from  a  carelessly
117              chosen directory would prevent the administrator from unmounting
118              the file system that holds that directory.
119
120              Specifying  --no-chdir  suppresses  this  behavior,   preventing
121              ovs-vswitchd  from changing its current working directory.  This
122              may be useful for collecting core  files,  since  it  is  common
123              behavior  to write core dumps into the current working directory
124              and the root directory is not a good directory to use.
125
126              This option has no effect when --detach is not specified.
127
128       --no-self-confinement
129              By default daemon will try to self-confine itself to  work  with
130              files  under  well-know,  at build-time whitelisted directories.
131              It is better to stick with this default behavior and not to  use
132              this  flag  unless  some other Access Control is used to confine
133              daemon.  Note that in contrast to other access control implemen‐
134              tations  that are typically enforced from kernel-space (e.g. DAC
135              or MAC), self-confinement is imposed from the user-space  daemon
136              itself  and hence should not be considered as a full confinement
137              strategy, but instead should be viewed as an additional layer of
138              security.
139
140       --user Causes  ovs-vswitchd  to  run  as  a different user specified in
141              "user:group", thus dropping most of the root  privileges.  Short
142              forms "user" and ":group" are also allowed, with current user or
143              group are assumed respectively. Only daemons started by the root
144              user accepts this argument.
145
146              On   Linux,   daemons   will   be   granted   CAP_IPC_LOCK   and
147              CAP_NET_BIND_SERVICES before dropping root  privileges.  Daemons
148              that  interact  with  a  datapath, such as ovs-vswitchd, will be
149              granted three  additional  capabilities,  namely  CAP_NET_ADMIN,
150              CAP_NET_BROADCAST  and  CAP_NET_RAW.  The capability change will
151              apply even if the new user is root.
152
153              On Windows, this option is not currently supported. For security
154              reasons,  specifying  this  option will cause the daemon process
155              not to start.
156
157   Service Options
158       The following options are valid only on Windows platform.
159
160       --service
161              Causes ovs-vswitchd to run as a service in the  background.  The
162              service  should already have been created through external tools
163              like SC.exe.
164
165       --service-monitor
166              Causes the ovs-vswitchd service to be automatically restarted by
167              the  Windows  services  manager if the service dies or exits for
168              unexpected reasons.
169
170              When --service is not specified, this option has no effect.
171
172   Public Key Infrastructure Options
173       -p privkey.pem
174       --private-key=privkey.pem
175              Specifies  a  PEM  file  containing  the  private  key  used  as
176              ovs-vswitchd's identity for outgoing SSL connections.
177
178       -c cert.pem
179       --certificate=cert.pem
180              Specifies a PEM file containing a certificate that certifies the
181              private key specified on -p or --private-key to be  trustworthy.
182              The certificate must be signed by the certificate authority (CA)
183              that the peer in SSL connections will use to verify it.
184
185       -C cacert.pem
186       --ca-cert=cacert.pem
187              Specifies  a  PEM  file  containing  the  CA  certificate   that
188              ovs-vswitchd  should  use to verify certificates presented to it
189              by SSL peers.  (This may be the same certificate that SSL  peers
190              use  to verify the certificate specified on -c or --certificate,
191              or it may be a different one, depending on  the  PKI  design  in
192              use.)
193
194       -C none
195       --ca-cert=none
196              Disables  verification  of  certificates presented by SSL peers.
197              This introduces a security risk, because it means that  certifi‐
198              cates cannot be verified to be those of known trusted hosts.
199
200       --bootstrap-ca-cert=cacert.pem
201              When cacert.pem exists, this option has the same effect as -C or
202              --ca-cert.  If it does not exist, then ovs-vswitchd will attempt
203              to  obtain the CA certificate from the SSL peer on its first SSL
204              connection and save it to the named PEM file.  If it is success‐
205              ful,  it will immediately drop the connection and reconnect, and
206              from then on all SSL connections must be authenticated by a cer‐
207              tificate signed by the CA certificate thus obtained.
208
209              This  option  exposes  the SSL connection to a man-in-the-middle
210              attack obtaining the initial CA certificate, but it may be  use‐
211              ful for bootstrapping.
212
213              This option is only useful if the SSL peer sends its CA certifi‐
214              cate as part of the SSL certificate  chain.   The  SSL  protocol
215              does not require the server to send the CA certificate.
216
217              This option is mutually exclusive with -C and --ca-cert.
218
219       --peer-ca-cert=peer-cacert.pem
220              Specifies  a  PEM file that contains one or more additional cer‐
221              tificates to send to SSL peers.  peer-cacert.pem should  be  the
222              CA certificate used to sign ovs-vswitchd's own certificate, that
223              is, the  certificate  specified  on  -c  or  --certificate.   If
224              ovs-vswitchd's  certificate  is  self-signed, then --certificate
225              and --peer-ca-cert should specify the same file.
226
227              This option is not useful in normal operation, because  the  SSL
228              peer  must  already have the CA certificate for the peer to have
229              any confidence in ovs-vswitchd's identity.  However, this offers
230              a  way for a new installation to bootstrap the CA certificate on
231              its first SSL connection.
232
233   Logging Options
234       -v[spec]
235       --verbose=[spec]
236              Sets logging levels.  Without any spec, sets the log  level  for
237              every  module and destination to dbg.  Otherwise, spec is a list
238              of words separated by spaces or commas or colons, up to one from
239              each category below:
240
241              ·      A  valid  module name, as displayed by the vlog/list com‐
242                     mand on ovs-appctl(8), limits the log level change to the
243                     specified module.
244
245              ·      syslog,  console,  or file, to limit the log level change
246                     to only to the system log, to the console, or to a  file,
247                     respectively.   (If  --detach  is specified, ovs-vswitchd
248                     closes its standard file descriptors, so logging  to  the
249                     console will have no effect.)
250
251                     On  Windows platform, syslog is accepted as a word and is
252                     only useful along with the  --syslog-target  option  (the
253                     word has no effect otherwise).
254
255              ·      off,  emer,  err,  warn, info, or dbg, to control the log
256                     level.  Messages of the given severity or higher will  be
257                     logged,  and  messages of lower severity will be filtered
258                     out.  off filters out all  messages.   See  ovs-appctl(8)
259                     for a definition of each log level.
260
261              Case is not significant within spec.
262
263              Regardless  of  the  log  levels set for file, logging to a file
264              will not take place unless --log-file  is  also  specified  (see
265              below).
266
267              For compatibility with older versions of OVS, any is accepted as
268              a word but has no effect.
269
270       -v
271       --verbose
272              Sets the maximum logging verbosity level, equivalent  to  --ver‐
273              bose=dbg.
274
275       -vPATTERN:destination:pattern
276       --verbose=PATTERN:destination:pattern
277              Sets  the  log  pattern  for  destination  to pattern.  Refer to
278              ovs-appctl(8) for a description of the valid syntax for pattern.
279
280       -vFACILITY:facility
281       --verbose=FACILITY:facility
282              Sets the RFC5424 facility of the log message.  facility  can  be
283              one  of kern, user, mail, daemon, auth, syslog, lpr, news, uucp,
284              clock, ftp, ntp, audit, alert, clock2, local0,  local1,  local2,
285              local3,  local4, local5, local6 or local7. If this option is not
286              specified, daemon is used as the default for  the  local  system
287              syslog  and local0 is used while sending a message to the target
288              provided via the --syslog-target option.
289
290       --log-file[=file]
291              Enables logging to a file.  If file is  specified,  then  it  is
292              used  as  the exact name for the log file.  The default log file
293              name   used   if   file    is    omitted    is    /var/log/open‐
294              vswitch/ovs-vswitchd.log.
295
296       --syslog-target=host:port
297              Send  syslog  messages  to  UDP port on host, in addition to the
298              system syslog.  The host must be a numerical IP address,  not  a
299              hostname.
300
301       --syslog-method=method
302              Specify method how syslog messages should be sent to syslog dae‐
303              mon.  Following forms are supported:
304
305              ·      libc, use libc syslog() function.  This  is  the  default
306                     behavior.   Downside  of  using this options is that libc
307                     adds fixed prefix to every message before it is  actually
308                     sent  to  the  syslog  daemon  over  /dev/log UNIX domain
309                     socket.
310
311              ·      unix:file, use UNIX domain socket directly.  It is possi‐
312                     ble to specify arbitrary message format with this option.
313                     However, rsyslogd 8.9 and older versions use  hard  coded
314                     parser  function  anyway  that  limits UNIX domain socket
315                     use.  If you want to use arbitrary  message  format  with
316                     older rsyslogd versions, then use UDP socket to localhost
317                     IP address instead.
318
319              ·      udp:ip:port, use UDP socket.  With this method it is pos‐
320                     sible  to  use  arbitrary  message format also with older
321                     rsyslogd.  When sending syslog messages over  UDP  socket
322                     extra  precaution  needs  to  be  taken into account, for
323                     example, syslog daemon needs to be configured  to  listen
324                     on  the  specified  UDP  port,  accidental iptables rules
325                     could be interfering with local syslog traffic and  there
326                     are  some security considerations that apply to UDP sock‐
327                     ets, but do not apply to UNIX domain sockets.
328
329   Other Options
330       --unixctl=socket
331              Sets the name of the control socket on which  ovs-vswitchd  lis‐
332              tens  for  runtime  management  commands (see RUNTIME MANAGEMENT
333              COMMANDS, below).  If socket does not begin with /, it is inter‐
334              preted as relative to /var/run/openvswitch.  If --unixctl is not
335              used   at   all,   the   default   socket   is    /var/run/open‐
336              vswitch/ovs-vswitchd.pid.ctl,   where   pid   is  ovs-vswitchd's
337              process ID.
338
339              On Windows a local named pipe is used to listen for runtime man‐
340              agement  commands.   A  file  is created in the absolute path as
341              pointed by socket or if --unixctl is not used at all, a file  is
342              created  as ovs-vswitchd.ctl in the configured OVS_RUNDIR direc‐
343              tory.  The file exists just to mimic  the  behavior  of  a  Unix
344              domain socket.
345
346              Specifying none for socket disables the control socket feature.
347
348       -h
349       --help Prints a brief help message to the console.
350
351       -V
352       --version
353              Prints version information to the console.
354

RUNTIME MANAGEMENT COMMANDS

356       ovs-appctl(8) can send commands to a running ovs-vswitchd process.  The
357       currently supported commands are described below.  The command descrip‐
358       tions assume an understanding of how to configure Open vSwitch.
359
360   GENERAL COMMANDS
361       exit --cleanup
362              Causes  ovs-vswitchd  to  gracefully  terminate. If --cleanup is
363              specified,   release   datapath    resources    configured    by
364              ovs-vswitchd.   Otherwise,  datapath  flows  and other resources
365              remains undeleted.
366
367       qos/show-types interface
368              Queries the interface for a list of  Quality  of  Service  types
369              that are configurable via Open vSwitch for the given interface.
370
371       qos/show interface
372              Queries the kernel for Quality of Service configuration and sta‐
373              tistics associated with the given interface.
374
375       bfd/show [interface]
376              Displays detailed  information  about  Bidirectional  Forwarding
377              Detection  configured  on interface.  If interface is not speci‐
378              fied, then displays detailed information  about  all  interfaces
379              with BFD enabled.
380
381       bfd/set-forwarding [interface] status
382              Force  the  fault  status of the BFD module on interface (or all
383              interfaces if none is  given)  to  be  status.   status  can  be
384              "true",  "false",  or  "normal"  which  reverts  to the standard
385              behavior.
386
387       cfm/show [interface]
388              Displays detailed information about Connectivity  Fault  Manage‐
389              ment  configured  on  interface.  If interface is not specified,
390              then displays detailed information about all interfaces with CFM
391              enabled.
392
393       cfm/set-fault [interface] status
394              Force  the  fault  status of the CFM module on interface (or all
395              interfaces if none is  given)  to  be  status.   status  can  be
396              "true",  "false",  or  "normal"  which  reverts  to the standard
397              behavior.
398
399       stp/tcn [bridge]
400              Forces a topology change event on bridge if  it's  running  STP.
401              This  may  cause it to send Topology Change Notifications to its
402              peers and flush its MAC table.  If no bridge is given, forces  a
403              topology change event on all bridges.
404
405       stp/show [bridge]
406              Displays detailed information about spanning tree on the bridge.
407              If bridge is not specified, then displays  detailed  information
408              about all bridges with STP enabled.
409
410       rstp/tcn [bridge]
411              Forces  a  topology change event on bridge if it's running RSTP.
412              This may cause it to send Topology Change Notifications  to  its
413              peers  and flush its MAC table.  If no bridge is given, forces a
414              topology change event on all bridges.
415
416       rstp/show [bridge]
417              Displays detailed information about rapid spanning tree  on  the
418              bridge.   If  bridge  is  not  specified, then displays detailed
419              information about all bridges with RSTP enabled.
420
421   BRIDGE COMMANDS
422       These commands manage bridges.
423
424       fdb/flush [bridge]
425              Flushes bridge MAC  address  learning  table,  or  all  learning
426              tables if no bridge is given.
427
428       fdb/show bridge
429              Lists  each  MAC  address/VLAN  pair  learned  by  the specified
430              bridge, along with the port on which it was learned and the  age
431              of the entry, in seconds.
432
433       fdb/stats-clear [bridge]
434              Clear  bridge MAC address learning table statistics, or all sta‐
435              tistics if no bridge is given.
436
437       fdb/stats-show bridge
438              Show MAC address learning table  statistics  for  the  specified
439              bridge.
440
441       mdb/flush [bridge]
442              Flushes  bridge multicast snooping table, or all snooping tables
443              if no bridge is given.
444
445       mdb/show bridge
446              Lists each multicast group/VLAN pair learned  by  the  specified
447              bridge,  along with the port on which it was learned and the age
448              of the entry, in seconds.
449
450       bridge/reconnect [bridge]
451              Makes bridge drop all of its OpenFlow controller connections and
452              reconnect.   If  bridge  is not specified, then all bridges drop
453              their controller connections and reconnect.
454
455              This command might be useful for debugging  OpenFlow  controller
456              issues.
457
458       bridge/dump-flows bridge
459              Lists  all  flows  in bridge, including those normally hidden to
460              commands such as ovs-ofctl dump-flows.  Flows set up  by  mecha‐
461              nisms  such as in-band control and fail-open are hidden from the
462              controller since it is not allowed to modify or override them.
463
464   BOND COMMANDS
465       These commands manage bonded ports on an Open  vSwitch's  bridges.   To
466       understand  some  of  these  commands,  it is important to understand a
467       detail of the bonding implementation called ``source  load  balancing''
468       (SLB).   Instead  of  directly  assigning  Ethernet source addresses to
469       slaves, the bonding implementation computes a  function  that  maps  an
470       48-bit  Ethernet  source  addresses into an 8-bit value (a ``MAC hash''
471       value).  All of the Ethernet addresses that map to a single 8-bit value
472       are then assigned to a single slave.
473
474       bond/list
475              Lists all of the bonds, and their slaves, on each bridge.
476
477       bond/show [port]
478              Lists  all of the bond-specific information (updelay, downdelay,
479              time until the next rebalance) about the given bonded  port,  or
480              all  bonded  ports  if no port is given.  Also lists information
481              about each slave: whether it is enabled or disabled, the time to
482              completion  of  an  updelay  or downdelay if one is in progress,
483              whether it is the active  slave,  the  hashes  assigned  to  the
484              slave.   Any  LACP information related to this bond may be found
485              using the lacp/show command.
486
487       bond/migrate port hash slave
488              Only valid for SLB bonds.  Assigns a given MAC  hash  to  a  new
489              slave.   port  specifies  the bond port, hash the MAC hash to be
490              migrated (as a decimal number between 0 and 255), and slave  the
491              new slave to be assigned.
492
493              The reassignment is not permanent: rebalancing or fail-over will
494              cause the MAC hash to be shifted to a new  slave  in  the  usual
495              manner.
496
497              A MAC hash cannot be migrated to a disabled slave.
498
499       bond/set-active-slave port slave
500              Sets slave as the active slave on port.  slave must currently be
501              enabled.
502
503              The setting is  not  permanent:  a  new  active  slave  will  be
504              selected if slave becomes disabled.
505
506       bond/enable-slave port slave
507       bond/disable-slave port slave
508              Enables (or disables) slave on the given bond port, skipping any
509              updelay (or downdelay).
510
511              This setting is not permanent: it persists only until  the  car‐
512              rier status of slave changes.
513
514       bond/hash mac [vlan] [basis]
515              Returns the hash value which would be used for mac with vlan and
516              basis if specified.
517
518       lacp/show [port]
519              Lists all of the LACP related information about the given  port:
520              active or passive, aggregation key, system id, and system prior‐
521              ity.  Also lists information about each  slave:  whether  it  is
522              enabled or disabled, whether it is attached or detached, port id
523              and priority, actor information, and  partner  information.   If
524              port  is not specified, then displays detailed information about
525              all interfaces with CFM enabled.
526
527       lacp/stats-show [port]
528              Lists various stats about LACP PDUs (number of RX/TX  PDUs,  bad
529              PDUs  received)  and  slave  state (number of time slave's state
530              expired/defaulted and carrier  status  changed)  for  the  given
531              port.   If  port  is  not  specified, then displays stats of all
532              interfaces with LACP enabled.
533
534   DPCTL DATAPATH DEBUGGING COMMANDS
535       The primary way to configure ovs-vswitchd is through the  Open  vSwitch
536       database,  e.g. using ovs-vsctl(8).  These commands provide a debugging
537       interface for managing datapaths.  They  implement  the  same  features
538       (and syntax) as ovs-dpctl(8).  Unlike ovs-dpctl(8), these commands work
539       with datapaths that are integrated into ovs-vswitchd (e.g.  the  netdev
540       datapath type).
541
542       Do   not  use  commands  to  add  or  remove  or  modify  datapaths  if
543       ovs-vswitchd is running because this interferes with ovs-vswitchd's own
544       datapath management.
545
546       dpctl/add-dp dp [netdev[,option]...]
547              Creates datapath dp, with a local port also named dp.  This will
548              fail if a network device dp already exists.
549
550              If netdevs are specified, ovs-vswitchd  adds  them  to  the  new
551              datapath, just as if add-if was specified.
552
553       dpctl/del-dp dp
554              Deletes  datapath  dp.   If  dp  is  associated with any network
555              devices, they are automatically removed.
556
557       dpctl/add-if dp netdev[,option]...
558              Adds each netdev to the set of network devices datapath dp moni‐
559              tors,  where  dp is the name of an existing datapath, and netdev
560              is the name of one of the host's  network  devices,  e.g.  eth0.
561              Once a network device has been added to a datapath, the datapath
562              has complete ownership of the network device's traffic  and  the
563              network device appears silent to the rest of the system.
564
565              A  netdev  may be followed by a comma-separated list of options.
566              The following options are currently supported:
567
568              type=type
569                     Specifies the type of port to add.  The default  type  is
570                     system.
571
572              port_no=port
573                     Requests  a specific port number within the datapath.  If
574                     this option is not specified then one will  be  automati‐
575                     cally assigned.
576
577              key=value
578                     Adds an arbitrary key-value option to the port's configu‐
579                     ration.
580
581              ovs-vswitchd.conf.db(5) documents the available port  types  and
582              options.
583
584       dpctl/set-if dp port[,option]...
585              Reconfigures  each  port  in  dp as specified.  An option of the
586              form key=value adds the specified key-value option to  the  port
587              or  overrides  an  existing  key's value.  An option of the form
588              key=, that is, without a value, deletes the key-value named key.
589              The  type  and  port number of a port cannot be changed, so type
590              and port_no are only allowed if they match the existing configu‐
591              ration.
592
593       dpctl/del-if dp netdev...
594              Removes each netdev from the list of network devices datapath dp
595              monitors.
596
597       dpctl/dump-dps
598              Prints the name of each configured datapath on a separate line.
599
600       dpctl/show [-s | --statistics] [dp...]
601              Prints a summary of configured datapaths, including their  data‐
602              path  numbers  and  a  list of ports connected to each datapath.
603              (The local port is identified as port 0.)  If -s or --statistics
604              is specified, then packet and byte counters are also printed for
605              each port.
606
607              The datapath numbers consists of flow stats and mega  flow  mask
608              stats.
609
610              The  "lookups"  row  displays three stats related to flow lookup
611              triggered by processing incoming packets in the datapath.  "hit"
612              displays number of packets matches existing flows. "missed" dis‐
613              plays the number of packets not matching any existing  flow  and
614              require  user space processing.  "lost" displays number of pack‐
615              ets destined for user space  process  but  subsequently  dropped
616              before reaching userspace. The sum of "hit" and "miss" equals to
617              the total number of packets datapath processed.
618
619              The "flows" row displays the number of flows in datapath.
620
621              The "masks" row displays the mega flow mask stats. This  row  is
622              omitted  for datapath not implementing mega flow. "hit" displays
623              the total number of masks visited for matching incoming packets.
624              "total" displays number of masks in the datapath. "hit/pkt" dis‐
625              plays the average number of masks visited per packet; the  ratio
626              between "hit" and total number of packets processed by the data‐
627              path.
628
629              If one or more datapaths  are  specified,  information  on  only
630              those datapaths are displayed.  Otherwise, ovs-vswitchd displays
631              information about all configured datapaths.
632
633   DATAPATH FLOW TABLE DEBUGGING COMMANDS
634       The following commands are primarily useful for debugging Open vSwitch.
635       The  flow  table entries (both matches and actions) that they work with
636       are not OpenFlow flow entries.  Instead, they are different and consid‐
637       erably  simpler flows maintained by the Open vSwitch kernel module.  Do
638       not use  commands  to  add  or  remove  or  modify  datapath  flows  if
639       ovs-vswitchd  is  running because it interferes with ovs-vswitchd's own
640       datapath flow management.  Use  ovs-ofctl(8),  instead,  to  work  with
641       OpenFlow flow entries.
642
643       The  dp argument to each of these commands is optional when exactly one
644       datapath exists, in which case that datapath is the default.  When mul‐
645       tiple datapaths exist, then a datapath name is required.
646
647       dpctl/dump-flows [-m | --more] [--names | --no-names] [dp] [filter=fil‐
648       ter] [type=type]
649              Prints to the console all flow entries in datapath dp's flow ta‐
650              ble.   Without  -m  or  --more, output omits match fields that a
651              flow wildcards entirely; with -m or --more, output includes  all
652              wildcarded fields.
653
654              If  filter=filter  is  specified,  only  displays the flows that
655              match the filter. filter is a flow in the form similiar to  that
656              accepted  by  ovs-ofctl(8)'s  add-flow  command. (This is not an
657              OpenFlow flow: besides  other  differences,  it  never  contains
658              wildcards.)   The  filter  is  also  useful  to match wildcarded
659              fields   in   the   datapath   flow.   As   an   example,   fil‐
660              ter='tcp,tp_src=100'  will  match  the  datapath flow containing
661              'tcp(src=80/0xff00,dst=8080/0xff)'.
662
663              If type=type is specified, only displays  flows  of  a  specific
664              type.   type can be offloaded to display only rules offloaded to
665              the HW or ovs to display only rules from  the  OVS  tables.   By
666              default all rules are displayed.
667
668       dpctl/add-flow [dp] flow actions
669
670       dpctl/mod-flow  [--clear]  [--may-create] [-s | --statistics] [dp] flow
671       actions
672              Adds or modifies a flow in dp's flow table that, when  a  packet
673              matching flow arrives, causes actions to be executed.
674
675              The  add-flow  command  succeeds  only  if flow does not already
676              exist in dp.  Contrariwise, mod-flow without  --may-create  only
677              modifies  the  actions for an existing flow.  With --may-create,
678              mod-flow will add a new flow or modify an existing one.
679
680              If -s or --statistics is specified,  then  mod-flow  prints  the
681              modified  flow's statistics.  A flow's statistics are the number
682              of packets and bytes that have  passed  through  the  flow,  the
683              elapsed  time  since the flow last processed a packet (if ever),
684              and (for TCP flows) the union of the TCP flags processed through
685              the flow.
686
687              With  --clear,  mod-flow  zeros  out the flow's statistics.  The
688              statistics printed if -s or --statistics is also  specified  are
689              those from just before clearing the statistics.
690
691              NOTE:  flow  and  actions  do  not  match  the  syntax used with
692              ovs-ofctl(8)'s add-flow command.
693
694              Usage Examples
695
696              Forward ARP between ports 1 and 2 on datapath myDP:
697
698                     ovs-dpctl add-flow myDP \
699                       "in_port(1),eth(),eth_type(0x0806),arp()" 2
700
701                     ovs-dpctl add-flow myDP \
702                       "in_port(2),eth(),eth_type(0x0806),arp()" 1
703
704              Forward all IPv4 traffic between two addresses on ports 1 and 2:
705
706                     ovs-dpctl add-flow myDP \
707                       "in_port(1),eth(),eth_type(0x800),\
708                        ipv4(src=172.31.110.4,dst=172.31.110.5)" 2
709
710                     ovs-dpctl add-flow myDP \
711                       "in_port(2),eth(),eth_type(0x800),\
712                        ipv4(src=172.31.110.5,dst=172.31.110.4)" 1
713
714       dpctl/del-flow [-s | --statistics] [dp] flow
715              Deletes the flow from dp's flow table that matches flow.  If  -s
716              or  --statistics  is specified, then del-flow prints the deleted
717              flow's statistics.
718
719       dpctl/get-flow [dp] ufid:ufid [-m | --more] [--names | --no-names]
720              Fetches the flow from dp's flow  table  with  unique  identifier
721              ufid.   ufid  must  be  specified  as a string of 32 hexadecimal
722              characters.
723
724       dpctl/del-flows [dp]
725              Deletes all flow entries from datapath dp's flow table.
726
727   CONNECTION TRACKING TABLE COMMANDS
728       The following commands are useful for  debugging  and  configuring  the
729       connection tracking table in the datapath.
730
731       The  dp argument to each of these commands is optional when exactly one
732       datapath exists, in which case that datapath is the default.  When mul‐
733       tiple datapaths exist, then a datapath name is required.
734
735       N.B.(Linux  specific): the system datapaths (i.e. the Linux kernel mod‐
736       ule Open vSwitch datapaths) share a single  connection  tracking  table
737       (which is also used by other kernel subsystems, such as iptables, nfta‐
738       bles and the regular host stack).  Therefore, the following commands do
739       not apply specifically to one datapath.
740
741       dpctl/dump-conntrack [-m | --more] [-s | --statistics] [dp] [zone=zone]
742              Prints  to the console all the connection entries in the tracker
743              used by dp.  If zone=zone is specified, only shows  the  connec‐
744              tions  in  zone.   With  --more,  some  implementation  specific
745              details are included. With --statistics timeouts and  timestamps
746              are added to the output.
747
748       dpctl/flush-conntrack [dp] [zone=zone] [ct-tuple]
749              Flushes  the  connection entries in the tracker used by dp based
750              on zone and connection tracking tuple ct-tuple.  If ct-tuple  is
751              not  provided, flushes all the connection entries.  If zone=zone
752              is specified, only flushes the connections in zone.
753
754              If ct-tuple is provided, flushes the connection entry  specified
755              by  ct-tuple  in  zone. The zone defaults to 0 if it is not pro‐
756              vided.  An example of an IPv4 ICMP ct-tuple:
757
758              "ct_nw_src=10.1.1.1,ct_nw_dst=10.1.1.2,ct_nw_proto=1,icmp_type=8,icmp_code=0,icmp_id=10"
759
760              An example of an IPv6 TCP ct-tuple:
761
762              "ct_ipv6_src=fc00::1,ct_ipv6_dst=fc00::2,ct_nw_proto=6,ct_tp_src=1,ct_tp_dst=2"
763
764       dpctl/ct-stats-show [dp] [zone=zone] [-m | --more]
765              Displays the number of connections grouped by protocol  used  by
766              dp.  If zone=zone is specified, numbers refer to the connections
767              in zone.  With --more, groups by connection state for each  pro‐
768              tocol.
769
770       dpctl/ct-bkts [dp] [gt=threshold]
771              For  each  conntrack  bucket, displays the number of connections
772              used by dp.  If gt=threshold is specified,  bucket  numbers  are
773              displayed  when the number of connections in a bucket is greater
774              than threshold.
775
776       dpctl/ct-set-maxconns [dp] maxconns
777              Sets the maximum limit of connection tracker entries to maxconns
778              on  dp.   This  can be used to reduce the processing load on the
779              system due to connection tracking or simply limiting  connection
780              tracking.   If the number of connections is already over the new
781              maximum limit  request  then  the  new  maximum  limit  will  be
782              enforced when the number of connections decreases to that limit,
783              which normally happens due to connection expiry.  Only supported
784              for userspace datapath.
785
786       dpctl/ct-get-maxconns [dp]
787              Prints  the  maximum  limit of connection tracker entries on dp.
788              Only supported for userspace datapath.
789
790       dpctl/ct-get-nconns [dp]
791              Prints the current number of connection tracker entries  on  dp.
792              Only supported for userspace datapath.
793
794       dpctl/ct-set-limits             [dp]            [default=default_limit]
795       [zone=zone,limit=limit]...
796              Sets the maximum allowed number of connections in  a  connection
797              tracking  zone.  A specific zone may be set to limit, and multi‐
798              ple zones may be specified with a comma-separated  list.   If  a
799              per-zone  limit  for  a  particular zone is not specified in the
800              datapath, it defaults to the default per-zone limit.  A  default
801              zone  may  be specified with the default=default_limit argument.
802              Initially, the default per-zone limit is unlimited.   An  unlim‐
803              ited  number of entries may be set with 0 limit.  Only supported
804              for Linux kernel datapath.
805
806       dpctl/ct-del-limits [dp] zone=zone[,zone]...
807              Deletes the connection tracking limit for zone.  Multiple  zones
808              may  be  specified  with a comma-separated list.  Only supported
809              for Linux kernel datapath.
810
811       dpctl/ct-get-limits [dp] [zone=zone[,zone]...]
812              Retrieves the maximum allowed number of connections and  current
813              counts  per-zone.   If zone is given, only the specified zone(s)
814              are printed.  If no zones are specified, all the zone limits and
815              counts  are  provided.   The command always displays the default
816              zone limit.  Only supported for Linux kernel datapath.
817
818   DPIF-NETDEV COMMANDS
819       These commands are used to expose internal information (mostly  statis‐
820       tics)  about the "dpif-netdev" userspace datapath. If there is only one
821       datapath (as is often the case, unless dpctl/ commands are  used),  the
822       dp  argument  can  be omitted. By default the commands present data for
823       all pmd threads in the datapath. By specifying the "-pmd  Core"  option
824       one can filter the output for a single pmd in the datapath.
825
826       dpif-netdev/pmd-stats-show [-pmd core] [dp]
827              Shows  performance  statistics for one or all pmd threads of the
828              datapath dp. The special thread "main" sums up the statistics of
829              every non pmd thread.
830
831              The sum of "emc hits", "smc hits", "megaflow hits" and "miss" is
832              the number of packet lookups performed by the  datapath.  Beware
833              that a recirculated packet experiences one additional lookup per
834              recirculation, so there may be more lookups than forwarded pack‐
835              ets in the datapath.
836
837              Cycles  are  counted  using  the TSC or similar facilities (when
838              available on the platform). The duration of one cycle depends on
839              the processing platform.
840
841              "idle  cycles" refers to cycles spent in PMD iterations not for‐
842              warding any any packets. "processing cycles"  refers  to  cycles
843              spent  in PMD iterations forwarding at least one packet, includ‐
844              ing the cost for polling, processing and transmitting said pack‐
845              ets.
846
847              To reset these counters use dpif-netdev/pmd-stats-clear.
848
849       dpif-netdev/pmd-stats-clear [dp]
850              Resets  to  zero the per pmd thread performance numbers shown by
851              the  dpif-netdev/pmd-stats-show  and   dpif-netdev/pmd-perf-show
852              commands.  It will NOT reset datapath or bridge statistics, only
853              the values shown by the above commands.
854
855       dpif-netdev/pmd-perf-show [-nh] [-it iter_len] [-ms ms_len] [-pmd core]
856       [dp]
857              Shows  detailed  performance metrics for one or all pmds threads
858              of the user space datapath.
859
860              The collection of detailed statistics can be controlled by a new
861              configuration   parameter   "other_config:pmd-perf-metrics".  By
862              default it is disabled. The run-time overhead, when enabled,  is
863              in the order of 1%.
864
865
866              —      used cycles
867              —      forwared packets
868              —      number of rx batches
869              —      packets/rx batch
870              —      max. vhostuser queue fill level
871              —      number of upcalls
872              —      cycles spent in upcalls
873
874              This raw recorded data is used threefold:
875
876
877              1.     In histograms for each of the following metrics:
878                     —      cycles/iteration (logarithmic)
879                     —      packets/iteration (logarithmic)
880                     —      cycles/packet
881                     —      packets/batch
882                     —      max. vhostuser qlen (logarithmic)
883                     —      upcalls
884                     —      cycles/upcall  (logarithmic)  The  histograms bins
885                            are divided linear or logarithmic.
886              2.     A cyclic history of the above metrics for 1024 iterations
887              3.     A cyclic history of the  cummulative/average  values  per
888                     millisecond wall clock for the last 1024 milliseconds:
889                     —      number of iterations
890                     —      avg. cycles/iteration
891                     —      packets (Kpps)
892                     —      avg. packets/batch
893                     —      avg. max vhost qlen
894                     —      upcalls
895                     —      avg. cycles/upcall
896
897              The command options are:
898
899              -nh    Suppress the histograms
900
901              -it iter_len
902                     Display the last iter_len iteration stats
903
904              -ms ms_len
905                     Display the last ms_len millisecond stats
906
907              The output always contains the following global PMD statistics:
908
909                     Time: 15:24:55.270 .br Measurement duration: 1.008 s
910
911                     pmd thread numa_id 0 core_id 1:
912
913                       Cycles:            2419034712  (2.40 GHz)
914                       Iterations:            572817  (1.76 us/it)
915                       - idle:                486808  (15.9 % cycles)
916                       - busy:                 86009  (84.1 % cycles)
917                       Rx   packets:             2399607    (2381   Kpps,  848
918                     cycles/pkt)
919                       Datapath passes:      3599415  (1.50 passes/pkt)
920                       - EMC hits:            336472  ( 9.3 %)
921                       - SMC hits:                 0  ( 0.0 %)
922                       - Megaflow hits:      3262943   (90.7  %,  1.00  subtbl
923                     lookups/hit)
924                       - Upcalls:                  0  ( 0.0 %, 0.0 us/upcall)
925                       - Lost upcalls:             0  ( 0.0 %)
926                       Tx packets:           2399607  (2381 Kpps)
927                       Tx batches:            171400  (14.00 pkts/batch)
928
929              Here  "Rx  packets" actually reflects the number of packets for‐
930              warded by the datapath. "Datapath passes" matches the number  of
931              packet  lookups  as  reported  by the dpif-netdev/pmd-stats-show
932              command.
933
934              To reset the counters and start a new measurement use  dpif-net‐
935              dev/pmd-stats-clear.
936
937       dpif-netdev/pmd-perf-log-set  on|off  [-b  before]  [-a after] [-e|-ne]
938       [-us usec] [-q qlen]
939              The userspace "netdev" datapath is able  to  supervise  the  PMD
940              performance  metrics  and detect iterations with suspicious sta‐
941              tistics according to the following criteria:
942
943              —      The  iteration  lasts  longer  than   usec   microseconds
944                     (default  250).  This can be used to capture events where
945                     a PMD is blocked or interrupted for such a period of time
946                     that there is a risk for dropped packets on any of its Rx
947                     queues.
948
949              —      The max vhost qlen  exceeds  a  threshold  qlen  (default
950                     128). This can be used to infer virtio queue overruns and
951                     dropped packets inside a VM, which are not visible in OVS
952                     otherwise.
953
954              Such  suspicious  iterations  can  be logged together with their
955              iteration statistics in the ovs-vswitchd.log to be able to  cor‐
956              relate them to packet drop or other events outside OVS.
957
958              The above command enables (on) or disables (off) supervision and
959              logging at run-time and can be used to adjust the above  thresh‐
960              olds for detecting suspicious iterations. By default supervision
961              and logging is disabled.
962
963              The command options are:
964
965              -b before
966                     The number of iterations before the suspicious  iteration
967                     to be logged (default 5).
968
969              -a after
970                     The  number  of iterations after the suspicious iteration
971                     to be logged (default 5).
972
973              -e     Extend logging interval if another  suspicious  iteration
974                     is detected before logging occurs.
975
976              -ne    Do  not  extend  logging  interval  if another suspicious
977                     iteration is detected before logging occurs (default).
978
979              -q qlen
980                     Suspicious vhost queue  fill  level  threshold.  Increase
981                     this to 512 if the Qemu supports 1024 virtio queue length
982                     (default 128).
983
984              -us usec
985                     Change the duration threshold for a suspicious  iteration
986                     (default 250 us).
987
988       Note:  Logging  of suspicious iterations itself consumes a considerable
989       amount of processing cycles of a PMD which may be visible in the itera‐
990       tion  history.   In  the worst case this can lead OVS to detect another
991       suspicious iteration caused by logging.
992
993       If more than 100 iterations around a  suspicious  iteration  have  been
994       logged  once, OVS falls back to the safe default values (-b 5 -a 5 -ne)
995       to avoid that logging itself continuously  causes  logging  of  further
996       suspicious iterations.
997
998       dpif-netdev/pmd-rxq-show [-pmd core] [dp]
999              For  one  or all pmd threads of the datapath dp show the list of
1000              queue-ids with port names, which this thread polls.
1001
1002       dpif-netdev/pmd-rxq-rebalance [dp]
1003              Reassigns rxqs to pmds in the datapath dp based on their current
1004              usage.
1005
1006   NETDEV-DPDK COMMANDS
1007       These commands manage DPDK related ports (type=dpdk*).
1008
1009       netdev-dpdk/set-admin-state [interface] up | down
1010              Change  the  admin  state  for DPDK interface to up or down.  If
1011              interface is not specified, then it applies to all DPDK ports.
1012
1013       netdev-dpdk/detach pci-address
1014              Detaches device with corresponding pci-address from DPDK.   This
1015              command can be used to detach device if it wasn't detached auto‐
1016              matically after port deletion. Refer to  the  documentation  for
1017              details and instructions.
1018
1019       netdev-dpdk/get-mempool-info [interface]
1020              Prints  the  debug  information  about  memory pool used by DPDK
1021              interface.  If called without arguments, information of all  the
1022              available  mempools will be printed. For additional mempool sta‐
1023              tistics enable  CONFIG_RTE_LIBRTE_MEMPOOL_DEBUG  while  building
1024              DPDK.
1025
1026   DATAPATH DEBUGGING COMMANDS
1027       These  commands  query  and  modify datapaths.  They are are similar to
1028       ovs-dpctl(8) commands.  dpif/show  has  the  additional  functionality,
1029       beyond  dpctl/show  of  printing OpenFlow port numbers.  The other com‐
1030       mands are redundant and will be removed in a future release.
1031
1032       dpif/dump-dps
1033              Prints the name of each configured datapath on a separate line.
1034
1035       dpif/show
1036              Prints a summary of configured datapaths,  including  statistics
1037              and  a  list  of connected ports.  The port information includes
1038              the OpenFlow port number, datapath port number,  and  the  type.
1039              (The local port is identified as OpenFlow port 65534.)
1040
1041       dpif/dump-flows [-m] dp
1042              Prints to the console all flow entries in datapath dp's flow ta‐
1043              ble. Without -m, output omits match fields that a flow wildcards
1044              entirely; with -m output includes all wildcarded fields.
1045
1046              This  command  is  primarily  useful for debugging Open vSwitch.
1047              The flow table entries that it displays are  not  OpenFlow  flow
1048              entries.   Instead,  they are different and considerably simpler
1049              flows maintained by the datapath module.  If you wish to see the
1050              OpenFlow flow entries, use ovs-ofctl dump-flows.
1051
1052       dpif/del-flows dp
1053              Deletes  all  flow  entries  from  datapath  dp's flow table and
1054              underlying datapath implementation (e.g., kernel  datapath  mod‐
1055              ule).
1056
1057              This command is primarily useful for debugging Open vSwitch.  As
1058              discussed in dpif/dump-flows, these  entries  are  not  OpenFlow
1059              flow entries.
1060
1061   OFPROTO COMMANDS
1062       These  commands  manage the core OpenFlow switch implementation (called
1063       ofproto).
1064
1065       ofproto/list
1066              Lists the names of the running ofproto instances.  These are the
1067              names that may be used on ofproto/trace.
1068
1069       ofproto/trace [options] [dpname] odp_flow [packet]
1070       ofproto/trace [options] bridge br_flow [packet]]
1071       ofproto/trace-packet-out [options] [dpname] odp_flow [packet] actions
1072       ofproto/trace-packet-out [options bridge br_flow  [packet] actions
1073              Traces  the  path  of  an  imaginary  packet  through switch and
1074              reports the path that it took.  The  initial  treatment  of  the
1075              packet varies based on the command:
1076
1077              ·      ofproto/trace  looks  the  packet up in the OpenFlow flow
1078                     table, as if the packet had arrived on an OpenFlow port.
1079
1080              ·      ofproto/trace-packet-out applies the  specified  OpenFlow
1081                     actions,  as  if  the  packet, flow, and actions had been
1082                     specified in an OpenFlow ``packet-out'' request.
1083
1084              The packet's headers (e.g. source and destination) and  metadata
1085              (e.g. input port), together called its ``flow,'' are usually all
1086              that matter for the purpose of tracing a packet.  You can  spec‐
1087              ify the flow in the following ways:
1088
1089              dpname odp_flow
1090                     odp_flow  is a flow in the form printed by ovs-dpctl(8)'s
1091                     dump-flows command.  If all of your bridges have the same
1092                     type, which is the common case, then you can omit dpname,
1093                     but if you have bridges of  different  types  (say,  both
1094                     ovs-netdev  and  ovs-system),  then you need to specify a
1095                     dpname to disambiguate.
1096
1097              bridge br_flow
1098                     br_flow is a flow in the form similar to that accepted by
1099                     ovs-ofctl(8)'s  add-flow  command.  (This is not an Open‐
1100                     Flow flow: besides other differences, it  never  contains
1101                     wildcards.)   bridge  names  of  the bridge through which
1102                     br_flow should be traced.
1103
1104              These commands support the following options:
1105
1106              --generate
1107                     Generate a packet from  the  flow  (see  below  for  more
1108                     information).
1109
1110              --l7 payload
1111              --l7-len length
1112                     Accepted  only with --generate (see below for more infor‐
1113                     mation).
1114
1115              --consistent
1116                     Accepted by  ofproto-trace-packet-out  only.   With  this
1117                     option, the command rejects actions that are inconsistent
1118                     with the specified packet.  (An example of  an  inconsis‐
1119                     tency  is  attempting to strip the VLAN tag from a packet
1120                     that does not have a VLAN  tag.)   Open  vSwitch  ignores
1121                     most  forms  of inconsistency in OpenFlow 1.0 and rejects
1122                     inconsistencies  in  later  versions  of  OpenFlow.   The
1123                     option is necessary because the command does not ordinar‐
1124                     ily imply a particular OpenFlow version.   One  exception
1125                     is  that, when actions includes an action that only Open‐
1126                     Flow 1.1 and later supports (such as  push_vlan),  --con‐
1127                     sistent is automatically enabled.
1128
1129              --ct-next flags
1130                     When   the   traced   flow  triggers  conntrack  actions,
1131                     ofproto/trace will automatically trace the forked  packet
1132                     processing  pipeline  with user specified ct_state.  This
1133                     option sets the ct_state flags that the conntrack  module
1134                     will  report.  The  flags must be a comma- or space-sepa‐
1135                     rated list of the following connection tracking flags:
1136
1137                     ·      trk: Include to indicate connection  tracking  has
1138                            taken place.
1139
1140                     ·      new: Include to indicate a new flow.
1141
1142                     ·      est: Include to indicate an established flow.
1143
1144                     ·      rel: Include to indicate a related flow.
1145
1146                     ·      rpl: Include to indicate a reply flow.
1147
1148                     ·      inv:  Include  to indicate a connection entry in a
1149                            bad state.
1150
1151                     ·      dnat: Include to indicate a packet whose  destina‐
1152                            tion IP address has been changed.
1153
1154                     ·      snat: Include to indicate a packet whose source IP
1155                            address has been changed.
1156
1157                     When --ct-next is unspecified, or when  there  are  fewer
1158                     --ct-next  options  than ct actions, the flags default to
1159                     trk,new.
1160
1161              Most commonly, one specifies only a flow, using one of the forms
1162              above,  but sometimes one might need to specify an actual packet
1163              instead of just a flow:
1164
1165              Side effects.
1166                     Some actions have side effects.  For example, the  normal
1167                     action  can  update the MAC learning table, and the learn
1168                     action can change OpenFlow tables.   The  trace  commands
1169                     only perform side effects when a packet is specified.  If
1170                     you want side effects to take place, then you must supply
1171                     a packet.
1172
1173                     (Side  effects  when  tracing do not have external conse‐
1174                     quences.  Even if a packet is specified, a trace will not
1175                     output  a packet or generate sFlow, NetFlow or controller
1176                     events.)
1177
1178              Incomplete information.
1179                     Most of the time, Open vSwitch can figure out  everything
1180                     about  the  path  of a packet using just the flow, but in
1181                     some special circumstances it needs to look at  parts  of
1182                     the  packet that are not included in the flow.  When this
1183                     is the case, and you do not supply a packet, then a trace
1184                     command will tell you it needs a packet.
1185
1186              If  you  wish  to include a packet as part of a trace operation,
1187              there are two ways to do it:
1188
1189              --generate
1190                     This option, added to one of the ways to specify  a  flow
1191                     already described, causes Open vSwitch to internally gen‐
1192                     erate a packet with the flow described and  then  to  use
1193                     that  packet.   If  your goal is to execute side effects,
1194                     then --generate is the easiest way to do it, but --gener‐
1195                     ate  is not a good way to fill in incomplete information,
1196                     because it generates  packets  based  on  only  the  flow
1197                     information,  which  means that the packets really do not
1198                     have any more information than the flow.
1199
1200                     By default, for protocols that allow  arbitrary  L7  pay‐
1201                     loads, the generated packet has 64 bytes of payload.  Use
1202                     --l7-len to change the payload length, or --l7 to specify
1203                     the exact contents of the payload.
1204
1205              packet This  form  supplies  an explicit packet as a sequence of
1206                     hex digits.  An Ethernet frame is at least 14 bytes long,
1207                     so  there  must be at least 28 hex digits.  Obviously, it
1208                     is inconvenient to type in the hex digits by hand, so the
1209                     ovs-pcap(1) and ovs-tcpundump(1) utilities provide easier
1210                     ways.
1211
1212                     With this form, packet  headers  are  extracted  directly
1213                     from  packet,  so  the odp_flow or br_flow should specify
1214                     only metadata. The metadata can be:
1215
1216                     skb_priority
1217                            Packet QoS priority.
1218
1219                     pkt_mark
1220                            Mark of the packet.
1221
1222                     ct_state
1223                            Connection state of the packet.
1224
1225                     ct_zone
1226                            Connection tracking zone for packet.
1227
1228                     ct_mark
1229                            Connection mark of the packet.
1230
1231                     ct_label
1232                            Connection label of the packet.
1233
1234                     tun_id The tunnel ID on which the packet arrived.
1235
1236                     in_port
1237                            The port on which the packet arrived.
1238
1239              The in_port value is kernel datapath port number for  the  first
1240              format  and OpenFlow port number for the second format. The num‐
1241              bering of these two types of port usually differs and  there  is
1242              no relationship.
1243
1244       Usage examples:
1245
1246           Trace an unicast ICMP echo request on ingress port 1 to destination
1247           MAC 00:00:5E:00:53:01
1248               ofproto/trace br in_port=1,icmp,icmp_type=8,\
1249               dl_dst=00:00:5E:00:53:01
1250
1251           Trace an unicast ICMP echo reply on ingress port 1  to  destination
1252           MAC 00:00:5E:00:53:01
1253               ofproto/trace br in_port=1,icmp,icmp_type=0,\
1254               dl_dst=00:00:5E:00:53:01
1255
1256           Trace an ARP request on ingress port 1
1257               ofproto/trace br in_port=1,arp,arp_op=1
1258
1259           Trace an ARP reply on ingress port 1
1260               ofproto/trace br in_port=1,arp,arp_op=2
1261
1262   VLOG COMMANDS
1263       These commands manage ovs-vswitchd's logging settings.
1264
1265       vlog/set [spec]
1266              Sets  logging  levels.  Without any spec, sets the log level for
1267              every module and destination to dbg.  Otherwise, spec is a  list
1268              of words separated by spaces or commas or colons, up to one from
1269              each category below:
1270
1271              ·      A valid module name, as displayed by the  vlog/list  com‐
1272                     mand on ovs-appctl(8), limits the log level change to the
1273                     specified module.
1274
1275              ·      syslog, console, or file, to limit the log  level  change
1276                     to  only to the system log, to the console, or to a file,
1277                     respectively.
1278
1279                     On Windows platform, syslog is accepted as a word and  is
1280                     only  useful  along  with the --syslog-target option (the
1281                     word has no effect otherwise).
1282
1283              ·      off, emer, err, warn, info, or dbg, to  control  the  log
1284                     level.   Messages of the given severity or higher will be
1285                     logged, and messages of lower severity will  be  filtered
1286                     out.   off  filters  out all messages.  See ovs-appctl(8)
1287                     for a definition of each log level.
1288
1289              Case is not significant within spec.
1290
1291              Regardless of the log levels set for file,  logging  to  a  file
1292              will  not  take  place  unless ovs-vswitchd was invoked with the
1293              --log-file option.
1294
1295              For compatibility with older versions of OVS, any is accepted as
1296              a word but has no effect.
1297
1298       vlog/set PATTERN:destination:pattern
1299              Sets  the  log  pattern  for  destination  to pattern.  Refer to
1300              ovs-appctl(8) for a description of the valid syntax for pattern.
1301
1302       vlog/list
1303              Lists the supported logging modules and their current levels.
1304
1305       vlog/list-pattern
1306              Lists logging patterns used for each destination.
1307
1308       vlog/close
1309              Causes ovs-vswitchd to close its log file, if it is open.   (Use
1310              vlog/reopen to reopen it later.)
1311
1312       vlog/reopen
1313              Causes  ovs-vswitchd  to  close its log file, if it is open, and
1314              then reopen it.  (This is useful after rotating  log  files,  to
1315              cause a new log file to be used.)
1316
1317              This  has  no  effect  unless  ovs-vswitchd was invoked with the
1318              --log-file option.
1319
1320       vlog/disable-rate-limit [module]...
1321       vlog/enable-rate-limit [module]...
1322              By default, ovs-vswitchd limits the rate at which  certain  mes‐
1323              sages  can  be  logged.   When  a message would appear more fre‐
1324              quently than the limit,  it  is  suppressed.   This  saves  disk
1325              space,  makes  logs easier to read, and speeds up execution, but
1326              occasionally troubleshooting requires more  detail.   Therefore,
1327              vlog/disable-rate-limit allows rate limits to be disabled at the
1328              level of an individual log module.  Specify one or  more  module
1329              names, as displayed by the vlog/list command.  Specifying either
1330              no module names at all or the keyword any disables  rate  limits
1331              for every log module.
1332
1333              The  vlog/enable-rate-limit command, whose syntax is the same as
1334              vlog/disable-rate-limit, can be used to re-enable a  rate  limit
1335              that was previously disabled.
1336
1337   MEMORY COMMANDS
1338       These commands report memory usage.
1339
1340       memory/show
1341              Displays  some  basic  statistics  about  ovs-vswitchd's  memory
1342              usage.  ovs-vswitchd  also  logs  this  information  soon  after
1343              startup and periodically as its memory consumption grows.
1344
1345   COVERAGE COMMANDS
1346       These commands manage ovs-vswitchd's ``coverage counters,'' which count
1347       the number of times particular events occur during a daemon's  runtime.
1348       In addition to these commands, ovs-vswitchd automatically logs coverage
1349       counter values, at INFO level, when it detects that the  daemon's  main
1350       loop takes unusually long to run.
1351
1352       Coverage counters are useful mainly for performance analysis and debug‐
1353       ging.
1354
1355       coverage/show
1356              Displays the averaged per-second rates for the last few seconds,
1357              the  last  minute and the last hour, and the total counts of all
1358              of the coverage counters.
1359
1360   OPENVSWITCH TUNNELING COMMANDS
1361       These commands query and modify OVS tunnel components.
1362
1363       ovs/route/add ipv4_address/plen output_bridge [GW]
1364              Adds ipv4_address/plen route to  vswitchd  routing  table.  out‐
1365              put_bridge  needs to be OVS bridge name.  This command is useful
1366              if OVS cached routes does not look right.
1367
1368       ovs/route/show
1369              Print all routes in OVS  routing  table,  This  includes  routes
1370              cached from system routing table and user configured routes.
1371
1372       ovs/route/del ipv4_address/plen
1373              Delete ipv4_address/plen route from OVS routing table.
1374
1375       tnl/neigh/show
1376
1377       tnl/arp/show
1378              OVS  builds  ARP  cache  by  snooping are messages. This command
1379              shows ARP cache table.
1380
1381       tnl/neigh/set bridge ip mac
1382
1383       tnl/arp/set bridge ip mac
1384              Adds or modifies an ARP cache entry in  bridge,  mapping  ip  to
1385              mac.
1386
1387       tnl/neigh/flush
1388
1389       tnl/arp/flush
1390              Flush ARP table.
1391
1392       tnl/egress_port_range [num1] [num2]
1393              Set  range  for  UDP source port used for UDP based Tunnels. For
1394              example VxLAN. If case of zero  arguments  this  command  prints
1395              current range in use.
1396

OPENFLOW IMPLEMENTATION

1398       This section documents aspects of OpenFlow for which the OpenFlow spec‐
1399       ification requires documentation.
1400
1401   Packet buffering.
1402       The OpenFlow specification, version 1.2, says:
1403
1404              Switches  that  implement  buffering  are  expected  to  expose,
1405              through  documentation,  both the amount of available buffering,
1406              and the length of time before buffers may be reused.
1407
1408       Open vSwitch does not maintains any packet buffers.
1409
1410   Bundle lifetime
1411       The OpenFlow specification, version 1.4, says:
1412
1413              If the  switch  does  not  receive  any  OFPT_BUNDLE_CONTROL  or
1414              OFPT_BUNDLE_ADD_MESSAGE  message  for  an opened bundle_id for a
1415              switch  defined  time  greater  than  1s,   it   may   send   an
1416              ofp_error_msg  with  OFPET_BUNDLE_FAILED type and OFPBFC_TIMEOUT
1417              code.  If the switch does not receive any new message in a  bun‐
1418              dle  apart  from  echo  request and replies for a switch defined
1419              time  greater  than  1s,  it  may  send  an  ofp_error_msg  with
1420              OFPET_BUNDLE_FAILED type and OFPBFC_TIMEOUT code.
1421
1422       Open  vSwitch  implements  default  idle bundle lifetime of 10 seconds.
1423       (This  is  configurable  via  other-config:bundle-idle-timeout  in  the
1424       Open_vSwitch table. See ovs-vswitchd.conf.db(5) for details.)
1425

LIMITS

1427       We  believe these limits to be accurate as of this writing.  These lim‐
1428       its assume the use of the Linux kernel datapath.
1429
1430       ·      ovs-vswitchd started through  ovs-ctl(8)  provides  a  limit  of
1431              65535 file descriptors.  The limits on the number of bridges and
1432              ports is decided by the availability of file descriptors.   With
1433              the  Linux kernel datapath, creation of a single bridge consumes
1434              three file descriptors and adding a  port  consumes  "n-handler-
1435              threads"  file  descriptors  per  bridge port.  Performance will
1436              degrade beyond 1,024 ports per bridge due to  fixed  hash  table
1437              sizing.  Other platforms may have different limitations.
1438
1439       ·      2,048  MAC  learning  entries  per bridge, by default.  (This is
1440              configurable via other-config:mac-table-size in the  Bridge  ta‐
1441              ble.  See ovs-vswitchd.conf.db(5) for details.)
1442
1443       ·      Kernel flows are limited only by memory available to the kernel.
1444              Performance will  degrade  beyond  1,048,576  kernel  flows  per
1445              bridge  with  a 32-bit kernel, beyond 262,144 with a 64-bit ker‐
1446              nel.  (ovs-vswitchd should never install anywhere near that many
1447              flows.)
1448
1449       ·      OpenFlow  flows  are  limited only by available memory.  Perfor‐
1450              mance is linear in the number of unique wildcard patterns.  That
1451              is, an OpenFlow table that contains many flows that all match on
1452              the same fields in the same way has a constant-time lookup,  but
1453              a  table that contains many flows that match on different fields
1454              requires lookup time linear in the number of flows.
1455
1456       ·      255 ports per bridge participating in 802.1D Spanning Tree  Pro‐
1457              tocol.
1458
1459       ·      32 mirrors per bridge.
1460
1461       ·      15  bytes for the name of a port.  (This is a Linux kernel limi‐
1462              tation.)
1463

SEE ALSO

1465       ovs-appctl(8), ovsdb-server(1).
1466
1467
1468
1469Open vSwitch                        2.10.1                     ovs-vswitchd(8)
Impressum