KeyDef Command

Reference Documentation

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

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

Supported Options Per Feature Set

Supported Feature Sets
N-ANL4 N-ANL5
N-ANL6
N-ANL7
N-ANL8
N-ANL9
N-ANL10
  X X
Options Bit-level Masks     X

The syntax for the KeyDef command is shown below:

<KeyDef>             ::= 'KeyDef' '[' <KeyOptionSpec> ']' '=' '(' <ProtocolFieldSpec> ')’
<KeyOptionSpec>      ::= <KeyOption> [ ';' <keyOptions> ]
<KeyOption>          ::= ( 'Name' '=' <Identifier> ) |
                         ( 'KeyType' '=' <Identifier> ) |
                         ( 'IpProtocolField' '=' <IpProtocolFieldExtraction> ) |
                         ( 'KeySort' '=' <KeySorting> ) |
                         ( 'Tag' '=' <Identifier> )
<IpProtocolFieldExtraction> ::= 'Outer' | 'Inner' | 'None'
<KeySorting>         ::= 'Sorted' | 'None'
<ProtocolFieldSpec>  ::= [ <Mask> ':' ] <ProtocolField8> [ ',’ <ProtocolFieldSpec> ]
<Mask>               ::= <HexString> | <BinaryString>

KeyType command is used for both the Key matcher functionality and Flow matcher functionality; the sections below will specify the similarities and differences.

The KeyDef command instantiates a key definition from a key type. A key definition specifies how keys programmed into the hardware map to fields in a packet.

Key matcher

  • Name: The name for the key definition.
  • KeyType: The name of the key type the key definition instantiates.
  • IpProtocolField: N/A
  • KeySort: N/A
  • Tag: For a description of the 'Tag' option please refer to Tag Option.

Flow matcher

  • Name: The name for the key definition.
  • KeyType: The name of the key type the key definition instantiates.
  • IpProtocolField: IP protocol field extraction used with flow matching.
  • KeySort: Enable/disable sorting of protocol fields.
  • Tag: For a description of the 'Tag' option please refer to Tag Option.

Description of options and fields

Name option

The name option is mandatory and must be a unique name for every key definition. The Key Test uses the name as reference to a specific key definition.

KeyType option

The name of a previously defined key type to be used for this key definition (see KeyType Command). The number of right-hand side fields in this key definition must match the number of fields in the key type.

IpProtocolField option

Flow Matcher keys include an 8 bit IP protocol field. The IpProtocolField option specifies whether the IP protocol field shall be extracted from the outer or inner IP protocol field of the received packets. When set to None no extraction will be performed. Instead the 8 bit IP protocol field of the key will be all-zeros.

KeySort option

The KeySort option specifies whether the protocol fields shall be sorted before key look-up. The sorting is based on the numerical value of the first two protocol fields. If the numerical value of the first protocol field of an incoming packet is greater than the numerical value of the second protocol field, the fields will be swapped before key look-up. This implies that Flow Stream learn-records must be programmed with the lesser numerical value first.

Protocol field sorting is especially useful in span-port use cases where upstream and down stream packets are received on the same port (see IP flows in span port configuration - key sorting). Applying sorting in such use cases enables the adapter to distinguish packets from the two directions and thereby enables statistics per flow direction and automatic termination of TCP flows.

Protocol field sorting is enabled by the KeySort option, i.e. KeySort=Sorted.

When protocol field sorting is enabled special restriction on protocol field selection applies.

  • The number of protocol fields must be 2 or 3 or 4
  • The first two protocol fields must have the same size
  • When 3 protocol fields are used, the size of the third field may not exceed 32
  • When 4 protocol fields are used, the size of the third field and fourth field must be 16. Further, the two fields must be consecutive.

Notice: When 4 protocol fields are used and the comparison of the first and second field results in a swap before key look-up, the third and fourth field will also be swapped before the look-up.

The example below shows a configuration of a 5-tuple look-up on IPv4 packets.

keytype[name=ktflow] = {32, 32, 16, 16}
keydef[name=kdflow;keytype=ktflow;prot=outer;keysort=sorted] = (layer3header[12]/32, layer3header[16]/32, layer4header[0]/16,layer4header[2]/16)
assign[streamid=42] = layer3protocol == ipv4 and key(kdflow,KeyID=1) == 4

The IP addresses, L4 protocol and L4 port values to be matched are programmed using FlowWrite on a Flow Stream.

Protocol field specification option

The right-hand side of the command is a list of protocol fields to be extracted from a received packet and used when matching against keys. The fields can be prepended with an optional mask that can be used to ignore certain parts of keys when matching. If the width of a field (the number after the "/") is shorter than the one specified in the key type, a mask is implicitly constructed to ignore the remaining bits of that field in the keys. Consider for example the following key type:

KeyType[Name=MyKT] = {32}

The following two key definitions are equivalent:

KeyDef[Name=MyKD; KeyType=MyKt] = ( {0xFFFF0000:Layer3Header[12]/32} )
KeyDef[Name=MyKD; KeyType=MyKt] = (Layer3Header[12]/16)

When the field width is smaller than the key type width (implicit mask) and an explicit mask is also specified, the explicit mask applies to the smaller field size:

KeyType[Name=MyKT] = {32}

The following two key definitions are equivalent:

KeyDef[Name=MyKD; KeyType=MyKt] = ( {0xF00F0000:Layer3Header[12]/32} )
KeyDef[Name=MyKD; KeyType=MyKt] = (0xF00F:Layer3Header[12]/16)

The following key definition will throw an error because the explicit mask is wider than the field:

KeyDef[Name=MyKD; KeyType=MyKt] = ( {0xFFFF0000:Layer3Header[12]/24} )

When using a mask on a key definition, whether it be implicit or explicit, it is important to set the ignored bits of the keys (entered with the KeyList command) to zero, as the mask is only applied to the key definition and not the stored keys. E.g. the following will not work:

KeyType[Name=MyKT] = {32}
KeyDef[Name=MyKD; KeyType=MyKt] = ( {0xFFFF0000:Layer3Header[12]/32} )
KeyList[KeyType=MyKT; KeySet=8] = ([192.168.1.1])

The two lower bytes are masked out in the key definition, so when entering the key, the lower two bytes shall also be zero, i.e. the correct way of entering the key would be:

KeyList[KeyType=MyKT; KeySet=8] = ([192.168.0.0])

All key definitions of a key type must be instantiated before either adding keys on the key type using the KeyList command or using key definitions in a filter (see Key Tests). Once either of these has taken place it is no longer possible to add more key definitions on that key type.

Key matcher - Examples

The following example shows how to create two key definitions that can be used to match flows based on source and destination ip addresses. First a key type is defined:

KeyType[Name=MyKT; Access=Full] = {32, 32}

In this example it is assumed that up- and down-link traffic is received on the same port on the adapter. It will therefore be necessary to do two accesses to the key database per received packet: one normal access (uplink) and one where the two 32 bit fields are swapped (downlink). Because of this "multi access per packet" the key type must be configured with "Access=Full" as explained in the key type documentation. The up- and down-link key definitions can now be created:

KeyDef[Name=UpLink; KeyType=MyKT] = (Layer3Header[12]/32, Layer3Header[16]/32)
KeyDef[Name=DownLink; KeyType=MyKT] = (Layer3Header[16]/32, Layer3Header[12]/32)

Two keys definitions have been instantiated. These can now be used in a filter expression:

Assign[StreamId=0] = Layer3Protocol == IPv4 and (Key(UpLink) == 3 OR Key(DownLink) == 3)

Keys can be added to the database as follows:

KeyList[KeyType=MyKT; KeySet=3] = ([192.168.1.3], [172.16.20.2])

The KeyList command is documented in the KeyList section and the filtering component of the key matcher is documented in the Key Tests section along with more examples.

Flow matcher matcher - Examples

See Flow matcher feature for examples and flowmatch/flowmatch_example_main.cpp for a C++ code example.