Overview

Sequence numbers in protocols can be used for statistics such as gap detection and out of order packet counts. By default, these sequence numbers are tracked in the context of a stack stream (for example, a different set of sequence numbers for each source IP address / source UDP port / destination IP address / destination UDP port combination), but there may be occasions where this is incorrect. One possible case of this would be with line arbitration where only packets from one line are forwarded, but the line may switch at any time, causing a sequence number to potentially be shared over multiple stack streams. If the sequence number was tracked in the context of a single stack stream, a gap would be seen when the line switched.

To avoid this, configurable sequence number contexts can be defined for any protocol.

Detail

Datafields from the protocol with the configurable sequence number context (or any protocols before it) are used as keys to create an instance of a context. Each combination of datafield values will track an independent stream of sequence numbers.

The configurable sequence number context can be independent from the stack stream context, or be added to the stack stream context (in most cases this would be similar to adding ip.src_host, ip.src_port, ip.dst_host, ip.dst_port to the key datafields, but more efficient).

An expiration policy may be needed to prevent the number of contexts from growing out of control, where there may be many different combinations of values of the key datafields that are no longer useful after a while. Where the context is added to the stack stream context, it will expire at the same time as the stack stream, at the latest (e.g. when a TCP stream closes, or a stream has no activity for a while), and the policy applies to each stack stream individually (e.g. an expiration policy limiting the maximum number of contexts will be applied per stack stream context). An expiration policy should only be added if required, as it has an overhead.

The different types of expiration policies are described at https://beeks.atlassian.net/wiki/spaces/CFD/pages/6652104/Datafield+mapping#Cache-Expiration-Policies , although the configuration for them is described on this page.

Stack Configuration

Tables

sequence_handling

Parameter	Type	Required	Default	Description
key_df_list	list of strings	Y		A list of datafield names to use as keys to create the context.
add_to_stack_stream	boolean	Y		True if this context should be added to the stack stream context. False if this context should be unrelated to the stack stream.
expiration_policy_type	enum (`none`, `maximum_size`, `time`)	Y		Type of the expiration policy.
expiration_policy_maximum_size	uint64	N		Only valid when `expiration_policy_type` is `maximum_size`. The maximum number of contexts allowed.
expiration_policy_expiration_time_seconds	uint64	N		Only valid when `expiration_policy_type` is `time`. The length of time, in seconds, that a context is kept for when not used.
expiration_policy_timestamp	string	N	TIMESTAMP	Only valid when `expiration_policy_type` is `time`. The datafield name to use for the expiration.

Example

To define a sequence number context for an ACD configuration module that uses the datafield cboe_bzx.HdrUnitas the key to create the context (i.e. messages with the same value of cboe_bzx.HdrUnit have sequence numbers that are all part of the same sequence):

{
  "decACD": {
    "parameters": {
      "decoder_json_config": "cboe_bzx.acd.json"
    },
    "tables": {
      "sequence_handling": [
        {
          "key_df_list": [
            "cboe_bzx.Hdr_Unit",
          ],
          "add_to_stack_stream": false,
          "expiration_policy_type": "none"
        }
      ]
    }
  }
}