NAME
pppd - Point to Point Protocol daemon

SYNOPSIS
pppd [ options ] [ tty_name ] [ speed ]

DESCRIPTION
The Point-to-Point Protocol (PPP) provides a method for
transmitting datagrams over serial point-to-point links. PPP is
composed of three parts: a method for encapsulating datagrams over
serial links, an extensible Link Control Protocol (LCP), and a
family of Network Control Protocols (NCP) for establishing and
configuring different network-layer protocols.

The encapsulation scheme is provided by driver code in the kernel.
pppd provides the basic LCP, authentication support, and an NCP for
establishing and configuring the Internet Protocol (IP) (called the
IP Control Protocol, IPCP).

FREQUENTLY USED OPTIONS
<tty_name>
Communicate over the named device. The string "/dev/" is
prepended if necessary. If no device name is given, pppd will
use the controlling terminal, and will not fork to put itself
in the background.

<speed>
Set the baud rate to <speed>. On systems such as 4.4BSD and
NetBSD, any speed can be specified. Other systems (e.g.
SunOS) allow only a limited set of speeds.

asyncmap <map>
Set the async character map to <map>. This map describes
which control characters cannot be successfully received over
the serial line. pppd will ask the peer to send these
characters as a 2-byte escape sequence. The argument is a 32
bit hex number with each bit representing a character to
escape. Bit 0 (00000001) represents the character 0x00; bit 31
(80000000) represents the character 0x1f or ^_. If multiple
asyncmap options are given, the values are ORed together. If
no asyncmap option is given, no async character map will be
negotiated for the receive direction; the peer will then
escape all control characters.

auth Require the peer to authenticate itself before allowing
network packets to be sent or received.

connect <p>
Use the executable or shell command specified by <p> to set up
the serial line. This script would typically use the "chat"
program to dial the modem and start the remote ppp session.

crtscts
Use hardware flow control (i.e. RTS/CTS) to control the flow
of data on the serial port.

xonxoff
Use software flow control (i.e. XON/XOFF) to control the flow
of data on the serial port. This option is not implemented on
BSD or Ultrix systems at present.

-crtscts
A synonym for xonxoff.

defaultroute
Add a default route to the system routing tables, using the
peer as the gateway, when IPCP negotiation is successfully
completed. This entry is removed when the PPP connection is
broken.

disconnect <p>
Run the executable or shell command specified by <p> after
pppd has terminated the link. This script could, for example,
issue commands to the modem to cause it to hang up if hardware
modem control signals were not available.

escape xx,yy,...
Specifies that certain characters should be escaped on
transmission (regardless of whether the peer requests them to
be escaped with its async control character map). The
characters to be escaped are specified as a list of hex
numbers separated by commas. Note that almost any character
can be specified for the escape option, unlike the asyncmap
option which only allows control characters to be specified.
The characters which may not be escaped are those with hex
values 0x20 - 0x3f or 0x5e.

file <f>
Read options from file <f> (the format is described below).

lock Specifies that pppd should use a UUCP-style lock on the serial
device to ensure exclusive access to the device.

mru <n>
Set the MRU [Maximum Receive Unit] value to <n> for
negotiation. pppd will ask the peer to send packets of no
more than <n> bytes. The minimum MRU value is 128. The
default MRU value is 1500. A value of 296 is recommended for
slow links (40 bytes for TCP/IP header + 256 bytes of data).

netmask <n>
Set the interface netmask to <n>, a 32 bit netmask in "decimal
dot" notation (e.g. 255.255.255.0).

passive
Enables the "passive" option in the LCP. With this option,
pppd will attempt to initiate a connection; if no reply is
received from the peer, pppd will then just wait passively for
a valid LCP packet from the peer (instead of exiting, as it
does without this option).

silent
With this option, pppd will not transmit LCP packets to
initiate a connection until a valid LCP packet is received
from the peer (as for the "passive" option with old versions
of pppd).

OPTIONS
<local_IP_address>:<remote_IP_address>
Set the local and/or remote interface IP addresses. Either
one may be omitted. The IP addresses can be specified with a
host name or in decimal dot notation (e.g. 150.234.56.78).
The default local address is the (first) IP address of the
system (unless the noipdefault option is given). The remote
address will be obtained from the peer if not specified in any
option. Thus, in simple cases, this option is not required.
If a local and/or remote IP address is specified with this
option, pppd will not accept a different value from the peer
in the IPCP negotiation, unless the ipcp-accept-local and/or
ipcp-accept-remote options are given, respectively.

-all Don’t request or allow negotiation of any options for LCP and
IPCP (use default values).

-ac Disable Address/Control compression negotiation (use default,
i.e. address/control field disabled).

-am Disable asyncmap negotiation (use the default asyncmap, i.e.
escape all control characters).

-as <n>
Same as asyncmap <n>

-d Increase debugging level (same as the debug option).

-detach
Don’t fork to become a background process (otherwise pppd will
do so if a serial device is specified).

-ip Disable IP address negotiation (with this option, the remote
IP address must be specified with an option on the command
line or in an options file).

-mn Disable magic number negotiation. With this option, pppd
cannot detect a looped-back line.

-mru Disable MRU [Maximum Receive Unit] negotiation (use default,
i.e. 1500).

-p Same as the passive option.

-pc Disable protocol field compression negotiation (use default,
i.e. protocol field compression disabled).

+ua <p>
Agree to authenticate using PAP [Password Authentication
Protocol] if requested by the peer, and use the data in file
<p> for the user and password to send to the peer. The file
contains the remote user name, followed by a newline, followed
by the remote password, followed by a newline. This option is
obsolescent.

+pap Require the peer to authenticate itself using PAP.

-pap Don’t agree to authenticate using PAP.

+chap
Require the peer to authenticate itself using CHAP
[Cryptographic Handshake Authentication Protocol]
authentication.

-chap
Don’t agree to authenticate using CHAP.

-vj Disable negotiation of Van Jacobson style IP header
compression (use default, i.e. no compression).

debug
Increase debugging level (same as -d). If this option is
given, pppd will log the contents of all control packets sent
or received in a readable form. The packets are logged
through syslog with facility daemon and level debug. This
information can be directed to a file by setting up
/etc/syslog.conf appropriately (see syslog.conf(5)). (If pppd
is compiled with extra debugging enabled, it will log messages
using facility local2 instead of daemon).

domain <d>
Append the domain name <d> to the local host name for
authentication purposes. For example, if gethostname()
returns the name porsche, but the fully qualified domain name
is porsche.Quotron.COM, you would use the domain option to set
the domain name to Quotron.COM.

modem
Use the modem control lines. On Ultrix, this option implies
hardware flow control, as for the crtscts option. (This
option is not fully implemented.)

kdebug n
Enable debugging code in the kernel-level PPP driver. The
argument n is a number which is the sum of the following
values: 1 to enable general debug messages, 2 to request that
the contents of received packets be printed, and 4 to request
that the contents of transmitted packets be printed.

local
Don’t use the modem control lines.

mtu <n>
Set the MTU [Maximum Transmit Unit] value to <n>. Unless the
peer requests a smaller value via MRU negotiation, pppd will
request that the kernel networking code send data packets of
no more than n bytes through the PPP network interface.

name <n>
Set the name of the local system for authentication purposes
to <n>.

user <u>
Set the user name to use for authenticating this machine with
the peer using PAP to <u>.

usehostname
Enforce the use of the hostname as the name of the local
system for authentication purposes (overrides the name
option).

remotename <n>
Set the assumed name of the remote system for authentication
purposes to <n>.

proxyarp
Add an entry to this system’s ARP [Address Resolution
Protocol] table with the IP address of the peer and the
Ethernet address of this system.

login
Use the system password database for authenticating the peer
using PAP.

noipdefault
Disables the default behaviour when no local IP address is
specified, which is to determine (if possible) the local IP
address from the hostname. With this option, the peer will
have to supply the local IP address during IPCP negotiation
(unless it specified explicitly on the command line or in an
options file).

lcp-echo-interval <n>
If this option is given, pppd will send an LCP echo-request
frame to the peer every n seconds. Under Linux, the echo-
request is sent when no packets have been received from the
peer for n seconds. Normally the peer should respond to the
echo-request by sending an echo-reply. This option can be
used with the lcp-echo-failure option to detect that the peer
is no longer connected.

lcp-echo-failure <n>
If this option is given, pppd will presume the peer to be dead
if n LCP echo-requests are sent without receiving a valid LCP
echo-reply. If this happens, pppd will terminate the
connection. Use of this option requires a non-zero value for
the lcp-echo-interval parameter. This option can be used to
enable pppd to terminate after the physical connection has
been broken (e.g., the modem has hung up) in situations where
no hardware modem control lines are available.

lcp-restart <n>
Set the LCP restart interval (retransmission timeout) to <n>
seconds (default 3).

lcp-max-terminate <n>
Set the maximum number of LCP terminate-request transmissions
to <n> (default 3).

lcp-max-configure <n>
Set the maximum number of LCP configure-request transmissions
to <n> (default 10).

lcp-max-failure <n>
Set the maximum number of LCP configure-NAKs returned before
starting to send configure-Rejects instead to <n> (default
10).

ipcp-restart <n>
Set the IPCP restart interval (retransmission timeout) to <n>
seconds (default 3).

ipcp-max-terminate <n>
Set the maximum number of IPCP terminate-request transmissions
to <n> (default 3).

ipcp-max-configure <n>
Set the maximum number of IPCP configure-request transmissions
to <n> (default 10).

ipcp-max-failure <n>
Set the maximum number of IPCP configure-NAKs returned before
starting to send configure-Rejects instead to <n> (default
10).

pap-restart <n>
Set the PAP restart interval (retransmission timeout) to <n>
seconds (default 3).

pap-max-authreq <n>
Set the maximum number of PAP authenticate-request
transmissions to <n> (default 10).

chap-restart <n>
Set the CHAP restart interval (retransmission timeout for
challenges) to <n> seconds (default 3).

chap-max-challenge <n>
Set the maximum number of CHAP challenge transmissions to <n>
(default 10).

chap-interval <n>
If this option is given, pppd will rechallenge the peer every
<n> seconds.

ipcp-accept-local
With this option, pppd will accept the peer’s idea of our
local IP address, even if the local IP address was specified
in an option.

ipcp-accept-remote
With this option, pppd will accept the peer’s idea of its
(remote) IP address, even if the remote IP address was
specified in an option.

OPTIONS FILES
Options can be taken from files as well as the command line. pppd
reads options from the files /etc/ppp/options and ~/.ppprc before
looking at the command line. An options file is parsed into a
series of words, delimited by whitespace. Whitespace can be
included in a word by enclosing the word in quotes ("). A
backslash ( quotes the following character. A hash (#) starts a
comment, which continues until the end of the line.

AUTHENTICATION
pppd provides system administrators with sufficient access control
that PPP access to a server machine can be provided to legitimate
users without fear of compromising the security of the server or
the network it’s on. In part this is provided by the
/etc/ppp/options file, where the administrator can place options to
require authentication whenever pppd is run, and in part by the PAP
and CHAP secrets files, where the administrator can restrict the
set of IP addresses which individual users may use.

The default behaviour of pppd is to agree to authenticate if
requested, and to not require authentication from the peer.
However, pppd will not agree to authenticate itself with a
particular protocol if it has no secrets which could be used to do
so.

Authentication is based on secrets, which are selected from secrets
files (/etc/ppp/pap-secrets for PAP, /etc/ppp/chap-secrets for
CHAP). Both secrets files have the same format, and both can store
secrets for several combinations of server (authenticating peer)
and client (peer being authenticated). Note that pppd can be both
a server and client, and that different protocols can be used in
the two directions if desired.

A secrets file is parsed into words as for a options file. A
secret is specified by a line containing at least 3 words, in the
order client, server, secret. Any following words on the same line
are taken to be a list of acceptable IP addresses for that client.
If there are only 3 words on the line, it is assumed that any IP
address is OK; to disallow all IP addresses, use "-". If the
secret starts with an ‘@’, what follows is assumed to be the name
of a file from which to read the secret. A "*" as the client or
server name matches any name. When selecting a secret, pppd takes
the best match, i.e. the match with the fewest wildcards.

Thus a secrets file contains both secrets for use in authenticating
other hosts, plus secrets which we use for authenticating ourselves
to others. Which secret to use is chosen based on the names of the
host (the ‘local name’) and its peer (the ‘remote name’). The
local name is set as follows:

if the usehostname option is given,
then the local name is the hostname of this machine (with the
domain appended, if given)

else if the name option is given,
then use the argument of the first name option seen

else if the local IP address is specified with a hostname,
then use that name

given)
else use the hostname of this machine (with the domain appended, if

When authenticating ourselves using PAP, there is also a ‘username’
which is the local name by default, but can be set with the user
option or the +ua option.

The remote name is set as follows:

if the remotename option is given,
then use the argument of the last remotename option seen

else if the remote IP address is specified with a hostname,
then use that host name

else the remote name is the null string "".

Secrets are selected from the PAP secrets file as follows:

* For authenticating the peer, look for a secret with client ==
username specified in the PAP authenticate-request, and server ==
local name.

* For authenticating ourselves to the peer, look for a secret with
client == our username, server == remote name.

When authenticating the peer with PAP, a secret of "" matches any
password supplied by the peer. If the password doesn’t match the
secret, the password is encrypted using crypt() and checked against
the secret again; thus secrets for authenticating the peer can be
stored in encrypted form. If the login option was specified, the
username and password are also checked against the system password
database. Thus, the system administrator can set up the pap-
secrets file to allow PPP access only to certain users, and to
restrict the set of IP addresses that each user can use.

Secrets are selected from the CHAP secrets file as follows:

* For authenticating the peer, look for a secret with client ==
name specified in the CHAP-Response message, and server == local
name.

* For authenticating ourselves to the peer, look for a secret with
client == local name, and server == name specified in the CHAP-
Challenge message.

Authentication must be satisfactorily completed before IPCP (or any
other Network Control Protocol) can be started. If authentication
fails, pppd will terminated the link (by closing LCP). If IPCP
negotiates an unacceptable IP address for the remote host, IPCP
will be closed. IP packets can only be sent or received when IPCP
is open.

In some cases it is desirable to allow some hosts which can’t
authenticate themselves to connect and use one of a restricted set
of IP addresses, even when the local host generally requires
authentication. If the peer refuses to authenticate itself when
requested, pppd takes that as equivalent to authenticating with PAP
using the empty string for the username and password. Thus, by
adding a line to the pap-secrets file which specifies the empty
string for the client and password, it is possible to allow
restricted access to hosts which refuse to authenticate themselves.

ROUTING
When IPCP negotiation is completed successfully, pppd will inform
the kernel of the local and remote IP addresses for the ppp
interface. This is sufficient to create a host route to the remote
end of the link, which will enable the peers to exchange IP
packets. Communication with other machines generally requires
further modification to routing tables and/or ARP (Address
Resolution Protocol) tables. In some cases this will be done
automatically through the actions of the routed or gated daemons,
but in most cases some further intervention is required.

Sometimes it is desirable to add a default route through the remote
host, as in the case of a machine whose only connection to the
Internet is through the ppp interface. The defaultroute option
causes pppd to create such a default route when IPCP comes up, and
delete it when the link is terminated.

In some cases it is desirable to use proxy ARP, for example on a
server machine connected to a LAN, in order to allow other hosts to
communicate with the remote host. The proxyarp option causes pppd
to look for a network interface on the same subnet as the remote
host (an interface supporting broadcast and ARP, which is up and
not a point-to-point or loopback interface). If found, pppd
creates a permanent, published ARP entry with the IP address of the
remote host and the hardware address of the network interface
found.

EXAMPLES
In the simplest case, you can connect the serial ports of two
machines and issue a command like

pppd /dev/ttya 9600 passive

to each machine, assuming there is no getty running on the serial
ports. If one machine has a getty running, you can use kermit or
tip on the other machine to log in to the first machine and issue a
command like

pppd passive

Then exit from the communications program (making sure the
connection isn’t dropped), and issue a command like

pppd /dev/ttya 9600

The process of logging in to the other machine and starting pppd
can be automated by using the connect option to run chat, for
example:

pppd /dev/ttya 38400 connect ’chat "" "" "login:" "username"
"Password:" "password" "% " "exec pppd passive"’

(Note however that running chat like this will leave the password
visible in the parameter list of pppd and chat.)

If your serial connection is any more complicated than a piece of
wire, you may need to arrange for some control characters to be
escaped. In particular, it is often useful to escape XON (^Q) and
XOFF (^S), using asyncmap a0000. If the path includes a telnet,
you probably should escape ^] as well (asyncmap 200a0000). If the
path includes an rlogin, you will need to use the escape ff option
on the end which is running the rlogin client, since many rlogin
implementations are not transparent; they will remove the sequence
[0xff, 0xff, 0x73, 0x73, followed by any 8 bytes] from the stream.

DIAGNOSTICS
Messages are sent to the syslog daemon using facility LOG_DAEMON.
(This can be overriden by recompiling pppd with the macro LOG_PPP
defined as the desired facility.) In order to see the error and
debug messages, you will need to edit your /etc/syslog.conf file to
direct the messages to the desired output device or file.

The debug option causes the contents of all control packets sent or
received to be logged, that is, all LCP, PAP, CHAP or IPCP packets.
This can be useful if the PPP negotiation does not succeed. If
debugging is enabled at compile time, pppd uses facility LOG_LOCAL2
instead of LOG_DAEMON, and the debug option causes additional
debugging messages to be logged.

Debugging can also be enabled by sending a SIGUSR1 to the pppd
process. Debugging may be disabled by sending a SIGUSR2 to the
pppd process.

FILES
/var/run/pppn.pid (BSD), /etc/ppp/pppn.pid (SunOS)
Process-ID for pppd process on ppp interface unit n.

/etc/ppp/ip-up
A program or script which is executed when the link is
available for sending and receiving IP packets (that is, IPCP
has come up). It is executed with the parameters interface-
name tty-device speed local-IP-address remote-IP-address.

This program or script is executed with the same real and
effective user-ID as pppd, that is, at least the effective
user-ID and possibly the real user-ID will be root. This is
so that it can be used to manipulate routes, run privileged
daemons (e.g. sendmail), etc. Be careful that the contents
of the /etc/ppp/ip-up and /etc/ppp/ip-down scripts do not
compromise your system’s security.

/etc/ppp/ip-down
A program or script which is executed when the link is no
longer available for sending and receiving IP packets. This
script can be used for undoing the effects of the
/etc/ppp/ip-up script. It is invoked with the same parameters
as the ip-up script, and the same security considerations
apply, since it is executed with the same effective and real
user-IDs as pppd.

/etc/ppp/pap-secrets
Usernames, passwords and IP addresses for PAP authentication.

/etc/ppp/chap-secrets
Names, secrets and IP addresses for CHAP authentication.

/etc/ppp/options
System default options for pppd, read before user default
options or command-line options.

~/.ppprc
User default options, read before command-line options.

/etc/ppp/options.ttyname
System default options for the serial port being used, read
after command-line options.

SEE ALSO
RFC1144
Jacobson, V. Compressing TCP/IP headers for low-speed serial
1990 February.

RFC1321
Rivest, R. The MD5 Message-Digest Algorithm. 1992 April.

RFC1332
McGregor, G. PPP Internet Protocol Control Protocol (IPCP).
1992 May.

RFC1334
Lloyd, B.; Simpson, W.A. PPP authentication protocols. 1992
October.

RFC1548
Simpson, W.A. The Point-to-Point Protocol (PPP). 1993
December.

RFC1549
Simpson, W.A. PPP in HDLC Framing. 1993 December

NOTES
The following signals have the specified effect when sent to the
pppd process.

SIGINT, SIGTERM
These signals cause pppd to terminate the link (by closing
LCP), restore the serial device settings, and exit.

SIGHUP
Indicates that the physical layer has been disconnected. pppd
will attempt to restore the serial device settings (this may
produce error messages on Suns), and then exit.

BUGS
The use of the modem control lines and the effects of the modem and
local options are not well defined.

AUTHORS
Drew Perkins, Brad Clements, Karl Fox, Greg Christy, Brad Parker
(brad@fcr.com), Paul Mackerras (paulus@cs.anu.edu.au)