Note: this document has been drawn from the tcpdump man page. The original version can be found at www.tcpdump.org.
pcap_compile() is used to compile a string into a filter program. The resulting filter program can then be applied to some stream of packets to determine which packets will be supplied to pcap_loop(), pcap_dispatch(), pcap_next(), or pcap_next_ex().
The filter expression consists of one or more primitives. Primitives usually consist of an id (name or number) preceded by one or more qualifiers. There are three different kinds of qualifier:
[`fddi' is actually an alias for `ether'; the parser treats them identically as meaning ``the data link level used on the specified network interface.'' FDDI headers contain Ethernet-like source and destination addresses, and often contain Ethernet-like packet types, so you can filter on these FDDI fields just as with the analogous Ethernet fields. FDDI headers also contain other fields, but you cannot name them explicitly in a filter expression.
Similarly, `tr' and `wlan' are aliases for `ether'; the previous paragraph's statements about FDDI headers also apply to Token Ring and 802.11 wireless LAN headers. For 802.11 headers, the destination address is the DA field and the source address is the SA field; the BSSID, RA, and TA fields aren't tested.]
In addition to the above, there are some special `primitive' keywords that don't follow the pattern: gateway, broadcast, less, greater and arithmetic expressions. All of these are described below.
More complex filter expressions are built up by using the words and, or and not to combine primitives. E.g., `host foo and not port ftp and not port ftp-data'. To save typing, identical qualifier lists can be omitted. E.g., `tcp dst port ftp or ftp-data or domain' is exactly the same as `tcp dst port ftp or tcp dst port ftp-data or tcp dst port domain'.
Allowable primitives are:
ip host hostwhich is equivalent to:
ether proto \ip and host hostIf host is a name with multiple IP addresses, each address will be checked for a match.
ether host ehost and not host hostwhich can be used with either names or numbers for host / ehost.) This syntax does not work in IPv6-enabled configuration at this moment.
tcp src port portwhich matches only tcp packets whose source port is port.
len <= length.
len >= length.
proto pwhere p is one of the above protocols.
ip6 protochain 6matches any IPv6 packet with TCP protocol header in the protocol header chain. The packet may contain, for example, authentication header, routing header, or hop-by-hop option header, between IPv6 header and TCP header. The BPF code emitted by this primitive is complex and cannot be optimized by the BPF optimizer code, and is not supported by filter engines in the kernel, so this can be somewhat slow, and may cause more packets to be dropped.
ether proto pwhere p is one of the above protocols.
ether proto pwhere p is one of the above protocols. Note that not all applications using pcap(3PCAP) currently know how to parse these protocols.
vlan 100 && vlan 200filters on VLAN 200 encapsulated within VLAN 100, and
vlan && vlan 300 && ipfilters IPv4 protocols encapsulated in VLAN 300 encapsulated within any higher order VLAN.
mpls 100000 && mpls 1024filters packets with an outer label of 100000 and an inner label of 1024, and
mpls && mpls 1024 && host 192.9.200.1filters packets to or from 192.9.200.1 with an inner label of 1024 and any outer label.
pppoes 0x27 && ipfilters IPv4 protocols encapsulated in PPPoE session id 0x27.
geneve 0xb && ipfilters IPv4 protocols encapsulated in Geneve with VNI 0xb. This will match both IP directly encapsulated in Geneve as well as IP contained inside an Ethernet frame.
iso proto pwhere p is one of the above protocols.
proto [ expr : size ]Proto is one of ether, fddi, tr, wlan, ppp, slip, link, ip, arp, rarp, tcp, udp, icmp, ip6 or radio, and indicates the protocol layer for the index operation. (ether, fddi, wlan, tr, ppp, slip and link all refer to the link layer. radio refers to the "radio header" added to some 802.11 captures.) Note that tcp, udp and other upper-layer protocol types only apply to IPv4, not IPv6 (this will be fixed in the future). The byte offset, relative to the indicated protocol layer, is given by expr. Size is optional and indicates the number of bytes in the field of interest; it can be either one, two, or four, and defaults to one. The length operator, indicated by the keyword len, gives the length of the packet.
For example, `ether[0] & 1 != 0' catches all multicast traffic. The expression `ip[0] & 0xf != 5' catches all IPv4 packets with options. The expression `ip[6:2] & 0x1fff = 0' catches only unfragmented IPv4 datagrams and frag zero of fragmented IPv4 datagrams. This check is implicitly applied to the tcp and udp index operations. For instance, tcp[0] always means the first byte of the TCP header, and never means the first byte of an intervening fragment.
Some offsets and field values may be expressed as names rather than as numeric values. The following protocol header field offsets are available: icmptype (ICMP type field), icmp6type (ICMP v6 type field) icmpcode (ICMP code field), icmp6code (ICMP v6 code field), and tcpflags (TCP flags field).
The following ICMP type field values are available: icmp-echoreply, icmp-unreach, icmp-sourcequench, icmp-redirect, icmp-echo, icmp-routeradvert, icmp-routersolicit, icmp-timxceed, icmp-paramprob, icmp-tstamp, icmp-tstampreply, icmp-ireq, icmp-ireqreply, icmp-maskreq, icmp-maskreply.
The following ICMPv6 type fields are available: icmp6-echo, icmp6-echoreply, icmp6-multicastlistenerquery, icmp6-multicastlistenerreportv1, icmp6-multicastlistenerdone, icmp6-routersolicit, icmp6-routeradvert, icmp6-neighborsolicit, icmp6-neighboradvert, icmp6-redirect, icmp6-routerrenum, icmp6-nodeinformationquery, icmp6-nodeinformationresponse, icmp6-ineighbordiscoverysolicit, icmp6-ineighbordiscoveryadvert, icmp6-multicastlistenerreportv2, icmp6-homeagentdiscoveryrequest, icmp6-homeagentdiscoveryreply, icmp6-mobileprefixsolicit, icmp6-mobileprefixadvert, icmp6-certpathsolicit, icmp6-certpathadvert, icmp6-multicastrouteradvert, icmp6-multicastroutersolicit, icmp6-multicastrouterterm.
The following TCP flags field values are available: tcp-fin, tcp-syn, tcp-rst, tcp-push, tcp-ack, tcp-urg, tcp-ece, tcp-cwr.
Primitives may be combined using:
Negation has highest precedence. Alternation and concatenation have equal precedence and associate left to right. Note that explicit and tokens, not juxtaposition, are now required for concatenation.
If an identifier is given without a keyword, the most recent keyword is assumed. For example,
not host vs and aceis short for
not host vs and host acewhich should not be confused with
not ( host vs or ace )