Control Path Trace
==================

Commands
========
   netq trace <mac> [vlan <1-4096>] from (<src-hostname>|<ip-src>) [vrf <vrf>] [around <text-time>] [bidir] [json|detail|pretty] [debug]
   netq trace <ip> from (<src-hostname>|<ip-src>) [vrf <vrf>] [around <text-time>] [bidir] [json|detail|pretty] [debug]

Usage
=====
netq trace provides control path tracing (no real packets are sent) from
a specified source to a specified destination. The trace covers complete
end-to-end path tracing including bridged, routed and Vxlan overlay paths.
ECMP is supported as well as checking for forwarding loops, MTU consistency
across all paths, and VLAN consistency across all paths.  Reverse path
trace is also available as an option.

Trace output can be generated in multiple formats.  This includes the default
tabular output, a 'detail' tabular output, as well as 'pretty' output that
presents an intuitive graph like display like the following:

cumulus@tor-1:~# netq trace 27.0.0.23 from tor-1 pretty
Number of Paths: 2
Number of Paths with Errors: 0
Number of Paths with Warnings: 0
Path MTU: 9202

 tor-1 uplink-2 -- downlink-5 spine-2 downlink-1 -- uplink-2 torc-11 <uplink-2>
       uplink-1 -- downlink-5 spine-1 downlink-1 -- uplink-1 torc-11 <uplink-2>

The traversal of the graph is from left to right.  Each node (in bold) has a
left segment that contains input information (e.g. ingress port, router interface,
vlan etc.) and a right segment of output information.  A -- represents a physical
link to the next node.  In the example above, there are two paths (one through
spine-1 and one through spine-2) because the environment is leveraging equal
cost routing.

You can trace by MAC as well:

cumulus@torc-11:mgmt-vrf:~# netq trace 00:02:00:00:00:27 vlan 1001 from hostd-11  pretty
Number of Paths: 6
Number of Paths with Errors: 0
Number of Paths with Warnings: 0
Path MTU: 9152

 hostd-11 torbond1.1001 -- swp7 <vlan1001> torc-12 vni: 34 swp5 -- swp4 spine-3 swp7 -- swp5 vni: 34 tor-1 swp6 -- swp1.1001 hosts-11 <swp1.1001>
                                                           swp4 -- swp4 spine-2 swp7 -- swp4 vni: 34 tor-1 swp6 -- swp1.1001 hosts-11 <swp1.1001>
                                                           swp3 -- swp4 spine-1 swp7 -- swp3 vni: 34 tor-1 swp6 -- swp1.1001 hosts-11 <swp1.1001>
          torbond1.1001 -- swp7 <vlan1001> torc-11 vni: 34 swp5 -- swp3 spine-3 swp7 -- swp5 vni: 34 tor-1 swp6 -- swp1.1001 hosts-11 <swp1.1001>
                                                           swp4 -- swp3 spine-2 swp7 -- swp4 vni: 34 tor-1 swp6 -- swp1.1001 hosts-11 <swp1.1001>
                                                           swp3 -- swp3 spine-1 swp7 -- swp3 vni: 34 tor-1 swp6 -- swp1.1001 hosts-11 <swp1.1001>


In case the paths contain a high enough hop count that the graph like output
becomes too wide, the tabular output can provide a fixed width display without
sacrificing useful details. For example:

root@torc-11:mgmt-vrf:~# netq trace 00:02:00:00:00:27 vlan 1001 from hostd-11  detail
Number of Paths: 6
Number of Paths with Errors: 0
Number of Paths with Warnings: 0
Path MTU: 9152

Id  Hop Hostname        InPort          InVlan InTunnel              InRtrIf         InVRF           OutRtrIf        OutVRF          OutTunnel             OutPort         OutVlan
--- --- --------------- --------------- ------ --------------------- --------------- --------------- --------------- --------------- --------------------- --------------- -------
1   1   hostd-11                                                                                     torbond1.1001   default                               torbond1.1001
    2   torc-12         swp7            1001                         vlan1001        vrf1                                            vni: 34               swp5
    3   spine-3         swp4                                         swp4            default         swp7            default                               swp7
    4   tor-1           swp5                   vni: 34                                                                                                     swp6            1001
    5   hosts-11        swp1.1001                                                                    swp1.1001
--- --- --------------- --------------- ------ --------------------- --------------- --------------- --------------- --------------- --------------------- --------------- -------
2   1   hostd-11                                                                                     torbond1.1001   default                               torbond1.1001
    2   torc-12         swp7            1001                         vlan1001        vrf1                                            vni: 34               swp4
    3   spine-2         swp4                                         swp4            default         swp7            default                               swp7
    4   tor-1           swp4                   vni: 34                                                                                                     swp6            1001
    5   hosts-11        swp1.1001                                                                    swp1.1001
--- --- --------------- --------------- ------ --------------------- --------------- --------------- --------------- --------------- --------------------- --------------- -------
3   1   hostd-11                                                                                     torbond1.1001   default                               torbond1.1001
    2   torc-12         swp7            1001                         vlan1001        vrf1                                            vni: 34               swp3
    3   spine-1         swp4                                         swp4            default         swp7            default                               swp7
    4   tor-1           swp3                   vni: 34                                                                                                     swp6            1001
    5   hosts-11        swp1.1001                                                                    swp1.1001
--- --- --------------- --------------- ------ --------------------- --------------- --------------- --------------- --------------- --------------------- --------------- -------
4   1   hostd-11                                                                                     torbond1.1001   default                               torbond1.1001
    2   torc-11         swp7            1001                         vlan1001        vrf1                                            vni: 34               swp5
    3   spine-3         swp3                                         swp3            default         swp7            default                               swp7
    4   tor-1           swp5                   vni: 34                                                                                                     swp6            1001
    5   hosts-11        swp1.1001                                                                    swp1.1001
--- --- --------------- --------------- ------ --------------------- --------------- --------------- --------------- --------------- --------------------- --------------- -------
5   1   hostd-11                                                                                     torbond1.1001   default                               torbond1.1001
    2   torc-11         swp7            1001                         vlan1001        vrf1                                            vni: 34               swp4
    3   spine-2         swp3                                         swp3            default         swp7            default                               swp7
    4   tor-1           swp4                   vni: 34                                                                                                     swp6            1001
    5   hosts-11        swp1.1001                                                                    swp1.1001
--- --- --------------- --------------- ------ --------------------- --------------- --------------- --------------- --------------- --------------------- --------------- -------
6   1   hostd-11                                                                                     torbond1.1001   default                               torbond1.1001
    2   torc-11         swp7            1001                         vlan1001        vrf1                                            vni: 34               swp3
    3   spine-1         swp3                                         swp3            default         swp7            default                               swp7
    4   tor-1           swp3                   vni: 34                                                                                                     swp6            1001
    5   hosts-11        swp1.1001                                                                    swp1.1001
--- --- --------------- --------------- ------ --------------------- --------------- --------------- --------------- --------------- --------------------- --------------- -------

Each block represents a path (with the path id), and each row represents a hop
along the path, each column provides specific input and output information.

Errors and warnings encountered along the paths are reported in the summary
section at the beginning of the output, with a one line description of each
of the problems, e.g. MTU mismatch or routing loop encountered.

Legend
======
Any errors are shown in red, and warnings are shown in yellow. VTEPs are shown
in BLUE. A node in the 'pretty' output is shown in BOLD, and a router interface
is wrapped in <>.
