Tip

This is the documentation for the 24.06 version. Looking for the documentation of the latest version? Have a look here.

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 is dpdk-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 the maximum value on the filter. The filter will restrict matches within the total packets traced. If the trace capture maximum is too low, the filter can never reach its own maximum 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 to 0xffff.

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) and more-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.