Configuration Guide for VMX-Capture

We introduced the filter section earlier in this document in Stack Probe: Packet Filtering and Decoding. Every stack probe needs a filter section defined, even if that section is blank.

From version 13.1 of Beeks Analytics, we have supplemented the basic BPF syntax with a filter module that provides the user with more control over the traffic that is being processed by the stack probe.

Basic BPF

The simplest packet filter configuration is to directly specify an inline BPF expression in the main probe configuration.

{
  "probe": {
    "parameters": {
      "name": "Inline BPF",
      "filter": "tcp dst port 12345",
      "protocols": [
        {
          "type": "module",
          "value": "ethernet"
        }
      ]
    }
  }
}

Filter Modules

Filter modules provide a pluggable system to create new types of packet filters. This pluggable system offers more flexibility than the straightforward BPF filter. Stack configuration parameters for filter modules can be found with the get_config_params utility with the prefix pkt_filter_.

BPF Filter Module

This filter module provides for more advanced BPF configuration.

Parameters

Parameter	Type	Required	Default	Description
bpf_expression	string	N		BPF expression
linktype	string	N	DLT_EN10MB	Linktype for BPF filter
snaplen	int	N	65535	Maximum amount of packet data captured, to pass to the BPF compiler
netmask	string	N		Broadcast netmask, to pass to the BPF compiler

$ /opt/tsa/bin/get_config_params pkt_filter_bpf
pkt_filter_bpf  bpf_expression      longstring   false  BPF expression
pkt_filter_bpf  linktype            Enum<DLT_A429,DLT_A653_ICM,....,DLT_ZWAVE_R3> false  Linktype for BPF filter
pkt_filter_bpf  snaplen             int          false  Maximum amount of packet data captured, to pass to the BPF compiler
pkt_filter_bpf  netmask             string       false  Broadcast netmask, to pass to the BPF compiler

Changing linktype can be useful if running a vpmux with GRE, where there may not be an ethernet header, in which case you could use DLT_IPv4 or DLT_RAW (auto-detect IP version). Link types are described at https://www.tcpdump.org/linktypes.html .

It may not be useful to change snaplen, which is a parameter passed when compiling the BPF expression and indicates the maximum length of the captured packet.

netmask is only useful when using the “broadcast” keyword in bpf_expression. It is simplest to specify this as a hex netmask, e.g. “0xffffff00” for a 24 bit netmask.

Example

{
  "probe": {
    "parameters": {
      "name": "All BPF config",
      "filter_module": {
        "type": "module",
        "value": "bpf",
        "id": "pktFilterBPF"
      },
      "protocols": [
        {
          "type": "module",
          "value": "ethernet"
        } 
      ]   
    }   
  },  
  "pktFilterBPF": {
    "parameters": {
      "bpf_expression": "tcp dst port 12345",
      "linktype": "DLT_EN10MB",
      "netmask": "0xffffff00"
    }
  }
}

VLAN BPF Filter Module

This filter module provides ethernet header parsing and simpler VLAN configuration as well as BPF.

Specifying the VLANs in a separate filter module allows for simpler maintenance of the configuration for BPF syntax, especially in setups that require complex VLAN stacking or asymmetric VLAN tagging.

Parameters

Parameter	Type	Required	Default	Description
bpf_expression	string	N		BPF expression
linktype	string	N	DLT_EN10MB	Linktype for BPF filter
snaplen	int	N	65535	Maximum amount of packet data captured, to pass to the BPF compiler
netmask	string	N		Broadcast netmask, to pass to the BPF compiler
skip_ethernet_layer	bool	N		True: Skip the ethernet layer and don’t pass it to the BPF expression. Else False.

$ /opt/tsa/bin/get_config_params pkt_filter_vlan_bpf
pkt_filter_vlan_bpf bpf_expression      longstring   false  BPF expression
pkt_filter_vlan_bpf linktype            Enum<DLT_A429,DLT_A653_ICM,.....,DLT_ZWAVE_R3> false  Linktype for BPF filter
pkt_filter_vlan_bpf snaplen             int          false  Maximum amount of packet data captured, to pass to the BPF compiler
pkt_filter_vlan_bpf netmask             string       false  Broadcast netmask, to pass to the BPF compiler
pkt_filter_vlan_bpf vlan_id_matches     table
pkt_filter_vlan_bpf skip_ethernet_layer bool         false  True to skip the ethernet layer and not pass it to the BPF expression, else false

Many parameters are shared from the BPF Filter Module.

Use skip_ethernet_layer to tell the filter how to pass data to the BPF, i.e., whether to pass data from the beginning of the packet (skip_ethernet_layer = false) or to parse the ethernet layer and only pass data from the next layer (skip_ethernet_layer = true). If this value is true, linktype defaults to DLT_RAW (which assumes an IP packet). This can be used to avoid having to specify multiple combinations of “vlan” and the expression in bpf_expression or for parsing ethertypes not supported by BPF, such as the Arista timestamping ethertype.

Tables

vlan_id_matches

Parameter	Type	Required	Default	Description
vlan_id_match	string list	Y		List of VLAN IDs, ? for any single VLAN

$ /opt/tsa/bin/get_config_params pkt_filter_vlan_bpf table
%begin_table_def pkt_filter_vlan_bpf vlan_id_matches false
vlan_id_match List<string> true   List of VLAN IDs, ? for any single VLAN
%end_table_def

vlan_id_matches allows you to specify lists of VLAN IDs and wildcards that will pass the filter. E.g., an empty VLAN ID list [] will only pass a packet with no VLANs, a VLAN list with [“12”, “?”] will pass packets with exactly 2 VLAN IDs, the first being 12 and the next being any value. When specified, skip_ethernet_layer defaults to true (which avoids having to provide the vlan specification additionally in the bpf filter).

Example

{
  "probe": {
    "parameters": {
      "name": "All VLAN BPF config",
      "filter_module": {
        "type": "module",
        "value": "vlan_bpf",
        "id": "pktFilterVLANBPF"
      },
      "protocols": [
        {
          "type": "module",
          "value": "ethernet"
        }
      ]
    }
  },
  "pktFilterVLANBPF": {
    "parameters": {
      "bpf_expression": "tcp dst port 12345",
      "linktype": "DLT_RAW",
      "netmask": "0xffffff00",
      "skip_ethernet_layer": true
    },
    "tables": {
      "vlan_id_matches": [
        {
          "vlan_id_match": [
            "12",
            "?"
          ]
        },
        {
          "vlan_id_match": []
        }
      ]
    }
  }
}