nfdump Filter Syntax Cheatsheet

cheatsheet.md

nfdump 1.8.x Filter Syntax Cheatsheet

This reference is derived from the 1.8.x filter grammar. Filters are supplied as the final nfdump argument or read from a file with -f filterfile.

nfdump -r flows 'proto tcp and dst port 443'
nfdump -r flows -f incident.filter

Quote filters containing shell metacharacters such as >, (, ), !, *, or +.

Fundamentals

Item	Details
Boolean operators	and / *, or / +, and not / !. and binds more tightly than or; use parentheses to group expressions.
Comparators	=, ==, <, >, <=, >=; word forms are EQ, LT, GT, LE, and GE. Omit the comparator for equality. != and NE are not filter operators.
Numbers	Decimal, hexadecimal (0x22), or decimal with K, M, G, or T multipliers (base 1000).
Case	All keywords are case-insensitive.
Strings	May be unquoted unless they collide with a keyword or contain shell/special characters. Quote strings with single or double quotes when in doubt.
Comments/includes	In filter files, # starts a comment. @include file inserts another filter file (maximum nesting depth: 10).
Aliases	cnt = count, host = ip, and xlate = nat.

Match-all, record, and exporter fields

Filter	Meaning	Example
any	Always true.	not (proto tcp) and any
ipv4, ipv6	Record has IPv4 or IPv6 flow addresses.	ipv6 and proto udp
ident string	File/source identifier matches exactly.	ident border-router
count comp number	Consecutive input-record number.	count > 1000
engine type comp number, engine-type comp number	Exporter engine type (0..255).	engine-type 9
engine id comp number, engine-id comp number	Exporter engine ID (0..255).	engine id = 2
exporter id comp number, exporter sysid comp number	nfdump exporter/sysid (0..65535).	exporter sysid 7

Addresses, networks, routing, geo, and time zones

ip, net, and geo accept the direction forms shown below. An unqualified form tests both source and destination where meaningful.

Filter	Meaning	Example
[src|dst] ip address	Flow endpoint address. host is an alias for ip. Host names are resolved at compile time.	src ip 192.0.2.10
[src|dst] ip tor	Endpoint is a Tor exit node; requires a Tor DB.	dst host tor
[src|dst] ip in [list]	Endpoint is in a space- or comma-separated IP/CIDR list.	src ip in [192.0.2.1, 2001:db8::/32]
[src|dst] net network/netbits	Endpoint is in an IPv4 or IPv6 CIDR network.	dst net 2001:db8:1::/48
[src|dst] net network netmask	Endpoint is in an IPv4 network with a dotted netmask.	src net 192.0.2.0 255.255.255.0
[src|dst] nat ip/net ...	Translated endpoint address/network. xlate is an alias for nat.	src nat net 198.51.100.0/24
[src|dst] tun ip/net ...	Tunnel endpoint address/network.	dst tun ip 2001:db8::1
next ip/net ...	IP routing next hop.	next net 192.0.2.0/24
bgp next ip/net ...	BGP next hop.	bgp next ip 192.0.2.254
router ip/net ...	Exporting router address.	router ip 198.51.100.2
[src|dst|tun|src tun|dst tun] geo CC	Two-letter MaxMind country code; requires a geoDB.	src geo CH
[src|dst] tz IANA-name	IANA time-zone name; requires a geoDB.	dst tz America/New_York

Protocol, ports, counters, and flow fields

Filter	Meaning	Example
proto protocol-or-number	IP protocol, such as tcp, udp, icmp, ipv6, gre, or a number.	proto tcp
tun proto protocol-or-number	Tunnel protocol.	tun proto gre
[src|dst] port comp number	Flow source/destination port.	dst port 443
[src|dst] nat port comp number	Translated source/destination port.	dst nat port 8443
[src|dst] port in [list]	Source/destination port in a numeric list.	port in [53, 80, 443]
icmp type comp number, icmp code comp number	ICMP/ICMPv6 type or code; implies ICMP protocol.	icmp type 8
[in|out] packets comp number	Inbound or reverse-flow packet counter. No qualifier means inbound.	out packets > 10K
[in|out] bytes comp number	Inbound or reverse-flow byte counter. No qualifier means inbound.	bytes > 1G
flows comp number	Flow counter, including aggregation count.	flows >= 10
duration comp milliseconds	Calculated flow duration in milliseconds.	duration > 5000
pps, bps, bpp	Calculated inbound packets/s, bits/s, or bytes/packet.	bps > 100M
[src|dst] tos comp number	Source/destination ToS value (0..255).	dst tos 46
[in|out] if number	Input/output interface number.	in if 12
[src|dst] vlan number	Source/destination VLAN.	src vlan 100
[src|dst] mask number	Source/destination network-mask field.	dst mask 24
flowdir 0|1, flowdir ingress|egress	Flow direction.	flowdir ingress
etherType number	Layer-2 EtherType.	etherType 0x86dd
fwdstat comp number, fwdstat name	Forwarding status. Names include Ukwn, Forw, Frag, Drop, DaclD, Daclp, Noroute, Dadj, Dfrag, Dbadh, Dbadtlen, Dbadhlen, DbadTTL, Dpolicy, Dwred, Drpf, Dforus, DbadOf, Dhw, Term, Tadj, TincAdj, and Tforus.	fwdstat Drop

AS, TTL, TCP flags, MPLS, and MAC addresses

Filter	Meaning	Example
[src|dst|prev|next] as comp number	Source, destination, previous-adjacent, or next-adjacent AS.	next as 64512
[src|dst|prev|next] as in [list]	AS is in a numeric list.	src as in [64512, 64513]
ttl comp number, min ttl comp number, max ttl comp number	Any, minimum, or maximum IP TTL.	min ttl < 4
ttl equal	Minimum and maximum TTL are equal.	ttl equal
flags flag-string, flags comp number	TCP flags. String letters: F, S, R, P, A, U, E, C; X means all of F/S/R/P/A/U. Prefix the string with = for an exact mask.	flags S and not flags AFRPU
mpls labelN comp number	MPLS label number N.	mpls label2 = 16000
mpls expN comp number	Experimental bits of MPLS label N.	mpls exp1 = 5
mpls eos comp number	End-of-stack MPLS label.	mpls eos = 16
mpls any comp number	Any MPLS label in the stack.	mpls any 16000
mac address	Any MAC address in the record.	mac 00:11:22:33:44:55
in|out [src|dst] mac address	Selected input/output source/destination MAC address.	in src mac 00:11:22:33:44:55

Time, observation, VRF, and latency

Filter	Meaning	Example
first seen comp ISO-8601, last seen comp ISO-8601	First/last flow timestamp. Partial ISO-8601 values are expanded; milliseconds are supported.	first seen >= 2026-01-01T00:00
observation domain id comp number	IPFIX observation domain ID.	observation domain id 42
observation point id comp number	IPFIX observation point ID.	observation point id 7
ingress vrf comp number, egress vrf comp number	Ingress/egress VRF ID.	ingress vrf 10
client latency comp milliseconds, server latency comp milliseconds	nprobe/IPFIX client or server network latency.	client latency > 100

Payload filters

Payload filters apply only when payload is present in the flow record. dns may be prefixed with in or out; content and regex test the record payload data.

Filter	Meaning	Example
payload content string	Case-sensitive byte-string search.	payload content 'GET /'
payload regex regex [flags]	PCRE2 match over the complete payload length.	payload regex 'GET /.+HTTP/1\\.1' i
[in|out] payload dns defined	Valid DNS query/answer payload.	in payload dns defined
[in|out] payload dns name string	DNS query name contains a string.	payload dns name example
[in|out] payload dns address|addr string	DNS answer/additional address contains a string.	payload dns addr '192.0.2.'
payload ssl defined	Valid SSL/TLS handshake.	payload ssl defined
payload ssl version version	SSL 1.0, 2.0, or 3.0.	payload ssl version 3.0
payload tls version version	TLS 1.0, 1.1, 1.2, or 1.3.	payload tls version 1.3
payload ssl|tls sni string	TLS SNI contains a string.	payload tls sni example.org
payload ja3 defined, payload ja3 md5	JA3 available or equals an MD5 hash.	payload ja3 defined
payload ja4 defined, payload ja4 hash	JA4 available or equals a JA4 hash.	payload ja4 t13d1516h2_8daaf6152771_b186095e22b6
payload ja4s hash	JA4 server fingerprint; requires a build with JA4 server support.	payload ja4s t130400_c030_1b122d51bd39

PCRE2 regex details

payload regex requires a build with PCRE2; without it the filter fails to compile. Matching is binary-safe: it uses the stored payload length, so embedded NUL bytes do not truncate the subject. The syntax is PCRE2/Perl-compatible, not the former reduced matcher syntax. Useful constructs include groups (...) and (?:...), alternation |, anchors ^/$, classes [...], quantifiers ?, *, +, {n,m}, lazy quantifiers, and escapes such as \\d, \\w, \\s, \\r, \\n, and \\xHH for a raw byte. Flags are separate optional arguments: i (case-insensitive), m (multiline anchors), and s (dot matches newlines). See https://www.pcre.org/current/doc/html/pcre2syntax.html.

To bound pathological expressions, each worker limits a match to 500,000 match operations, 512 KiB PCRE2 heap, and depth 10,000; JIT stacks range from 32 KiB to 512 KiB. A limit hit makes that payload fail the regex test.

NSEL, NAT, and pflog filters

Filter	Meaning	Example
asa event event-or-number	ASA/NSEL event (ignore, create, term, delete, deny) or number.	asa event deny
asa denied reason	ASA extended denial reason, such as ingress, egress, interface, or nosyn.	asa denied nosyn
asa xevent comp number	ASA extended event value.	asa xevent > 0
asa user string	ASA user name matches exactly.	asa user alice
nat event add|delete, nat event comp number	NAT/NEL event.	nat event add
[src|dst] nat ip/net ...	NAT translated address/network.	dst nat ip 203.0.113.5
[src|dst] nat port comp number	NAT translated port.	src nat port 50000
nat pblock start|end|step|size comp number	NAT port-block property.	nat pblock size = 64
[src|dst] port in nat pblock	Flow port is within its NAT port block.	dst port in nat pblock
ingress acl comp number, egress acl comp number	NSEL ACL/ACE/XACE value.	ingress acl 101
pf action action	pflog action.	pf action block
pf reason reason	pflog reason.	pf reason state-limit
pf rule comp number	pflog rule number.	pf rule >= 100
pf dir in|out, pf interface string	pflog direction or interface name.	pf interface em0

Examples

# TCP services exposed to the Internet
nfdump -r flows 'proto tcp and dst port in [22, 80, 443] and not dst net 10.0.0.0/8'

# Large HTTPS flows with a selected TLS SNI
nfdump -r flows 'proto tcp and port 443 and bytes > 100M and payload tls sni example.org'

# Embedded binary HTTP request marker; \x00 is a raw NUL byte in the regex subject
nfdump -r flows "payload regex 'GET\\x00/.*HTTP/1\\.1' s"

# Flow time window and source-country restriction
nfdump -r flows 'first seen >= 2026-01-01 and first seen < 2026-02-01 and src geo CH'

Version 1.8.x

Resources:

• https://github.com/phaag/nfdump
• nfdump(1)
• https://www.pcre.org/current/doc/html/pcre2syntax.html