KeyList Command

Reference Documentation

Intel® PAC
Napatech SmartNIC
Content Type
Reference Information
Capture Software Version
Link™ Capture Software 12.10
Napatech Software Suite: KeyList Command

This section specifies the syntax and semantics for the KeyList command.

Supported Options Per Feature Set

Supported Feature Sets

The syntax for the KeyList command is shown below:

<KeyListDef>        ::= 'KeyList' '[' <KeyListOptionSpec> ']' '=' <KeyDataSpec>
<KeyListOptionSpec> ::= <KeyListOption> [ ';' <KeyListOptionSpec> ]
<KeyListOption>     ::= ( 'KeySet' '=' <KeySetId> ) |
                        ( 'Color' '=' <32-bit value> ) |
                        ( 'StreamId' '=' <7-bit value> ) |
                        ( 'KeyType' '=' <Identifier> ) |
                        ( 'Tag' '=' <Identifier> )
<KeyDataSpec>       ::= '(' <KeyData> [ ';' 'Color' '=' <32-bit value> ] [ ';' 'StreamId' '=' <8-bit value> ]')' [ ',' <KeyDataSpec> ]
<KeyData>           ::= <IPv4AddrValue> | <IPv6AddrValue> | <KeyValue> |
                        '{' <IPv4AddrMask> ':' <Ipv4AddrValue> '}' |
                        '{' <IPv6AddrMask> ':' <Ipv6AddrValue> '}' |
                        '{' <KeyValue> ':' <KeyValue> '}' |
                        '(' <IPv4AddrValue> '..' <IPv4AddrValue> ')' |
                        '(' <IPv6AddrValue> '..' <IPv6AddrValue> ')' |
                        '(' <KeyValue> '..' <KeyValue> ')'
<KeyValue>          ::= <HexString> | <BinaryString> | <32-bit decimal value>

The KeyList command is used to add keys to the key database much like the legacy IPMatchList command is used to add ip addresses. The KeyList command takes the following options:

  • KeyType: The name of the key type the key(s) belong to.
  • KeySet: The KeySet the key(s) should be tagged with.
  • Color: The color to be added to the key(s) if the key type supports color information.
  • StreamId: The stream to be added to the key(s) if the key type supports color information.
  • Port: A port or port range used to control which adapters the key is added to.

The "KeySet" parameter is a number between 3 and 15. It functions as a tag that is used in filter expressions when matching keys. A key is only tagged with one key set value, but several keys in a key type may be tagged with different key set values. However once a key set is used in elements of a key type (in keys or through filter expressions) that key set value cannot be used in other key types.

The "Color" parameter can only be used if the associated key type has been configured with "ColorInfo=True". When a packet matches a key with color information attached to it, that color is transferred to the packet descriptor before it is sent to the host computer. This can be used to identify which "flow" a packet belongs to if one views the color as a sort of "flow id".

The "StreamId" parameter can only be used if the associated key type has been configured with "StreamInfo=True". When a packet matches a key with stream information in it and the matching filter has been configured to do so (see Key Tests), the packet is routed to the stream specified with the StreamId parameter. It should be noted that when the StreamId option is used, a hostbuffer is allocated. This might lead to a hostbuffer shortage on adapters that that do not use the key matching feature so the "Port" option should be used to avoid programming the key on those adapters.

For a description of the 'Tag' option please refer to Tag Option.

Several keys can be programmed in one KeyList command and for each key, the color and stream specified in the options apply to all those keys. The color and/or stream can however be overridden in the individual keys as shown in the examples below.

Masks are supported on key fields, but it should be noted that when using masks on keys, a separate memory area in the key database is used and its capacity is limited compared to non-masked keys.

Ranges are supported but only for keys types with one field and only one range can be programmed per KeyList command.


This section presents various examples of using the KeyList command to add keys to the key database. First a couple of key type are defined:

KeyType[Name=MyKT1] = {128, 32, 16}
KeyType[Name=MyKT2; ColorInfo=True; StreamInfo=True] = {128, 32, 16}

Note that the key type "MyKT2" supports color and stream information. Before keys can be added the key types must have at least one key definition attached to them:

KeyDef[Name=MyKD1; KeyType=MyKT1] = (Layer3Header[8]/128, InnerLayer3Header[12]/32, InnerLayer4Header[0]/16)
KeyDef[Name=MyKD2; KeyType=MyKT2] = (Layer3Header[8]/128, InnerLayer3Header[12]/32, InnerLayer4Header[0]/16)

Keys can now be added:

KeyList[KeyType=MyKT1; KeySet=3] = ([0:0:0:0:0:0:0:1], 0x123, 80), ([0:0:0:0:0:0:0:2], 0x1234, 8080)
KeyList[KeyType=MyKT1; KeySet=3] = (0x123456789abcdef0123456789abcdef0, [], 0x50)
KeyList[KeyType=MyKT1; KeySet=3] = (0x12345, {[ff.ff.00.00]:[]}, 'b1011001001101)

Note that in the first line two keys are added in one KeyList command. In the last line a masked key has been added as the middle field is formatted with a mask. These examples show that it is possible to enter data in a variety of ways (ipv4 addresses, ipv6 addresses, hexadecimal and decimal numbers as well as binary numbers). The next lines show how to add keys with color/stream information:

KeyList[KeyType=MyKT2; KeySet=4; Color=12; StreamId=30] = ([0:0:0:0:0:0:0:1], 0x123, 80), ([0:0:0:0:0:0:0:2], 0x1234, 8080)
KeyList[KeyType=MyKT2; KeySet=4; Color=12; StreamId=30] = ([0:0:0:0:0:0:0:3], 0x321, 22;StreamId=5),([0:0:0:0:0:0:0:4], 0x4321, 808;Color=20;StreamId=2)

In the first line the color and stream is set on both keys in the list. In the second line two keys are also entered, but in this case the stream and/or color is overridden in the individual keys.