PPP.FILTER(MST_PPP)

NAME

ppp.Filter - PPP packet filter specification file format

DESCRIPTION

The file /usr/lib/mstppp/Filter describes how on-demand PPP links are managed. By default , any type of packet may:

These actions are not always appropriate and packet traffic should be controlled. The filter file allows individual control based on many of the packet's attributes and components, including type, source, destination, direction, and service. These selection criteria may be specified for any of the situations listed at the beginning of the paragraph.

The file /usr/lib/mstppp/Filter only filters packets on a PPP link. To filter packets on any kind of network (such as Ethernet or Token Ring), use the SCO Internet Security Package.

The details of the filtering which are recorded by a fourth activity, packet logging, may also be selected using packet information.

FORMAT

Hostnames and IP addresses

Lines beginning with a hostname or IP address or the special word `default ', are considered the beginning of a new set of filtering specifications. The filtering specifications are applied to any packet crossing the point-to-point link connecting the host to the peer named by that initial hostname or IP address.

Four Keywords

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 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.

Stanzas

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 contains 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:

The Special Keyword 'all'

Usually, it is unnecessary to use `all' because pppd automatically adds a `!all ' at the end of a stanza list if the last stanza is not negated or `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, and all others being passed.

Network Masks

If a network is specified, either by name or by address, 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 (!).

Log Filter Keywords and Flags

In the `log ' filter specification, the special keyword `trace ' causes the contents (as well as the 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.

The SYN Keyword

Pppd can distinguish between outbound and inbound packets, i.e. those which originate at the host versus those that originate at the other end of the link. TCP data streams are opened when the initiator sends a SYN packet to the intended recipient when using of TCP applications such as telnet or FTP. The special keyword `syn ' allows filtering or logging these connection-starting packets. Qualifying it with `recv ' or `send ' allows a session to be started or logged only if it is in the indicated direction. The special keyword `fin ' allows filtering or logging the packets that close TCP connections.

The `src' and `dst' Keywords

The `src ' and `dst ' keywords refer to source and destination and are used to distinguish a packet 's ports , addresses or hostnames.. If both are applied to the same stanza, e.g. /src/dst , both the source and destination address and/or port must match.

The `unreach' Keyword

The `unreach = ' keyword causes an ICMP Destination Unreachable message to be sent to the packet's source address , bearing the indicated code field, which may be chosen from the table shown below. The `unreach ' messages are described in RFCs 792, 1122 and 1812.

The currently available pnemonic ICMP Unreachable codes are:

# NAME
DESCRIPTION
0 net
The destination network is unreachable
1 host
The destination host is unreachable
2 prot or protocol
The designated transport protocol is not supported
3 port
The designated transport protocol (e.g., UDP) is unable to demultiplex the datagram but has no protocol mechanism to inform the sender.
4 needfrag
Fragmentation is needed and the Don't Fragment flag is set
5 srcfail
Source route failed
6 net-unknown
The destination network is unknown. This code normally should not be generated. It implies that the destination network does not exist. Code 0 (Network Unreachable) should be used in place of Code 6.
7 host-unknown
The destination host is unknown.
8 *
The source host is isolated. Routers should not generate Code 8; whichever of Codes 0 (Network Unreachable ) and 1 (Host Unreachable) is appropriate should be used instead.
9 *
Communication with the destination network is administratively prohibited. This code was intended for use by end-to-end encryption devices used by U.S military agencies. Routers should use the newly defined Code 13 (Communication Administratively Prohibited) if they administratively filter packets.
10 *
Communication with the destination host is administratively prohibited. Same reasoning as message 9 above.
11 net-tos
Destination network unreachable for the designated type of service
12 host-tos
Destination host unreachable for the designated type of service
13 prohibited
Communication Administratively Prohibited
14 precedence
Host Precedence Violation
15 precedence-cutoff
Precedence cutoff in effect
rst
This is a special keyword which will not send an ICMP Destination Unreachable message but instead a TCP RST packet.

The `ip-opt' keyword

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.
satid
SATNET Stream Identifier (obsolete)
ssrr
Strict Source Routing is used to route the internet datagram based on information supplied by the source.
sscrt
Either Loose Source Routing or Strict Source Routing
any
Any IP option, could even match the No Operation option.

EXAMPLES

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

A `pass ' 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

The `pass' Lines

The `pass specification:

ex. pass nntp/137.39.1.2 !nntp
ex. pass telnet /syn /recv /137.175.0.0
Alas, the `pass ' specification 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. UDP does not use the SYN and FIN packets that can be used to characterize the direction in which a TCP stream is being initiated.

The `bringup' and `keepup' Lines

The `bringup ' and `keepup ' lines are appropriate for an intermittent dialup connection, so that various error conditions won 't cause the link to be established, nor keep the call open beyond its usefulness.

The `log rejected' Line

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

The following Filter file provides these instructions for the PPP daemon :
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.

Þ telnet and FTP sessions
Þ SMTP electronic mail
Þ NNTP network news
#
# 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 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 .

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 1700. 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 augment /etc/services this way you can using Filter file entries like,

pass !x11/syn /send

which is much more readable than the alternative:

pass !6000/tcp/syn /send

A list of TCP and UDP service numbers and names, culled from the Assigned Numbers RFC , is available in Services.ex.

SEE ALSO

tun(MST_PPP), ppp.Auth (MST_PPP), ppp.Devices (MST_PPP), ppp.Dialers (MST_PPP), ppp.Keys (MST_PPP), ppp.Systems (MST_PPP), pppd (MST_PPP), RFC 791, RFC 792, RFC 1055 , RFC 1661 , RFC 1332, RFC 1122, RFC 1144, RFC 1700 RFC 1812.

COPYRIGHT INFORMATION

Copyright 1991, 1992, 1993, 1994, 1995, 1996 Morning Star Technologies Inc.; all rights reserved.