Communications Programming Concepts

Packet Capture Library Filter Expressions

The filter expression is passed into the pcap_compile subroutine to specify the packets that should be captured. If no filter expression is given, all packets on the network will be captured. Otherwise, only packets for which the filter expression is True will be captured. The filter expression is an ASCII string that consists of one or more primitives. Primitives usually consist of an id (name or number) preceded by one or more qualifiers. There are three types of qualifiers:

type	Specifies what kind of device the id name or number refers to. Possible types are host, net, and port. Examples are `host foo`, `net 128.3`, `port 20`. If there is no type qualifier, then host is assumed.
dir	Specifies a particular transfer direction to or from id. Possible directions are src, dst, src or dst, and src and dst. Some examples with dir qualifiers are: `src foo`, `dst net 128.3`, `src`or`dst port ftp-data`. If there is no dir qualifier, src or dst is assumed.
proto	Restricts the match to a particular protocol. Possible protoqualifiers are: ether, ip, arp, rarp, tcp, and udp. Examples are: `ether src foo`, `arp net 128.3`, `tcp port 21`. If there is no proto qualifier, all protocols consistent with the type are assumed. For example, `src foo` means `ip` or `arp`, `net bar` means `ip` or `arp` or `rarp net bar`, and `port 53` means `tcp` or `udp port 53`.

There are also some special primitive keywords that do not follow the pattern: broadcast, multicast, less, greater, and arithmetic expressions. All of these keywords are described in the following information.

Allowable Primitives

The following primitives are allowed:

dst host Host	True if the value of the IP (Internet Protocol) destination field of the packet is the same as the value of the Host variable, which can be either an address or a name.
dst port Port	True if the packet is TCP/IP (Transmission Control Protocol/Internet Protocol) or IP/UDP (Internet Protocol/User Datagram Protocol) and has a destination port value of Port. The port can be a number or a name used in /etc/services. If a name is used, both the port number and protocol are checked. If a number or ambiguous name is used, only the port number is checked (`dst port 513` will print both TCP/login traffic and UDP/who traffic, and `port domain` will print both TCP/domain and UDP/domain traffic).
DST net Net	True if the value of the IP destination address of the packet has a network number of Net. Note that Net must be in dotted decimal format.
greater Length	True if the packet has a length greater than or equal to the Length variable. This is equivalent to the following: len > = Length
host Host	True if the value of either the IP source or destination of the packet is the same as the value of the Host variable. You can add the keywords ip, arp, or rarp in front of any previous host expressions as in the following: ip host Host If the Host variable is a name with multiple IP addresses, each address will be checked for a match.
ip, arp,rarp	These keywords are abbrieviated forms of the following: proto ip, proto arp, and proto rarp.
ip broadcast	True if the packet is an IP broadcast packet. It checks for the all-zeroes and all-ones broadcast conventions, and looks up the local subnet mask.
ip multicast	True if the packet is an IP multicast packet.
ip proto Protocol	True if the packet is an IP packet of protocol type Protocol. Protocol can be a number or one of the names icmp,udp, or tcp.
less Length	True if the packet has a length less than or equal to Length. This is equivalent to the following: len < = Length
net Net	True if the value of either the IP source or destination address of the packet has a network number of Net. Note that Net must be in dotted decimal format
net Net/Len	True if the value of either the IP source or destination address of the packet has a network number of Net and a netmask with the width of Len bits. Note that Net must be in dotted decimal format.
net Net mask Mask	True if the value of either the IP source or destination address of the packet has a network number of Net and the specific netmask of Mask. Note that Net and Mask must be in dotted decimal format.
port Port	True if the value of either the source or the destination port of the packet is Port. You can add the keywords tcp or udp in front of any of the previous port expressions, as in the following: tcp src port port which matches only TCP packets.
proto Protocol	True if the packet is of type Protocol. Protocol can be a number or a name like ip, arp, or rarp.
src host Host	True if the value of the IP source field of the packet is the same as the value of the Host variable.
src net Net	True if the value of the IP source address of the packet has a network number of Net. Note that Net must be in dotted decimal format.
src port Port	True if the value of the Port variable is the same as the value of the source port.
tcp, udp, icmp	These keywords are abbrieviated forms of the following: ip proto tcp, ip proto udp, or ip proto icmp

Relational Operators of the Expression Parameter

The simple relationship:

expr relop expr

Is true where relop is one of the following:

ampersand (&)
asterisk (*)
equal (=)
exclamation point and equal sign (!=) and expr is an arithmetic

expression composed of integer constants (expressed in standard C syntax)
greater than (>)
greater than or equal to (>=)
less than (<)
less than or equal to (<=)
length operator
minus sign (-)
pipe (|)
plus sign (+)
slash (/)
special packet data accessors

To access data inside the packet, use the following syntax:

proto [ expr : size ]

Proto is one of the keywords ip, arp, rarp, tcp or icmp, and indicates the protocol layer for the index operation. The byte offset relative to the indicated protocol layer is given by expr. The indicator 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 byte. The length operator, indicated by the keyword len, gives the length of the packet.

For example, expression ip[0] & 0xf != 5 catches only nonfragmented datagrams and frag 0 of fragmented datagrams. This check is implicitly implied to the tcp and udp index operations. For example, tcp[0] always means the first byte of the TCP header, and never means the first byte of an intervening fragment.

Combining Primitives

More complex filter expressions are created by using the words and, or, and not to combine primitives. For example, host foo and not port ftp and not port ftp-data. To save typing, identical qualifier lists can be omitted. For example, 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.

Primitives can be combined using a parenthesized group of primitives and operators

A
Negation (`!' or `not').
Concatenation (`and').
Alternation (`or').

Negation has highest precedence. Alternation and concatenation have equal precedence and associate left to right.

If an identifier is given without a keyword, the most recent keyword is assumed. For example:

not host gil and devo

This filter captures packets that do not have a source or destination of host gil and also packets that do have a source or destination of host devo. It is an abbreviated version of the following:

not host gil and host devo

Avoid confusing it with the following filter which captures packets that do not have a source or destination of either gil or devo:

not (host gil or devo)