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.