Knowledge base:
Cheatsheet BPF filters
Posted by Pieter Vandercammen, Last modified by Pieter Vandercammen on 03 August 2021 06:38 PM

This article collects a number of example BPF filters. The filters are grouped by the OSI layer.

These BPF filters are used throughout the ByteBlower API.

Layer 3 Network: IP, IP6, ARP, ...

Example Description
ip Captures all TCP traffic regardless of lower layers transport layers
ip6 Selects all IP6 traffic. This is not a default filter but has been added to ByteBlower.
arp Capture only traffic over IP
icmp All ICMP traffic.
igmp Multicast traffic

Layer 4 Transport: TCP and UDP

This is the transport layer, ByteBlower supports the two major families: TCP and UDP. Both protocols can be used over IPv4 or IPv6. The network layer doesn't need to be mentioned explicitly in the filter.

In the examples below we'll use tcp by default, but the last 3 example filters can also be used with udp.

Example Description
tcp Captures all TCP traffic regardless of lower layers transport layers
udp Same as above, but for UDP
ip and tcp Capture only traffic over IP
ip6 and tcp Selects for ip6 and TCP. This not a default BPF filter.
(ip or ip6) and tcp Same behavior as the first filter. This line is only included as an example, prefer to use the first one.

Filter on ports

Both TCP and UDP use ports. In the examples below, the filters are shown for both protocols.

TCP UDP Description
tcp port 80 udp port 80 Captures all traffic from or to port 80. Both directions are collected.
This mainly useful for TCP.
tcp src port 80 udp src port 80 Capture only traffic transmitted from port 80.
tcp dst port 80 udp dst port 80 The inverse of the one above, captures all traffic with port 80 as destination

Filter on TCP flags

The filters below are TCP specific. They filter on specific flags. This makes the following filters very useful to capture only the start of traffic, the end or any abnormal behavior.

This type of filters use the array operators of BPF. The filter tcp[13:1] fetches a single byte at offset 13; i.e. the fourteenth byte of the TCP header. This can be written even easier using the tcpflags shorthand. That is used most heavily in the filters below.

Other shorthands are those for those to select the individual bits of the tcp-flags: tcp-fin (= 0x01),

  • tcp-fin, with value 0x01
  • tcp-syn, 0x02
  • tcp-rst, 0x04
  • tcp-push, 0x08
  • tcp-ack, 0x10
  • tcp-urg, 0x20

The BPF syntax has no such definitions for the slightly newer TCP flags: ECE (0x40), CWR (0x80) and NS (0x100). These flags are related Congestion Notification (rfc3168, rfc3540). Especially this last one poses a challenge, it's the final example in the list below.

TCP Description
tcp[tcpflags] == tcp-syn Selects the initial  SYN packet. This is the initiation of the session by the TCP client.
tcp[tcpflags] == (tcp-syn + tcp-ack) This SYN+ACK response from the TCP server.
(tcp[tcpflags] & tcp-syn) > 0 All packets with the SYN flag enabled. This filter matches the traffic of the above two.
This filter uses the bitwise and operator ('&') to select the the Syn bit out of the TCP flags.
(tcp[tcpflags] & tcp-fin) > 0 All packets with a Fin flag. Similar to the filter directly above, this also selects packets with Fin + Ack.
tcp[tcpflags] == tcp-rst Selects all TCP Resets
(tcp[tcpflags] & tcp-fin) > 0 All packets with a Fin flag.
(tcp[tcpflags] & 0x40)  > 0 This filters captures all packets with the ECE flag enabled. Both the initial negation is thus captured, as well as a TCP session echoing congestion on the network.
(tcp[tcpflags] & (0x40 + tcp-syn))  == (0x40 + tcp-syn) Like the above, this filter selects packets with ECE flag enabled. Extra in this filter is to only select the initial handshake. This is done by adding the tcp-syn value.
In other words, this filters all session that capable to react to Explicit Congestion Notifications.
(tcp[tcpflags] & (0x40 + tcp-syn))  == 0x40 The filter is the inverse of the above. It also packets with the ECE flags but also requires for these packets to have the tcp-syn flag disabled.
This filters thus on actual cases where the session reactes to an explicit congestion notification.
(tcp[12:2] & 0x100) > 0 As promised, in the last filter the NS flag, or ECN-nonce is used.
This flags is experimental, and makes the filter much complex.

The NS flag has value 0x100, this larger the usual single byte for the TCP flags.

As a result, 12:2 is used instead of tcpflags. This expression selects 2 bytes at an offset of 12 bytes in the TCP header.

The remainder of this BPF filter is similar to the above.

(0 vote(s))
Helpful
Not helpful

Comments (0)

We to help you!