ppp.Filter(4) ppp.Filter(4)
NAME [Toc] [Back]
ppp.Filter - PPP packet filter specification file format
DESCRIPTION [Toc] [Back]
The file /etc/ppp/Filter 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 [Toc] [Back]
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 IP address or the special word
`default', 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 IP address. The hostname
or IP 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 IP address in the
first column of the filter file, and associated with the link peer, is
unrelated to the source or destination IP 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' 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:
bringup 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 `pass' section.
pass Describes those packets that will be allowed to
traverse the link on an already-established
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
ppp.Filter(4) ppp.Filter(4)
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.
keepup Describes packets that will reset the idle timer,
thereby keeping the line connected.
log 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, 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 message types or codes (which can
be found in <netinet/ip_icmp.h>) along with the `/icmp' 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 is not 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.)
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. 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
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
ppp.Filter(4) ppp.Filter(4)
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
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.
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
ppp.Filter(4) ppp.Filter(4)
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 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
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 [Toc] [Back]
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:
# 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
The default behavior is no restriction of packets, and no logging.
Internet Firewall [Toc] [Back]
A `pass' line like this might be appropriate as a security firewall
between an organizational network and the larger Internet:
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
ppp.Filter(4) ppp.Filter(4)
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 `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.
An Extremely Complex Example [Toc] [Back]
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,
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003
ppp.Filter(4) ppp.Filter(4)
(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.
#
# 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:
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: August 2003
ppp.Filter(4) ppp.Filter(4)
#
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 [Toc] [Back]
Simpler filter specifications allow pppd 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 specification 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
Filter and Systems instead.
If you want to specify all Domain Name System traffic, use `domain'
which will be expanded to entries for both 53/tcp and 53/udp. (Some
DNS traffic uses each transport.) To allow queries but disable domain
transfers, use !domain/tcp. Similarly, some systems' older
/etc/services 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 123/tcp entry
along with the correct 123/udp. The correct solution is to remove the
123/tcp entry from /etc/services. A workaround would be to specify
123/udp in Filter.
DEC ULTRIX 4.2 and some other systems may have no entry for FTP's data
socket in their /etc/services 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 `ftp-data' to /etc/services, or use 20/tcp explicitly
in Filter. The former is preferable because it will cause the log
file entry to contain the symbolic name (`ftp-data') rather than the
socket/protocol notation.
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: August 2003
ppp.Filter(4) ppp.Filter(4)
If your /etc/services file is missing some application-level protocols
that you consider useful, you can populate it with entries from the
Assigned Numbers 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
/etc/services file as received from your system's manufacturer. If
you augment your /etc/services this way, then instead of using entries
like
pass !6000/tcp/syn/send
your Filter could use entries like
pass !x11/syn/send
which is much more readable. A list of TCP and UDP service numbers
and names, culled from the Assigned Numbers RFC, is available in
Examples/services.ex.
AUTHOR [Toc] [Back]
ppp.Filter was developed by the HP.
SEE ALSO [Toc] [Back]
ppp.Auth(4), ppp.Devices(4), ppp.Dialers(4), ppp.Keys(4),
ppp.Systems(4), services(4), pppd(1), RFC 791, RFC 792, RFC 1055, RFC
1548, RFC 1332, RFC 1122, RFC 1144, RFC 1340.
Hewlett-Packard Company - 8 - HP-UX 11i Version 2: August 2003 [ Back ] |
