filter(4)


filter -- format of a packet filter file

Synopsis

tag [ expression ]
. . .

Description

A packet filter provides a means of limiting what packets pass through, bringup or reset the idle timer (if appropriate) for a network interface.

Files named for an individual MDI network interface in the directory hierarchy /etc/pf.d/protocol store packet filter specifications for that interface. For example, the file /etc/pf.d/IP/net0 would hold IP packet filter definitions for the net0 interface.

The file /etc/pf.d/IP/ppp stores packet filter specifications for the Internet protocols running over the PPP serial-line protocol.

Packet filters for a LAN network adapter can be loaded into the kernel using pushfilter(1M). Separate filters may be used for the incoming and outgoing streams of an interface, or the same filter may be applied to both streams.

A filter file can contain several entries which must be identified by tags which are unique to that file. Each entry specifies the characteristics of the filter. Only packets for which the expression evaluates as true are considered to meet the selection criteria. If no expression is present, all packets are considered to meet the selection criteria, and any existing filter for the interface is unloaded.

Each field is separated from others by white space or a tab. Each entry may consist of up to 8192 characters, and can extend beyond a single line by ending each line of the entry except the last with a backslash (``\''). Comments begin with a ``#'' and extend to the end of the line. Blank lines, or lines beginning with a ``#'', are ignored.

For PPP interfaces, an IPCP entry in the PPP configuration file can include the specifications bringup, keepup, passin and passout to specify which filters should be configured when the link is established. The filters may be defined using the ppptalk(1M) command, but they will not take effect until the link is taken down and brought up again.

For SLIP interfaces, the -p option with a tag value as its argument should be specified to the slattach(1Mtcp) command). Each PPP and SLIP interface may specify its own filters or two or more interfaces may share a filter.

Expressions

An expression consists of one or more primitives, and should evaluate to true for packets that should be allowed to traverse the interface (or bring up or keep up a PPP link). and to false for packets that should be discarded. Complex filter expressions may be built up by using the operators and, and or to combine primitives, and not (or !) to negate the sense of primitives, for example:
   host foo and !port ftp and !port ftp-data
This means ``pass packets going to or coming from the host named foo provided that they not going to or coming from the FTP control or data ports''.

Negation (not) has highest precedence. Alternation (or) and concatenation (and) have equal precedence and associate left to right. Note that concatenation requires explicit and tokens, not just simple juxtaposition. Primitives may be grouped using parentheses. For example, the previous expression could be written as:

   host foo and !(port ftp or port ftp-data)
Note that alternation and concatenation operators obey the usual conversion rules with regard to the placement of the not operator and parentheses:

not A and not B is equivalent to not (A or B)
not A or not B is equivalent to not (A and B)

Multiple primitives within the same entry which only differ by the value of the primitive variable may be combined. For example, the following expressions are equivalent:

   dst port ftp or dst port ftp-data
   dst port ftp or ftp-data
Both these expressions mean ``pass packets that are bound for the FTP control or data ports''.

The primitive expressions are:


[ dst | src ] host host
True if the IP source or destination field of the packet is host, which may be either an address or a host name.

If dst is specified, the expression is true only if the destination field is host. If src is specified, the expression is true only if the source field is host.


[ dst | src ] net net
True if the IP source or destination field of the packet includes a network number of net, which may be either an address (without trailing 0 octets) or a network name.

If dst is specified, the expression is true only if the destination field includes a network number of net. If src is specified, the expression is true only if the source field includes a network number of net.


[ tcp | udp ][ dst | src ] port port
True if the packet is IP/TCP or IP/UDP and has a source or destination port value of port, which can be a number or a name defined 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. For example, dst port 513 will be true for both TCP rlogin and UDP rwho traffic, and port domain will be true for both TCP and UDP DNS traffic.

If dst is specified, the expression is true only if the destination field has a destination port value of port. If src is specified, the expression is true only if the source field has a destination port value of port. Specifying a protocol further limits the match. protocol can one of icmp, tcp. or udp. For example , tcp src port port matches only TCP packets from port port.


ip broadcast
True if the packet is an IP broadcast packet. It checks for both 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, which can be a number or one of icmp, udp, or tcp.

icmp
Equivalent to ip proto icmp.

tcp
Equivalent to ip proto tcp.

udp
Equivalent to ip proto udp.

expr relop expr
True if the relation holds. The relational operator, relop, is one of >, <, >=, <=, ==, or !=. expr is an arithmetic expression composed of integer constants, the binary operators +, -, *, /, &, |, <<, or >>, the unary operator -, the length function (len), and special operators that can be used to access packet data.

To access data inside the packet, use one of the following syntax forms:

protocol[expr]
protocol[expr:size]

protocol is one of ip, tcp, udp, or icmp, and indicates the protocol header to which the index operation will be applied. expr is an offset in bytes relative to the start of the header. size is optional and indicates the number of bytes in the field of interest; it can be either 1, 2, or 4. If not specified, the default size is 1 byte.

Tests on TCP segments and UDP datagrams, such as tcp[0] and udp[0], are always applied to the TCP or UDP header. They are never applied to an intervening fragment.

The following table shows useful tests for IP headers.

Test Description
ip[0] & 0xf0 == 1024 Examine the protocol version, and match if this is 1024 (4<<8) for IPv4
ip[0] & 0xf > 5 Examine the length of the header (number of 32-bit words), and match all IP datagrams that have options defined
ip[0] & 0xf > 5 and ip[20] == code Examine the IP option header, and match its value against code. Example values are 0x7 for record route, 0x44 for timestamp, 0x83 for loose source routing, and 0x89 for strict source routing
ip[1] & 0x10 != 0 Examine the type-of-service field, and match if its ``Minimize delay'' flag is set
ip[2:2] > len Examine the total length of the datagram (in bytes), and match if this is greater than len
ip[6:2] & 0x1fff == 0 Examine the fragment offset of the datagram (in bytes), and match only unfragmented datagrams and fragment zero of fragmented IP datagrams
ip[6:2] & 0x2000 != 0 Match if the ``More fragments'' flag is set. Unfragmented datagrams and final fragments do not set this
ip[6:2] & 0x3fff == 0 Match unfragmented datagrams only
ip[6:2] & 0x4000 != 0 Match if the ``Don't fragment'' flag is set
ip[9:1] == protocol Examine the protocol field, and match its value against protocol. Example values are 1 for ICMP, 2 for IGMP, 6 for TCP, and 17 for UDP

 +----------------------+-----------------------------------------+
 |Test                  | Description                             |
 +----------------------+-----------------------------------------+
 |ip[0] & 0xf0 == 1024  | Examine the protocol version, and match |
 |                      | if this is 1024 (4<<8) for IPv4         |
 +----------------------+-----------------------------------------+
 |ip[0] & 0xf > 5       | Examine the length of the header        |
 |                      | (number of 32-bit words), and match all |
 |                      | IP datagrams that have options defined  |
 +----------------------+-----------------------------------------+
 |ip[0] & 0xf > 5 and   | Examine the IP option header, and match |
 |ip[20] == code        | its value against code. Example values  |
 |                      | are 0x7 for record route, 0x44 for      |
 |                      | timestamp, 0x83 for loose source        |
 |                      | routing, and 0x89 for strict source     |
 |                      | routing                                 |
 +----------------------+-----------------------------------------+
 |ip[1] & 0x10 != 0     | Examine the type-of-service field, and  |
 |                      | match if its ``Minimize delay'' flag is |
 |                      | set                                     |
 +----------------------+-----------------------------------------+
 |ip[2:2] > len         | Examine the total length of the         |
 |                      | datagram (in bytes), and match if this  |
 |                      | is greater than len                     |
 +----------------------+-----------------------------------------+
 |ip[6:2] & 0x1fff == 0 | Examine the fragment offset of the      |
 |                      | datagram (in bytes), and match only     |
 |                      | unfragmented datagrams and fragment     |
 |                      | zero of fragmented IP datagrams         |
 +----------------------+-----------------------------------------+
 |ip[6:2] & 0x2000 != 0 | Match if the ``More fragments'' flag is |
 |                      | set.  Unfragmented datagrams and final  |
 |                      | fragments do not set this               |
 +----------------------+-----------------------------------------+
 |ip[6:2] & 0x3fff == 0 | Match unfragmented datagrams only       |
 +----------------------+-----------------------------------------+
 |ip[6:2] & 0x4000 != 0 | Match if the ``Don't fragment'' flag is |
 |                      | set                                     |
 +----------------------+-----------------------------------------+
 |ip[9:1] == protocol   | Examine the protocol field, and match   |
 |                      | its value against protocol.  Example    |
 |                      | values are 1 for ICMP, 2 for IGMP, 6    |
 |                      | for TCP, and 17 for UDP                 |
 +----------------------+-----------------------------------------+
A generic test for ICMP message types is icmp[0] == type [ and icmp[1] == code ]. The following table shows some useful types and codes.

Type Code Description
0 0 Echo reply (used by ping)
3 0-15 Destination unreachable
0 Network unreachable
1 Host unreachable
3 Port unreachable
4 Fragmentation prevented by set ``Don't fragment'' bit
5 Source route failed
9 Destination network prohibited
10 Destination host prohibited
13 Communication prohibited by filtering
4 0 Source quench
5 0-3 Redirect
0 Redirect for network
1 Redirect for host
8 0 Echo request (used by ping)
9 0 Router advertisement
10 0 Router solicitation
11 0 Time-to-live fell to 0 during transit (used by traceroute)
1 Time-to-live fell to 0 during reassembly
12 0-1 Parameter problem
13 0 Timestamp request
14 0 Timestamp reply
17 0 Address mask request
18 0 Address mask reply

 +-----+------+------------------------------------------------------------+
 |Type | Code | Description                                                |
 +-----+------+------------------------------------------------------------+
 |0    | 0    | Echo reply (used by ping)                                  |
 +-----+------+------------------------------------------------------------+
 |3    | 0-15 | Destination unreachable                                    |
 +-----+------+------------------------------------------------------------+
 |     | 0    | Network unreachable                                        |
 +-----+------+------------------------------------------------------------+
 |     | 1    | Host unreachable                                           |
 +-----+------+------------------------------------------------------------+
 |     | 3    | Port unreachable                                           |
 +-----+------+------------------------------------------------------------+
 |     | 4    | Fragmentation prevented by set ``Don't fragment'' bit      |
 +-----+------+------------------------------------------------------------+
 |     | 5    | Source route failed                                        |
 +-----+------+------------------------------------------------------------+
 |     | 9    | Destination network prohibited                             |
 +-----+------+------------------------------------------------------------+
 |     | 10   | Destination host prohibited                                |
 +-----+------+------------------------------------------------------------+
 |     | 13   | Communication prohibited by filtering                      |
 +-----+------+------------------------------------------------------------+
 |4    | 0    | Source quench                                              |
 +-----+------+------------------------------------------------------------+
 |5    | 0-3  | Redirect                                                   |
 +-----+------+------------------------------------------------------------+
 |     | 0    | Redirect for network                                       |
 +-----+------+------------------------------------------------------------+
 |     | 1    | Redirect for host                                          |
 +-----+------+------------------------------------------------------------+
 |8    | 0    | Echo request (used by ping)                                |
 +-----+------+------------------------------------------------------------+
 |9    | 0    | Router advertisement                                       |
 +-----+------+------------------------------------------------------------+
 |10   | 0    | Router solicitation                                        |
 +-----+------+------------------------------------------------------------+
 |11   | 0    | Time-to-live fell to 0 during transit (used by traceroute) |
 +-----+------+------------------------------------------------------------+
 |     | 1    | Time-to-live fell to 0 during reassembly                   |
 +-----+------+------------------------------------------------------------+
 |12   | 0-1  | Parameter problem                                          |
 +-----+------+------------------------------------------------------------+
 |13   | 0    | Timestamp request                                          |
 +-----+------+------------------------------------------------------------+
 |14   | 0    | Timestamp reply                                            |
 +-----+------+------------------------------------------------------------+
 |17   | 0    | Address mask request                                       |
 +-----+------+------------------------------------------------------------+
 |18   | 0    | Address mask reply                                         |
 +-----+------+------------------------------------------------------------+
The following tests access the source and destination port numbers defined in TCP and UDP headers.

Protocol Source port Destination port
TCP tcp[0:2] tcp[2:2]
UDP udp[0:2] udp[2:2]

 +---------+-------------+------------------+
 |Protocol | Source port | Destination port |
 +---------+-------------+------------------+
 |TCP      | tcp[0:2]    | tcp[2:2]         |
 +---------+-------------+------------------+
 |UDP      | udp[0:2]    | udp[2:2]         |
 +---------+-------------+------------------+
A generic test for flag bits being set in a TCP header is tcp[13:1] & flag != 0 where flag can be any of the following values ORed together:

Flag Bit Meaning if set
0x01 FIN Finished sending data
0x02 SYN Synchronize sequence numbers
0x04 RST Reset a connection
0x08 PSH Push the data to an application
0x10 ACK Acknowledge a sequence number
0x20 URG There is urgent data

 +-----+-----+---------------------------------+
 |Flag | Bit | Meaning if set                  |
 +-----+-----+---------------------------------+
 |0x01 | FIN | Finished sending data           |
 +-----+-----+---------------------------------+
 |0x02 | SYN | Synchronize sequence numbers    |
 +-----+-----+---------------------------------+
 |0x04 | RST | Reset a connection              |
 +-----+-----+---------------------------------+
 |0x08 | PSH | Push the data to an application |
 +-----+-----+---------------------------------+
 |0x10 | ACK | Acknowledge a sequence number   |
 +-----+-----+---------------------------------+
 |0x20 | URG | There is urgent data            |
 +-----+-----+---------------------------------+

len
A function that returns the length of the packet in bytes. This function should be used in a relational expression to return a true or false value.

less length
True if the packet has a length less than or equal to length. This is equivalent to len <= length.

greater length
True if the packet has a length greater than or equal to length. This is equivalent to len >= length.

byte index operator value
Evaluate the truth of applying operator value to the byte at offset index inside the packet. Possible operators are & (bitwise and), | (bitwise or), < (less than), > (greater than), and = (equals). index and value must both be integer values.

Files


/etc/pf.d/IP/ppp
filter specification file for IP over PPP

/etc/pf.d/IP/interface
filter specification file for IP over interface

References

inconfig(1Mtcp), named.boot(4tcp), netstat(1Mtcp), ppptalk(1M), protocols(4tcp), pushfilter(1M), resolv.conf(4tcp), services(4tcp), slattach(1Mtcp)

RFC 768, RFC 791, RFC 792, RFC 793, RFC 1060, RFC 1122, RFC 1579

``Obtaining RFCs from the Internet'' in Administering TCP/IP and Internet services


© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004