ppp.Filter(4)ppp.Filter(4)NAMEppp.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 con‐
trol 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 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 associ‐
ated 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 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 mentioned 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 keep‐
ing 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 indi‐
cated 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 corresponding
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, auto‐
matically 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 specified
if it is of a different size than the default for that class of net‐
work. 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 sig‐
nifies 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 initiated in
the indicated direction. The special keyword allows filtering or log‐
ging 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 follow‐
ing:
net The destination network is unreachable.
host The destination host is unreachable.
prot The designated transport protocol is not sup‐
ported.
protocol The designated transport protocol is not sup‐
ported.
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 admin‐
istratively prohibited.
net-tos The destination network is unreachable for the
designated type of service.
host-tos The destination host is unreachable for the des‐
ignated 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, bear‐
ing 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 inter‐
net datagram takes.
ts Time Stamp.
security Security is used to carry Security, Compartmenta‐
tion, User Group (TCC), and Handling Restriction
Codes compatible with DOD requirements.
lsrr Loose Source Routing is used to route the inter‐
net datagram based on information supplied by the
source.
ssrr Strict Source Routing is used to route the inter‐
net 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 ses‐
sions, 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 filesys‐
tems 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 permit‐
ted 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 neigh‐
bor 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 mes‐
sages 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 initi‐
ated. 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 (Unreach‐
able, 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 speci‐
fication 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 trans‐
port.) 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 con‐
sider 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 ALSOpppd(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)
