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

NAME

6       ovs-dpctl - administer Open vSwitch datapaths
7

SYNOPSIS

9       ovs-dpctl [options] command [switch] [args...]
10

DESCRIPTION

12       The ovs-dpctl program can create, modify, and delete Open vSwitch data‐
13       paths.  A single machine may host any number of datapaths.
14
15       This program works only with datapaths that are implemented outside  of
16       ovs-vswitchd  itself,  such as the Linux and Windows kernel-based data‐
17       paths.  To manage datapaths that are integrated into ovs-vswitchd, such
18       as  the  userspace  (netdev)  datapath, use ovs-appctl(8) to invoke the
19       dpctl/* commands, which are documented in ovs-vswitchd(8).
20
21       A newly created datapath is associated with only one network device,  a
22       virtual  network device sometimes called the datapath's ``local port''.
23       A newly created datapath is not, however, associated with  any  of  the
24       host's  other  network  devices.  To intercept and process traffic on a
25       given network device, use the add-if command  to  explicitly  add  that
26       network device to the datapath.
27
28       If ovs-vswitchd(8) is in use, use ovs-vsctl(8) instead of ovs-dpctl.
29
30       Most  ovs-dpctl commands that work with datapaths take an argument that
31       specifies the name of the  datapath.   Datapath  names  take  the  form
32       [type@]name, where name is the network device associated with the data‐
33       path's local port.   If  type  is  given,  it  specifies  the  datapath
34       provider of name, otherwise the default provider system is assumed.
35
36       The following commands manage datapaths.  Do not use commands to add or
37       remove or modify datapaths if  ovs-vswitchd  is  running  because  this
38       interferes with ovs-vswitchd's own datapath management.
39
40       add-dp dp [netdev[,option]...]
41              Creates datapath dp, with a local port also named dp.  This will
42              fail if a network device dp already exists.
43
44              If netdevs are specified, ovs-dpctl adds them to the  new  data‐
45              path, just as if add-if was specified.
46
47       del-dp dp
48              Deletes  datapath  dp.   If  dp  is  associated with any network
49              devices, they are automatically removed.
50
51       add-if dp netdev[,option]...
52              Adds each netdev to the set of network devices datapath dp moni‐
53              tors,  where  dp is the name of an existing datapath, and netdev
54              is the name of one of the host's  network  devices,  e.g.  eth0.
55              Once a network device has been added to a datapath, the datapath
56              has complete ownership of the network device's traffic  and  the
57              network device appears silent to the rest of the system.
58
59              A  netdev  may be followed by a comma-separated list of options.
60              The following options are currently supported:
61
62              type=type
63                     Specifies the type of port to add.  The default  type  is
64                     system.
65
66              port_no=port
67                     Requests  a specific port number within the datapath.  If
68                     this option is not specified then one will  be  automati‐
69                     cally assigned.
70
71              key=value
72                     Adds an arbitrary key-value option to the port's configu‐
73                     ration.
74
75              ovs-vswitchd.conf.db(5) documents the available port  types  and
76              options.
77
78       set-if dp port[,option]...
79              Reconfigures  each  port  in  dp as specified.  An option of the
80              form key=value adds the specified key-value option to  the  port
81              or  overrides  an  existing  key's value.  An option of the form
82              key=, that is, without a value, deletes the key-value named key.
83              The  type  and  port number of a port cannot be changed, so type
84              and port_no are only allowed if they match the existing configu‐
85              ration.
86
87       del-if dp netdev...
88              Removes each netdev from the list of network devices datapath dp
89              monitors.
90
91       dump-dps
92              Prints the name of each configured datapath on a separate line.
93
94       [-s | --statistics] show [dp...]
95              Prints a summary of configured datapaths, including their  data‐
96              path  numbers  and  a  list of ports connected to each datapath.
97              (The local port is identified as port 0.)  If -s or --statistics
98              is specified, then packet and byte counters are also printed for
99              each port.
100
101              The datapath numbers consists of flow stats and mega  flow  mask
102              stats.
103
104              The  "lookups"  row  displays three stats related to flow lookup
105              triggered by processing incoming packets in the datapath.  "hit"
106              displays number of packets matches existing flows. "missed" dis‐
107              plays the number of packets not matching any existing  flow  and
108              require  user space processing.  "lost" displays number of pack‐
109              ets destined for user space  process  but  subsequently  dropped
110              before reaching userspace. The sum of "hit" and "miss" equals to
111              the total number of packets datapath processed.
112
113              The "flows" row displays the number of flows in datapath.
114
115              The "masks" row displays the mega flow mask stats. This  row  is
116              omitted  for datapath not implementing mega flow. "hit" displays
117              the total number of masks visited for matching incoming packets.
118              "total" displays number of masks in the datapath. "hit/pkt" dis‐
119              plays the average number of masks visited per packet; the  ratio
120              between "hit" and total number of packets processed by the data‐
121              path.
122
123              If one or more datapaths  are  specified,  information  on  only
124              those  datapaths  are  displayed.  Otherwise, ovs-dpctl displays
125              information about all configured datapaths.
126
127   DATAPATH FLOW TABLE DEBUGGING COMMANDS
128       The following commands are primarily useful for debugging Open vSwitch.
129       The  flow  table entries (both matches and actions) that they work with
130       are not OpenFlow flow entries.  Instead, they are different and consid‐
131       erably  simpler flows maintained by the Open vSwitch kernel module.  Do
132       not use  commands  to  add  or  remove  or  modify  datapath  flows  if
133       ovs-vswitchd  is  running because it interferes with ovs-vswitchd's own
134       datapath flow management.  Use  ovs-ofctl(8),  instead,  to  work  with
135       OpenFlow flow entries.
136
137       The  dp argument to each of these commands is optional when exactly one
138       datapath exists, in which case that datapath is the default.  When mul‐
139       tiple datapaths exist, then a datapath name is required.
140
141       [-m  |  --more]  [--names | --no-names] dump-flows [dp] [filter=filter]
142       [type=type]
143              Prints to the console all flow entries in datapath dp's flow ta‐
144              ble.   Without  -m  or  --more, output omits match fields that a
145              flow wildcards entirely; with -m or --more, output includes  all
146              wildcarded fields.
147
148              If  filter=filter  is  specified,  only  displays the flows that
149              match the filter. filter is a flow in the form similiar to  that
150              accepted  by  ovs-ofctl(8)'s  add-flow  command. (This is not an
151              OpenFlow flow: besides  other  differences,  it  never  contains
152              wildcards.)   The  filter  is  also  useful  to match wildcarded
153              fields   in   the   datapath   flow.   As   an   example,   fil‐
154              ter='tcp,tp_src=100'  will  match  the  datapath flow containing
155              'tcp(src=80/0xff00,dst=8080/0xff)'.
156
157              If type=type is specified, only displays flows of the  specified
158              types.     This    option    supported   only   for   ovs-appctl
159              dpctl/dump-flows.  type is a comma  separated  list,  which  can
160              contain any of the following:
161                 ovs - displays flows handled in the ovs dp
162                 tc - displays flows handled in the tc dp
163                 offloaded - displays flows offloaded to the HW
164                 non-offloaded - displays flows not offloaded to the HW
165                 all - displays all the types of flows
166
167              By  default  all  the  types  of flows are displayed.  ovs-dpctl
168              always acts as if the type was ovs.
169
170       add-flow [dp] flow actions
171
172       [--clear] [--may-create] [-s | --statistics] mod-flow [dp] flow actions
173              Adds or modifies a flow in dp's flow table that, when  a  packet
174              matching flow arrives, causes actions to be executed.
175
176              The  add-flow  command  succeeds  only  if flow does not already
177              exist in dp.  Contrariwise, mod-flow without  --may-create  only
178              modifies  the  actions for an existing flow.  With --may-create,
179              mod-flow will add a new flow or modify an existing one.
180
181              If -s or --statistics is specified,  then  mod-flow  prints  the
182              modified  flow's statistics.  A flow's statistics are the number
183              of packets and bytes that have  passed  through  the  flow,  the
184              elapsed  time  since the flow last processed a packet (if ever),
185              and (for TCP flows) the union of the TCP flags processed through
186              the flow.
187
188              With  --clear,  mod-flow  zeros  out the flow's statistics.  The
189              statistics printed if -s or --statistics is also  specified  are
190              those from just before clearing the statistics.
191
192              NOTE:  flow  and  actions  do  not  match  the  syntax used with
193              ovs-ofctl(8)'s add-flow command.
194
195              Usage Examples
196
197              Forward ARP between ports 1 and 2 on datapath myDP:
198
199                     ovs-dpctl add-flow myDP \
200                       "in_port(1),eth(),eth_type(0x0806),arp()" 2
201
202                     ovs-dpctl add-flow myDP \
203                       "in_port(2),eth(),eth_type(0x0806),arp()" 1
204
205              Forward all IPv4 traffic between two addresses on ports 1 and 2:
206
207                     ovs-dpctl add-flow myDP \
208                       "in_port(1),eth(),eth_type(0x800),\
209                        ipv4(src=172.31.110.4,dst=172.31.110.5)" 2
210
211                     ovs-dpctl add-flow myDP \
212                       "in_port(2),eth(),eth_type(0x800),\
213                        ipv4(src=172.31.110.5,dst=172.31.110.4)" 1
214
215       [-s | --statistics] del-flow [dp] flow
216              Deletes the flow from dp's flow table that matches flow.  If  -s
217              or  --statistics  is specified, then del-flow prints the deleted
218              flow's statistics.
219
220       [-m | --more] [--names | --no-names] get-flow [dp] ufid:ufid
221              Fetches the flow from dp's flow  table  with  unique  identifier
222              ufid.   ufid  must  be  specified  as a string of 32 hexadecimal
223              characters.
224
225       del-flows [dp]
226              Deletes all flow entries from datapath dp's flow table.
227
228   CONNECTION TRACKING TABLE COMMANDS
229       The following commands are useful for  debugging  and  configuring  the
230       connection tracking table in the datapath.
231
232       The  dp argument to each of these commands is optional when exactly one
233       datapath exists, in which case that datapath is the default.  When mul‐
234       tiple datapaths exist, then a datapath name is required.
235
236       N.B.(Linux  specific): the system datapaths (i.e. the Linux kernel mod‐
237       ule Open vSwitch datapaths) share a single  connection  tracking  table
238       (which is also used by other kernel subsystems, such as iptables, nfta‐
239       bles and the regular host stack).  Therefore, the following commands do
240       not apply specifically to one datapath.
241
242       ipf-set-enabled [dp] v4|v6
243       ipf-set-disabled [dp] v4|v6
244              Enables  or disables IP fragmentation handling for the userspace
245              connection tracker.  Either v4 or v6 must  be  specified.   Both
246              IPv4  and IPv6 fragment reassembly are enabled by default.  Only
247              supported for the userspace datapath.
248
249       ipf-set-min-frag [dp] v4|v6 minfrag
250              Sets the minimum fragment size (L3 header  and  data)  for  non-
251              final  fragments to minfrag.  Either v4 or v6 must be specified.
252              For enhanced DOS security, higher  minimum  fragment  sizes  can
253              usually be used.  The default IPv4 value is 1200 and the clamped
254              minimum is 400.  The default IPv6 value is 1280, with a  clamped
255              minimum  of  400, for testing flexibility.  The maximum fragment
256              size is not clamped, however, setting this value too high  might
257              result  in  valid  fragments  being dropped.  Only supported for
258              userspace datapath.
259
260       ipf-set-max-nfrags [dp] maxfrags
261              Sets the maximum number of fragments tracked  by  the  userspace
262              datapath  connection  tracker to maxfrags.  The default value is
263              1000 and the clamped maximum is 5000.  Note that packet  buffers
264              can  be  held  by  the  fragmentation module while fragments are
265              incomplete, but will timeout after 15 seconds.  Memory pool siz‐
266              ing  should  be  set  accordingly when fragmentation is enabled.
267              Only supported for userspace datapath.
268
269       [-m | --more] ipf-get-status [dp]
270              Gets the configuration settings and fragment counters associated
271              with  the  fragmentation handling of the userspace datapath con‐
272              nection tracker.  With -m or --more, also dumps the IP  fragment
273              lists.  Only supported for userspace datapath.
274
275       [-m | --more] [-s | --statistics] dump-conntrack [dp] [zone=zone]
276              Prints  to the console all the connection entries in the tracker
277              used by dp.  If zone=zone is specified, only shows  the  connec‐
278              tions  in  zone.   With  --more,  some  implementation  specific
279              details are included. With --statistics timeouts and  timestamps
280              are added to the output.
281
282       flush-conntrack [dp] [zone=zone] [ct-tuple]
283              Flushes  the  connection entries in the tracker used by dp based
284              on zone and connection tracking tuple ct-tuple.  If ct-tuple  is
285              not  provided, flushes all the connection entries.  If zone=zone
286              is specified, only flushes the connections in zone.
287
288              If ct-tuple is provided, flushes the connection entry  specified
289              by  ct-tuple  in  zone. The zone defaults to 0 if it is not pro‐
290              vided.  The userspace connection tracker requires flushing  with
291              the original pre-NATed tuple and a warning log will be otherwise
292              generated.  An example of an IPv4 ICMP ct-tuple:
293
294              "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"
295
296              An example of an IPv6 TCP ct-tuple:
297
298              "ct_ipv6_src=fc00::1,ct_ipv6_dst=fc00::2,ct_nw_proto=6,ct_tp_src=1,ct_tp_dst=2"
299
300       [-m | --more] ct-stats-show [dp] [zone=zone]
301              Displays the number of connections grouped by protocol  used  by
302              dp.  If zone=zone is specified, numbers refer to the connections
303              in zone.  With --more, groups by connection state for each  pro‐
304              tocol.
305
306       ct-bkts [dp] [gt=threshold]
307              For  each  conntrack  bucket, displays the number of connections
308              used by dp.  If gt=threshold is specified,  bucket  numbers  are
309              displayed  when the number of connections in a bucket is greater
310              than threshold.
311
312       ct-set-maxconns [dp] maxconns
313              Sets the maximum limit of connection tracker entries to maxconns
314              on  dp.   This  can be used to reduce the processing load on the
315              system due to connection tracking or simply limiting  connection
316              tracking.   If the number of connections is already over the new
317              maximum limit  request  then  the  new  maximum  limit  will  be
318              enforced when the number of connections decreases to that limit,
319              which normally happens due to connection expiry.  Only supported
320              for userspace datapath.
321
322       ct-get-maxconns [dp]
323              Prints  the  maximum  limit of connection tracker entries on dp.
324              Only supported for userspace datapath.
325
326       ct-get-nconns [dp]
327              Prints the current number of connection tracker entries  on  dp.
328              Only supported for userspace datapath.
329
330       ct-set-limits [dp] [default=default_limit] [zone=zone,limit=limit]...
331              Sets  the  maximum allowed number of connections in a connection
332              tracking zone.  A specific zone may be set to limit, and  multi‐
333              ple  zones  may  be specified with a comma-separated list.  If a
334              per-zone limit for a particular zone is  not  specified  in  the
335              datapath,  it defaults to the default per-zone limit.  A default
336              zone may be specified with the  default=default_limit  argument.
337              Initially,  the  default per-zone limit is unlimited.  An unlim‐
338              ited number of entries may be set with 0 limit.  Only  supported
339              for Linux kernel datapath.
340
341       ct-del-limits [dp] zone=zone[,zone]...
342              Deletes  the connection tracking limit for zone.  Multiple zones
343              may be specified with a comma-separated  list.   Only  supported
344              for Linux kernel datapath.
345
346       ct-get-limits [dp] [zone=zone[,zone]...]
347              Retrieves  the maximum allowed number of connections and current
348              counts per-zone.  If zone is given, only the  specified  zone(s)
349              are printed.  If no zones are specified, all the zone limits and
350              counts are provided.  The command always  displays  the  default
351              zone limit.  Only supported for Linux kernel datapath.
352

OPTIONS

354       -t
355       --timeout=secs
356              Limits  ovs-dpctl runtime to approximately secs seconds.  If the
357              timeout expires, ovs-dpctl will exit with a SIGALRM signal.
358
359       -v[spec]
360       --verbose=[spec]
361              Sets logging levels.  Without any spec, sets the log  level  for
362              every  module and destination to dbg.  Otherwise, spec is a list
363              of words separated by spaces or commas or colons, up to one from
364              each category below:
365
366              ·      A  valid  module name, as displayed by the vlog/list com‐
367                     mand on ovs-appctl(8), limits the log level change to the
368                     specified module.
369
370              ·      syslog,  console,  or file, to limit the log level change
371                     to only to the system log, to the console, or to a  file,
372                     respectively.    (If  --detach  is  specified,  ovs-dpctl
373                     closes its standard file descriptors, so logging  to  the
374                     console will have no effect.)
375
376                     On  Windows platform, syslog is accepted as a word and is
377                     only useful along with the  --syslog-target  option  (the
378                     word has no effect otherwise).
379
380              ·      off,  emer,  err,  warn, info, or dbg, to control the log
381                     level.  Messages of the given severity or higher will  be
382                     logged,  and  messages of lower severity will be filtered
383                     out.  off filters out all  messages.   See  ovs-appctl(8)
384                     for a definition of each log level.
385
386              Case is not significant within spec.
387
388              Regardless  of  the  log  levels set for file, logging to a file
389              will not take place unless --log-file  is  also  specified  (see
390              below).
391
392              For compatibility with older versions of OVS, any is accepted as
393              a word but has no effect.
394
395       -v
396       --verbose
397              Sets the maximum logging verbosity level, equivalent  to  --ver‐
398              bose=dbg.
399
400       -vPATTERN:destination:pattern
401       --verbose=PATTERN:destination:pattern
402              Sets  the  log  pattern  for  destination  to pattern.  Refer to
403              ovs-appctl(8) for a description of the valid syntax for pattern.
404
405       -vFACILITY:facility
406       --verbose=FACILITY:facility
407              Sets the RFC5424 facility of the log message.  facility  can  be
408              one  of kern, user, mail, daemon, auth, syslog, lpr, news, uucp,
409              clock, ftp, ntp, audit, alert, clock2, local0,  local1,  local2,
410              local3,  local4, local5, local6 or local7. If this option is not
411              specified, daemon is used as the default for  the  local  system
412              syslog  and local0 is used while sending a message to the target
413              provided via the --syslog-target option.
414
415       --log-file[=file]
416              Enables logging to a file.  If file is  specified,  then  it  is
417              used  as  the exact name for the log file.  The default log file
418              name   used   if   file    is    omitted    is    /var/log/open‐
419              vswitch/ovs-dpctl.log.
420
421       --syslog-target=host:port
422              Send  syslog  messages  to  UDP port on host, in addition to the
423              system syslog.  The host must be a numerical IP address,  not  a
424              hostname.
425
426       --syslog-method=method
427              Specify method how syslog messages should be sent to syslog dae‐
428              mon.  Following forms are supported:
429
430              ·      libc, use libc syslog() function.  Downside of using this
431                     options  is  that libc adds fixed prefix to every message
432                     before it is actually sent  to  the  syslog  daemon  over
433                     /dev/log UNIX domain socket.
434
435              ·      unix:file, use UNIX domain socket directly.  It is possi‐
436                     ble to specify arbitrary message format with this option.
437                     However,  rsyslogd  8.9 and older versions use hard coded
438                     parser function anyway that  limits  UNIX  domain  socket
439                     use.   If  you  want to use arbitrary message format with
440                     older rsyslogd versions, then use UDP socket to localhost
441                     IP address instead.
442
443              ·      udp:ip:port, use UDP socket.  With this method it is pos‐
444                     sible to use arbitrary message  format  also  with  older
445                     rsyslogd.   When  sending syslog messages over UDP socket
446                     extra precaution needs to  be  taken  into  account,  for
447                     example,  syslog  daemon needs to be configured to listen
448                     on the specified  UDP  port,  accidental  iptables  rules
449                     could  be interfering with local syslog traffic and there
450                     are some security considerations that apply to UDP  sock‐
451                     ets, but do not apply to UNIX domain sockets.
452
453              ·      null, discards all messages logged to syslog.
454
455              The  default  is  taken  from  the OVS_SYSLOG_METHOD environment
456              variable; if it is unset, the default is libc.
457
458       -h
459       --help Prints a brief help message to the console.
460
461       -V
462       --version
463              Prints version information to the console.
464

SEE ALSO

466       ovs-appctl(8), ovs-vswitchd(8)
467
468
469
470Open vSwitch                        2.12.0                        ovs-dpctl(8)
Impressum