Dataplane Packet Tracing¶
TNSR offers a means to trace packet actions through the dataplane. This is different from a packet capture in that a packet capture looks at the contents of a packet while a trace inspects how a packet flows through the dataplane. A trace shows basic information about a packet and the actions taken on the packet by the dataplane along the way.
Tip
While tracing is different from a packet capture a trace can be filtered on certain packet properties, see Trace Match Filtering for details.
Trace Capture¶
A trace capture records the actions taken by the dataplane on a given number of packets. The trace includes packet header data such as IP addresses, MAC addresses, and so on as well as which actions were taken by the dataplane (i.e. which dataplane nodes processed the packet). This gives a view of how a packet flowed through the dataplane, including whether or not the dataplane dropped a packet or allowed it to egress.
trace capture node <input-node> [maximum <max>] [verbose] [pre-clear] [filter]
- node <input-node>:
The dataplane input node to capture on. For a list, enter
trace capture node ?
. The most common choice isdpdk-input
.- maximum <max>:
The maximum number of packets to include in the trace.
Note
When using a Trace Filter, set the
maximum
value here larger than themaximum
value on the filter. The filter will restrict matches within the total packets traced. If the trace capturemaximum
is too low, the filter can never reach its ownmaximum
value unless every packet in the trace happens to match.- verbose:
Include additional data in the trace output.
- pre-clear:
Clear the packet trace buffer before starting this trace.
- filter:
Activate classify filter matching for this capture session.
To manually clear the packet trace buffer, use trace clear
.
Trace Filter¶
Filtering restricts the trace output to match only packets which involve a specific dataplane graph node. There are numerous graph nodes for a variety of purposes.
trace filter (exclude|include) node <graph-node> [maximum <max>]
- (exclude|include):
Action for this filter.
- exclude:
Match packets which do not include a given node.
- include:
Match packets which include the given node.
- node <graph-node>:
A graph node name. Use
trace filter <action> node ?
for a list.- maximum <max>:
The maximum number of packets matching this filter to include in the output.
Note
Filters are also restricted by the total size of the trace capture. A trace
capture can stop before it reaches the maximum
value on the filter if it
reaches its own maximum
value first.
For example, an include
filter may result in an empty trace if no packets
in the trace capture match the filter before the capture reaches its maximum
number of packets. Similarly, an exclude
filter may result in an empty
trace if the filter matches and excludes all packets in the trace capture.
trace filter none
Clear all trace filters.
Note
Trace filtering is ineffective if the trace capture node is error-drop
.
When capturing the error-drop
node, it is always the last node in the
graph trace. Trace filtering isn’t applied until a match occurrs after the
packet crosses the trace capture node. Since error-drop
is always last,
then the filter cannot match any other parameters as processing has already
stopped at that point.
Trace Match Filtering¶
An alternate way to filter trace captures is via the classify system, also known as trace match filtering. Trace matching filters a capture by various aspects of packet contents at layer 2 (Ethernet), layer 3 (IPv4/IPv6), and layer 4 (TCP or UDP).
Defining a new match filter¶
From main or config
mode, enter the trace match <name>
command to define
a new match filter and enter config-trace-match
mode.
tnsr# trace match <name>
tnsr(config-trace-match)#
From within config-trace-match
the following commands are available:
- description <text>
Defines a description for this trace match.
- ethernet
Enters Ethernet (Layer 2) Matching mode.
- ip4
Enters IPv4 (Layer 3) Matching mode.
- ip6
Enters IPv6 (Layer 3) Matching mode.
- tcp
Enters TCP (Layer 4) Matching mode.
- udp
Enters UDP (Layer 4) Matching mode.
Ethernet (Layer 2) Matching¶
This mode defines Ethernet (Layer 2) properties of the packet to match.
The following commands are available from within config-trace-ether
mode:
- destination mac-address <mac-addr>
A destination MAC address in colon-separated format (e.g.
00:00:00:00:00:00
).- destination mask <mask-val>
A mask for the destination MAC address to match partial addresses.
- ethertype <type-name>
An IETF Ethertype name or a value in the range
0x600
to0xffff
.Tip
For a list of names, enter
ethertype ?
at the CLI.- source mac-address <mac-addr>
A source MAC address in colon-separated format (e.g.
00:00:00:00:00:00
).- source mask <mask-val>
A mask for the source MAC address to match partial addresses.
- vlan-dot1q [(pcp <val>|tag <inner-tag>)]
If present, the packet allows octets for dot1q VLAN tag information.
- pcp <val>
The optional inner dot1q VLAN Priority Code Point (class of service) within the range
0..7
.- tag <inner-tag>
The optional inner dot1q VLAN tag value.
- vlan-dot1q vlan-dot1ad [(pcp <val>|tag <outer-tag>)]
If present, the packet allows octets for dot1ad outer VLAN tag and dot1q inner VLAN tag information.
- pcp <val>
The optional dot1ad outer VLAN Priority Code Point (class of service) within the range
0..7
.- tag <outer-tag>
The optional outer dot1ad VLAN tag value.
IPv4 (Layer 3) Matching¶
This mode defines IPv4 (Layer 3) properties of the packet to match.
The following commands are available from within config-trace-ip4
mode:
- checksum <uint16>
The checksum field is used for error-checking the packet.
- destination-ip-prefix <prefix>
The destination IPv4 address and prefix mask length.
- dscp <val:0..63>
Formerly called the ToS field, this is the differentiated services (DiffServ) code within the range
0..63
.- ecn <val:0..3>
The Explicit Congestion Notification value within the range
0..3
.- flags <value>
Bit values for
dont-fragment
(position 1) andmore-fragments
(position 2) flags.If the
dont-fragment
flag is set, and fragmentation is required to route the packet, then the packet is dropped.For fragmented packets, all fragments except the last have the
more-fragments
flag set.- fragmentation-offset <val:0..8191>
The fragmentation-offset specifies the offset within the range
0..8191
of a particular fragment relative to the beginning of the original unfragmented IP datagram.- identification <uint16>
The identifcation field was used experimentally for fragmentation grouping.
- ihl <val:5-15>
The internet header length (ihl) states the size of the IPv4 header in 32-byte quantities within the range
5..15
.- length <val:20..65535>
The total length field states the size of the entire packet in bytes within the range
20..65535
.- protocol <uint8>
Specifies the protocol used in the data portion of the IP datagram.
- source-ip-prefix <prefix>
The source IPv4 address and prefix mask length.
- ttl <uint16>
Specifies the number of router hops a packet can traverse before it is dropped.
- version <val>
The IP version, which should always be
4
for IPv4 packets.
IPv6 (Layer 3) Matching¶
This mode defines IPv6 (Layer 3) properties of the packet to match.
The following commands are available from within config-trace-ip6
mode:
- destination-prefix <prefix>
The destination IPv6 address and prefix mask length.
- flow-label <val:0..1048575>
The 20-bit flow identifier value in the range
0..1048575
.- hop-limit <uint8>
The maximum forwarding count before a packet is dropped.
- next-header <uint8>
The protocol type of the next header.
- payload-length <uint16>
The length of the payload in octets.
- source-prefix <prefix>
The source IPv6 address and prefix mask length.
- traffic-class <val>
The combined differentiated services field in the high 6 bits and the Explicit Congestion Notification (ECN) in the low 2 bits.
- version <val>
The IP version, which should always be
6
for IPv6 packets.
TCP (Layer 4) Matching¶
This mode defines TCP (Layer 4) properties of the packet to match.
The following commands are available from within config-trace-tcp
mode:
- acknowledgement-number <uint16>
Acknowledgement number within the session.
- checksum <uint16>
The checksum of the packet.
- data-offset <uint16>
The size of the TCP header in 32-bit words.
- destination-port <port-number>
The TCP destination port number in the range
1-65535
.- flags <flag-val>
Bit values for TCP flags:
fin
,syn
,rst
,psh
,ack
,urg
,ece
,cwr
,ns
in positions 0-8 respectively.- sequence-number <uint16>
Sequence number within the session.
- source-port <port-number>
The TCP source port number in the range
1-65535
.- window <uint16>
The receive window size.
UDP (Layer 4) Matching¶
This mode defines UDP (Layer 4) properties of the packet to match.
The following commands are available from within config-trace-udp
mode:
- checksum <uint16>
The checksum of the packet.
- destination-port <port-number>
The UDP destination port number in the range
1-65535
.- length <uint16>
The length of the packet in bytes.
- source-port <port-number>
The UDP source port number in the range
1-65535
.
Trace Match Example¶
The following example is a trace match to look for incoming IKE packets from any remote peer on UDP port 500:
tnsr# trace match ike
tnsr(config-trace-match)# udp
tnsr(config-trace-udp)# destination-port 500
tnsr(config-trace-udp)# exit
tnsr(config-trace-match)# exit
When starting the capture, add the filter
parameter at the end to activate
trace matching:
tnsr# trace capture node dpdk-input maximum 5 pre-clear filter
View a Trace¶
Trace results are stored in a temporary buffer in memory. To view the trace, use:
show trace [maximum <max>]
- maximum <max>:
The maximum number of packets to display from the trace
After viewing the results, the trace can be discarded by clearing the buffer
with trace clear
.