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.