ppp.Filter(4)

Format

Comments begin with a # and extend to the end of the line; blank lines, or lines beginning with a #, are ignored. Upper/lower case distinctions are ignored in hostname specifications, but are significant elsewhere. Fields are separated by horizontal or vertical white space (blanks or tabs or newlines).

If a line begins with a hostname or IPv4/IPv6 address or the special words default or default6 for IPv6, that line is considered to be the beginning of a new set of filtering specifications. The filtering specifications will be applied to any packet crossing the point-to-point link connecting this host to the peer named by that initial hostname or IPv4/IPv6 address. The hostname or IPv4/IPv6 address in the first column of the filter file refers to the peer (system or router or terminal server) at the remote end of the point-to-point (PPP or SLIP) link. The hostname or IPv4/IPv6 address in the first column of the filter file, and associated with the link peer, is unrelated to the source or destination IPv4/IPv6 address of any packet crossing the link. If the link peer's address doesn't match any name or address specified in the first column of filter file, the filter specification following the special word default for IPv4 packets and default6 for IPv6 packets will be used.

If a newline is followed by white space, that line is a continuation of the filtering specification already in progress.

There are four keywords to describe the actions taken by pppd in response to a particular packet:

After each action keyword comes stanzas, separated by white space, describing packets that fit the criteria for that action. Each stanza is processed in the order shown in the file, and contain restrictions or permissions on the packets encountered. As soon as a pattern or a condition is found that matches the packet in question, pppd takes the indicated action and ignores the rest of the listed stanzas (i.e., inclusive or with shortcut evaluation).

Stanzas may contain IP protocol numbers, optionally hyphen-separated ranges of TCP or UDP port numbers along with the /tcp or /udp qualifier, numbers representing ICMP/ICMPv6 message types or codes (which can be found in <netinet/ip_icmp.h> and <netinet/icmp6.h>) along with the /icmp or /icmp6 for ICMPv6 qualifier, service names corresponding to entries in /etc/services, or names or IP addresses of hosts or networks, or the special keyword all, which is the default for all actions except log, where the default is !all. (Usually, it is unnecessary to use all; as a convenience, pppd automatically adds a !all at the end of a stanza list if the last stanza isnot negated, and add an all at the end of a stanza list if the last stanza is negated. For example, in the typical case of log this sensibly results in only those packets matching the stanzas shown being logged, and no others. In the typical case of pass, this results in certain listed packets being restricted, but allowing the passage of all others.)

For IPv4 packets filtering if a network is specified, either by name or by address, then the corresponding network mask must also be specified if it is of a different size than the default for that class of network. The network mask and additional and conditions within a stanza are separated by slashes (/), and may be specified either as a series of decimal numbers separated by periods, or as a single 32-bit hexadecimal number. For IPv6 networks specify a prefix or a IPv6 address with prefix length separated by a slash (/). The sense of a stanza may be negated by prefixing it with an exclamation mark (!).

In the log filter specification, the special keyword trace causes the contents (as well as headers) of the indicated type of packet to be written to the log file. Also in the log filter specification, the special flag rejected signifies that the packet is to be logged only if it was rejected by the pass filter.

Since TCP data streams are opened when the initiator sends a SYN packet to the intended recipient, pppd can distinguish between outbound (sent from this host) and inbound (coming from the other end of the link) uses of TCP applications such as telnet or FTP. The special keyword syn allows filtering or logging these connection starters. Qualifying it with recv or send allows sessions to be started or logged only if they are initiated in the indicated direction. The special keyword fin allows filtering or logging the packets that close TCP connections.

The src and dst keywords serve to distinguish ports, addresses or hostnames, as applying to the source or destination, respectively, of the packet. If both are applied to the same stanza (e.g. .../src/dst), then both the source and destination address and/or port must match.

The unreach= keyword causes an ICMP Destination Unreachable message (RFC 792 and RFC 1122 section 3.2.2.1) to be sent to the packet's source address, bearing the indicated code field, which may be chosen from the following:

The unreach= keyword also causes an ICMPv6 Destination Unreachable message (RFC 2463 section 3.1) to be sent to the IPv6 packet's source address, bearing the indicated code field, which may be chosen from the following:

The ip-opt= keyword can be used to select packets based on whether they bear various IP options (RFC 1122 section 3.2.1.8 and RFC 791 section 3.1 (pps 16ff)), selected from the following:

Default Behavior

The following Filter file describes the default behavior of pppd, either in the absence of a filter specification file or in the case of an empty file:

The default behavior is no restriction of packets, and no logging.

Internet Firewall

A pass line like this might be appropriate as a security firewall between an organizational network and the larger Internet:

This pass specification allows NNTP (Usenet news) transactions with one peer and no others. It allows incoming Telnet sessions from hosts on only one network, disallows all other incoming Telnet, SUPDUP, and FTP sessions, and allows all outgoing Telnet SUPDUP, and FTP sessions.

It allows X Window System clients running elsewhere to display on local window servers, but it allows no local X clients to use displays located elsewhere. It disallows all SUN RPC traffic, thereby guarding the local YP/NIS and NFS servers from outside probes and filesystem mounts. Alas, it also disallows local machines from mounting filesystems resident on NFS servers elsewhere, but this can't be helped because NFS uses RPC which is a UDP service, and therefore without the SYN and FIN packets that can be used to characterize the direction in which a TCP stream is being initiated. It blocks several other sorts of traffic that could be used for nefarious purposes, and the absence of a trailing !all means that any traffic not explicitly blocked is permitted to pass.

The bringup and keepup lines are appropriate for an intermittent dial-up connection, so that various error conditions won't cause the link to be established, nor to keep the call open beyond its usefulness. OSPF (Open Shortest Path First) routing packets (IP protocol number 89, from RFC-1340) will cross the link, but won't cause it to be brought up, nor keep it up if it's otherwise idle. Usenet news traffic won't bring up the link, but once started, the link won't be shut off in the middle of a news batch. The log rejected line keeps a record of every packet that is blocked by the pass line, so that unsuccessful penetration attempts will be noted.

For IPv6 filter line add similar to:

An Extremely Complex Example

The following Filter file instructs the daemon that a connection to any neighbor except the host "backbone" be brought up in response to any packet except for those generated by NTP, ICMP Destination Unreachable, and rwhod. If those are the only types of packets flowing across the link, it will not be kept up, but all packets are allowed to cross the link while it is up. Packets sent out will not reset the idle timer, but packets received from the peer will. If the peer goes down and modem problems cause the phone not to be hung up, (and the idle command-line argument has been specified) pppd will hang up the connection and retry.

In the special case of the host "backbone" (perhaps a server belonging to a network connectivity vendor), only telnet and FTP sessions, SMTP electronic mail, NNTP network news, and Domain Name System queries are considered sufficient cause to bring the link up or to keep it up if otherwise idle.

Once the link is up, all the above plus NTP clock chimes and ICMP messages may flow across the link. No packets to or from a particular host, nor any packets except Domain Name System queries and responses for any host on subnet 42 of the class B network 137.175 are ever allowed to cross the link, nor would they cause the link to be initiated. We allow telnet and FTP sessions only if they are initiated in the outbound direction.

We log one-line descriptions of various ICMP problem messages (Unreachable, Time Exceeded), and the complete contents of ICMP messages reporting IP header problems. We log all telnet and FTP sessions, including inbound attempts (though they will fail because they are excluded in the pass specification above). We also log the header of the first packet of any electronic mail message flowing over this link on its way to or from a specific host.