1ovn-trace(8)                      OVN Manual                      ovn-trace(8)
2
3
4
5build/.PP
6

NAME

8       ovn-trace - Open Virtual Network logical network tracing utility
9

SYNOPSIS

11       ovn-trace [options] [datapath] microflow
12
13       ovn-trace [options] --detach
14

DESCRIPTION

16       This utility simulates packet forwarding within an OVN logical network.
17       It can be used to run through ``what-if’’ scenarios: if a packet origi‐
18       nates at a logical port, what will happen to it and where will it ulti‐
19       mately  end  up?  Users  already  familiar  with   the   Open   vSwitch
20       ofproto/trace  command  described in ovs-vswitch(8) will find ovn-trace
21       to be a similar tool for logical networks.
22
23       ovn-trace works by reading the Logical_Flow and other tables  from  the
24       OVN  southbound  database (see ovn-sb(5)). It simulates a packet’s path
25       through logical networks by repeatedly looking it  up  in  the  logical
26       flow table, following the entire tree of possibilities.
27
28       ovn-trace  simulates only the OVN logical network. It does not simulate
29       the physical elements on which the logical  network  is  layered.  This
30       means  that,  for  example,  it  is unimportant how VMs are distributed
31       among hypervisors, or whether their  hypervisors  are  functioning  and
32       reachable,  so  ovn-trace will yield the same results regardless. There
33       is one important exception: ovn-northd, the daemon that  generates  the
34       logical  flows  that  ovn-trace simulates, treats logical ports differ‐
35       ently based on whether they are up or down. Thus, if you see surprising
36       results, ensure that the ports involved in a simulation are up.
37
38       The  simplest  way  to  use  ovn-trace is to provide the microflow (and
39       optional datapath) arguments on the command line. In this case, it sim‐
40       ulates  the  behavior  of  a  single packet and exits. For an alternate
41       usage model, see Daemon Mode below.
42
43       The optional datapath argument specifies the name of  a  logical  data‐
44       path.  Acceptable names are the name from the northbound Logical_Switch
45       or Logical_Router table, the UUID of a record from one of those tables,
46       or  the  UUID  of  a record from the southbound Datapath_Binding table.
47       (The datapath is optional because ovn-trace can figure it out from  the
48       inport that the microflow matches.)
49
50       The  microflow  argument describes the packet whose forwarding is to be
51       simulated, in the syntax of an OVN logical expression, as described  in
52       ovn-sb(5),  to  express  constraints.  The parser understands prerequi‐
53       sites; for example, if the expression refers to ip4.src,  there  is  no
54       need to explicitly state ip4 or eth.type == 0x800.
55
56       For  reasonable  L2  behavior,  the  microflow  should include at least
57       inport and eth.dst, plus eth.src if port security is enabled. For exam‐
58       ple:
59
60           inport == "lp11" && eth.src == 00:01:02:03:04:05 && eth.dst == ff:ff:ff:ff:ff:ff
61
62
63       For  reasonable  L3 behavior, microflow should also include ip4.src and
64       ip4.dst (or ip6.src and ip6.dst) and ip.ttl. For example:
65
66           inport == "lp111" && eth.src == f0:00:00:00:01:11 && eth.dst == 00:00:00:00:ff:11
67           && ip4.src == 192.168.11.1 && ip4.dst == 192.168.22.2 && ip.ttl == 64
68
69
70       Here’s an ARP microflow example:
71
72           inport == "lp123"
73           && eth.dst == ff:ff:ff:ff:ff:ff && eth.src == f0:00:00:00:01:11
74           && arp.op == 1 && arp.sha == f0:00:00:00:01:11 && arp.spa == 192.168.1.11
75           && arp.tha == ff:ff:ff:ff:ff:ff && arp.tpa == 192.168.2.22
76
77
78       ovn-trace will reject erroneous  microflow  expressions,  which  beyond
79       syntax  errors  fall into two categories. First, they can be ambiguous.
80       For example, tcp.src == 80 is ambiguous because it does not state  IPv4
81       or  IPv6  as the Ethernet type. ip4 && tcp.src > 1024 is also ambiguous
82       because it does not constrain bits of  tcp.src  to  particular  values.
83       Second, they can be contradictory, e.g. ip4 && ip6.
84

OUTPUT

86       ovn-trace  supports the three different forms of output, each described
87       in a separate section below. Regardless of the selected output  format,
88       ovn-trace  starts the output with a line that shows the microflow being
89       traced in OpenFlow syntax.
90
91   Detailed Output
92       The detailed form of output is also the default form. This form  groups
93       output  into sections headed up by the ingress or egress pipeline being
94       traversed. Each pipeline lists each table that was visited  (by  number
95       and  name), the ovn-northd source file and line number of the code that
96       added the flow, the match expression and priority of the  logical  flow
97       that was matched, and the actions that were executed.
98
99       The  execution  of  OVN  logical  actions  naturally  forms a ``control
100       stack’’ that resembles that of a program  in  conventional  programming
101       languages  such  as  C or Java. Because the next action that calls into
102       another logical flow table for a lookup is a recursive  construct,  OVN
103       ``programs’’  in  practice  tend to form deep control stacks that, dis‐
104       played in the obvious way using additional indentation for each  level,
105       quickly  use up the horizontal space on all but the widest displays. To
106       make  detailed  output  more  readable,  without  loss  of  generality,
107       ovn-trace  omits indentation for ``tail recursion,’’ that is, when next
108       is the last action in a logical flow, it does not indent details of the
109       next table lookup more deeply. Output still uses indentation when it is
110       needed for clarity.
111
112       OVN ``programs’’ traces also tend to encounter long strings of  logical
113       flows with match expression 1 (which matches every packet) and the sin‐
114       gle action next;. These are uninteresting and merely clutter output, so
115       ovn-trace omits them entirely even from detailed output.
116
117       The  following  excerpt  from detailed ovn-trace output shows a section
118       for a packet traversing the ingress pipeline of  logical  datapath  ls1
119       with  ingress  logical port lp111. The packet matches a logical flow in
120       table 0 (aka ls_in_port_sec_l2) with priority 50 and executes  next(1);
121       to pass to table 1. Tables 1 through 11 are trivial and omitted. In ta‐
122       ble 19 (aka ls_in_l2_lkup), the packet matches a flow with priority  50
123       based on its Ethernet destination address and the flow’s actions output
124       the packet to the lrp11-attachement logical port.
125
126           ingress(dp="ls1", inport="lp111")
127           ---------------------------------
128           0. ls_in_port_sec_l2: inport == "lp111", priority 50
129           next(1);
130           19. ls_in_l2_lkup: eth.dst == 00:00:00:00:ff:11, priority 50
131           outport = "lrp11-attachment";
132           output;
133
134
135   Summary Output
136       Summary output includes the logical pipelines visited by a  packet  and
137       the  logical  actions  executed on it. Compared to the detailed output,
138       however, it removes details of tables and logical flows traversed by  a
139       packet.  It  uses a format closer to that of a programming language and
140       does not attempt to avoid indentation. The summary output equivalent to
141       the above detailed output fragment is:
142
143           ingress(dp="ls1", inport="lp111") {
144           outport = "lrp11-attachment";
145           output;
146           ...
147           };
148
149
150   Minimal Output
151       Minimal  output  includes  only  actions  that  modify packet data (not
152       including OVN registers or metadata such as outport) and output actions
153       that  actually  deliver  a  packet  to  a logical port (excluding patch
154       ports). The operands of actions that modify packet data  are  displayed
155       reduced  to  constants, e.g. ip4.dst = reg0; might be show as ip4.dst =
156       192.168.0.1; if that was the value actually loaded. This yields  output
157       even simpler than the summary format. (Users familiar with Open vSwitch
158       may recognize this as similar in spirit to the datapath actions  listed
159       at the bottom of ofproto/trace output.)
160
161       The  minimal output format reflects the externally seen behavior of the
162       logical networks more than it does the implementation. This makes  this
163       output format the most suitable for use in regression tests, because it
164       is least likely to change when logical flow tables are rearranged with‐
165       out semantic change.
166

STATEFUL ACTIONS

168       Some  OVN  logical actions use or update state that is not available in
169       the southbound database. ovn-trace handles these actions  as  described
170       below:
171
172              ct_next
173                     By  default  ovn-trace  treats  flows  as ``tracked’’ and
174                     ``established.’’ See the description of the  --ct  option
175                     for a way to override this behavior.
176
177              ct_dnat (without an argument)
178                     Forks the pipeline. In one fork, advances to the next ta‐
179                     ble as if next; were executed. The packet is not changed,
180                     on the assumption that no NAT state was available. In the
181                     other fork, the pipeline continues without  change  after
182                     the ct_dnat action.
183
184              ct_snat (without an argument)
185                     This  action  distinguishes  between  gateway routers and
186                     distributed routers. A gateway router  is  defined  as  a
187                     logical  datapath  that  contains  an l3gateway port; any
188                     other logical datapath is  a  distributed  router.  On  a
189                     gateway router, ct_snat; is treated as a no-op. On a dis‐
190                     tributed router, it is treated the same way as ct_dnat;.
191
192              ct_dnat(ip)
193              ct_snat(ip)
194                   Forks the pipeline. In one fork, sets ip4.dst (or  ip4.src)
195                   to  ip  and  ct.dnat  (or ct.snat) to 1 and advances to the
196                   next table as if next; were executed. In  the  other  fork,
197                   the pipeline continues without change after the ct_dnat (or
198                   ct_snat) action.
199
200              ct_lb;
201              ct_lb(ip[:port]...);
202                   Forks the pipeline. In one fork, sets ip4.dst (or  ip6.dst)
203                   to  one  of the load-balancer addresses and the destination
204                   port to its associated port, if any, and sets ct.dnat to 1.
205                   With one or more arguments, gives preference to the address
206                   specified on --lb-dst, if any; without arguments, uses  the
207                   address  and port specified on --lb-dst. In the other fork,
208                   the pipeline  continues  without  change  after  the  ct_lb
209                   action.
210
211              ct_commit
212              put_arp
213              put_nd
214                   These actions are treated as no-ops.
215

DAEMON MODE

217       If  ovn-trace  is invoked with the --detach option (see Daemon Options,
218       below), it runs in the background as a daemon and accepts commands from
219       ovs-appctl  (or  another  JSON-RPC  client) indefinitely. The currently
220       supported commands are described below.
221
222              trace [options] [datapath] microflow
223                     Traces microflow through datapath and  replies  with  the
224                     results of the trace. Accepts the options described under
225                     Trace Options below.
226
227              exit   Causes ovn-trace to gracefully terminate.
228

OPTIONS

230   Trace Options
231       --detailed
232       --summary
233       --minimal
234            These options control the form and level of  detail  in  ovn-trace
235            output. If more than one of these options is specified, all of the
236            selected forms are output, in the order listed above, each  headed
237            by a banner line. If none of these options is given, --detailed is
238            the default. See Output, above, for a description of each kind  of
239            output.
240
241       --all
242            Selects all three forms of output.
243
244       --ovs[=remote]
245            Makes  ovn-trace  attempt to obtain and display the OpenFlow flows
246            that correspond to each OVN logical flow. To do so, ovn-trace con‐
247            nects  to remote (by default, unix:/br-int.mgmt) over OpenFlow and
248            retrieves the flows. If remote is specified, it must be an  active
249            OpenFlow connection method described in ovsdb(7).
250
251            To  make the best use of the output, it is important to understand
252            the  relationship  between  logical  flows  and  OpenFlow   flows.
253            ovn-architecture(7),  under Architectural Physical Life Cycle of a
254            Packet, describes this relationship. Keep in  mind  the  following
255            points:
256
257            ·      ovn-trace currently shows all the OpenFlow flows to which a
258                   logical flow corresponds,  even  though  an  actual  packet
259                   ordinarily matches only one of these.
260
261            ·      Some  logical  flows can map to the Open vSwitch ``conjunc‐
262                   tive  match’’  extension  (see  ovs-fields(7)).   Currently
263                   ovn-trace cannot display the flows with conjunction actions
264                   that effectively produce the conj_id match.
265
266            ·      Some logical flows may not be represented in  the  OpenFlow
267                   tables  on a given hypervisor, if they could not be used on
268                   that hypervisor.
269
270            ·      Some OpenFlow flows do not  correspond  to  logical  flows,
271                   such  as OpenFlow flows that map between physical and logi‐
272                   cal ports. These flows will never show up in a trace.
273
274            ·      When ovn-trace omits uninteresting logical flows from  out‐
275                   put, it does not look up the corresponding OpenFlow flows.
276
277       --ct=flags
278            This  option sets the ct_state flags that a ct_next logical action
279            will report. The flags must be a comma- or space-separated list of
280            the following connection tracking flags:
281
282            ·      trk:  Include  to  indicate  connection  tracking has taken
283                   place. (This bit is set automatically even if not listed in
284                   flags.
285
286            ·      new: Include to indicate a new flow.
287
288            ·      est: Include to indicate an established flow.
289
290            ·      rel: Include to indicate a related flow.
291
292            ·      rpl: Include to indicate a reply flow.
293
294            ·      inv: Include to indicate a connection entry in a bad state.
295
296            ·      dnat:  Include  to  indicate  a packet whose destination IP
297                   address has been changed.
298
299            ·      snat: Include to indicate a packet whose source IP  address
300                   has been changed.
301
302            The  ct_next action is used to implement the OVN distributed fire‐
303            wall. For testing, useful flag combinations include:
304
305            ·      trk,new: A packet in a flow in either direction  through  a
306                   firewall that has not yet been committed (with ct_commit).
307
308            ·      trk,est:  A packet in an established flow going out through
309                   a firewall.
310
311            ·      trk,rpl: A packet coming in through a firewall in reply  to
312                   an established flow.
313
314            ·      trk,inv: An invalid packet in either direction.
315
316            A  packet  might  pass through the connection tracker twice in one
317            trip through OVN: once following egress from a  VM  as  it  passes
318            outward through a firewall, and once preceding ingress to a second
319            VM as it passes inward  through  a  firewall.  Use  multiple  --ct
320            options to specify the flags for multiple ct_next actions.
321
322            When  --ct  is  unspecified,  or when there are fewer --ct options
323            than ct_next actions, the flags default to trk,est.
324
325       --lb-dst=ip[:port]
326            Sets the IP from VIP pool to use as  destination  of  the  packet.
327            --lb-dst is not available in daemon mode.
328
329       --select-id=id
330            Specify the id to be selected by the select action. id must be one
331            of the values listed in the select action. Otherwise, a random  id
332            is  selected  from the list, as if --select-id were not specified.
333            --select-id is not available in daemon mode.
334
335       --friendly-names
336       --no-friendly-names
337            When cloud management systems such as OpenStack are layered on top
338            of  OVN, they often use long, human-unfriendly names for ports and
339            datapaths, for example, ones that include entire  UUIDs.  They  do
340            usually include friendlier names, but the long, hard-to-read names
341            are the ones that appear in matches and actions.  By  default,  or
342            with  --friendly-names,  ovn-trace  substitutes  these  friendlier
343            names for the long names in its output. Use --no-friendly-names to
344            disable  this  behavior; this option might be useful, for example,
345            if a program is going to parse ovn-trace output.
346
347   Daemon Options
348       --pidfile[=pidfile]
349              Causes a file (by default, program.pid) to be created indicating
350              the  PID  of the running process. If the pidfile argument is not
351              specified, or if it does not begin with /, then it is created in
352              .
353
354              If --pidfile is not specified, no pidfile is created.
355
356       --overwrite-pidfile
357              By  default,  when --pidfile is specified and the specified pid‐
358              file already exists and is locked by a running process, the dae‐
359              mon refuses to start. Specify --overwrite-pidfile to cause it to
360              instead overwrite the pidfile.
361
362              When --pidfile is not specified, this option has no effect.
363
364       --detach
365              Runs this program as a background process.  The  process  forks,
366              and  in  the  child it starts a new session, closes the standard
367              file descriptors (which has the side effect of disabling logging
368              to  the  console), and changes its current directory to the root
369              (unless --no-chdir is specified). After the child completes  its
370              initialization, the parent exits.
371
372       --monitor
373              Creates  an  additional  process  to monitor this program. If it
374              dies due to a signal that indicates a programming  error  (SIGA‐
375              BRT, SIGALRM, SIGBUS, SIGFPE, SIGILL, SIGPIPE, SIGSEGV, SIGXCPU,
376              or SIGXFSZ) then the monitor process starts a new copy of it. If
377              the daemon dies or exits for another reason, the monitor process
378              exits.
379
380              This option is normally used with --detach, but  it  also  func‐
381              tions without it.
382
383       --no-chdir
384              By  default,  when --detach is specified, the daemon changes its
385              current  working  directory  to  the  root  directory  after  it
386              detaches.  Otherwise, invoking the daemon from a carelessly cho‐
387              sen directory would prevent the  administrator  from  unmounting
388              the file system that holds that directory.
389
390              Specifying  --no-chdir  suppresses this behavior, preventing the
391              daemon from changing its current working directory. This may  be
392              useful for collecting core files, since it is common behavior to
393              write core dumps into the current working directory and the root
394              directory is not a good directory to use.
395
396              This option has no effect when --detach is not specified.
397
398       --no-self-confinement
399              By  default  this daemon will try to self-confine itself to work
400              with files under  well-known  directories  determined  at  build
401              time.  It  is better to stick with this default behavior and not
402              to use this flag unless some other Access  Control  is  used  to
403              confine  daemon.  Note  that in contrast to other access control
404              implementations that are typically  enforced  from  kernel-space
405              (e.g.  DAC  or  MAC), self-confinement is imposed from the user-
406              space daemon itself and hence should not be considered as a full
407              confinement  strategy,  but instead should be viewed as an addi‐
408              tional layer of security.
409
410       --user=user:group
411              Causes this program to run as  a  different  user  specified  in
412              user:group,  thus  dropping  most  of the root privileges. Short
413              forms user and :group are also allowed,  with  current  user  or
414              group  assumed,  respectively.  Only daemons started by the root
415              user accepts this argument.
416
417              On   Linux,   daemons   will   be   granted   CAP_IPC_LOCK   and
418              CAP_NET_BIND_SERVICES  before  dropping root privileges. Daemons
419              that interact with a datapath, such  as  ovs-vswitchd,  will  be
420              granted  three  additional  capabilities,  namely CAP_NET_ADMIN,
421              CAP_NET_BROADCAST and CAP_NET_RAW. The  capability  change  will
422              apply even if the new user is root.
423
424              On Windows, this option is not currently supported. For security
425              reasons, specifying this option will cause  the  daemon  process
426              not to start.
427
428   Logging Options
429       -v[spec]
430       --verbose=[spec]
431            Sets  logging  levels.  Without  any  spec, sets the log level for
432            every module and destination to dbg. Otherwise, spec is a list  of
433            words separated by spaces or commas or colons, up to one from each
434            category below:
435
436            ·      A valid module name, as displayed by the vlog/list  command
437                   on ovs-appctl(8), limits the log level change to the speci‐
438                   fied module.
439
440            ·      syslog, console, or file, to limit the log level change  to
441                   only  to  the  system  log,  to  the console, or to a file,
442                   respectively. (If --detach is specified, the daemon  closes
443                   its  standard  file  descriptors, so logging to the console
444                   will have no effect.)
445
446                   On Windows platform, syslog is accepted as a  word  and  is
447                   only useful along with the --syslog-target option (the word
448                   has no effect otherwise).
449
450            ·      off, emer, err, warn, info, or  dbg,  to  control  the  log
451                   level.  Messages  of  the  given severity or higher will be
452                   logged, and messages of lower  severity  will  be  filtered
453                   out.  off filters out all messages. See ovs-appctl(8) for a
454                   definition of each log level.
455
456            Case is not significant within spec.
457
458            Regardless of the log levels set for file, logging to a file  will
459            not take place unless --log-file is also specified (see below).
460
461            For compatibility with older versions of OVS, any is accepted as a
462            word but has no effect.
463
464       -v
465       --verbose
466            Sets the maximum logging verbosity  level,  equivalent  to  --ver‐
467            bose=dbg.
468
469       -vPATTERN:destination:pattern
470       --verbose=PATTERN:destination:pattern
471            Sets  the  log  pattern  for  destination  to  pattern.  Refer  to
472            ovs-appctl(8) for a description of the valid syntax for pattern.
473
474       -vFACILITY:facility
475       --verbose=FACILITY:facility
476            Sets the RFC5424 facility of the log message. facility can be  one
477            of kern, user, mail, daemon, auth, syslog, lpr, news, uucp, clock,
478            ftp, ntp, audit, alert, clock2, local0,  local1,  local2,  local3,
479            local4, local5, local6 or local7. If this option is not specified,
480            daemon is used as the default for  the  local  system  syslog  and
481            local0  is used while sending a message to the target provided via
482            the --syslog-target option.
483
484       --log-file[=file]
485            Enables logging to a file. If file is specified, then it  is  used
486            as the exact name for the log file. The default log file name used
487            if file is omitted is /var/log/ovn/program.log.
488
489       --syslog-target=host:port
490            Send syslog messages to UDP port on host, in addition to the  sys‐
491            tem  syslog.  The host must be a numerical IP address, not a host‐
492            name.
493
494       --syslog-method=method
495            Specify method as how syslog messages should  be  sent  to  syslog
496            daemon. The following forms are supported:
497
498            ·      libc,  to use the libc syslog() function. Downside of using
499                   this options is that libc adds fixed prefix to  every  mes‐
500                   sage  before  it is actually sent to the syslog daemon over
501                   /dev/log UNIX domain socket.
502
503            ·      unix:file, to use a UNIX domain socket directly. It is pos‐
504                   sible to specify arbitrary message format with this option.
505                   However, rsyslogd 8.9 and older  versions  use  hard  coded
506                   parser  function anyway that limits UNIX domain socket use.
507                   If you want to use  arbitrary  message  format  with  older
508                   rsyslogd  versions,  then  use  UDP  socket to localhost IP
509                   address instead.
510
511            ·      udp:ip:port, to use a UDP socket. With this  method  it  is
512                   possible  to  use  arbitrary message format also with older
513                   rsyslogd. When sending  syslog  messages  over  UDP  socket
514                   extra  precaution needs to be taken into account, for exam‐
515                   ple, syslog daemon needs to be configured to listen on  the
516                   specified  UDP  port,  accidental  iptables  rules could be
517                   interfering with local syslog traffic and  there  are  some
518                   security  considerations  that apply to UDP sockets, but do
519                   not apply to UNIX domain sockets.
520
521            ·      null, to discard all messages logged to syslog.
522
523            The default is taken from the OVS_SYSLOG_METHOD environment  vari‐
524            able; if it is unset, the default is libc.
525
526   PKI Options
527       PKI  configuration  is  required  to  use SSL for the connection to the
528       database (and the switch, if --ovs is specified).
529
530              -p privkey.pem
531              --private-key=privkey.pem
532                   Specifies a PEM file containing the  private  key  used  as
533                   identity for outgoing SSL connections.
534
535              -c cert.pem
536              --certificate=cert.pem
537                   Specifies  a  PEM file containing a certificate that certi‐
538                   fies the private key specified on -p or --private-key to be
539                   trustworthy. The certificate must be signed by the certifi‐
540                   cate authority (CA) that the peer in SSL  connections  will
541                   use to verify it.
542
543              -C cacert.pem
544              --ca-cert=cacert.pem
545                   Specifies a PEM file containing the CA certificate for ver‐
546                   ifying certificates presented to this program by SSL peers.
547                   (This  may  be  the  same certificate that SSL peers use to
548                   verify the certificate specified on -c or --certificate, or
549                   it  may  be a different one, depending on the PKI design in
550                   use.)
551
552              -C none
553              --ca-cert=none
554                   Disables verification  of  certificates  presented  by  SSL
555                   peers.  This  introduces  a security risk, because it means
556                   that certificates cannot be verified to be those  of  known
557                   trusted hosts.
558
559   Other Options
560       --db database
561              The  OVSDB database remote to contact. If the OVN_SB_DB environ‐
562              ment variable is set, its value is used as the  default.  Other‐
563              wise, the default is unix:/db.sock, but this default is unlikely
564              to be useful outside of single-machine OVN test environments.
565
566              -h
567              --help
568                   Prints a brief help message to the console.
569
570              -V
571              --version
572                   Prints version information to the console.
573
574
575
576OVN 20.12.0                        ovn-trace                      ovn-trace(8)
Impressum