ppp.Filter(4) Kernel Interfaces Manual ppp.Filter(4)
NAME
ppp.Filter - PPP packet filter specification file format
DESCRIPTION
The file describes how on-demand PPP links are to be managed. By default, any type of packet causes the link (if down) to be brought up
(connected to its remote end); any packet is allowed to traverse the link; and any packet is sufficient to reset the idle timer, expiration
of which would cause the link to be shut down. This combination is not always appropriate behavior, so the filter file allows individual
control based on the packet type and its source or destination. These selection criteria may be specified for any of the three phases of
operation: bringing up the link, passing packets on the link, and shutting down the link due to inactivity. Packet logging detail may
also be selected using the same criteria.
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 or 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 connect-
ing 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 des-
tination 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 for IPv4 packets and 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 in response to a particular packet:
Describes those packets that will cause a call to be placed and a
connection initiated. Packets of this sort also must qualify to "pass" across the link, either by being explicitly men-
tioned or by inclusion in a larger class in the section.
Describes those packets that will be allowed to traverse the link on
an already-established connection. Only packets which would be passed can cause the link to be brought up. Any packet
that is not passed is optionally logged, then discarded.
Describes packets that will reset the idle timer, thereby keeping the
line connected.
Describes packets whose headers or contents are to be noted in the log file.
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, takes the indicated action and ignores the rest of the listed stanzas (i.e., inclu-
sive or with shortcut evaluation).
Stanzas may contain IP protocol numbers, optionally hyphen-separated ranges of TCP or UDP port numbers along with the or qualifier, numbers
representing ICMP/ICMPv6 message types or codes (which can be found in and along with the or for ICMPv6 qualifier, service names corre-
sponding to entries in or names or IP addresses of hosts or networks, or the special keyword which is the default for all actions except
where the default is (Usually, it is unnecessary to use as a convenience, automatically adds a at the end of a stanza list if the last
stanza negated, and add an at the end of a stanza list if the last stanza is negated. For example, in the typical case of this sensibly
results in those packets matching the stanzas shown being logged, and no others. In the typical case of 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 speci-
fied if it is of a different size than the default for that class of network. The network mask and additional 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 filter specification, the special keyword causes the contents (as well as headers) of the indicated type of packet to be written to
the log file. Also in the filter specification, the special flag signifies that the packet is to be logged only if it was rejected by the
filter.
Since TCP data streams are opened when the initiator sends a SYN packet to the intended recipient, 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
allows filtering or logging these connection starters. Qualifying it with or allows sessions to be started or logged only if they are ini-
tiated in the indicated direction. The special keyword allows filtering or logging the packets that close TCP connections.
The and 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. then both the source and destination address and/or port must match.
The 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:
net The destination network is unreachable.
host The destination host is unreachable.
prot The designated transport protocol is not supported.
protocol The designated transport protocol is not supported.
port The designated transport protocol (e.g., UDP) is unable to demultiplex the datagram but has no protocol mechanism to
inform the sender.
needfrag Fragmentation is needed and the Don't Fragment flag is set.
srcfail Source route failed.
net-unknown The destination network is unknown.
host-unknown The destination host is unknown.
host-isolated The source host is isolated.
net-prohibited Communication with the destination network is administratively prohibited.
host-prohibited
Communication with the destination host is administratively prohibited.
net-tos The destination network is unreachable for the designated type of service.
host-tos The destination host is unreachable for the designated type of service.
The 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:
noroute6 No route to destination.
admin-prohibited
Communication with destination administratively prohibited
addr6 Destination address in unreachable
port6 Destination port unreachable
The 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:
rr Record Route is used to trace the route an internet datagram takes.
ts Time Stamp.
security Security is used to carry Security, Compartmentation, User Group (TCC), and Handling Restriction Codes compatible
with DOD requirements.
lsrr Loose Source Routing is used to route the internet datagram based on information supplied by the source.
ssrr Strict Source Routing is used to route the internet datagram based on information supplied by the source.
srcrt Either Loose Source Routing or Strict Source Routing.
any Any IP option - could even match the No Operation option.
EXAMPLES
Default Behavior
The following file describes the default behavior of either in the absence of a filter specification file or in the case of an empty file:
# Filter - PPP configuration file,
# binding packet types to actions.
# Describes the default behavior of the daemon:
default bringup all pass all keepup all log !all
default6 bringup all pass all keepup all log !all
The default behavior is no restriction of packets, and no logging.
Internet Firewall
A line like this might be appropriate as a security firewall between an organizational network and the larger Internet:
internet-gateway
bringup !ntp !3/icmp !5/icmp !11/icmp !who !route
!nntp !89
pass nntp/137.39.1.2 !nntp
telnet/syn/recv/137.175.0.0
!telnet/syn/recv !ftp/syn/recv
!login/syn/recv !shell/syn/recv !who
!sunrpc !chargen !tftp !supdup/syn/recv
!exec !syslog !route !6000/tcp/syn/send
keepup !send !ntp !3/icmp !5/icmp !11/icmp
!who !route !89
log rejected
This 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 means that any traffic not explicitly blocked is permitted to pass.
The and lines are appropriate for an intermittent dial-up connection, so that various error conditions won't cause the link to be estab-
lished, 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 line keeps a record of every packet that is
blocked by the line, so that unsuccessful penetration attempts will be noted.
For IPv6 filter line add similar to:
<IPv6 link local gateway address> #like fe80::2222
# which type of traffic should/shouldn't bring up the line
bringup !ntp !128/icmp6 !137/icmp6 !who !route !nntp
# which type of packets should be passed/rejected
pass !nntp
!telnet/syn/recv
# Don't allow any packets from network whose prefix matches
# prefix cafe.
!cafe::1234/16
!ftp/syn/recv !login/syn/recv !shell/syn/recv
# which type of packets should/shouldn't restart
# the idle timer
keepup !send !ntp !137/icmp !who !route
# which type of packets should/shouldn't be logged
log rejected
An Extremely Complex Example
The following 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 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) 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 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.
#
# Filter - PPP configuration file binding packet
# types to actions.
#
# For packets that would pass, these services
# will bring up the link:
#
backbone bringup smtp nntp domain telnet ftp
#
# Once brought up, these will pass (or not):
#
pass !131.119.250.104
domain/137.175.42.0/255.255.255.0
!137.175.42.0/0xffffff00
# (alternative ways of
# expressing subnet mask)
!telnet/syn/recv !ftp/syn/recv
domain smtp nntp ntp icmp telnet ftp
#
# Packets received for the services shown will
# reset the idle timer.
#
keepup !send smtp nntp domain telnet ftp
#
# Only these messages will have headers or contents
# logged, unless higher-level debugging is set:
#
log 3/icmp 11/icmp 12/icmp/trace
telnet/syn ftp/syn
smtp/syn/terminus.netsys.com
#
default bringup !ntp !3/icmp !who
keepup !send !ntp !3/icmp !who
RECOMMENDATIONS
Simpler filter specifications allow to start up quicker and run faster, with less processing overhead for each packet, but that overhead is
likely to present a problem only at very high line speeds (like T1). The "backbone" example shown above is severe overkill for the sake of
illustration, evolved over a period of several weeks, and took the authors several tries to get right. Start with a simple filter specifi-
cation and add each special case only as the need arises, usually as the result of watching packet logs. Then test carefully to ensure
that your change had only the desired effect.
Be very careful with header logging and even more careful with packet content tracing. Make the selection criteria very narrow, or the log
file will grow extremely large in a short period of time. Also, if the daemon is running on a diskless workstation or if the log file is
on a NFS-mounted file system, excessive amounts of logging information will drastically impede the daemon's ability to process at high
packet rates. Remember, NFS writes are synchronous.
If you specify host names, be sure that their addresses are available locally, even with the connection down. If you find that you must
bring up a connection to resolve a domain name, consider using that host's IP address (decimal numbers separated by periods) in both and
instead.
If you want to specify all Domain Name System traffic, use which will be expanded to entries for both and (Some DNS traffic uses each
transport.) To allow queries but disable domain transfers, use Similarly, some systems' older files, as distributed by the manufacturer,
list NTP as a TCP service. When the current UDP NTP implementation was installed on your system, the administrator may have left the old
entry along with the correct The correct solution is to remove the entry from A workaround would be to specify in
DEC ULTRIX 4.2 and some other systems may have no entry for FTP's data socket in their file. If you want to log the bulk data connections
as well as the control connections, you'll need to either add an entry for to or use explicitly in The former is preferable because it will
cause the log file entry to contain the symbolic name rather than the socket/protocol notation.
If your file is missing some application-level protocols that you consider useful, you can populate it with entries from the Assigned Num-
bers RFC, number 1340. For example, you may find it useful to add lines like
gopher 70/tcp
gopher 70/udp
kerberos 88/tcp
kerberos 88/udp
snmp 161/tcp
snmp 161/udp
nextstep 178/tcp
nextstep 178/udp
prospero 191/tcp
prospero 191/udp
x11 6000/tcp
if you're using those applications, and if they're not already in your file as received from your system's manufacturer. If you augment
your this way, then instead of using entries like
pass !6000/tcp/syn/send
your could use entries like
pass !x11/syn/send
which is much more readable. A list of TCP and UDP service numbers and names, selected from the Assigned Numbers RFC, is available in
AUTHOR
was developed by HP.
SEE ALSO
pppd(1), ppp.Auth(4), ppp.Devices(4), ppp.Dialers(4), ppp.Keys(4), ppp.Systems(4), services(4).
RFC 791, RFC 792, RFC 1055, RFC 1548, RFC 1332, RFC 1122, RFC 1144, RFC 1340.
ppp.Filter(4)