Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > P

ppp.Filter(4)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

ppp.Filter — PPP packet filter specification file format

DESCRIPTION

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

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 default or default6 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 associated 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 default for IPv4 packets and default6 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 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.

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/ICMPv6 message types or codes (which can be found in <netinet/ip_icmp.h> and <netinet/icmp6.h>) along with the /icmp or /icmp6 for ICMPv6 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 isnot 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.)

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 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. 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 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 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 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 unreach= 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 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 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 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 default6 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

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.

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 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, (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: # 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.

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.

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, selected from the Assigned Numbers RFC, is available in Examples/services.ex.

AUTHOR

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

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.