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.  Downside of using this
306                     options  is  that libc adds fixed prefix to every message
307                     before it is actually sent  to  the  syslog  daemon  over
308                     /dev/log UNIX domain socket.
309
310              ·      unix:file, use UNIX domain socket directly.  It is possi‐
311                     ble to specify arbitrary message format with this option.
312                     However,  rsyslogd  8.9 and older versions use hard coded
313                     parser function anyway that  limits  UNIX  domain  socket
314                     use.   If  you  want to use arbitrary message format with
315                     older rsyslogd versions, then use UDP socket to localhost
316                     IP address instead.
317
318              ·      udp:ip:port, use UDP socket.  With this method it is pos‐
319                     sible to use arbitrary message  format  also  with  older
320                     rsyslogd.   When  sending syslog messages over UDP socket
321                     extra precaution needs to  be  taken  into  account,  for
322                     example,  syslog  daemon needs to be configured to listen
323                     on the specified  UDP  port,  accidental  iptables  rules
324                     could  be interfering with local syslog traffic and there
325                     are some security considerations that apply to UDP  sock‐
326                     ets, but do not apply to UNIX domain sockets.
327
328              ·      null, discards all messages logged to syslog.
329
330              The  default  is  taken  from  the OVS_SYSLOG_METHOD environment
331              variable; if it is unset, the default is libc.
332
333   Other Options
334       --unixctl=socket
335              Sets the name of the control socket on which  ovs-vswitchd  lis‐
336              tens  for  runtime  management  commands (see RUNTIME MANAGEMENT
337              COMMANDS, below).  If socket does not begin with /, it is inter‐
338              preted as relative to /var/run/openvswitch.  If --unixctl is not
339              used   at   all,   the   default   socket   is    /var/run/open‐
340              vswitch/ovs-vswitchd.pid.ctl,   where   pid   is  ovs-vswitchd's
341              process ID.
342
343              On Windows a local named pipe is used to listen for runtime man‐
344              agement  commands.   A  file  is created in the absolute path as
345              pointed by socket or if --unixctl is not used at all, a file  is
346              created  as ovs-vswitchd.ctl in the configured OVS_RUNDIR direc‐
347              tory.  The file exists just to mimic  the  behavior  of  a  Unix
348              domain socket.
349
350              Specifying none for socket disables the control socket feature.
351
352       -h
353       --help Prints a brief help message to the console.
354
355       -V
356       --version
357              Prints version information to the console.
358

RUNTIME MANAGEMENT COMMANDS

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

OPENFLOW IMPLEMENTATION

1449       This section documents aspects of OpenFlow for which the OpenFlow spec‐
1450       ification requires documentation.
1451
1452   Packet buffering.
1453       The OpenFlow specification, version 1.2, says:
1454
1455              Switches  that  implement  buffering  are  expected  to  expose,
1456              through documentation, both the amount of  available  buffering,
1457              and the length of time before buffers may be reused.
1458
1459       Open vSwitch does not maintains any packet buffers.
1460
1461   Bundle lifetime
1462       The OpenFlow specification, version 1.4, says:
1463
1464              If  the  switch  does  not  receive  any  OFPT_BUNDLE_CONTROL or
1465              OFPT_BUNDLE_ADD_MESSAGE message for an opened  bundle_id  for  a
1466              switch   defined   time   greater   than  1s,  it  may  send  an
1467              ofp_error_msg with OFPET_BUNDLE_FAILED type  and  OFPBFC_TIMEOUT
1468              code.   If the switch does not receive any new message in a bun‐
1469              dle apart from echo request and replies  for  a  switch  defined
1470              time  greater  than  1s,  it  may  send  an  ofp_error_msg  with
1471              OFPET_BUNDLE_FAILED type and OFPBFC_TIMEOUT code.
1472
1473       Open vSwitch implements default idle bundle  lifetime  of  10  seconds.
1474       (This  is  configurable  via  other-config:bundle-idle-timeout  in  the
1475       Open_vSwitch table. See ovs-vswitchd.conf.db(5) for details.)
1476

LIMITS

1478       We believe these limits to be accurate as of this writing.  These  lim‐
1479       its assume the use of the Linux kernel datapath.
1480
1481       ·      ovs-vswitchd  started  through  ovs-ctl(8)  provides  a limit of
1482              65535 file descriptors.  The limits on the number of bridges and
1483              ports  is decided by the availability of file descriptors.  With
1484              the Linux kernel datapath, creation of a single bridge  consumes
1485              three  file  descriptors  and  each port consumes one additional
1486              file descriptor.  Other platforms  may  have  different  limita‐
1487              tions.
1488
1489       ·      8,192  MAC  learning  entries  per bridge, by default.  (This is
1490              configurable via other-config:mac-table-size in the  Bridge  ta‐
1491              ble.  See ovs-vswitchd.conf.db(5) for details.)
1492
1493       ·      Kernel flows are limited only by memory available to the kernel.
1494              Performance will  degrade  beyond  1,048,576  kernel  flows  per
1495              bridge  with  a 32-bit kernel, beyond 262,144 with a 64-bit ker‐
1496              nel.  (ovs-vswitchd should never install anywhere near that many
1497              flows.)
1498
1499       ·      OpenFlow  flows  are  limited only by available memory.  Perfor‐
1500              mance is linear in the number of unique wildcard patterns.  That
1501              is, an OpenFlow table that contains many flows that all match on
1502              the same fields in the same way has a constant-time lookup,  but
1503              a  table that contains many flows that match on different fields
1504              requires lookup time linear in the number of flows.
1505
1506       ·      255 ports per bridge participating in 802.1D Spanning Tree  Pro‐
1507              tocol.
1508
1509       ·      32 mirrors per bridge.
1510
1511       ·      15  bytes  for  the name of a port, for ports implemented in the
1512              Linux kernel.  Ports implemented in  userspace,  such  as  patch
1513              ports,  do  not  have  an arbitrary length limitation.  OpenFlow
1514              also limit port names to 15 bytes.
1515

SEE ALSO

1517       ovs-appctl(8), ovsdb-server(1).
1518
1519
1520
1521Open vSwitch                        2.12.0                     ovs-vswitchd(8)
Impressum