Packet Coloring

In this chapter

This chapter describes the packet coloring functionality, which enables tagging of captured frames with packet colors.

Color assignment

A color value can be assigned to each packet through the NTPL interface. Each NTPL filter can contribute to the final color value of a packet in different ways:

For each matching filter, the value of the Assign option ColorMask is bitwise OR'ed to the final color value.
For the highest priority matching filter, the value of the Assign option Color is bitwise OR'ed to the final color value.
For the highest priority matching filter with key tests, the value(s) of the KeyList option Color used when the key(s) were added is bitwise OR'ed to the final color value.

In this way, several matching filters can contribute to the final color of a packet. Each bit in the color value can be used to indicate a particular matching filter expression.

The ColorMask and Color options are mutually exclusive within the same filter.

The color value is defined as a 32-bit value, but for some descriptors, only part of the color value can be stored and retrieved:

The least significant 6 bits of the color value can be retrieved from packets with extended packet descriptor 9 using the NET_GET_PKT_COLOR macro.
The least significant 6 bits of the color value can be retrieved from packets with dynamic packet descriptor 1.
The least significant 6, 14 or 22 bits of the color value, or optionally the full color value, can be retrieved from packets with dynamic packet descriptor 2.
The full color value can be retrieved from packets with dynamic packet descriptor 3 (the least significant 14 bits from the color_lo field and the most significant 18 bits from the color_hi field).
The least significant 8 bits of the color value, or optionally the full color value, can be retrieved from packets with dynamic packet descriptor 4 (from the color0 field or the color1 field, respectively).

Example

This NTPL example sets up a filter that captures IPv4 frames and VLAN-encapsulated frames into stream 3 and gives them color 5:

Assign[StreamId=3; Color=5] = (Layer3Protocol == IPV4 OR Encapsulation == VLAN)

Overlapping filters using ColorMask

This NTPL example encodes combinations of layer 4 and layer 3 protocols in the color value:

Assign[ColorMask=0x20] = Layer4protocol==TCP
Assign[ColorMask=0x10] = Layer4protocol==UDP
Assign[ColorMask=0x08] = Layer3protocol==IPv6
Assign[ColorMask=0x04] = Layer3protocol==IPv4
Assign[StreamId=3] = All

Layer 4 and layer 3 protocols can be tested independently since the ColorMask is applied for each matching filter, regardless of priority.

Overlapping filters using Priority

If two overlapping filters, for instance an IP filter and a TCP filter, are defined (with two different color values), the packet color of frames matching both filters can be uniquely defined by assigning priorities to the filters (see DN-0449). If the TCP filter has a higher priority than the IP filter, the TCP color is returned to TCP/IP frames, and the IP color is returned for all other IP frames, for instance UDP/IP frames.

Illustration

This NTPL example captures UDP, TCP and IP frames using three different filters:

Assign[StreamId=1; Color=1; Priority=1] = Layer4Protocol == UDP
Assign[StreamId=1; Color=2; Priority=1] = Layer4Protocol == TCP
Assign[StreamId=1; Color=3; Priority=2] = Layer3Protocol == IP

This figure illustrates the example, where UDP frames, TCP frames and IP/ICMP frames are tagged with different packet colors.