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  a  specific
158              type.   type can be offloaded to display only rules offloaded to
159              the HW or ovs to display only rules from  the  OVS  tables.   By
160              default all rules are displayed.
161
162       add-flow [dp] flow actions
163
164       [--clear] [--may-create] [-s | --statistics] mod-flow [dp] flow actions
165              Adds  or  modifies a flow in dp's flow table that, when a packet
166              matching flow arrives, causes actions to be executed.
167
168              The add-flow command succeeds only  if  flow  does  not  already
169              exist  in  dp.  Contrariwise, mod-flow without --may-create only
170              modifies the actions for an existing flow.   With  --may-create,
171              mod-flow will add a new flow or modify an existing one.
172
173              If  -s  or  --statistics  is specified, then mod-flow prints the
174              modified flow's statistics.  A flow's statistics are the  number
175              of  packets  and  bytes  that  have passed through the flow, the
176              elapsed time since the flow last processed a packet  (if  ever),
177              and (for TCP flows) the union of the TCP flags processed through
178              the flow.
179
180              With --clear, mod-flow zeros out  the  flow's  statistics.   The
181              statistics  printed  if -s or --statistics is also specified are
182              those from just before clearing the statistics.
183
184              NOTE: flow and  actions  do  not  match  the  syntax  used  with
185              ovs-ofctl(8)'s add-flow command.
186
187              Usage Examples
188
189              Forward ARP between ports 1 and 2 on datapath myDP:
190
191                     ovs-dpctl add-flow myDP \
192                       "in_port(1),eth(),eth_type(0x0806),arp()" 2
193
194                     ovs-dpctl add-flow myDP \
195                       "in_port(2),eth(),eth_type(0x0806),arp()" 1
196
197              Forward all IPv4 traffic between two addresses on ports 1 and 2:
198
199                     ovs-dpctl add-flow myDP \
200                       "in_port(1),eth(),eth_type(0x800),\
201                        ipv4(src=172.31.110.4,dst=172.31.110.5)" 2
202
203                     ovs-dpctl add-flow myDP \
204                       "in_port(2),eth(),eth_type(0x800),\
205                        ipv4(src=172.31.110.5,dst=172.31.110.4)" 1
206
207       [-s | --statistics] del-flow [dp] flow
208              Deletes  the flow from dp's flow table that matches flow.  If -s
209              or --statistics is specified, then del-flow prints  the  deleted
210              flow's statistics.
211
212       [-m | --more] [--names | --no-names] get-flow [dp] ufid:ufid
213              Fetches  the  flow  from  dp's flow table with unique identifier
214              ufid.  ufid must be specified as  a  string  of  32  hexadecimal
215              characters.
216
217       del-flows [dp]
218              Deletes all flow entries from datapath dp's flow table.
219
220   CONNECTION TRACKING TABLE COMMANDS
221       The  following  commands  are  useful for debugging and configuring the
222       connection tracking table in the datapath.
223
224       The dp argument to each of these commands is optional when exactly  one
225       datapath exists, in which case that datapath is the default.  When mul‐
226       tiple datapaths exist, then a datapath name is required.
227
228       N.B.(Linux specific): the system datapaths (i.e. the Linux kernel  mod‐
229       ule  Open  vSwitch  datapaths) share a single connection tracking table
230       (which is also used by other kernel subsystems, such as iptables, nfta‐
231       bles and the regular host stack).  Therefore, the following commands do
232       not apply specifically to one datapath.
233
234       [-m | --more] [-s | --statistics] dump-conntrack [dp] [zone=zone]
235              Prints to the console all the connection entries in the  tracker
236              used  by  dp.  If zone=zone is specified, only shows the connec‐
237              tions  in  zone.   With  --more,  some  implementation  specific
238              details  are included. With --statistics timeouts and timestamps
239              are added to the output.
240
241       flush-conntrack [dp] [zone=zone] [ct-tuple]
242              Flushes the connection entries in the tracker used by  dp  based
243              on  zone and connection tracking tuple ct-tuple.  If ct-tuple is
244              not provided, flushes all the connection entries.  If  zone=zone
245              is specified, only flushes the connections in zone.
246
247              If  ct-tuple is provided, flushes the connection entry specified
248              by ct-tuple in zone. The zone defaults to 0 if it  is  not  pro‐
249              vided.  An example of an IPv4 ICMP ct-tuple:
250
251              "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"
252
253              An example of an IPv6 TCP ct-tuple:
254
255              "ct_ipv6_src=fc00::1,ct_ipv6_dst=fc00::2,ct_nw_proto=6,ct_tp_src=1,ct_tp_dst=2"
256
257       [-m | --more] ct-stats-show [dp] [zone=zone]
258              Displays  the  number of connections grouped by protocol used by
259              dp.  If zone=zone is specified, numbers refer to the connections
260              in  zone.  With --more, groups by connection state for each pro‐
261              tocol.
262
263       ct-bkts [dp] [gt=threshold]
264              For each conntrack bucket, displays the  number  of  connections
265              used  by  dp.   If gt=threshold is specified, bucket numbers are
266              displayed when the number of connections in a bucket is  greater
267              than threshold.
268
269       ct-set-maxconns [dp] maxconns
270              Sets the maximum limit of connection tracker entries to maxconns
271              on dp.  This can be used to reduce the processing  load  on  the
272              system  due to connection tracking or simply limiting connection
273              tracking.  If the number of connections is already over the  new
274              maximum  limit  request  then  the  new  maximum  limit  will be
275              enforced when the number of connections decreases to that limit,
276              which normally happens due to connection expiry.  Only supported
277              for userspace datapath.
278
279       ct-get-maxconns [dp]
280              Prints the maximum limit of connection tracker  entries  on  dp.
281              Only supported for userspace datapath.
282
283       ct-get-nconns [dp]
284              Prints  the  current number of connection tracker entries on dp.
285              Only supported for userspace datapath.
286
287       ct-set-limits [dp] [default=default_limit] [zone=zone,limit=limit]...
288              Sets the maximum allowed number of connections in  a  connection
289              tracking  zone.  A specific zone may be set to limit, and multi‐
290              ple zones may be specified with a comma-separated  list.   If  a
291              per-zone  limit  for  a  particular zone is not specified in the
292              datapath, it defaults to the default per-zone limit.  A  default
293              zone  may  be specified with the default=default_limit argument.
294              Initially, the default per-zone limit is unlimited.   An  unlim‐
295              ited  number of entries may be set with 0 limit.  Only supported
296              for Linux kernel datapath.
297
298       ct-del-limits [dp] zone=zone[,zone]...
299              Deletes the connection tracking limit for zone.  Multiple  zones
300              may  be  specified  with a comma-separated list.  Only supported
301              for Linux kernel datapath.
302
303       ct-get-limits [dp] [zone=zone[,zone]...]
304              Retrieves the maximum allowed number of connections and  current
305              counts  per-zone.   If zone is given, only the specified zone(s)
306              are printed.  If no zones are specified, all the zone limits and
307              counts  are  provided.   The command always displays the default
308              zone limit.  Only supported for Linux kernel datapath.
309

OPTIONS

311       -t
312       --timeout=secs
313              Limits ovs-dpctl runtime to approximately secs seconds.  If  the
314              timeout expires, ovs-dpctl will exit with a SIGALRM signal.
315
316       -v[spec]
317       --verbose=[spec]
318              Sets  logging  levels.  Without any spec, sets the log level for
319              every module and destination to dbg.  Otherwise, spec is a  list
320              of words separated by spaces or commas or colons, up to one from
321              each category below:
322
323              ·      A valid module name, as displayed by the  vlog/list  com‐
324                     mand on ovs-appctl(8), limits the log level change to the
325                     specified module.
326
327              ·      syslog, console, or file, to limit the log  level  change
328                     to  only to the system log, to the console, or to a file,
329                     respectively.   (If  --detach  is  specified,   ovs-dpctl
330                     closes  its  standard file descriptors, so logging to the
331                     console will have no effect.)
332
333                     On Windows platform, syslog is accepted as a word and  is
334                     only  useful  along  with the --syslog-target option (the
335                     word has no effect otherwise).
336
337              ·      off, emer, err, warn, info, or dbg, to  control  the  log
338                     level.   Messages of the given severity or higher will be
339                     logged, and messages of lower severity will  be  filtered
340                     out.   off  filters  out all messages.  See ovs-appctl(8)
341                     for a definition of each log level.
342
343              Case is not significant within spec.
344
345              Regardless of the log levels set for file,  logging  to  a  file
346              will  not  take  place  unless --log-file is also specified (see
347              below).
348
349              For compatibility with older versions of OVS, any is accepted as
350              a word but has no effect.
351
352       -v
353       --verbose
354              Sets  the  maximum logging verbosity level, equivalent to --ver‐
355              bose=dbg.
356
357       -vPATTERN:destination:pattern
358       --verbose=PATTERN:destination:pattern
359              Sets the log pattern  for  destination  to  pattern.   Refer  to
360              ovs-appctl(8) for a description of the valid syntax for pattern.
361
362       -vFACILITY:facility
363       --verbose=FACILITY:facility
364              Sets  the  RFC5424  facility of the log message. facility can be
365              one of kern, user, mail, daemon, auth, syslog, lpr, news,  uucp,
366              clock,  ftp,  ntp, audit, alert, clock2, local0, local1, local2,
367              local3, local4, local5, local6 or local7. If this option is  not
368              specified,  daemon  is  used as the default for the local system
369              syslog and local0 is used while sending a message to the  target
370              provided via the --syslog-target option.
371
372       --log-file[=file]
373              Enables  logging  to  a  file.  If file is specified, then it is
374              used as the exact name for the log file.  The default  log  file
375              name    used    if    file    is   omitted   is   /var/log/open‐
376              vswitch/ovs-dpctl.log.
377
378       --syslog-target=host:port
379              Send syslog messages to UDP port on host,  in  addition  to  the
380              system  syslog.   The host must be a numerical IP address, not a
381              hostname.
382
383       --syslog-method=method
384              Specify method how syslog messages should be sent to syslog dae‐
385              mon.  Following forms are supported:
386
387              ·      libc,  use  libc  syslog() function.  This is the default
388                     behavior.  Downside of using this options  is  that  libc
389                     adds  fixed prefix to every message before it is actually
390                     sent to the  syslog  daemon  over  /dev/log  UNIX  domain
391                     socket.
392
393              ·      unix:file, use UNIX domain socket directly.  It is possi‐
394                     ble to specify arbitrary message format with this option.
395                     However,  rsyslogd  8.9 and older versions use hard coded
396                     parser function anyway that  limits  UNIX  domain  socket
397                     use.   If  you  want to use arbitrary message format with
398                     older rsyslogd versions, then use UDP socket to localhost
399                     IP address instead.
400
401              ·      udp:ip:port, use UDP socket.  With this method it is pos‐
402                     sible to use arbitrary message  format  also  with  older
403                     rsyslogd.   When  sending syslog messages over UDP socket
404                     extra precaution needs to  be  taken  into  account,  for
405                     example,  syslog  daemon needs to be configured to listen
406                     on the specified  UDP  port,  accidental  iptables  rules
407                     could  be interfering with local syslog traffic and there
408                     are some security considerations that apply to UDP  sock‐
409                     ets, but do not apply to UNIX domain sockets.
410
411       -h
412       --help Prints a brief help message to the console.
413
414       -V
415       --version
416              Prints version information to the console.
417

SEE ALSO

419       ovs-appctl(8), ovs-vswitchd(8)
420
421
422
423Open vSwitch                        2.10.0                        ovs-dpctl(8)
Impressum