PPP.FILTER(MST

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:

cause the link, if down, to be brought up
traverse the link
reset the idle timer , preventing the timer from expiring which, in turn, cause the link to shut down

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

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 created by blanks, tabs or newlines. If a newline is followed by white space, that line is a continuation of the filtering specification already in progress.

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.

The hostname or IP address in the first column of the filter file refers to the peer at the remote end of the point-to-point link, which may be a system or router or terminal server .
The hostname or IP address 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.

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:

IP protocol numbers which are optionally hyphen-separated ranges of TCP or UDP port numbers defined by the `/tcp ' or `/udp' qualifier
Numbers representing ICMP message types or codes along with the `/icmp ' qualifier. (ICMP numbers are listed in <netinet/ip_icmp.h>. )
Service names corresponding to entries in /etc/services
Names or IP address es of hosts or networks
The special keywords `all', or `!all'. The former, `all', is the default for all actions except `log', where the default is `!all '

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:

Allows NNTP (Usenet news) transactions with one peer and no others.

ex. pass nntp/137.39.1.2 !nntp

Allows incoming Telnet sessions from hosts on only one network

ex. pass telnet /syn /recv /137.175.0.0

Disallows all other incoming Telnet, SUPDUP, and FTP sessions
Allows all outgoing Telnet SUPDUP, and FTP sessions.
Allows X Window System clients running elsewhere to display on local window servers
Disallows local X clients to use displays located elsewhere.
Disallows all SUN RPC traffic, thereby guarding the local YP/NIS and NFS servers from outside probes and filesystem mounts.

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.

Blocks several other sorts of traffic that could be used for nefarious purposes
Allows passage of any traffic not explicitly blocked because the filter does not end with `!all'

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.

OSPF (Open Shortest Path First) routing packets, identified by the IP protocol number 89, 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

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 :

Allow any packet except those generated by NTP, ICMP Destination Unreachable, and rwhod . to bring up a connection to any neighbor except the host `backbone'

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.

Disallow outbound packets to reset the idle timer
Allow packets received from the peer to reset the idle timer
Hang up the connection and retry if the idle command-line argument has been specified when the peer goes down and modem problems cause the phone not to be hung up
Allow Domain Name System queries to bring up the link and keep it up if otherwise idle
In the special case of the host `backbone', such as a network connectivity vendor server, only bring up the link or keep it up if otherwise idle, for the following:

Þ telnet and FTP sessions
Þ SMTP electronic mail
Þ NNTP network news

Once the link is up, allow all the above plus NTP clock chimes and ICMP messages to flow across the link.
Block all packets to or from a particular host,
Block any packets except Domain Name System queries and responses for any host on subnet 42 of the class B network 137.175 and don't allow them to bringup the link. would they cause the link to be initiated
Allow telnet and FTP sessions only if they are initiated in the outbound direction.
Log one-line descriptions of various ICMP problem messages including Unreachable and Time Exceeded
Log the complete contents of ICMP messages reporting IP header problems. Log all telnet and FTP sessions, including inbound attempts (though they will fail because they are excluded in the `pass ' specification above
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 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.

PPP.FILTER(MST_PPP)

NAME