DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

MorningStar PPP User's Guide

Systems, Devices, and Dialers - An Analogy

This example may help describe how the Systems, Devices, and Dialers files work in conjunction to allow an on-demand outbound connection. Consider the analogy that can be drawn between the communication needs of a small business and the needs of a system which supports PPP connections.

Before opening the business, the owner assesses the company's communication needs. Obviously, its telecommunications system must support on-demand communications and inbound and outbound calling. The list of communications needs includes:

How are these pieces of the business' telecommunications system analogous to the pieces of the PPP configuration? The table below provides the answer:

Need
Pizza Business System
PPP Configuration
Communications access
a line to the telephone company's local switch over which inbound and outbound calls are transmitted

Could also need a dedicated line for security alarm

the same

Could also handle a dedicated, or Direct connection

Interface device
the telephone to answer or place calls
the system's modem (device), listed in the PPP Devices file
Memory for dialing information
the telephone's memory for storing numbers for one-touch dialing
the PPP Dialers file containing modem dialing instructions
List of potential communications partners
a telephone directory including numbers, addresses, and contact names
the PPP Systems file containing numbers, logins, and passwords

Of course, the contemporary business could have many other communications needs, such as voice mail, fax machines, Internet service, etc. But those listed in the table are, at least, supportive of outbound, dialed connections. Hopefully they help illustrate the way the Systems, Devices, and Dialers files support on-demand, outbound PPP connections.

Arranging for Outbound and Inbound PPP Connections

Throughout the following examples the local machine running MST PPP will be called robin. The peer, or remote neighbor, with which robin will establish an outbound connection to is called lark.

If you follow the steps outlined below, substituting names and addresses for your own local and remote machines, you will be able to test a simple PPP connection. These procedures are not comprehensive and contain minimal instructions about such things as setting up a packet filter for security. This, and configuration of other important PPP options, such as Link Management, Data Compression and Authentication, are explained elsewhere, and the manual pages in the appendix contain details on incorporating those features, and more, in your PPP configuration.

Overview

The steps for setting up an outbound PPP connection include:

The steps for setting up an inbound PPP connection include:

When these steps are completed and the system robin is re-booted, the following events will occur:

1. Autostart starts the daeomn for an on-demand connection from robin to lark.
2. If IP traffic is initiatied to lark, pppd will dial out to lark as follows:
3. pppd searches the lines of the Systems file looking for an entry in the name field which matches lark's hostname or IP address.
4. When the match of a hostname or IP address is made, the Systems speed field provides an index to an entry in the Devices file with a matching speed.
5. The dialer field in Devices provides an index to an entry in the Dialers file.
6. Lark's phone number is dialed.
7. Robin's chat script (in the Systems file), sends robin's login name and password to lark.
8. Lark verifies robin's password by comparing it to the entry in the /etc/passwd file.
9. If the login is successful, /usr/lib/mstppp/Login-robin is run.
10. /usr/lib/mstppp/Login-robin will start pppd on lark, which will comunicate with pppd on robin to negotiate and establish a PPP connection.

The Outbound connection

Autostart - starting pppd

When robin is booted a PPP daemon will be started for the outbond link to lark. There is no example /usr/lib/mstppp/Autostart file; you must create it. It contains the one line necessary to start pppd. In our example, here's what we would put in Autostart:

pppd robin:lark auto idle 150

The pppd started here has this connection configuration:

local and remote hosts
robin and lark
daemon management option
respond to the arrival of a packet by initiating a connection to peer (auto)
link management option
idle timer in effect (idle)
idle timer value
shut down the link if 150 seconds pass without receiving or transmitting a packet

Systems - Adding an Entry for Connecting to lark

Add this line to robin's /usr/lib/mstppp/Systems file:

199.199.199.2 Any ACU 38400 5551212 "" \r\d in:--in: \dprobin word: \qpassword

This provides the following configuration for robin's connection to lark:

call what host
lark
when
Any day any time (Any)
using what device
Any Call Unit that matches the speed in the next field (ACU)
at what DTE speed
38400 BPS (38400)
at what telephone number
5551212
expect what string
in: substring of login: if true, send next field. If false, send string between dashes followed by carriage return and expect in: Can be used to elicit a response out of peer.
send what string
send Probin followed by a carriage return (implicit)
expect what string
word: a substring of password:
send what string
mypasswd followed by a carriage return (implicit)

Devices - Adding an entry for Connecting to lark

Add this line to robin's /usr/lib/mstppp/Devices file:

T1600 tty1A 38400 rtscts

This line provides this configuration for robin's connection to lark:

use what modem
Telebit model 1600 (T1600)
on which system device
outbound device (tty1A)
at what speed
38400 BPS (38400)
optional parameters
hardware flow control (rtscts)

Dailers - Adding an entry for Connecting to lark

The /usr/lib/mstppp/Dialers file is already installed on robin. Here's what the Telebit 1600 entry looks like:

T1600 ABORT NO\sCARRIER ABORT NO\sDIALTONE ABORT BUSY \ ABORT RRING\r\n\r\nRRING\r\n\r\nRRING ABORT ERROR \ TIMEOUT 5 "" AT OK-AT-OK ATS111=0DT\T TIMEOUT 60 CONNECT

This elaborate dialer string will cause pppd to abort the connection attempt if any of several things go wrong with the telephone call, then will disable UUCP spoofing in the modem before dialing the destination telephone number. Look through the Dialers file for modem entries for your type of modem. If none are defined, use the dialer entry "GENERIC".

Connection among the configuration files

The peer's machine name, lark, is used as an index into the Systems file. The first matching entry found is used. The DTE speed in the Systems file is used as an index into the Devices file. Lastly, the dialer entry specified in the Devices file is used as an index into the Dialers file.

The inbound connection

Adding an account for robin to login to lark

Although may bot initiate outbound calls, and therefore may not have to start pppd at boot time, it does need to be prepared for an inbounc connection from robin. To do this, add this entry to lark's /etc/passwd file and execute the following command:

Probin::105:42:Robin's PPP login:/usr/lib/mstppp:/usr/lib/mstppp/Login-robin # passwd Probin New password: some password Retype new password: some password #

The '105' in the password entry is a unique user ID (uid) for this PPP login. The '42' is the group ID (gid) associated with the 'ppp' group in lark's /etc/group file.

Creating robin's Login Shell Script

Robin's PPP user's login shell script can be located anywhere and named whatever you choose. For purposes of this illustration, the login script will be /usr/lib/mstppp/Login-robin. Look carefully at the last line in the sample script shown below before you create the file and manually add the lines. Notice that the word 'hostname' is surrounded by backquotes, not regular quotes or apostrophes. `hostname`, with the backquotes, tells the system to insert the output of the command hostname in this space in the pppd command line. We recommend that you make sure backquotes are used by copying this script from /usr/lib/mstppp/Examples/Login.ex, rather than inserting them manually.

#!/bin/sh # PPP login shell example for SystemV Unix PATH=/usr/bin:/usr/lib/mstppp:/etc:/bin PPPHOME=/usr/lib/mstppp export PATH PPPHOME mesg n stty -tostop exec pppd `hostname`:robin idle 150 rtscts

hostname will return lark, the current machine and robin is the peer. The idle timer is set to 150 seconds and pppd will use hardware flow control.

Checking Permissions

Following the creation of the shell script, make sure the script is executable with the following command:

# chmod 755 /usr/lib/mstppp/Login-robin

Lark's PPP daemon should be mode 4750, meaning it is suid root and executable by members of its group, but not by general users. Perform this test to find out if this is true:

# ls -l /usr/lib/mstppp/pppd

The results should look something like this:

-rwsr-x--- 1 root ppp 338527 Oct 2 07:37 /usr/lib/mstppp/pppd

If not, use chmod and chown to change mode and ownership as follows:

# chmod 4750 /usr/lib/mstppp/pppd # chown root:ppp /usr/lib/mstppp/pppd

Testing the robin-lark link

The PPP configuration is now complete. Follow these steps to test the outbound connection from robin to lark.

  1. You can either reboot your machine or run /usr/lib/mstppp/Sysinit to start pppd.
  2. Check to make sure pppd was started:
  3. Use telnet to bring up the link and type ^D to exit the login. There will be a half minute pause while robin dials the phone, the modems establish a carrier, the Systems chat script completes, the answering pppd is started on lark, and the two pppd's negotiate.

    Pause

The log file will be appended to and will show how the link was initiated:

8/4-14:14:53-14902 tcp 137.175.2.11/1204-> 131.187.1.131 \ telnet 40 syn bringup 8/4-14:14:54-14902 Dialing lark (cua 38400 5551212 T1600) 8/4-14:15:23-14902 PPP connected to 131.187.1.131

This log file snippet shows that the telnet session to lark caused the link to be initiated.

MST PPP is installed, configured, running and connected on both ends of our links. When the link is up, users should be able to access each peer machine using any TCP/IP application such as telnet, ftp, etc.

If either machine is connected to a local area network, you can set up IP routing on the two networks so that hosts on either network can communicate with hosts on the other, using machines on the ends of the PPP links as routers. Routing is discussed in later sections.

Additional Information

Non-Generic Login Scripts

In most cases, all inbound PPP logins can use the same generic Login script. But if you want a host to start pppd with a special option like "require authentication", make that login account use a specific login shell tailored to that host. Call it /usr/lib/mstppp/Login-host, for example, and change the pppd line to reflect whatever options you wish to have:

exec pppd `hostname`:robin idle 130 rtscts requireauth

Creating a Simple Filter File

Note: A filter file is not necessary for pppd operation. It is only discussed here as an example on how you might use the Filter file.

The MST PPP Filter file specifies the ways in which static packet filtering handles outbound and inbound TCP packets. Though the filtering can be very complex if desired, a simple filter will suffice for demonstration purposes between robin and lark.

An example other than the one shown below is in /usr/lib/mstppp/Examples/Filter.ex and a lengthy explanation of static packet filtering is included in this manual.

Here is the Filter file to use for testing the robin-lark link:

default bringup !ntp !3/icmp !who
keepup !send !ntp !3/icmp !who
pass !route
log !nntp tcp/syn /recv

This filter says to:

bringup the connection for any traffic other than:

    Network Time Protocol packets
    ICMP Network Unreachable messages
    packets from the in.rwhod daemon

(!ntp)
(!3/icmp)
(!who)
keepup the link for all packets except those sent by robin
and those that will not bringup the connection
(!send)
(!ntp) (!3/icmp) (!who)
pass all packets except for RIP routing messages between in.routed daemons
(!route)
log messages when an inbound TCP session is established
except for NNTP connections
(tcp/syn /recv)
(!nntp)

Note on Systems and Devices Entries

In both Systems and Devices, pppd selects the first line that matches its search criteria. If the connection attempt fails while using the method described by that line, pppd will search for the next matching line. Pppd will report a failure only when all the criteria-matching lines have been tried and exhausted.

For example, suppose two lines in Systems differed only by the values in the telephone number field like this:

lark Any;50 ACU 38400 5551212 in:--in: Probin word: mypasswd
lark Any;50 ACU 38400 5551223 in:--in: Probin word: mypasswd

Pppd would first try to connect by dialing 5551212. If pppd received a BUSY from the modem, it would dial the second number, 5551223.

Similarly, suppose a host has two different modems attached which can be used for outbound calls. The Devices entries might look like this:

T3000 tty1A 38400 rtscts
USRv32bis tty1B 38400 rtscts

Pppd would try to call out through /dev/tty1A. But suppose it's busy because an incoming UUCP connection is on /dev/tty1B. pppd will try /dev/tty1B instead.

IP Addresses on the pppd Command Line

Soft Addresses

If an IP address is input on the pppd command line, the address is offered during IPCP negotiations. However, at connection time, some terminal servers and other peers wish to assign an address for the host running MST PPP to use for the duration of the connection. Instruct MST PPP to allow assignment of an address that's different from the one on the pppd command line, by including a line like the following:

pppd `hostname`:192.0.2.5 auto idle 300

Because SLIP does not perform any IPCP negotiations, the tilde option will not function. See Common pppd Options for more information.

Dynamic address assignment

When an answering pppd is invoked in Login, it is told a pair of IP addresses on the command line. In the Login script, use any means to decide what IP addresses are put on the command line. Have them looked up in a file or a database, calculated algorithmically based on the incoming connection's username or other distinguishing feature, or invoke a program to ask a BOOTP server. The pppd command line arguments provide the mechanism; your Login script provides the policy.

Address Selected From a Small List

Here's an example Login script that uses the tty name to guarantee uniqueness of the addresses it assigns. This works fine for a small installation with few modem server serial ports and a fairly static configuration.

#!/bin/sh
TTY=`tty`
case $TTY in
/dev/tty1)
IP=192.0.2.1
;;
/dev/tty2)
IP=192.0.2.2
;;
esac
exec pppd `hostname`:$IP idle 300 rtscts

Address Calculated From tty Name

This script also uses the tty name to guarantee uniqueness of the addresses it assigns. You must define ttyN in your /etc/hosts file, NIS hosts map, NetInfo hosts map, or DNS database, according to the system used. This works better in a larger installation with more ports and a configuration that tends to change more often.

#!/bin/sh
TTY=`/bin/basename \`/bin/tty\``
exec pppd `hostname`:$TTY idle 300 rtscts

Security Techniques

It's impractical to impose thorough security policies on each internal host of the networks linked by an MST PPP connection. But MST PPP's strong security features support a variety of techniques that strengthen your network's ability to prevent loss.

In most cases, a single connection can be supported by more than one of MST PPP's security features. For example, a connection might use the following:

These features, and others, are discussed in the sections below.

Static Packet Filtering

Introduction

We recommend that you establish a security policy before you write a packet filter. A security policy is a statement based on thorough analysis of access needs, vulnerabilities, and real, or perceived, threats to your assets. You must identify the types of network traffic associated with these issues before you can create a packet filter that supports your security policy.

Morning Star Technologies' flexible filter-writing mechanism will also support your policy as you create your filter. Our philosophy is to provide a mechanism that won't force policy changes for the sake of writing acceptable rules.

The Foundations of Security Policies

In general, all security policies are based on one of two opposing strategies. Both types of policies are supported by MST filters.

The first strategy permits a few specific services and blocks everything else. If you follow this philosophy, a service will be unavailable if you commit an error of omission. This is a fail-safe, or closed, policy.

The second strategy blocks only specific services and permits everything else. If you begin from this premise, an error of omission may leave you unintentionally vulnerable when a fragile service is not blocked.

If you need aid in developing security policies, or would like more general information about network security and packet filtering, we recommend you begin by reading two books, "Firewalls and Internet Security " by Bill Cheswick and Steve Bellovin and "Building Internet Firewalls" by Brent Chapman and Elizabeth Zwicky.

Filter File Rulesets

Filter Basics

When pppd starts, the software checks for a filter file. If one is present, it is parsed and installed. The default filter filename for pppd isFilter'. If you want to give the file a different name, specify the new name as the argument for the pppd `filter' option. Only add the filter option if you want to change the name of the filter file.

A filter file contains rulesets for filtering packets. Each ruleset begins with one of the following:

You may write a specific ruleset for each connecting host, or a default ruleset will be used. The pppd parser will search for a ruleset that matches the IP address or hostname of the remote PPP/SLIP host, called the peer. This usually corresponds to the IP address placed on the right hand side of the colon on the pppd command line.

Ruleset Design

Hostname or IP Address

Rulesets are designed on a per-connecting-host basis rather than a per-interface basis. This provides support for devices acting as PPP or SLIP routing hubs. A hub workstation allows multiple hosts to establish IP connections and may support multiple hosts establishing connections at different times on the same interface.

If a hub supports different classes of users, MST PPP filters allow you to define different access policies for each group. A single hub workstation may support all of the following PPP/SLIP connections, each defined by a different ruleset:

Default Rulesets

Default rulesets are permitted. They simplify configuration when a single machine supports similar multiple hosts/connections which can be controlled by the same security policy.

Ruleset Order

The order in which rulesets appear is important. Default rulesets should appear early in the file because, after they are parsed, the parser continues searching for more matching rulesets. However, when addresses or hostnames in packets and rulesets match, the packet is processed and the parser stops its search.

When a match is found and the `non-default' ruleset is processed, its individual filters replace any default filters "remembered" from earlier in the file. This means that packet filtering may behave differently if thedefault' rule appears early or late in the file.

The Four Filters

A ruleset is made up of one to four filters which regulate the response to a packet. The filter's actions are defined by its initial keyword. Each type of filter may be used one time per connection. This table explains the keywords, the types of packets affected by the filters, and the filter's actions:

KEYWORD
PACKET TYPE
ACTION
bringup
outgoing dialup
defines packets which cause a connection to be established
keepup
inbound and outbound
dialup
defines packets which cause the idle timer to be reset, preventing the connection from going down
pass
all packets
defines packets which are allowed to pass through the filter. packets which don't pass don't bringup
log
all packets
defines the characteristics which will cause a message about a packet to be added to a log file

Defined and Default Filters

Filters defined in a ruleset replace any previous default definition for that filter. Defined filters are not additive with a default filter. If one of the keyword filters does not appear in a ruleset, that filter is defined by its the most recently parsed default ruleset. If there is no previous default ruleset, the implicit default is `all', except for the log filter, which defaults to ` !all'.

Filter Stanzas

Each filter is composed of a filter name followed by one or more stanzas (i.e., rules). Each packet passing through the interface is compared to the rules in the stanzas until a match is found, completing the filter operation. The ordering of the stanzas is therefore extremely important. Packets may match on many types of values, including:

Use of the Exclamation Mark to Negate

A stanza optionally begins with the negation operator, the exclamation mark (!). The mark is followed by one or more values and keywords, each separated by a slash (/). These value and keyword combinations create a specification for a packet.

An exclamation mark is a powerful specification in any filter rule. If an exclamation mark is placed at the beginning of a rule, it negates the action of the stanza's keyword. For example, compare the defaults for the Pass and Log filters:

Pass
all
Log
!all

The specification for Pass, and the lack of an exclamation mark, indicates the default is to pass all packets. On the other hand, the `!all' default designation for Log means no packets are logged.

Implicit Filter Endings

Each filter ends with an implicit stanza. The implicit ending stanza is `all' if the last stanza specified is negated by beginning with `!'. The implicit ending stanza is `!all' if the last stanza is not negated. While this is convenient and makes it unnecessary to actually define the final "match everything else" stanza, it is a good idea to explicitly specify this stanza to avoid simple errors that can greatly change the meaning of a filter.

Packets Overview

Each stanza represents a template used to find matching packets. The features you can place in your stanzas correspond to the fields in network messages. This allows you to filter at the IP level or the TCP /UDP/ICMP level.

IP - The Internet Protocol

The fields available at the IP level include the protocol (e.g., 1
[ICMP], 2 [IGMP], 6 [TCP], 8 [EGP], 17 [UDP], etc.), an address
(i.e., the source or destination address) and IP options (e.g., rr,
lsrr, etc.), and fragmentation.

MST does not provide a filter keyword for matching the version,
IHL, TOS, length, ID, TTL or checksum header fields.

ICMP - The Internet Control Message Protocol

ICMP messages may be filtered on the type and code fields.

In general, it is not a good idea to block all inbound or outbound ICMP messages because ICMP messages are an important way that status information is conveyed over an IP network. For instance, blocking ICMP Source Quench messages (Type 4), used to tell a packet source to slow down, can cause problems for other users and sites.

It is true that you should probably not permit ICMP Redirect messages (Type 5) to pass through your router since the routing on an internal node should not be changed by an external site.

If you want to block ping from being used for host discovery, then you should block inbound ICMP Echo packets (Type 8).

TCP - Transmission Control Protocol

The TCP header fields available for matching include port numbers (i.e., the source or destination port), the presence of the SYN bit without ACK, and the ACK, FIN and RST bits.

MST does not provide a method for filtering on TCP options, the presence of URG/EOM bits in the TCP options, or other TCP header fields.

Establishing a TCP connection requires synchronization. Each side must send it's own initial sequence number, receive a confirming acknowledgment from the other end, receive the other end's initial sequence number and send the confirming acknowledgment.

The steps in the sequence look like this:

Step Path TCP Bit Message
1 A B SYN my sequence number is X
2 A B ACK your sequence number is X
3 A B SYN my sequence number is Y
4 A B ACK your sequence number is Y

Packets 2 and 3 are normally combined into a single "SYN ACK" packet. This is called a three way handshake.

The SYN bit is set, with no ACK bit set, to show a TCP connection request. By blocking packets with the SYN bit set in a single direction, you may permit TCP connections in a single direction.

UDP - User Datagram Protocol

The UDP header fields available are the source and destination port numbers.

UDP does not permit a router to differentiate between inbound packets requesting new services and inbound packets returning data to outbound requests. This means that static filters which allow inside users access to services based on UDP also allow outside users to access the same service inside your network.

Recommended Reading

If the diagrams and information shown above are difficult to follow, we highly recommend these books on networking and the TCP/IP protocols:

Title: Computer Networks, 2nd edition
Author: Andrew S. Tanenbaum
Publisher : Prentice-Hall
Edition: 1988
ISBN: 0-13-162959-X

Title: Internetworking with TCP /IP Vols I, II and III
Authors : Douglas Comer and David Stevens
Publisher : Prentice-Hall
Editions: 1991 - 2
ISBN: 0-13-468505-9 (I), 0-13-472242-6 (II), 0-13-474222-2 (III)

Title: TCP /IP Illustrated: the protocols
Author : W. Richard Stevens
Publisher : Addison-Wesley
Edition : 1994
ISBN : 0-201-63346-9 (v.1)

Building a Stanza - General

Listed below are some general concepts to remember when writing a stanza:

Building a Stanza - Specifics

The section below explains how different features of a stanza should be written and the ways you include them in a stanza to affect the operations of the filter. The features are described in subsections which include a general explanation, an example, and a comment on the action caused by the example. The comments are shown on the same line as the example and begin with a `#' character.

We recommend that readers who are unfamiliar with filtering take the time to read this section from beginning to end. The topics and examples build on one another. Therefore, skipping through the examples, you may see references to keywords you do not recognize or miss the significance of relationships between some keywords. These topics are covered:

Numbers and Addresses

Numbers with no Qualifiers

A number by itself, without an associated protocol name such as tcp or udp, represents an IP protocol number. IP protocol numbers have a range of 0-255 and are assigned by the Internet Assigned Number Authority (IANA). The current list of IP protocols can be found in the ASSIGNED NUMBERS RFC.

Example:
!89 # block Open Shortest Path First (OSPF) Interior Gateway
# Protocol (IGP)

IP Addresses

An IP address may be represented in hexadecimal (e.g., 0xc0000201) or dotted quad (e.g., 192.0.2.1) notation and represent either a host address or a network address. Network addresses are simply used to represent contiguous ranges of hosts and therefore do not necessarily correspond to actual networks. A network address uses all zeros for the host portion of the address.

Example:
!192.168.199.1 # block packets to/from host 192.168.199.1

Netmasks

You must specify a netmask if the host portion of the network address does not match the "natural" netmask. A netmask may be represented in either hexadecimal or dotted quad notation. A network address must also be present or the netmask will be assumed to be an IP address.

Example:
10.7.123.0/255.255.255.0 # permit 10.7.123.0-10.7.123.255

Alternatively, you may specify the netmask after the address using a semicolon followed by the number of one bits in the network mask.

Example:
10.7.123.0;24 # permit 10.7.123.0-10.7.123.255

Keywords with Numbers

A number of keywords can describe features of the packets, including data within the packet header and the direction of travel.

IP Protocol keywords

Keywords exist for the most commonly used IP protocols, `tcp', `udp', and `icmp'. Use these keywords to prevent ambiguity when specifying port numbers or types. You must use `17/tcp' or `6/udp' to avoid ambiguity.

Port Numbers

`udp' or `tcp' combined with a number represents a port number.

Example:
25/tcp # permit SMTP mail

You may specify a range of ports using a hyphen-separated pair of numbers.

Example:
!0-1023/udp # block privileged UDP ports

Port Numbers and Services

Many systems provide a list of well known UDP and TCP port numbers in a services file or they supply contents of the file through a database service such as NIS or NetInfo. Filter stanzas may use the symbolic names for these port numbers.

Example:
smtp # permit SMTP (25/tcp) service

However, symbolic port names (i.e., services) can be ambiguous. For example, `domain' may be either `tcp' or `udp' port 53. When using keywords that are specific to a protocol like TCP, you must add the `tcp' keyword to the stanza to avoid errors.

Example:
!domain/tcp

Services are not the same as applications or protocols. Specifying `!telnet in the filter file does not prevent the `telnet' application from talking to the `smtp' port on the host, nor does it prevent someone from using the telnet protocol to talk to a telnet daemon (telnetd) running on a port number other than 23.

Numbered ICMP Messages

` icmp' with a single number represents an ICMP message type. `icmp' with two numbers represents a specific ICMP type and code combination. ICMP type and code values can be found in the ASSIGNED NUMBERS RFC3 or in the /usr/include/netinet/ip_icmp.h file directory on many systems.

Example :
!icmp/5 # block ICMP Redirect messages

Example:
!3/0/icmp # block ICMP Unreachable "bad net" messages

Keywords with Origins and Destinations

Frequently, a host acts as a router between two end points so packets may not originate or terminate at that host. Use the `src keyword to specify the point of origin or source and the `dst keyword to specify the endpoint or destination. The source or destination can be either an IP address or a service or port.

Example:
route/dst # permit packets to UDP port 520 on any host

The `src or `dst keyword applies to all addresses and ports in the stanza. Thus, you cannot specify both the source port and destination address or vice versa in the same stanza using the `src or `dst keywords.

Example:
10.0.0.1/route/dst # permit UDP packets to 10.0.0.1 port 520

Even more specific rules may be written by using the keywords `srcport', `dstport', `srcaddr', `dstaddr', `srcmask', and `dstmask' keywords in place of `src or `dst. The syntax of these keywords is `keyword=value'.

Example:
!srcaddr=10.7.127.0/srcmask=255.255.255.0/dstaddr=192.168.5.0

# block packets between the 10.7.127.0-10.7.127.255 and
# 192.168.5.0-192.168.5.255 networks

The workstation running the daemon is your point of reference regarding the direction of a packet. Packets written by the host are outbound, or sent, and are specified by the `send keyword. Packets read by the host are inbound, or received, and are specified by the `recv keyword. The two rules in the following example prevent spoofed packets for an internal network 192.168.12.0.

Example:
!recv /src /192.168.12.0
# block receiving packets from outside which claim to
# be from 192.168.12.0-192.168.12.255
!send /dst /192.168.12.0
# block sending packets to outside which claim to be # going to 192.168.12.0-192.168.12.255

Keywords based on TCP Packet Header Bits

Some qualifiers (i.e., keywords) may only be used in combination with other
qualifiers. For example, `syn, `fin, `rst', `ack' and `estab' are options or fields in TCP packet headers and may only be used when the qualifier `tcp' is directly stated in the rule or implied by a TCP protocol service. If the definition of a service allows it to use TCP and UDP packets the `tcp' qualifier must be explicitly added to the service name in the rule.

Example:
!tcp/syn /recv # block inbound TCP connection requests
smtp/syn # permit SMTP (25/tcp) connection requests
domain/tcp/syn # permit DNS (port 53) TCP connection requests

The `syn' Qualifying Keyword

A rule which qualifies a session with `recv or `send prevents the session from being started or logged unless it is initiated in the indicated direction. The initiator sends a SYN packet to the recipient to open a TCP data stream. This permits the filter to distinguish between outbound and inbound uses of TCP applications such as telnet or FTP. The special keyword `syn allows you to filter or log these connection starters. Unlike most other qualifiers, `syn' is actually a compound qualifier that tests for just the initial packet, which has a SYN bit set but not the ACK bit.

Using Other Keywords based on TCP Packet Header Fields

Keywords based on IP Options

The `ip-opt=' keyword can be used to select packets based on whether they bear various IP options, including those described in the table below:

OPTION
DESCRIPTION
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
srcrt
Either Loose Source Routing or Strict Source Routing
any
Any IP option including the `No Operation' option.

Example:
!ip-opt=srcrt # block source routed packets

The `frag' Keyword

The `frag' keyword permits filtering of IP fragments. When IP packets are larger than the media permit, the datagram can be fragmented into smaller segments, transmitted, and reassembled at the destination. IP datagrams can be up to 65,535 bytes long, but most physical networks do not support datagrams that large. Ethernet supports datagrams 1500 bytes long. SLIP's default is 1024 bytes.

The `all' Keyword

The special keyword `all' matches any packet. It typically appears at the end of a filter to either permit or block all unspecified packets. The software automatically implicitly adds `!all' at the end of a stanza list if the last stanza is not negated, and `all' at the end of a stanza list if the last stanza is negated. While not strictly necessary, it is a good a idea to explicitly state your preference.

Time Based Keywords

You may add time-based restrictions to your packet filter, limiting the types of traffic passing through the packet filter during the workday, or enabling additional access after business hours or on weekends.

Two keywords define time-based rules. They are the `weekday' and `daytime' keywords.

The syntax for using the keyword `weekday' in a qualifier is weekday=when', where `when' is a string indicating the days the rule should be applied. The `when' portion may be a list containing any of `Su', `Mo', `Tu', `We', `Th', `Fr' or `Sa'.

Example:
!ftp /syn /send /weekday=MoTuWeThFr

#prevents any weekday outbound ftp connection requests

The syntax for the keyword `daytime' qualifier is `weekday=time', where `time' is a string that indicates the hours of a day the rule should be applied. You may indicate hours in a range (for example, `daytime=0800-1800').

Example:
!ftp /syn /send /weekday=MoTuWeThFr/daytime=0800-1800
#prevents weekday outbound ftp connection requests
# between 8am and 6pm.

The Unreach Keyword and Sending ICMP Messages

In addition to permitting the packet to be passed or blocked, keywords also allow you to specify additional actions to take with any packet that matches the template. For example, you can silently drop the packet and/or send an ICMP message to notify the sender of the action.

The `unreach =' keyword causes an ICMP Destination Unreachable message to be sent to the packet's source address, bearing the indicated code field. The ICMP Code may be specified numerically or mnemonically.

Example:
!ip-opt=srcrt/unreach=srcfail # block source routed packets and notify #sender of failure
!tcp/113/unreach=1 #block RFC1413 Identification Protocol packets and #send a Destination unreachable host message.

The currently available pnemonic 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 Log and Trace Keywords

Use the keywords `log' and `trace' to log actions taken by the packet filter or dump the contents of the matching packet (in hex) to the system log.

Example 1:
!frag/trace # block and dump the contents of any IP fragment
# received

Example 2:
tcp/syn /send /log # pass and log all outbound TCP connection
# requests

There are two ways to invoke the `log keyword. The log filter allows you to define, in one location, all the packets you wish to log. Or you can add the log keyword to the individual rules in the `pass filter as shown in the above examples. Generally, it is easier to add a rule in the log filter requiring all rejected packets be logged rather than adding a `log' qualifier to all rules that block packets.

Stanza Syntax

The syntax of a stanza is very flexible. In general, the order of the values and keywords in the stanza are not fixed, although certain combinations of keywords are not allowed. The rules that do exist are:

Example:
The following rules describe the same packet filtering, and would cause the same template to be invoked.

Example 1:
!telnet /syn /recv /192.0.2.0/255.255.255.0

Example 2:
!192.0.2.0/recv /syn /255.255.255.0/telnet

Writing a Stanza

A Complex UDP example Concerning DNS Queries

The following section describes the writing of a rather complex packet filter involving the Domain Name System (DNS). It provides a good example of why you need to understand the applications in use when writing packet filters. It also shows the difficulty of writing static packet filters for UDP packets without permitting inbound network access in order to permit outbound service.

A brief explanation follows each rule. The explanation attempts to illustrate the security considerations which prompted the creation of the rule.

An Unsafe Domain Name System Rule

Your security policy should allow access for packets that need to cross the link to fulfill your needs, while still keeping out as many unrelated packets as possible. Look at the following example of a rule concerning domain name queries. It is one of easiest rules you could add to permit domain name queries, but it is also the most insecure.

1. domain/udp

Think of the stanza as though it were translated into this simple pseudo-code:

if
protocol is UDP AND
source or destination port is domain (53)
then
permit the packet to pass

This means that a user on an outside host sending a UDP packet from port 53 could reach ANY UDP destination port on ANY host on your local network, including privileged ports used by other services. This would not be "safe".

What Happens During Domain Name Queries

In the simplest case for domain queries, hosts on your network will send all `domain requests to your domain name server. Your server will check to see if it has the information cached. If not, it will query other domain name servers on the Internet to obtain the information.

The packet exchange will look similar to those shown below, where the entries mean the following:

dns.domain any.domain # the outbound domain request
dns.domain any.domain # the inbound response to the request

In appearance, this is similar to an actual log file entry. The diagram explains fields in a normal log entry.

udp 192.168.199.11/domain -> 10.0.5.1/domain 124
^ ^ ^ ^ ^ ^ ^
| | | | | | |
| | | | | | + packet size (bytes)
| | | | | + foreign port
| | | | + foreign address
| | | + direction
| | + local port
| + local address
+ protocol

Developing Safer Domain Name Request Rules

An Exercise in Simplifying Rules
This section illustrates a process you might go through to develop domain name rules. Throughout the steps, the illustration includes two paths you might take. The first shows how individual rules might be developed. The second shows how the first rules can be condensed with the same results. After each group of rules, we will evaluate the progress, considering loopholes which might be created by the way the rules have been written. Throughout the examples, we will use 192.168.199.11 to represent the IP address of the domain name server.

Step 1 Handling Domain Name Requests

The first example attempts to map each packet description into a separate rule to permit these packets through the pass filter. This results in two rules similar to the following:

a) udp/srcaddr=192.168.199.11/srcport=domain/send /dstport=domain
udp/dstaddr=192.168.199.11/dstport=domain/recv /srcport=domain

Alternatively, group (a) can be combined and simplified into a single rule similar to:

2) udp/192.168.199.11/dstport=domain/srcport=domain

Both the outbound request and the inbound response match this template and no packets to UDP ports other than domain (53) are permitted by the rule.

Domain Name Requests from Other Domain Name Servers

In general, domain name servers on the Internet will also want to query your domain name server to obtain information. The packet exchange will be very similar to the outbound request but reversed in order:

dns.domain any.domain # the inbound domain request
dns.domain any.domain # the outbound response to the request

This means that both the individual rules in example (a) and the combined rule in example (2), which were created to handle requests from outside hosts, are still functionally correct.

Step 2 - Rules for Domain Name Requests from Applications

There is a limitation associated with rules (a) and (2) concerning domain name queries. It arises because not all queries from the Internet will come from a domain name server. Some will come from applications, such as `nslookup or `host' that use an unprivileged port (i.e., a port in the range of 1024-65535).

The packet exchange for such an inbound domain query resembles the following, where `unpriv is any port from 1024-65535.

dns.domain any.unpriv # the inbound domain request
dns.domain any.unpriv # the outbound response to the request

Because the query comes from an unprivileged port, you will need to add two additional rules to example (a) to cope with the new packets. You will now need four stanzas to deal with domain queries.

(b) udp/dstaddr=192.168.199.11/dstport=domain/recv /srcport=1024-65535
udp/srcaddr=192.168.199.11/srcport=domain/send /dstport=1024-65535

In this situation, if you combined the original rules as in example (2), it can be modified to permit the inbound request by removing the restriction on `srcport'. However, the revised rule (2) will still block the outbound response, causing the query to fail. To permit the outbound packet, you must add another rule following rule (2). Call it rule (3).

(2) udp/192.168.199.11/dstport=domain
(3) udp/srcaddr=192.168.199.11/srcport=domain/send /dstport=1024-65535

Comparing the examples (a) and (b) to examples (2) and (3), you have reduced the number of rules needed from 4 to 2.

Checking the Outcome of Simplifying in Step 2

When trying to simplify, it is important you double-check your assumptions. You should not use "udp/192.168.199.11/srcport=domain", although it would permit the query to succeed, because it will also match packets that should not be permitted. That rule is similar in function to this pseudo-code that follows it.

(2) udp/192.168.199.11/srcport=domain

if
protocol is UDP AND
source or destination IP address is 192.168.199.11 AND
source port is domain (53)
then
permit the packet to pass

This means an outside host sending a UDP packet from port 53 to 192.168.199.11 can access ANY destination port, including privileged ports used by other services. This would not be "safe".

Similarly, if an internal user on the domain name server uses an application such as `nslookup' to send a query directly to another domain name server, rather than sending the query to the local domain name server, the packet traces and rules needed to deal with them will change.

dns.unpriv any.domain # the outbound domain request
dns.unpriv any.domain # the inbound response to the request

Step 3 - Matching Packets as Closely as Possible

If you want your templates to match the packets as closely as possible, you must add two further rules (c) to (a) and (b). You now have 6 rules if you have not attempted to condense the rules.

(c) udp/srcaddr=192.168.199.11/srcport=1024-65535/send /dstport=domain
udp/dstaddr=192.168.199.11/dstport=1024-65535/recv /srcport=domain

If you have simplified rules (a) and (b) and have used rules (2) and (3), the additional packets also cause rule (3) to block some of the necessary traffic. This is because the inbound packet, while originating from the domain port, does not have a source address of the domain name server. After making the change to accommodate the differences, by removing the restriction on direction (`send) and relaxing the restriction on address, you have replaced rule (3) with the edited rule resembling (4).

(2) udp/192.168.199.11/dstport=domain
(4) udp/192.168.199.11/srcport=domain/dstport=1024-65535

Step 4 - Minimizing External Control of Data Passing through the Packet Filter

Up to this point, the rules have always been based on the trust of data under local control. With static filtering, the second rule now permits data that is under external control through the packet filter.

if
protocol is UDP AND
source or destination IP address is 192.168.199.11 AND
source port is domain (53) AND
destination port is in the range 1024-65535
then
permit the packet to pass

This means that an external host can send UDP packets from port 53 to any unprivileged port on the domain name server without requiring an internal initiator. Unfortunately, there are a number of assigned ports, such as the normal default NFS port (2049/udp), which are allocated out of the unprivileged port range and can present security problems. You can minimize the risk by reducing services on your domain name server and by adding additional rules to block access to those services before the second rule. If you explicitly block access to the port first, the packet will not reach the rule that gives it permission to pass because the filter will stop as soon as a match is found.

Finally, an internal user on a local host other than the domain name server may use the `server' command of `nslookup' to change the default server. In this case, the packet will not be sent to the local domain name server but directly to the external domain name server.

any.unpriv any.domain # the outbound domain request
any.unpriv any.domain # the inbound response to the request

Once again, permitting the traffic to pass requires adding two additional rules, labeled (d) in the example, to group (a) (b) and (c). Now there are a total of 8 rules.

(d) udp/srcaddr=192.168.199.0/srcport=1024-65535/send /dstport=domain
udp/dstaddr=192.168.199.0/dstport=1024-65535/recv /srcport=domain

The condensed version of the rules also requires that rule (4) be modified to permit proper operation. The modification is required because the outbound packet has a destination port domain, but it is not to or from the IP address of the domain name server (192.168.199.11). After removing the IP address restriction, the final set of simplified rules is:

(2) udp/dstport=domain
(5) udp/srcport=domain/dstport=1024-65535

Conclusion

Domain name service offers a strong example of the tradeoff between functionality and security. It also illustrates the complexity of maintaining security. The level of service you decide to offer should strongly affect the rules you use. Your security policy should dictate the level of service you offer. You should not, in general, let the desired functionality dictate your security policy.

Writing a Stanza - Part 2

A Simple TCP Example

A Note about SYN Bits

To open a TCP data stream, the initiator sends a packet to the intended recipient. The SYN bit (with no ACK bit) is set in the TCP header to show a TCP connection request. The special keyword `syn will match packets which have the SYN bit set, but no ACK bit set. This allows you to filter or log packets which start connections.

The TCP protocol requires more than a single SYN packet for a TCP connection to work. This means you cannot enable TCP connections with a single `syn' rule.

Two Approaches to Filtering TCP connections

There are two approaches to filtering TCP connections. The first approach is to block `syn' packets you do not want to establish a service, while permitting all other packets for the service.

Example:
!telnet /syn /recv # block inbound telnet connection requests
telnet # permit all other telnet packets

The second approach is to permit the `syn packets you do want to establish a connection, followed by permitting any other non-SYN packets. The opposite of using the `syn' keyword is the `estab' keyword. `estab' describes any TCP packet that does not have the SYN bit set or that has both the SYN and ACK bits set in the TCP header.

Example:
telnet /syn /send # permit outbound telnet connection requests
telnet /estab # permit packets to established connections

Building Filters from Stanzas

Identifying Rulesets with Hostnames and Addresses

The first line of a ruleset must contain a hostname, IP address, or `default that identifies the interface you wish to use. For pppd, use the peer, or remote, IP address. This hostname or IP address must not be indented because the name/address will be assumed to be part of a rule and may or may not cause a syntax error.

We recommend that you use an IP address, but, if you use a hostname, it is important that the system can resolve the hostname locally. If the link must be up to resolve the name, the hostname matching will fail and the interface will be forced to use the default ruleset. This changes the meaning of your filter file and causes long delays because the connection will timeout while waiting for name resolution.

A Note on Ruleset Formatting

Each additional line of a ruleset (continuation lines) must be indented, using one or more white space characters (space or tab). If a line is not indented, the first word on the line is assumed to be a hostname for a new ruleset.

Any information which follows a `#' character on a line is assumed to be a comment and is ignored.

Ordering Stanzas Effectively

When a ruleset has been selected, each stanza is applied in order, top to bottom, and left to right. The filter returns when it finds a matching stanza. It is therefore important that you order stanzas in the Filter file in most specific to least specific (most general) order. If the order is reversed, the most general rule will match first and the filter will never reach the more specific rules.

Example: (CORRECT)
domain/192.0.2.1 # permit DNS to/from 192.0.2.1
!domain # prevent all (other) DNS

Example: (WRONG)
!domain # prevent all DNS
domain/192.0.2.1 # this rule is never reached

Isolating anIncorrect' Stanza

When pppd finds an error in the Filter file, the line number that caused the failure is reported. When a packet is rejected due to a filter and thelog rejected' keyword is used, the line number that caused the rejection can be recorded in the log file. Therefore, when tracking down problems, you can quickly isolate the correct stanza if only one stanza is used per line.

Working with Default Rulesets

The hardwired default ruleset is:

default bringup all pass all keepup all log !all

This is probably an unacceptable default if you are trying to filter packets. Your default should be the same as your most restrictive ruleset because it will keep your site secure if connection specific filtering fails due to a misconfigured IP address or hostname.

The following sections deal with two approaches to writing default rulesets. The difference between the two approaches is apparent from their names, the "closed policy" and the "open policy".

Open Policy Default Rulesets

If you are willing to accept most packets from a site from which you have not previously accepted traffic, a reasonable default filter might be:

default
bringup all
pass !exec !tftp all
keepup all
log rejected !all

Notice the use of `all' rather than `!all' at the end of each filter. This default ruleset will only block `tftp packets and `rexec' packets, two protocols that normally should never cross organizational boundaries.

A Note on Using the `log rejected' Filter

In the previous example, and in the following Closed Policy examples, we use the `log rejected filter. This is a good default log filter to use. When testing, it permits you to see that your filter is working as expected and keeps track of outside attempts to connect through to blocked services.

Closed Policy Default Rulesets

The closed policy default rulesets in the examples that follow illustrate the way services can be safely and incrementally allowed for a remote site. This approach begins from the premise that no packets should be allowed to pass.

Block All Packets

If your security policy changes and you must block packets from a formerly acceptable site, you might change the default filter to the following:

default bringup !all pass !all keepup !all log rejected !all

Block All Packets Except Electronic Mail

However, most sites are not this "paranoid" and are willing to permit electronic mail through the workstation or system. For this, and the following examples, it is important that you have the smtp service defined in your services file. To help prevent any problems due to this assumption, you could use the explicit port number, protocol, and IP address to test. Then, you might write the default this way:

default bringup !all pass 25/tcp !all keepup !all log rejected !all

The filter file is easier to read and comprehend if you use the service name. Still, specifying the explicit port number and protocol can also prevent someone from changing the meaning of your rulesets by subverting NIS. The benefit may be negligible, though, if the information is only checked against the local services file. Intruders able to modify the services file could also modify the filter file.

Limiting Electronic Mail to a Gateway Machine

If you wish to limit electronic mail access to a gateway machine, you need to add the qualification to the smtp stanza. The next two examples use the fictitious name/address bignfast/192.0.2.1:

default bringup !all pass smtp/bignfast !all keepup !all log rejected !all

Unresolvable Hostnames and Changing IP Addresses

In the last example, we used the hostnamebignfast'. But consider the inherent problem of using a hostname instead of the IP address. If the host address cannot be resolved, you may reach a state of "deadlock" because the name must be resolved for the service to begin, but the service must begin for the name to be resolved. The example below may be more reliable.

default bringup !all pass smtp/192.0.2.1 !all keepup !all log rejected !all

However, nothing is perfectly reliable. Being explicit can cause other problems if you change the address of the server. The reliability of using an IP address instead of a hostname, or vice versa, may only be decided on a site-by-site basis. Still, we strongly favor using IP addresses over using hostnames. One benefit is that specifying the explicit IP address prevents people from changing the meaning of your rulesets by DNS spoofing.

Conclusion

Build up the list of what you would let an unknown site do a little at a time as you discover services you wish to allow. The important thing is to remember to place `!all' at the end of each filter. You and any future manager can quickly see you are blocking all but specific packets and you reduce the chance that someone will accidentally change the meaning of the implicit ending stanza to `all'.

A Note - Blocking Loose Source and Strict Source Routing Options

Using the IP Source Routing options, it is possible for people to send packets to you that look like they are coming from a host on your network. Prevent this sort of attack by blocking packets that have the Loose Source Routing or Strict Source Routing IP options set. If you want to be restrictive, add the line below to all your rulesets, including your default ruleset in the default pass filter:

!ip-opt=srcrt

A Complete Filter - Closed Policy - An annotated example

Here's an example static filter configuration, appropriate for a system using pppd to create a PPP/SLIP link between the system 192.168.199.1 and a peer, 10.0.0.1, that is acting as the gateway to the Internet. The complete filter, minus the comments, follows this section.

The filter design reflects a fail-safe, or closed, policy.

default
pass !all # block all other packets
log rejected # packets rejected by packet filter

First, we define a default ruleset that is very restrictive. This is a fail-safe ruleset that will not pass any packets through the filter, but will notify you of all traffic you are missing.

10.0.0.1

This ruleset will be applied to any packet crossing the link connecting this host to the peer (10.0.0.1).

bringup
!3/icmp # ICMP unreachable messages
!5/icmp # ICMP redirect messages
!11/icmp # ICMP time exceeded messages
!who # WHO service (513/udp)
!route # routed /gated RIP service (520/udp)
!ntp # Network Time service (123/udp)
all # all other packets

If the link is configured for `dial on demand connections, the `bringup filter describes those packets that will cause a call to be placed and a connection to be initiated. The `bringup filter should be used to prevent the connection from being brought up inappropriately. It is a good idea to block packets that are responses to "bad" inbound packets, such as ICMP Destination unreachable messages, because they aren't "interesting" enough to dial the modem. You should also block services, such as the WHO service, that send packets at a regular intervals and would therefore never permit the link to stay down long. Any other sort of traffic will initiate a dial connection.

pass
!recv /ip-opt=srcrt/unreach=srcfail # Block SRCRT attacks

Don't allow any incoming packets with the Source Route option set in the IP header. Respond with an ICMP Destination Unreachable message with the Source Route Failed code value.

!192.168.199.0/recv /src /unreach =net # Block IP spoofing attacks
!192.168.199.0/send /dst /unreach =net # Block IP spoofing attacks

Block any incoming packets that claim to be from your net, and block any outgoing packets that claim to be destined for your net. Respond with an ICMP Destination Unreachable message with the Bad Net code value.

!127.0.0.0;8 # Block IP spoofing attacks

Silently block all packets that claim to be either to or from the loopback
network.

dstport=nntp/dstaddr=192.168.199.10/srcaddr=10.0.5.6
dstport=nntp/srcaddr=192.168.199.10/dstaddr=10.0.5.6
dstport=nntp/dstaddr=192.168.199.10/srcaddr=172.31.12.13
dstport=nntp/srcaddr=192.168.199.10/dstaddr=172.31.12.13
!nntp/unreach=rst

Allow Network News (Usenet) exchanges with only your known news neighbors (10.0.5.6 and 172.31.12.13) and your news server 192.168.199.10). Block any other NNTP traffic, and respond with a TCP RST message.

domain/tcp/192.168.199.11/dst /syn /recv # (53/tcp)
!domain/tcp/syn /recv #
domain/tcp/192.168.199.11 #

Allow outside hosts to obtain Domain Name Service zone transfers only if your end of the stream is really being handled by your domain name server. In this example, you first permit inbound requests to the domain name server, then block all other inbound requests, and finally allow any TCP packets to pass over the link if they are to or from the host 192.168.199.11 and to or from the domain port to pass over the link. The sender will not be notified that the packets are being dropped.

dstport=domain/udp/192.168.199.11 #permit domain queries
#(53/udp)
!domain # block domain (53/tcp, 53/udp)

Allow Domain Name Service (DNS) queries to and from the DNS server. Block all other domain requests. This second rule is not strictly necessary, since the final rule is `!all, however adding this rule makes it fail-safe.

smtp/192.168.199.14/dst /syn /recv # (25/tcp)
!smtp/syn /recv #
smtp #

Allow incoming electronic mail connection requests to reach your SMTP server, allow no other incoming SMTP connection requests, and allow yourself unlimited outbound SMTP access.

www/syn /recv /192.168.199.13/dst # (80/tcp)
!www/syn /recv /unreach =host #
www #

Allow incoming World Wide Web connection requests to reach your WWW server. Allow no other incoming WWW connection requests. And allow yourself unlimited outbound WWW access.

!dstport=ident/recv /unreach=rst # block IDENT service (113/tcp)

You don't use the RFC 1413 identification services, so you might as well bounce the queries at the gateway instead of having inetd refuse the connection. Respond with a TCP RST message. This does not improve the security of your packet filter, since the packets would be blocked by the final `!all', but it does reduce the delay in services that make use of `ident'.

!telnet /syn /recv /unreach=prohibited # block inbound TELNET requests
telnet # permit TELNET messages

Allow outbound telnet connections from your network to anywhere else.

!finger /syn /recv /unreach =prohibited # block inbound FINGER requests
finger # permit FINGER messages

Block incoming finger requests until you install a safe finger daemon.

ftp /syn /recv /dst /192.168.199.12 # permit inbound FTP for anon FTP
!ftp /syn /recv /unreach =host # block inbound FTP

# requests

Allow incoming FTP (file transfer) traffic that uses your Anonymous FTP server system, but block any other incoming FTP requests. Respond with an ICMP Destination Unreachable message with the Bad Host code value.

ftp # permit FTP messages
srcport=ftp -data/dstport=1024-65536/syn
!ftp -data/syn # block other FTP-DATA connections
ftp -data # permit FTP-DATA messages

After blocking the traffic specified above, allow both FTP command streams and FTP data streams to cross the link, both inbound and outbound.

dstport=33410-33515/udp/send # permit outbound traceroute operation

The traceroute tool probes high-numbered UDP ports and is so useful that you should let it through.

!5/icmp # block ICMP_REDIRECT
8/icmp/192.168.199.1 # permit ping of gateway
8/icmp/192.168.199.10 # permit ping of NNTP server
8/icmp/192.168.199.11 # permit ping of DNS server
8/icmp/192.168.199.12 # permit ping of FTP server
8/icmp/192.168.199.13 # permit ping of WWW server
8/icmp/192.168.199.14 # permit ping of SMTP server
!8/icmp/recv # block inbound ping address

# scanning
icmp # permit ICMP messages

Block ICMP redirect messages since the routing on an internal node should not be changed by an external site. Permit ICMP echo request packets, sent by `ping, to reach all hosts providing external services. Block all other inbound ping packets to prevent IP address probes. Finally, allow other ICMP messages to pass freely.

!all # block all other packets

Silently block all traffic not explicitly permitted to pass. Pass through the firewall only those packets explicitly permitted to pass.

keepup
!send # outbound traffic
!3/icmp # ICMP unreachable messages
!5/icmp # ICMP redirect messages
!11/icmp # ICMP time exceeded messages
!who # WHO protocol
!route # routed /gated RIP protocol
!ntp # Network Time Protocol
all # permit all other packets

The link will be considered active (non-idle) if any packet passes that's not specified in the keepup filter as being blocked. Since there are certain link failure modes that will allow your system to continue sending even though the peer is unresponsive, no outbound packets are permitted to reset the idle timer.

log
!8/icmp # ICMP ECHO packets
rejected # packets rejected by packet

# filter
tcp/syn # all TCP connection requests
!all # block all other packets

Log any packet blocked by the `pass filter above, except ICMP Echo messages. Also log all TCP connection requests.

A Complete Filter - Open Policy - An annotated example

This example of a filter is the product of an open policy. It was developed for the same system configuration as was used in the previous example demonstrating a filter developed for a closed policy. The system uses pppd to create a PPP/SLIP link between the system 192.168.201.1and a peer, 10.0.0.1, that is acting as the gateway to the Internet.

default

Since this ruleset is declared as the default ruleset and no ruleset has been defined for 10.0.0.1, it will be applied to any packet crossing the link connecting this host to any peer, including the Internet gateway (10.0.0.1).

bringup
!3/icmp # ICMP unreachable messages
!5/icmp # ICMP redirect messages
!11/icmp # ICMP time exceeded messages
!who # WHO service (513/udp)
!route # routed /gated RIP service

# (520/udp)
!ntp # Network Time service (123/udp)
all # all other packets

If the link is configured for `dial on demand connections, the `bringup filter describes those packets that will cause a call to be placed and a connection to be initiated. The `bringup filter should be used to prevent the connection from being brought up inappropriately. It is a good idea to block packets that are responses to "bad" inbound packets, such as ICMP Destination unreachable messages, that aren't "interesting" enough to dial the modem. You should also block services, such as the WHO service, that send packets at a regular intervals and would therefore never permit the link to stay down long. Any other sort of traffic will initiate a dial connection.

pass
!recv /ip-opt=srcrt/unreach =srcfail # Block SRCRT attacks

Don't allow any incoming packets with the Source Route option set in the IP header. Respond with an ICMP Destination Unreachable message that has the Source Route Failed code value.

!192.168.199.0/recv /src /unreach =net # Block IP spoofing

# attacks
!192.168.199.0/send /dst /unreach =net # Block IP spoofing
# attacks

Block any incoming packets that claim to be from your net, and block any outgoing packets that claim to be destined for your net. Respond with an ICMP Destination Unreachable message that has the Bad Net code value.

!127.0.0.0;8 # Block IP spoofing attacks

Silently block all packets that claim to be either to or from the loopback network.

!dstport=ident/recv /unreach=rst # block IDENT service (113/tcp)

You don't use the RFC 1413 identification services, so you might as well bounce the queries at the gateway instead of having inetd refuse the connection. Respond with a TCP RST message. This does not improve the security of your packet filter, since the packets would be blocked by the final!all', but it does reduce the delay in services that make use of `ident'.

!chargen/unreach=prohibited # block chargen service

# (19/tcp,19/udp)
!discard/unreach=prohibited # block discard service
# (9/tcp,9/udp)
!echo/unreach=prohibited # block echo service
# (7/tcp,7/udp)

Block access to your `` character generator'' port, and two others, because they are only meant as testing facilities and could be used by someone outside to swamp your network's bandwidth with unwanted, but otherwise harmless, traffic.

!5/icmp # block ICMP_REDIRECT

Block ICMP redirect messages since the routing on an internal node should not be changed by an external site.

!sunrpc # block portmap (sunrpc 111/tcp,111/udp)
!exec # block rexecd (512/tcp)
!login # block rlogind (513/tcp)
!shell # block rshd (514/tcp)
!syslog # block syslogd (514/udp)
!printer # block lpd (515/tcp)
!2049/udp # block nfsd (2049/udp)

Block access to a number of services that depend upon IP addresses for authentication, or that have no authentication built-in.

!tftp # block tftp (69/udp)

Block access to the tftp port because it is sometimes buggy and thus permit access to files that should not be distributed, such as password files. It is normally only used locally and should not be receiving requests from outside the local area network.

all # permit all other packets

Permit all traffic except that which you've explicitly specified as blocked, through the firewall.

keepup
!send # outbound traffic
!3/icmp # ICMP unreachable messages
!5/icmp # ICMP redirect messages
!11/icmp # ICMP time exceeded messages
!who # WHO protocol
!route # routed /gated RIP protocol
!ntp # Network Time Protocol
all # all other packets

The link will be considered active (non-idle) if any packet passes that's not specified as blocked in the keepup filter. Since there are certain link failure modes that will allow your system to continue sending even though the peer is unresponsive, no outbound traffic counts against the idle timer.

log
rejected # packets rejected by packet filter
!all # block all other packets

Log any packet blocked by the `pass filter above.

Common mistakes

A number of errors are common enough to be specifically pointed out.

Incorrect hostname

Earlier documentation for MST PPP used "Internet-gateway" to define the ruleset. This is the example hostname that was chosen to illustrate what the hostname might be. Many people have become confused and thought it was a special keyword. It is not! You must supply a real hostname or IP address or the keyword `default.

Incorrect Ruleset Indentation

Another common mistake is to accidentally indent the ruleset identifier (e.g. hostname, IP address, or `default). This causes the software to assume that it is a part of the previous ruleset rather than defining the start of a new ruleset.

Yet another common mistake is not indenting all the parts of a ruleset after the initial ruleset identifier. This will cause the software to assume that the stanza is the start of a new ruleset. This will cause both failures and/or delays as the software tries to resolve the stanza into an IP address.

Incorrect Use oftcp' andudp'

A different error is to fail to specify `tcp' or `udp' when a service can use either service but the keywords are applicable to only one. An example of this is the domain name service (DNS), which uses UDP for normal queries, but TCP for zone transfers. If you try to block inbound requests for a zone transfer you must remember to add the `tcp' qualifier to the service name `domain' to prevent a syntax error.

Attempting to Send Hostnames Requiring Resolution over Down Network Links

You can easily, but mistakenly, use a hostname that needs to be resolved because it is not defined or requires DNS, over a network link that is down. This causes failures and/or delays. Therefore, we would strongly recommend the use of only IP address in filter files.

Failing to Allow Passage offtp' Data Packets over theftp-data' Port

Less commonly, some people who do not fully understand the protocol only permit `ftp packets to pass through their filter. The FTP protocol actually uses two channels; the first channel is used for commands and the second port is for used for data. The second channel uses a separate port, commonly `ftp-data', but that is actually determined during the FTP negotiations. The second channel is normally a reverse channel used to transfer data back to the client.

Blocking Packets Required for Network Access

Finally, carefully make sure you permit passage of all packets required for your network access. Some Internet Service Providers (ISPs) require the use of a routing protocol and will mark the link inactive if they do not receive routing packets. This may require a rule in the pass clause of your ruleset to permit the route packets to traverse the link (e.g., `route').

Example of Static Packet Filter Developed for Closed Policy
default
pass !all # block all other packets
log rejected # packets rejected by packet filter
10.0.0.1
bringup
!3/icmp # ICMP unreachable messages
!5/icmp # ICMP redirect messages
!11/icmp # ICMP time exceeded messages
!who # WHO service (513/udp)
!route # routed /gated RIP service (520/udp)
!ntp # Network Time service (123/udp)
all # all other packets
pass
!recv /ip-opt=srcrt/unreach =srcfail # Block SRCRT attacks
!192.168.199.0/recv /src /unreach =net # Block IP spoofing attacks
!192.168.199.0/send /dst /unreach =net # Block IP spoofing attacks
!127.0.0.0;8 # Block IP spoofing attacks
dstport=nntp/dstaddr=192.168.199.10/srcaddr=10.0.5.6
dstport=nntp/srcaddr=192.168.199.10/dstaddr=10.0.5.6
dstport=nntp/dstaddr=192.168.199.10/srcaddr=172.31.12.13
dstport=nntp/srcaddr=192.168.199.10/dstaddr=172.31.12.13
!nntp/unreach=rst
domain/tcp/192.168.199.11/dst /syn /recv # (53/tcp)
!domain/tcp/syn /recv #
domain/tcp/192.168.199.11 #
dstport=domain/udp/192.168.199.11 # permit domain queries (53/udp)
!domain # block domain (53/tcp, 53/udp)
smtp/192.168.199.14/dst /syn /recv # (25/tcp)
!smtp/syn /recv #
smtp #
www/syn /recv /192.168.199.13/dst # (80/tcp)
!www/syn /recv /unreach=host #
www #
!dstport=ident/recv /unreach =rst # block IDENT service (113/tcp)
!telnet /syn /recv /unreach =prohibited # block inbound TELNET requests
telnet # permit TELNET messages
!finger /syn /recv /unreach=prohibited # block inbound FINGER requests
finger # permit FINGER messages
ftp /syn /recv /dst /192.168.199.12 # permit inbound FTP for anon FTP
!ftp /syn /recv /unreach =host # block inbound FTP requests
ftp # permit FTP messages
srcport=ftp -data/dstport=1024-65536/syn
!ftp -data/syn # block other FTP-DATA connections
ftp -data # permit FTP-DATA messages
dstport=33410-33515/udp/send # permit outbound traceroute
!5/icmp # block ICMP_REDIRECT
8/icmp/192.168.199.1 # permit ping of gateway
8/icmp/192.168.199.10 # permit ping of NNTP server
8/icmp/192.168.199.11 # permit ping of DNS server
8/icmp/192.168.199.12 # permit ping of FTP server
8/icmp/192.168.199.13 # permit ping of WWW server
8/icmp/192.168.199.14 # permit ping of SMTP server
!8/icmp/recv # block inbound ping address scanning
icmp # permit ICMP messages
!all # block all other packets
keepup
!send # outbound traffic
!3/icmp # ICMP unreachable messages
!5/icmp # ICMP redirect messages
!11/icmp # ICMP time exceeded messages
!who # WHO protocol
!route # routed /gated RIP protocol
!ntp # Network Time Protocol
all # permit all other packets
log
!8/icmp # ICMP ECHO packets
rejected # packets rejected by packet filter
tcp/syn # all TCP connection requests
!all # block all other packets


Example of Static Packet Filter Developed for Open Policy
default
bringup
!3/icmp # ICMP unreachable messages
!5/icmp # ICMP redirect messages
!11/icmp # ICMP time exceeded messages
!who # WHO service (513/udp)
!route # routed /gated RIP service (520/udp)
!ntp # Network Time service (123/udp)
all # all other packets
pass
!recv /ip-opt=srcrt/unreach=srcfail # Block SRCRT attacks
!192.168.199.0/recv /src /unreach=net # Block IP spoofing attacks
!192.168.199.0/send /dst /unreach=net # Block IP spoofing attacks
!127.0.0.0;8 # Block IP spoofing attacks
!dstport=ident/recv /unreach=rst # block IDENT service (113/tcp)
!chargen/unreach =prohibited # block chargen service
!discard/unreach=prohibited # block discard service
!echo/unreach=prohibited # block echo service (7/tcp,7/udp)
!5/icmp # block ICMP_REDIRECT
!sunrpc # block portmap (sunrpc 111/tcp,111/udp)
!exec # block rexecd (512/tcp)
!login # block rlogind (513/tcp)
!shell # block rshd (514/tcp)
!syslog # block syslogd (514/udp)
!printer # block lpd (515/tcp)
!2049/udp # block nfsd (2049/udp )
!tftp # block tftp (69/udp)
all # permit all other packets
keepup
!send # outbound traffic
!3/icmp # ICMP unreachable messages
!5/icmp # ICMP redirect messages
!11/icmp # ICMP time exceeded messages
!who # WHO protocol
!route # routed /gated RIP protocol
!ntp # Network Time Protocol
all # all other packets
log
rejected # packets rejected by packet filter
!all # block all other packets

Time-To-Call Restrictions

The second field on each line in the /usr/lib/mstppp/Systems file specifies the times pppd is allowed to attempt to establish connections. Two benefits of time restrictions are:
The Systems field is very flexible. It can be configured by day and by hour, with many different combinations allowed for the same connection. For example, the following entry allows connections on any day between 1 AM and 6AM or any time on Saturday and Sunday:

lark Any0100-0600|Sa|Su ACU 38400 5551212 in:--in: Probin word: mypasswd

Dial-Back

MST PPP supports the ability to maintain a connection when calling a modem which has a dial-back security feature. The /usr/lib/mstppp/Systems file chat script option \ M allows this by disabling delivery of SIGHUP to pppd . This signal usually results from loss of Carrier Detect and tells pppd to abruptly disconnect from the active session.

The Dial-Back Process

Typically, an answering modem with dial-back capability responds to a call by taking the following steps:

The modem

The calling modem might then demand the same type of identification before allowing remote data to flow through its serial interface to the local system.

Blocking SIGHUP with the Chat Script \M Option

The calling system's pppd must be prepared for the temporary lack of a Carrier Detect signal from its modem during the dial-back from the remote modem. To avoid receiving a SIGHUP, pppd instructs the UNIX system's serial drivers not to deliver the signal. In other words it says, "Temporarily treat the serial interface as if it were connected to a local device like a terminal or printer, instead of a modem." pppd does this by specifying \M in the `send phase of a /usr/lib/mstppp/Systems chat script.

Reversing the Instructions with the \m Option

After the disconnection period, through the `send phase option, \m, pppd tells the system's serial drivers to reverse the first instruction and respect the modem's full variety of control. For example, to dial into a system protected by a dial-back modem, the /usr/lib/mstppp/Systems chat script might be written like this:

#
# This connects to a system protected by a Telebit T3000 callback
# modem
# with S46=2.
#
server Any ACU 38400 19071234567 TIMEOUT 60 \
ENTER\sPASSWORD: my_modem_password \ M \
ENTER\SPASSWORD: my_modem_password \ m \
login: my_login_name ssword: my_login_password

Link Peer Authentication

Morning Star PPP implements both the Password Authentication Protocol (PAP) and the Challenge Handshake Authentication Protocol (CHAP). If pppd is invoked with either of the requireauth or requirechap options, it will demand that the peer (either calling or called) authenticate itself. The Auth file contains pairs of either names and secrets for CHAP negotiation, or usernames and passwords for PAP negotiation. If a peer provides a name or username, its secret or password must match that found in Auth or the authentication phase fails and the connection is terminated. Each name / secret pair in Auth may be followed by address patterns restricting the peer's negotiated IP address. If an address restriction is specified for a particular name and the peers negotiated IP address does not match the restriction address patterns, pppd will terminate the connection.

The rechap interval option instructs pppd to periodically (every interval seconds) challenge the peer to authenticate itself. If the peer fails the new challenge, the link is terminated.

SecureID

Sometimes an incoming call must penetrate the answering machine's SecureID system before its offered a login prompt. SecureID is a credit card sized device which provides the caller a code that matches one held by the answering system. The code changes frequently, but the card and the SecureID system are synchronized so that each has the same code at any given time.

MST PPP Support for SecureID Systems

MST PPP allows standard output from the xprompt program to populate a field in the /usr/lib/mstppp/Systems file. If you have xprompt and the C compiler, you can develop the means to input the current SecureID code into your Systems chat script. Ultimately, the chat script passes the callers code to the SecureID system during the login process.

Suppose the SecureID system answers incoming calls with the string `Identify Yourself!, expecting the incoming user to type the secret string that appears on the user's SecureID card. The Systems file entry for the calling system looks like this with an executable shell script called SecureCode in back quotes:

peer Any ACU 38400 5551212 self! `SecureCode` in: Pfoo word: bar

SecureCode is installed in the pppds search path set by the /usr/lib/mstppp/Autostart script that loads pppd. SecureCode would look something like this:

#!/bin/sh
DISPLAY=:0.0
export DISPLAY
prompt="`tr -d "\015" | tail -1`"
/usr/local/bin/X11R4/xprompt -rlen 20 -p $prompt

The Shell Script/xprompt/Chat Script Process

The integrated process described below provides a means for dialog between the user and the remote SecureID system. When pppd brings up the link on demand, the Systems chat script progresses until it sees ``self!". These steps follow:

When SecureCode, the command between the backquotes, exits, pppd sends its stdout across the modem to the SecureID barrier, just as if it had been typed directly by the user. If the string sent to the answering system matches the expected string, the user is identified and the expect/send couplets of the chat script continue.


Appendixes


Intro(MST_PPP)

NAME

Intro - Introduction to the Morning Star Technologies PPP manual pages.

This section contains the following manual pages:

TUN(MST_PPP)

NAME

tun - IP network tunnel driver

CONFIGURATION

pseudo-device tun[ n ]

SYNOPSIS

#include <sys/tun.h>
open("/dev/tun_n", mode);

DESCRIPTION

When IP packets are written to /dev/tun n or /dev/tun n+M,
they are received by the kernel 's IP layer on the network interface du n When the kernel's IP layer sends packets to the IP interface du n , they are available for reading on /dev/tun n or /dev/tun n+M.

Instead of having hardware and an associated kernel interface that support network functions, the tun driver allows a network interface to be implemented as a user-space process. While talking to the same set of tunnel drivers on the same system, different network interface processes can implement different IP encapsulation methods, such as RFC 877 for use over CCITT X.25-based public data networks, or RFC 1055 SLIP or RFC 1661/1332 PPP for use over dedicated line s and dialup modems.

The tun driver provides support for a pair of devices collectively known as an IP tunnel The two devices comprising a tunnel are known as the inbound and outbound sides, similar to the pairing between /dev/tty n (the inbound terminal) and /dev/cu n (the outbound `auto -call unit available on many systems). The outbound side's minor device number is that of the inbound side plus M , which is 128, though they together appear to IP as one interface. If both the inbound and outbound sides of a tunnel device are open, packets received from IP are delivered to only the inbound side.

If a TCP packet received from IP is part of a telnet, rlogin, or FTP command stream, it will be put in a fast queue . All packets in the fast queue are delivered to the user before any packets in the normal queue.

IOCTLS

A few special ioctls are provided for use on the /dev/tun* devices to supply the functionality needed by applications programs to emulate real hardware interfaces. The complete list of supported ioctls is:

TUIOSPTPT
Set or clear the IFF_POINTOPOINT in the associated network interface.
TUIOSADRMD
Set or clear `address mode', in which packets read are prefaced with four octets containing the destination IP address in network byte order. The third argument is a pointer to an integer containing either a zero or a one, indicating whether `address mode' should be cleared or set, respectively. If both `address mode' and `packed buffer mode' are set, each packet's length will come first, followed by the packet's destination address, followed by the packet itself
TUIOGADRMD
Get the current status of `address mode'.
TUIOSPKBMD
Set or clear `packed buffer mode' where multiple packets are encoded in single read/write buffers. The third argument is a pointer to an integer containing either a zero or a one, indicating whether `packed buffer mode' should be cleared or set, respectively. If set (1), each packet is preceded by four octets representing the next packet's length in octets. The following packet will then be aligned to the next multiple of four octets. If cleared (0), packets will be delivered one per read(3) from the tunnel device. If both `address mode' and `packed buffer mode' are set, each packet's length will come first, followed by the packet's address, followed by the packet itself.
TUIOGPKBMD
Get the current status of `packed buffer mode'.
TUIOSPKMAX
Set the max number of IP frames to send back in a packet buffer read.
TUIOGPKMAX
Get the PKMAX value.
TUIOSPKPAD
Set the number of long word zeroes to put on the front of each packet read in packed buffer mode.
TUIOGPKPAD
Get the number of pad words.
TUIOSNAME
Set the interface name (may only be invoked by the superuser).
TUIOGNAME
Get the interface name.
FIONBIO
Set or clear non-blocking mode for I/O operations

EXAMPLES

#include <sys/tun.h>
int tun_fd = -1, len;
char *packet;

tun_fd = open("/dev/tun0", O_RDWR);
ioctl(tun_fd, TUIOSNAME, "du");
len = read(tun_fd, packet, size);
write(tun_fd, packet, len);

ERRORS

If a packet is delivered to the interface for an address family other than AF_INET, EAFNOSUPPORT will be returned.

FILES

/dev/tun0 through /dev/tun M-1 `inbound tunnel devices
/dev/tun M through /dev/tun 2*M-1 ` outbound tunnel devices

SEE ALSO

ppp.Auth (MST_PPP), ppp.Devices (MST_PPP), ppp.Dialers (MST_PPP), ppp.Filter (MST_PPP), ppp.Keys (MST_PPP), ppp.Systems (MST_PPP), pppd (MST_PPP), RFC 1661 , RFC 1332, RFC 1144 , RFC 1055 , RFC 877

COPYRIGHT INFORMATION

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


PPP.AUTH(MST_PPP)

NAME

ppp.Auth - PPP authentication file format

DESCRIPTION

The file /usr/lib/mstppp/Auth on SCO systems contains values used by MST PPPs implementation of the link-level authentication protocols, CHAP (Challenge Handshake Authentication Protocol) and PAP (Password Authentication Protocol). This implementation of both CHAP and PAP conforms to RFC 1334, PPP Authentication Protocols.

CHAP is a stronger authentication mechanism. Use CHAP whenever possible instead of PAP. Earlier versions of MST PPP provided interoperability with draft versions of CHAP pppd s oldchap or olderchap command line options. However, these options are long out of date and have been eliminated from this version of the software.

SECURITY CONCERNS

The file /usr/lib/mstppp / Auth should be mode 600 or 400, and owned by root.

FORMAT

In the midst of the Name/Peer-ID and Secret/Password strings, ^x is translated into the appropriate control character before matching, and \xxx represents the character corresponding to the octal number xxx . Other special sequences are:

\s
Matches a space character (ASCII 0x20)
\t
Matches a horizontal tab character (ASCII 0x09)
\n
Matches a line feed character (ASCII 0x0a)
\r
Matches a carriage return character (ASCII 0x0d)

The fields have the following meaning:

name
The Name field of a sent or received CHAP Challenge or Response message, or the Peer-ID field of a sent or received PAP Authenticate-Request message. For transmitted packets, this is the hostname unless overridden by the pppd name option.
secret
The secret word that the peer also knows.
optional address restrictions
A set of zero or more patterns restricting the addresses that are allowed to be used with the named peer. Patterns are separated by spaces or tabs and are parsed from left to right.

Each pattern may begin with an exclamation mark to indicate that the following pattern should not be allowed.

The rest of the pattern consists of digits and periods, and optionally a leading or trailing asterisk, which will match anything. If none of the patterns match, then the address will be allowed if the last pattern began with an exclamation point, and will be disallowed otherwise.

If the optional address restriction field consists of only a single address, it replaces the destination address configured on the command line.

EXAMPLE

The following Auth provides pppd with a secret for use when a peer claims to be other-host, robin, orJack's machine'.

#
# Auth - PPP authentication name/secret file
# Format:
#name secret optional address restrictions
other-host secret-key !137.175.9.2 37.175.9.*/0xffffff00
robin dK3ig8G8hs 137.175.11.4
Jack's\smachine I\sam\sa\sjelly\sdonut.

SEE ALSO

tun(MST_PPP), ppp.Devices (MST_PPP), ppp.Dialers (MST_PPP), ppp.Filter (MST_PPP), ppp.Keys (MST_PPP), ppp.Systems (MST_PPP), pppd (MST_PPP), RFC 792, RFC 1661 , RFC 1332, RFC 1334 .

Brian Lloyd and William A. Simpson, "The PPP Authentication Protocols," Internet Draft, May 1992.

COPYRIGHT INFORMATION

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


PPP.DEVICES(MST_PPP)

NAME

ppp.Devices - PPP physical device description file format

DESCRIPTION

The file /usr/lib/mstppp/Devices on SCO systems associates dialer types with physical devices and speeds. Pppd examines it when placing a call to a neighboring machine. If no suitable speed is found, or if all dev ices associated with that speed are busy, pppd will try again later.

FORMAT

dialer
Contains either the string `Direct, the name of the modem dialing chat script in Dialers to use with this device, or the name of an external dialer program.
Device
The name of the device in the /dev directory ( tty1a, tty1A , etc.). Device names for SnapLink connections are followed by a slash and the port number in use ( rfd0, rfd1 , etc.).
speed
The baud rate of the synchronous connection, or a string to be matched against the speed field of entries in Systems when the Systems device field is set to ACU (Any Call Unit).

There is also a fourth field for describing options:

optional parameters
Any special handling for this device. Currently supported values are shown in the table below.
rtscts
Specifies that the line be conditioned for out-of-band EIA RS-232-D `hardware (RTS/CTS) flow control. The default is to use no flow control. For an outbound connection, this may be specified either in Devices or on the pppd command line.
Crtscts
A synonym for rtscts
xonxoff
Specifies that the line be conditioned for in-band (`software) flow control, using the characters DC3 (^S, XOFF, ASCII 0x13) to stop the flow and DC1 (^Q, XON, ASCII 0x11) to resume. The default is to use no flow control. For an outbound connection, this may be specified either in Devices or on the pppd command line.
internal-clocking
The SnapLink will provide the synchronous clock signal. By default, it expects the modem, CSU/DSU or modem eliminator to provide the clock signal. Internal-clocking cannot be used with RS-232 cables on the SnapLink.
32-bit-fcs
A SnapLink will calculate 32-bit FCS values for transmitted frames, and check received frames with 32-bit FCS calculations. This is not negotiable at connection establishment time. 32-bit FCS is only available when running synchronous PPP on the SnapLink.
min-flags=min flags
The number of additional HDLC flag characters a SnapLink should insert between data frames. The default and minimum is 2; the maximum is 16.
ignore-cd
Ignore the state of the CD (Carrier Detect, also called DCD, Data Carrier Detect) signal. This is useful for systems that don't support CD but want to run PPP over a dedicated line.

EXTERNAL DIALER

The external dialer program is run with the following arguments:

device name
The contents of the Device field from the Devices entry
speed
The contents of the Speed field of the Systems and Devices entries.
telephone number
The contents of the Phone Number field of the Systems entry.

This program also allows for optional parameters:

optional parameters
Copied from the Optional Parameters section of the Devices entry. If the external dialer program exits with status 0, then the dial attempt is considered to have succeeded. Any other exit status indicates a failure.

EXAMPLE

#
# Devices - PPP devices file

#
#Dialer device speed Optional parameters
T2500-PEP cua 19200-PEP rtscts
T1600 cub 38400 rtscts
Direct rsd0a/0 1536000 internal-clocking
Oddball rsd0a/1 64000 cua 9600 5551212

In the last line of this example, the 64Kb synchronous modem on the SnapLinks port 1 has an asynchronous dialer interface attached to the workstations port `a' The Systems line would look like

host Oddball rsd0a/1 64000 0

There must be a program (or an executable shell script) called /usr/lib/mstppp/Oddball that dials the modem when invoked as

Oddball rsd0a/1 64000 0 cua 9600 5551212

A warning message will be printed for each unrecognized optional parameter if the debug level is 2 or more.

CAVEATS

The external dialer is invoked as root , so you should take appropriate security precautions with its content and file protection.

SEE ALSO

tun(MST_PPP), ppp.Auth (MST_PPP), ppp.Dialers (MST_PPP), ppp.Filter (MST_PPP), ppp.Keys (MST_PPP), ppp.Systems (MST_PPP), pppd (MST_PPP), RFC 1661 , RFC 1332, RFC 1144 , RFC 1055 .

COPYRIGHT INFORMATION

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


PPP.DIALERS(MST_PPP)

NAME

ppp.Dialers - PPP dialer description file format

DESCRIPTION

The file /usr/lib/mstppp/Dialers on SCO systems describes how to dial each type of modem attached to the UNIX system that is to be made available for outbound PPP calls. After looking for modem dialers in Dialers.local , Pppd examines /usr/lib/mstppp/Dialers when placing a call to a neighboring machine. Entries in Dialers.local take precedence over those in /usr/lib/mstppp/Dialers.

When pppd selects a line from Systems , it uses thespeed ' field to select an entry in Devices , from which it uses thedialer ' field to select an entry in Dialers . Pppd then interprets thechat script ' field from that dialer description. The `dialer ' field may also be the name of a binary dialer program.

FORMAT

dialer
The name of this dialer , to be matched against the dialer field in Devices
chat-script
A description of the conversation that pppd holds with the modem.

CHAT SCRIPT PARTICULARS

A chat script takes the form of a space-separated list of expect-send pairs. At minimum, each pair consists of a field to expect the "remote" end to send, followed by a field to send in response. Unless asend' string ends with \ c , pppd will follow it by sending a carriage return character (ASCII 0x0d).

Chat scripts areexpect send expect send...', orexpect-send-expect send...', where thesend' following the hyphen is executed if the preceding expect fails to match received text.

Certain special words may be used in the chat script to control the behavior of pppd as it attempts to dial. Both ABORT and TIMEOUT must be in theexpect' phase of the chat script.

ABORT abort-string
If pppd sees abort-string while executing the remainder of the chat script , abort the dialing attempt and note the failure in the log file.
TIMEOUT timeout-time
While executing the current chat script , wait timeout-time seconds for a response before considering the dialing attempt to have timed out. Writes have a fixed 60-second timeout.

The expect-send couplet of "" P_WORD sets the line parity accordingly:

P_AUTO
Set transmission parity based on the parity observed in characters received inexpect' strings. This is the default.
P_ZERO
Transmit characters with the parity bit set to 0
(8 bits, no parity ).
P_ONE
Transmit characters with the parity bit set to 1
P_EVEN
Transmit characters with even parity.
P_ODD
Transmit characters with odd parity.

In the midst of either anexpect' string or a `send ' string, ^x gets translated into the appropriate control character, and \x gets translated into x . Other special sequences are:

\s
Send or receive a space character (ASCII 0x20)
\t
Send or receive a horizontal tab character (ASCII 0x09)
\n
Send or receive a line feed character (ASCII 0x0a)
\r
Send or receive a carriage return character (ASCII 0x0d)
\\
Send or receive a backslash character (ASCII 0x5c)
\^
Send or receive a carat character (ASCII 0x5e)
^>character>
Send or receive the single character Ctrl-<character> (ASCII 0x00 through 0x1f)
\ ddd
Send or receive a character, specified in octal d igits
\p
Pause for.25 second before proceeding (send only)
\d
Delay for 2 seconds before proceeding (send only)
\K
Send a break (.25 second of zero bits)
\M
Disable hangups (sets CLOCAL or LNOHANG)
\m
Enable hangups (unsets CLOCAL or LNOHANG) (the default )
\c
Don't append a carriage return character after sending the preceding string (send only)
\q
Don't print succeeding send strings (e.g. a password ) in any debugging or logging output. Subsequent \ q sequences togglequiet' mode.
\T
Insert the telephone number found in the fifth field of Systems here

EXAMPLE

#
# Dialers - PPP dialers file
#
# Dialer Chat script
T1600 ABORT NO \sCARRIER ABORT NO\sDIALTONE ABORT BUSY \
ABORT RRING \r\n\r\nRRING\r\n\r\nRRING \
ABORT ERROR TIMEOUT 5 "" AT OK-AT-OK \
ATS111=0DT\T TIMEOUT 30 CONNECT
#
T2500-PEP \
ABORT NO \sCARRIER ABORT NO\sDIALTONE ABORT BUSY \
ABORT RRING \r\n\r\nRRING\r\n\r\nRRING \
ABORT ERROR TIMEOUT 5 "" AT OK-AT-OK \
ATS111=0DT\T TIMEOUT 30 CONNECT \sFAST
#
USRv32bis \
ABORT ERROR ABORT NO \sANSWER ABORT NO\sCARRIER \
ABORT BUSY ABORT RRING \r\n\r\nRRING\r\n\r\nRRING \
ABORT NO \sDIAL\sTONE TIMEOUT 5 "" AT&F \
OK-ATQ0-OK ATB0E0X7&B1&H1&I0&K3&R2&S1 OK-AT-OK \
ATS01=1S02=255S19=0 OK-AT-OK ATDT\T TIMEOUT 30 \
CONNECT

SEE ALSO

tun(MST_PPP), ppp.Auth (MST_PPP), ppp.Devices (MST_PPP), ppp.Filter (MST_PPP), ppp.Keys (MST_PPP), ppp.Systems (MST_PPP), pppd (MST_PPP), RFC 1661, RFC 1332, RFC 1144 , RFC 1055 .

COPYRIGHT INFORMATION

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


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.


PPP.KEYS(MST_PPP)

NAME

ppp.Keys - PPP encryption keys file format

RESTRICTIONS

Encryption is not available in software exported from the USA, and therefore not available for international licenses.

DESCRIPTION

The keys file named in the gw-crypt option on the pppd command line contains key values used by MST PPP 's implementation of link-level encryption . Before transmission, packets with source and destination address es matching the endpoints on a keys file line are encrypted using DES with the key specified on that keys file line. Upon reception, packets with source and destination addresses matching those on a keys file line are decrypted using DES with the key specified on that keys file line.

FORMAT

Each key specification is on its own single line of up to 1023 characters. Comments in the keys file begin with a#' and extend to the end of the line; blank lines, or lines beginning with a `# ', are ignored. Fields are separated by horizontal white space (blanks or tabs).

The first two words on a key line are compared with the source and destination addresses of each packet to be transmitted and each received packet. The endpoint address specifications may contain either host or network names, or host or network addresses. 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 mask is separated from the network name or address by a slash (/),and may be specified either as a series of decimal numbers separated by periods, or as a single 32-bit hexadecimal number, optionally with a C-style `0x ' prefix.

The remainder of the key line is a 56 bit (14 digit) hexadecimal number (without the C-style `0x' prefix), used as the DES key between the specified pair of hosts or networks. The digits may be separated by horizontal white space for readability. If the key contains fewer or more than 14 hexadecimal digits, the line is ignored. If the key is weak or semi-weak, a warning message will be printed in the log file and the specified key will be used for encryption anyway.

EXAMPLE

The following keys file provides pppd with keys for use when encrypting or decrypting traffic between the indicated pairs of hosts or networks:

# # Keys - PPP encryption keys file #
# Format:

#endpoint endpoint key
frobozz.foo.com glitznorf.baz.edu feed face 00d aa
147.225.0.0 38.145.211.0/0xffffffc0 b1ff a c001 d00d 1
128.49.16.0/0xffffff00 198.137.240.100 0123456789abcd
193.124.250.136 143.231.1.0/0xffffff00 e1c3870e1c3870

RECOMMENDATIONS

Avoid using weak or semi-weak keys . These are weak DES keys:

00000000000000
FFFFFFFFFFFFFF
1E3C78F1E3C78F
E1C3870E1C3870

These are semi-weak DES keys :

01FC07F01FC07F
FE03F80FE03F80
1FC07F00FE03F8
E03F80FF01FC07
01C007001E0078
E003800F003C00
1FFC7FF0FFC3FF
FE3FF8FFE1FF87
003C00F001C007
1E007800E00380
E1FF87FF1FFC7F
FFC3FF0FFE3FF8

SECURITY CONCERNS

The keys file should be mode 600 or 400, and owned by root .

Packets' IP headers are not encrypted, though their TCP , UDP, or ICMP headers are encrypted along with the user data portion. This allows encrypted packets to traverse normal internetworks, but permits snoopers to analyze traffic by its endpoints.

Since the TCP , UDP, or ICMP header is encrypted, protocol-based filters along the packet 's path will be unable to discern whether it is SMTP , Telnet, or any other network service. This means that encrypted traffic will only permeate packet-filtering firewalls if the firewall allows all traffic between the endpoints, regardless of traffic type. MST PPP /SLIP software for UNIX systems, when deployed as the endpoint gateways of the encrypted traffic, decrypt incoming encrypted traffic before applying their configured packet filtering rules.

SEE ALSO

tun(MST_PPP), ppp.Auth (MST_PPP), ppp.Devices (MST_PPP), ppp.Dialers (MST_PPP), ppp.Filter (MST_PPP), ppp.Systems (MST_PPP), pppd (MST_PPP), RFC 792, RFC 1661 , RFC 1332, RFC 1334 .

COPYRIGHT INFORMATION

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


PPP.SYSTEMS(MST_PPP)

NAME

ppp.Systems - PPP neighboring systems description file format

DESCRIPTION

The file /usr/lib/mstppp/Systems on SCO systems describes how to connect with neighboring systems via PPP .

FORMAT

name The hostname or IP address of the destination machine, which should be resolvable locally.
when
Hours in a range are written as those from a 24 hour clock, 0800-1230 for example. If you do not specify a time, calls will be allowed at any time. A time range that spans 0000 is permitted. For example, 0800-0600 means that all times are allowed except times between 6 AM and 8 AM.

Examples:
MoTuTh0800-1740.
Wk0800-1230, (same as MoTuWeThFr)
Any0900-1700, (same as SuMoTuWeThFrSa).

Multiple date specifications are separated by a vertical bar (|). This example means that means that the system can be called any day between 1 AM and 6 AM or any time on Saturday and Sunday.

Example:
Any0100-0600|Sa|Su

The entire sequence of days and times may be followed by a semicolon and up to three decimal numbers separated by hyphens as described in the table below:

one
If only one number follows the semi-colon, it is used as the redial delay, which is the initial time (in seconds)before a failed call will be retried.

For example, Any;60 means call any time, but wait at least 60 seconds after a failure has occurred before trying to call again.

If a call retry fails, pppd doubles the delay before trying again. If no initial retry delay is specified, 10 seconds is assumed.

two
If two numbers follow the semicolon, the second number is the maximum redial delay, or the maximum time (in seconds) to delay before retrying a call. The retry time doubles with each unsuccessful call until it reaches this value, after which the call will be retried every time the maximum number of seconds passes.

If no maximum retry delay is specified, 3600 seconds is assumed.

three
If three numbers follow the semicolon, the third is the maximum redial delay. The callback delay is the time (in seconds) to wait before attempting to re-establish a previously active connection that ended because of an abrupt line disconnection (a Hangup or SIGHUP event in the log file ).

The default is not to delay before calling back.

device
If set to `ACU ', any device in Devices with a matching speed may be used. The device's dialer chat script will be executed first, followed by the Systems chat script.

If set to the name of a device in the /dev directory (tty00, cua, etc.), there may be an optional corresponding Direct entry in Devices , Dialers will not be consulted, and only the Systems chat script will be executed.

If set to `tcp', it must be followed by a slash, then the hostname or IP address of the system that will serve as the destination of the PPP link, then another slash, then the socket number on which to contact the remote PP daemon.

speed
The speed of the connection. If the device field is ACU , the speed field will be string matched against entries in Devices . Speeds must either be valid speed numbers or must begin with them (2400, 38400, 19200-PEP, etc.). If the device field is `tcp...' or `telnet ...', the speed field is ignored, but must be present as a place-holder.
phone number
The value to replace the \T escape sequence in the dialer script. If the device field names an entry in /dev, the phone number field is optional. If the device field is `tcp...' or `telnet ...', the phone number field is ignored if present, but must be present as a place-holder.
chat script
A description of the conversation that pppd holds with the remote machine.

During the delay following an unsuccessful call, any level 6 debugging messages written to pppd.log will have the message `dial failed' appended.

CHAT SCRIPT PARTICULARS

A chat script takes the form of a space-separated list of expect-send pairs. At minimum, each pair consists of a field to expect the "remote" end to send, followed by a field to send in response. Unless asend' string ends with \ c , pppd will follow it by sending a carriage return character (ASCII 0x0d).

Chat scripts areexpect send expect send...', orexpect-send-expect send...', where thesend' following the hyphen is executed if the preceding expect fails to match received text.

Certain special words may be used in the chat script to control the behavior of pppd as it attempts to dial. Both ABORT and TIMEOUT must be in the "expect" phase of the chat script.

ABORT abort-string
If pppd sees abort-string while executing the remainder of the chat script , abort the dialing attempt and note the failure in the log file.
TIMEOUT timeout-time
While executing the current chat script, wait timeout-time seconds for a response before considering the dialing attempt to have timed out. Writes have a fixed 60-second timeout.

The expect-send couplet of "" P_WORD sets the line parity accordingly:

P_AUTO
Set transmission parity based on the parity observed in characters received inexpect' strings. This is the default.
P_ZERO
Transmit characters with the parity bit set to 0
(8 bits, no parity).
P_ONE
Transmit characters with the parity bit set to 1
P_EVEN
Transmit characters with even parity.
P_ODD
Transmit characters with odd parity.

The backquote character (`) surrounds the name of a program that is to be run before proceeding. If the program is run in the `send ` phase of a chat script couplet, its standard output will be sent to the peer when the program exits. Chat script processing continues when the program exits.

In the midst of either anexpect' string or a `send ' string, ^x gets translated into the appropriate control character, and \x gets translated into x . Other special sequences are:

\s
Send or receive a space character (ASCII 0x20)
\t
Send or receive a horizontal tab character (ASCII 0x09)
\n
Send or receive a line feed character (ASCII 0x0a)
\r
Send or receive a carriage return character (ASCII 0x0d)
\\
Send or receive a backslash character (ASCII 0x5c)
\^
Send or receive a carat character (ASCII 0x5e)
^<character>
Send or receive the single character Ctrl-<character> (ASCII 0x00 through 0x1f)
\ ddd Send or receive a character, specified in octal d igits
\p
Pause for.25 second before proceeding (send only)
\d
Delay for 2 seconds before proceeding (send only)
\K
Send a break (.25 second of zero bits)
\M
Disable hangups (sets CLOCAL or LNOHANG)
\m
Enable hangups (unsets CLOCAL or LNOHANG) (the default)
\c
Don't append a carriage return character after sending the preceding string (send only)
\q
Don't print succeeding send strings (e.g. a password ) in any debugging or logging output. Subsequent \ q sequences togglequiet' mode.
\A
Parse the incoming string as an IP address, written as four decimal numbers separated by periods, and use it for the local end of the point-to-point connection (receive only)

EXAMPLE

In the example below:

If you are unsuccessful at connecting with `someone' you will try again in two seconds. If that attempt fails, you will wait four seconds before the next attempt; then eight, then sixteen, then thirty two, then forty seconds. You will continue attempting to contact `someone' every forty seconds.

Your retry intervals and maximum backoff values for `everyone' and `nobody' are the default `10-3600'.

The notation "" "" means to expect nothing, then send nothing, followed by a carriage return. The implicit carriage return is often useful for eliciting a response from a remote system.
#
# Systems - PPP systems file
#
everyone Any ACU 19200-PEP 5551212 in:--in: Pwe word: \ qfoObar
nobody Any ACU 38400 5551213 in:--in: Pthey word: \ qbaZz1ng
someone Any;2-40 cua 38400 0 in:--in: Pthem word: \qmeumBle
anyone Any rsd0a/0 1536000
pseudo-one Any;2-2 tcp/realone.somewhere.com/57

RECOMMENDATIONS

Retry and Backoff Times

Using the Default

The default retry time and backoff (i.e. Any;10-3600) are appropriate for use with dialup connections where the PPP connection must be reestablished as quickly as possible after an interruption but where it is not desirable to continuously redial a host that may be down.

Dedicated Lines or No-Cost connections

A much shorter maximum would be appropriate for a dedicated line between two systems, or where call attempts cost nothing.

Bi-Directional Dial Up Modems

Moderate call retry times, such as 60 seconds, work well on systems that can establish connections in either direction using dialup modems, to avoid deadlocks waiting for telephone busy signals from each calling the other at the same time. Because of the difference between the behaviors of originating and answering modems, the 60-second clocks will usually start ticking at different times, allowing one side to call the other without interference. Alternatively, different call retry times may be specified at either end of a link to help keep the two systems from calling each other simultaneously.

Specifying Host Names

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 in dotted quad format in Filter and Systems instead.

Automatic Failover

Automatic failover recovery can be arranged between systems that each have multiple modems, or multiple connection methods. If two systems are connected via a dedicated line (sync or async), that entry should be first in Systems , followed by another entry describing an on-demand dialup connection. See the MST PPP User Guide for more details.

SECURITY CONCERNS

The file /usr/lib/mstppp/Systems should be mode 600.

SEE ALSO

tun(MST_PPP), ppp.Auth (MST_PPP), ppp.Services(MST_PPP), ppp.Dialers (MST_PPP), ppp.Filter (MST_PPP), ppp.Keys (MST_PPP), pppd (MST_PPP), RFC 1661 , RFC 1332, RFC 1144 , RFC 1055 .

COPYRIGHT INFORMATION

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


PPPD(MST_PPP)

NAME

pppd - PPP daemon

SYNOPSIS

pppd [options...]

DESCRIPTION

Pppd is a daemon process used in UNIX systems to manage connections to other hosts using PPP , the Point to Point Protocol, or SLIP , the Serial Line Internet Protocol. It uses the UNIX host's native serial ports or the Morning Star SnapLink SCSI-attached high speed serial interface. It communicates with the UNIX kernel 's own TCP /IP implementation via the Morning Star IP tunnel driver . (see tun (MST_PPP))

DAEMON MANAGEMENT OPTIONS

FIELD
DESCRIPTION
auto
Requires the remote address. Start inautocall' mode and detach from the controlling terminal to run as a daemon . Initiate connection in response to a packet specified in the filter-file`bringup' category.
up
When used with auto , bring the link up immediately rather than waiting for traffic. If the link goes down, attempt to restart it after the call retry delay timer expires. Don't wait for an outbound packet.
dedicated
Implies up . Treat the connection as dedicated line rather than a demand-dial connection.

This option tells pppd to never give up on the connection. If the peer tries to shut down the link, pppd does, but will immediately try to reestablish the connection. Similarly, when first trying to connect, pppd will not give up after sending a fixed number of Configure-Request messages. As with dialup connections, hangup events (LQM failures, loss of Carrier Detect) will cause the device to be closed, and the Systems file is then checked for alternate entries. If none are available, the connection will be re-established after the call retry delay timer expires. Use a short call retry delay timer on dedicated circuits. Something like Any;5-30 should work well..

nodetach
Don't detach from the controlling terminal inautocall' mode. When used with log , this is useful for watching the progress of the PPP session.
log log-file
Append logging messages to log -file (default: /usr/adm/pppd .log ).
acct acct-file
Append session accounting messages to acct-file. If acct-file is the same as log-file, the session accounting messages is interleaved with other logging information.

filter filter-file
Look in filter-file for packet filtering and link management information
(default: /usr/lib/mstppp/Filter on SCO systems).
debug debug-level
Set the log file verbosity to debug-level, chosen from the following table:
0
Daemon start messages
1
Link status messages, calling attempts (the default)
2
Chat script processing, input framing errors
3
LCP, IPCP, PAP and CHAP negotiation
4
LQM status summaries
5
IP interface changes
6
IP message summaries
7
Full LQM reports
8
All PPP messages (without framing)
9
Characters read or written
10
Procedure call messages
11
Internal timers the lower-numbered levels

exec exec-cmd
Runexec-cmd up addr args' when the link comes up, andexec-cmd down addr args' when it goes down. Addr is the IP address of the peer, and args is the list of arguments given to pppd .
nonice
Run at a normal user process priority, rather than using the nice() library routine to elevate pppd's scheduling priority to 10.

COMMUNICATIONS OPTIONS

asyncmap async-map
Set the desired Async Control Character Map to async-map, expressed in C-style hexadecimal notation (default0xA0000).
noasyncmap
Disable LCP Async Control Character Map negotiation.
escape odd-character
In addition to characters specified in the PPP Async Control Character Map, which can include only 0x00 through 0x1F, apply the escaping algorithm when transmitting odd-character. The value of odd-character must be between 0x00 and 0xFF, and cannot be 0x5E, 0x7D or 0x7E.

Odd-character can be specified as a decimal number, in C-style hexadecimal notation, or as an ASCII character with optional^' control-character notation. For example, the XON character could be specified as 17, 0x11, or ^Q.

A warning will be printed in the log file and the character specified on the command line will not be escaped if a character specified with the escape argument is the same as a character contained in the peer's negotiated Async Control Character Map when the character is transformed into its escaped form,

Pppd will print an error message and exit if a character specified with the escape argument is the same as a character specified in another escape argument on the daemon's command line when transformed into its escaped form.

device
Communicate over the named device (default /dev/tty ).
comm-speed
Set communications rate to comm-speed bits per second.
poll poll-rate
Set SnapLink polling frequency, in polls per second. Recommend values are 20, 50, or 100 (default 50).
internal-clocking
A SnapLink will provide the synchronous clock signal (TXCLK and RXCLK). By default, it expects the modem, CSU/DSU or modem eliminator to provide the clock signal. Internal-clocking cannot be used with RS-232 cables on the SnapLink.
ignore-cd
Ignore the state of the CD (Carrier Detect, also called DCD, Data CarrierDetect) signal. This is useful for systems that don't support CD but want to run PPP over a dedicated line.
gw-crypt keys-file
Encrypt traffic between the pairs of hosts or networks specified in the designated keys file (see ppp.Keys (5)).
rtscts
Set the line to use out-of-band EIA RS-232-Dhardware' (RTS/CTS) flow control. (The default is to use no flow control.) For an outbound connection, this may be specified either in Devices or on the pppd command line. On SCO systems, rtscts cannot be used with either rtscts-rtsflow or rtscts-crtsfl .
crtscts
A synonym for rtscts.
rtscts-rtsflow
As above in rtscts , but sets both CTSFLOW and RTSFLOW. Cannot be used with either rtscts or rtscts-crtsfl.
crtscts-rtsflow
A synonym for rtscts-rtsflow .
rtscts-crtsfl
As above in rtscts , but sets CRTSFL and clears CTSFLOW and RTSFLOW. Cannot be used with either rtscts or rtsctsrtsflow.
crtscts-crtsfl
A synonym for rtscts-crtsfl .
xonxoff
Set the line to use in-band ('software') flow control, using the characters DC3 (^S, XOFF, ASCII 0x13) to stop the flow and DC1 (^Q, XON, ASCII 0x11) to resume. For an outbound connection, this may be specified either in Devices or on the pppd command line.
telnet
When used on an answering pppd command line, negotiate the telnet binary option and understand telnet escape processing. Not for use with device or auto .

LINK MANAGEMENT OPTIONS

nooptions
Disable all LCP and IPCP options.
noaccomp
Disable HDLC Address and Control Field compression.
noprotcomp
Disable LCP Protocol Field Compression.
compress
Offer all supported link compression types when negotiating. The default is to propose and accept no link compression type.
compress-pred1
Accept any supported compression type, but prefer Predictor type 1 compression.
compress-stac
Accept any supported compression type, but prefer Stac LZS compression.
nopred1
Never use Predictor-1 compression.
nostac
Never use Stac LZS compression.
slip
Use RFC 1055 LIP packet framing rather than PPP packet framing. Disables all option negotiation, and implies noasyncmap, noipaddress, vjslots 16, novjcid, nomagic, nomru , and mru 1006 if peer sends a header-compressed TCP packet.
extra-slip-end
When running in SLIP mode, prepend a SLIP packet framing character (0xC0) to each frame before transmission, even if this frame immediately follows the previous frame. By default, pppd transmits only one framing character between adjacent SLIP frames.
nomagic
Disable LCP Magic Number negotiation.
mru mru-size
Set LCP Maximum Receive Unit value to mru-size for negotiation. The default is 1500 for PPP and 1006 for SLIP. The value must be greater than 128.
nomru
Disable LCP Maximum Receive Unit negotiation, and use 1500 for your interface.
active
Begin LCP parameter negotiation immediately. Active is the default
passive
Do not send our first LCP packet until we receive an LCP packet from the peer.
timeout restart-time
Set the LCP, IPCP, CCP, PAP, and CHAP option negotiation restart timers to restart-time . The default is 3 seconds.
lqrinterval time
Send Link-Quality-Reports or Echo-Requests every time seconds (default 10 seconds). If the peer responds with a Protocol-Reject, send LCP Echo-Requests every time seconds instead, and use the received LCP Echo-Replies for link status policy decisions.
lqthreshold min/per
Set a minimum standard for link quality by considering the connection to have failed if fewer than min out of the last per LQRs we sent have been responded to by the peer (default 1/5). The per number can be no greater than 256 and cannot be 0.
echolqm
Use LCP Echo-Requests rather than standard Link-Quality-Report messages for link quality assessment and policy decisions. The peer can override this if it actively tries to configure Link Quality Monitoring unless the nolqm parameter is also specified.
nolqm
Don't send or recognize Link-Quality-Report messages. If echolqm is also specified, Echo-Request messages will be used to detect link failures.
idle idle-time
Shut down the link when idle-time seconds pass without receiving or transmitting a packet specified in the `keepup' category in the filter file. The default is to never shut down.
max-configure tries
Set the PPP Max-Configure counter to the value of tries . This is the maximum number of Configure-Requests sent without a response.
max-terminate tries
Set the PPP Max-Terminate counter to the value of tries . This is the maximum number of Terminate-Requests to be sent without a response.
max-failure tries
Set the PPP Max-Failure counter to the value of tries . This is the maximum number of Configure-Naks to be sent without a positive response. Default is 5, in accordance with RFC 1661

IP OPTIONS

local:remote
The address of this machine, followed by the expected address for the remote machine. Can be specified either as symbolic names or as literal IP address es, if their addresses cannot be discovered locally without using the PPP link.

Both addresses are optional, but a colon by itself is not valid, and the remote address is required when running as a daemon inautocall' mode. If onlylocal:' is specified when receiving an incoming call, the remote address will be discovered during IPCP IP -Address negotiations.

If either address is followed by a tilde character ('~'), or if the tilde appears alone, pppd accepts the IP address given by the peer during IPCP negotiations, whether for the local end or the peer's end of the link. (not available in SLIP mode)

Because SLIP cannot perform option negotiations, including IPCP, both addresses should normally be specified, and the tilde option is unavailable. To obtain a similar "feature", the peer must provide the IP address textually during the login process, and a new value must be obtained using the Systems file `\A' chat script feature (see ppp.Systems (MST_PPP)).

netmask subnet-mask
Set the subnet mask of the interface to subnet-mask, expressed either in C-style hexadecimal (e.g. 0xffffff00) or in decimal dotted-quad notation (e.g. 255.255.255.0). The default subnet mask will be appropriate for the network (class A, B, or C), assuming no subnetting.
noipaddress
Disable IPCP IP-Address negotiation.
need-ip-address
Force IPCP to ask the peer to assign us an IP address even if pppd was invoked with a local address on the command line.
vjcomp
Enable RFC 1144 `VJ' Van Jacobson TCP header compression negotiation with 16 slots and slot ID compression (this is the default with PPP framing).VJ' compression is enabled by default for async connections, and disabled by default for sync connections.
novjcomp
Disable RFC 1144 `VJ' Van Jacobson TCP header compression (this is the default with SLIP framing, until the peer sends a header-compressed
vjslots vj-slots
Set the number of VJ compression slots (min 3, max 256, default 16).
novjcid
Disable VJ compression slot ID compression (enabled by default).
rfc1172-vj
Backwards compatibility with older PPP implementations (4-byte VJ configuration option), but with the correct option negotiation value of 0x002d.
rfc1172-typo-vj
Backwards compatibility with older PPP implementations (4-byte VJ configuration option) that conform to the typographical error in RFC 1172 section 5.2 (Compression-Type value 0x0037).
rfc1172-addresses
Backwards compatibility with older PPP implementations that conform to RFC 1172 section 5.1 (IP-Addresses, IPCP configuration option 1) and not with the newer RFC 1332 (IP-Address, IPCP configuration option 3), but that respond with something besides a Configure-Reject when they receive an IPCP Configure-Request containing an option 3.

AUTHENTICATION OPTIONS

rechap interval
Demand that the peer re-authenticate itself (using CHAP) every interval seconds. If the peer fails the new challenge, the link is terminated.
requireauth
Require either PAP or CHAP authentication . Equivalent to individually specifying requirechap , requirepap and requiremschap .
requirechap
Require CHAP authentication as described in RFC 1334.
requiremschap
Require Microsoft MS CHAP authentication
name identifier
Provide the identifier used during PAP or CHAP negotiation. This option is necessary if the PPP peer requires authentication . The default value is the value returned by the gethostname (2) system call or the hostname (1) command.

ENCRYPTION OPTIONS

Encryption software is not available outside the United States, and therefore is not
available in international licenses.

gw-crypt keys-file
Encrypt traffic between the pairs of hosts or networks specified in the designated keys file (see ppp.Keys (5)).

MICROSOFT COMPATIBILITY OPTIONS

ms-dns
Set the MS DNS address to provide to the peer . First occurrence of this option on the command line sets the primary address. Second occurrence sets the secondary address.
ms-nbns address
Set the MS NBNS address to provide to the peer . First occurrence of this option on the command line sets the primary address. Second occurrence sets the secondary address.

LOG FILE

Status information is recorded in the log file by each copy of pppd running on a single machine. The default file for logging is /usr/adm/pppd.log . Each line in the file consists of a message preceded by the date, the time, and the process ID number of the daemon writing the message. The quantity and verbosity of messages are controlled with the debug option and with the log filter (see ppp.Filter (5)).

Each packet that:

or
The parts of the message are as follows:
1. The protocol ( tcp, udp, icmp , or a numeric protocol value ). For ICMP packets, the keyword icmp is followed by the ICMP message type and sub code, separated by slashes.
2. An IP address and, optionally, a TCP or UDP port number, followed by an arrow indicating whether the packet was sent ( ) or received ( )
3. Another address and port number. For transmitted packets, this is the source address . For received packets, this is the destination address . Well known TCP and UDP port numbers are replaced by the name returned by the getservbyport () library function.
4. The length of the packet in bytes before VJ TCP header compression .
5. Zero or more keywords. The keywords and their meanings are:
frag
the packet is a middle or later part of a fragmented IP frame
syn
the packet has the TCP SYN bit set
fin
the packet has the TCP FIN bit set
bringup
the transmitted packet matches the bringup filter and is bringing up the link
!keepup
the packet has been rejected by the keepup filter
!pass
the packet has been rejected by the pass filter
dial failed
the packet was dropped because pppd is waiting for the call retry timer to expire
(c)
the received packet is VJ TCP header compressed
(u)
the received packet is VJ TCP header uncompressed

For example, the following log file line indicates that at 2:06:26 PM on September 6, process ID 83 sent a 44-byte TCP packet with the SYN bit set from port 1050 on 63.1.6.3 to the SMTP port on 8.1.1.9.

9/6-14:06:26-83 tcp 63.1.6.3/1050 -> 8.1.1.9/smtp 44 syn

SIGNALS

When the following signals are received by pppd it closes and reopens the log file , re-reads the filter and key files, then takes the indicated actions:

SIGKILL
Don't use this. Never, never use this . Since pppd won't be able to shut down gracefully, it will leave your serial interfaces (whether /dev/tty or a SnapLink) and your IP tunnel driver in some unknown state. Use SIGTERM instead, so pppd will shut down cleanly, and leave the system in a well-defined state.
SIGINT
Disconnect gracefully from an active session. If inautocall' mode, reset all retry backoff interval. If up was specified, attempt to re-establish the link. Exit if not inautocall' mode.
SIGHUP
Disconnect abruptly from an active session. If up was specified, attempt to re-establish the link. Exit if not inautocall' mode.
SIGTERM
Disconnect gracefully from an active session, clean up the state of any serial and IP interfaces that are open, then exit.
SIGUSR1
Increment the verbosity level for logged debugging information.
SIGUSR2
Reset the debugging verbosity level to the base value (1, unless debug 0 was supplied on the command line).
SIGALRM
Take no action except to re-read the filter and key files.

EXAMPLE:

For outgoing PPP connections:

The file /etc/rc2.d/S89mstppp , shown here, starts up PPP upon booting the
system, and shuts it down during system shutdown:

#!/bin/sh
# Sysinit script for Morning Star Technologies PPP for SCO UNIX
#
# This file should be linked to appropriate places in
# /etc/rc0.d, /etc/rc2.d and /etc/init.d

PPPHOME=/usr/lib/mstppp
PATH=/bin:usr/bin:/usr/lib/mstppp:/etc
export PPPHOME PATH

LOGDIR=/usr/adm

case "$1" in
start')
if [ -f ${PPPHOME}/pppd ]; then
if [ -f ${LOGDIR}/pppd.log ]; then
mv ${LOGDIR}/pppd.log ${LOGDIR}/OLDpppd.log
fi
if [ -x ${PPPHOME}/Autostart ]; then
echo "Starting PPP..."
${PPPHOME}/Autostart
fi
fi ;;

stop')
while pid=`/bin/ps -e 2>/dev/null | /bin/grep pppd | /bin/grep -v grep`
do
[ -z "${pid}" ] && continue
set -- ${pid}
pid=$1

if [ "${pid}" != "" ]
then
/bin/kill -15 ${pid}
(echo "Stopping pppd(pid $pid)") > /dev/console
fi
done
;;

echo "Usage: $0 {start | stop}"
exit 1
;;
esac

The S89mstppp file executes /usr/lib/mstppp/Autostart , which executes another
script, /usr/lib/mstppp/exec.dialout for dialing out:

/usr/lib/mstppp/dialout 132.147.65.2~:132.147.65.254~ auto up \
exec /usr/lib/mstppp/exec.dialout netmask 255.255.255.0 idle 120

This file uses the script /usr/lib/mstppp.dialout
to call the system with an IP number of 132.147.65.254. The dialout file
is the script that actually executes pppd.

The local side of the connection (as defined in Autostart ) will have the IP
number 132.147.65.2. The remote side of the connection will have the IP
number 132.147.65.254.

The system will dialout immediately (up) and sets the idle timer to two
minutes (idle 120), causing the link to disconnect in two minutes if there
is no activity. The netmask is set to 255.255.255.0, and the script
called /usr/lib/mstppp/exec.dialout is executed when the link is established
or brought down. The ~'s at the end of the IP numbers indicate that the remote
side can reset the IP numbers when the link is established. To determine
what phone number and login sequence (chat Script) to use, the PPP daemon
consults the /usr/lib/mstppp/Systems file:

132.147.65.254 Any;5 ACU 38400 5551212 "" \r\d in:--in: \dpppuser word: passwd

Note that the IP number listed here is the initial IP number of the remote
system, matched in the Autostart file.

The PPP daemon uses the /usr/lib/mstppp/Devices file to determine the modem,
baud rate, and tty to use:

atdialSPORT tty1A 38400

The modem is a binary dialer in /usr/lib/uucp or an entry in the
/usr/lib/mstppp/Dialers file.

Incoming PPP setup

For incoming connections, a user needs to be created with the login shell
/usr/lib/mstppp/Login , with the home directory /usr/lib/mstppp . When a user
with this shell logs into the system, an attempt to create a PPP connection
is made.

pppuser:x:200:100:PPP account:/usr/lib/mstppp:/usr/lib/mstppp/Login

The login shell / usr/lib/mstppp/Login is actually a script that reads
the file /usr/lib/mstppp/Accounts . When the user "pppuser" logs in,
/usr/lib/mstppp/Login tries to match the user name "pppuser" against the
first field in the Accounts file:

pppuser 132.147.65.229:132.147.65.2 exec /usr/lib/mstppp/exec.dialin \
netmask 255.255.255.0 idle 300 rtscts
ppp2 132.147.65.229:132.147.65.4 exec /usr/lib/mstppp/exec.dialin \
netmask 255.255.255.0 idle 300 rtscts

In this case, the first line line matches the user "pppuser", and the PPP
daemon is executed using the arguments shown in the rest of the line in
this file:

132.147.65.229:132.147.65.2 exec /usr/lib/mstppp/exec.dialin \
netmask 255.255.255.0 idle 300 rtscts

In this example, the local IP number is assigned as 132.147.65.229, the
system dialing into this one is assigned IP number 132.147.65.2, with
netmask 255.255.255.0. The sysetm will bring down the link in 5 minutes if
there is no activity, (idle 300), and it uses hardware flow control.
(rtscts) The script /usr/lib/mstppp/exec.dialin is run when the link
is brought up or down.

ENVIRONMENT

The environment variable PPPHOME , if present, specifies the directory in which pppd looks for its configuration files ( Filter and Auth for all connections, along with Systems , Devices , and Dialers if the connection isoutbound '). You can specify PPPHOME either in the Startup script or in an incoming connection's Login script. If PPPHOME is not present, pppd will expect to find its configuration files in /usr/lib/mstppp/*.

SECURITY CONCERNS

Pppd should be mode 4750, owned by root, and executable only by the members of the group containing all the incoming PPP login users'.

STANDARDS CONFORMANCE

MST PPP implements the IETF Standard Point-to-Point Protocol and many of its options and extensions, conforming with RFCs 1661, 1549, 1332, 1333, 1334, and 1144. It can be configured to conform with earlier specifications of the PPP protocol, as described in RFCs 1134, 1171, and 1172. MST PPP also implements the nonstandard SLIP protocol as described in RFCs 1055 and 1144.

SEE ALSO

tun(MST_PPP), ppp.Auth (MST_PPP), ppp.Devices (MST_PPP), ppp.Dialers (MST_PPP), ppp.Filter (MST_PPP), ppp.Keys (MST_PPP), ppp.Systems (MST_PPP), RFC 1661 , RFC 1549, RFC 1332, RFC 1333 , RFC 1334 , RFC 1172, RFC 1144 , RFC 1055 , ds.internic.net:/internet-drafts/draft-ietf-pppext-compression -04.txt.