pppd(1M)
NAME
pppd - point to point protocol daemon
SYNOPSIS
pppd [tty_name] [speed] [options]
DESCRIPTION
The point-to-point protocol (PPP) provides a method for
transmitting datagrams over serial point-to-point links. PPP
is composed of three components: a facility for encapsulat-
ing 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 several NCPs for establishing and configuring the Inter-
net Protocol (referred to as the IP Control Protocol or
"IPCP") and IPv6 (IPV6CP).
OPTIONS
The following sections discuss the pppd options:
Options Files
Options are taken from files and the command line. pppd
reads options from the files /etc/ppp/options, $HOME/.ppprc
and /etc/ppp/options.ttyname (in that order) before process-
ing the options on the command line. (Command-line options
are scanned for the terminal name before the options.ttyname
file is read.) To form the name of the options.ttyname file,
the initial /dev/ is removed from the terminal name, and any
remaining forward slash characters (/) are replaced with
dots. For example, with serial device /dev/cua/a, option
file /etc/ppp/options.cua.a is read.
An options file is parsed into a series of words that are
delimited by whitespace. Whitespace can be included in a
word by enclosing the word in double-quotes ("). A backslash
(\) quotes the succeeding character. A hash (#) starts a
comment, which continues until the end of the line. There is
no restriction on using the file or call options within an
options file.
Frequently Used Options
<tty_name>
Communicate over the named device. The string /dev/ is
prepended if necessary. If no device name is given, or
if the name of the terminal connected to the standard
input is given, pppd uses that terminal and does not
fork to put itself in the background. A value for this
option from a privileged source cannot be overridden
by a non-privileged user.
<speed>
Set the baud rate to <speed> (a decimal number). The
default is to leave the baud rate unchanged. This
option is normally needed for dial-out only.
asyncmap <map>
Set the async character map to <map>. The map
describes which control characters cannot be success-
fully received over the serial line. pppd asks 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, pppd
attempts to negotiate a value of 0. If the peer
agrees, this disables escaping of the standard control
characters. Use the default-asyncmap option to disable
negotiation and escape all control characters.
auth Require the peer to authenticate itself before allow-
ing network packets to be sent or received. This
option is the default if the system has a default
route. If the auth or the noauth option is not speci-
fied, pppd allows the peer to use only those IP
addresses to which the system does not already have a
route.
call name
Read options from the file /etc/ppp/peers/name. This
file may contain privileged options, including noauth,
even if pppd is not being run by root. The name string
may not begin with a slash ("/") or include consecu-
tive periods ("..") as a pathname component.
callback number
Request a callback to the given telephone number using
Microsoft CBCP.
connect script
Use the executable or shell command specified by
script to set up the serial line. This script would
typically use the chat(1M) program to dial the modem
and start the remote PPP session. A value for this
option originating from a privileged source cannot be
overridden by a non-privileged user.
crtscts
Use hardware flow control, that is, RTS/CTS, to
control the flow of data on the serial port. If the
crtscts, nocrtscts, cdtrcts or nocdtrcts option is not
provided, the hardware flow control setting for the
serial port is left unchanged. Some serial ports lack
a true RTS output and use this mode to implement uni-
directional flow control. The serial port suspends
transmission when requested by the modem by means of
CTS but cannot request the modem to stop sending to
the computer. This mode allows the use of DTR as a
modem control line.
defaultroute
Add a default route to the system routing tables when
IPCP negotiation successfully completes, using the
peer as the gateway. This entry is removed when the
PPP connection is broken. This option is privileged if
the nodefaultroute option is specified.
disconnect script
Run the executable or shell command specified by
script after pppd terminates the link. Typically, this
script is used to command the modem to hang up if
hardware modem control signals are not available.
disconnect is not run if the modem has already hung
up. A value for this option originating from a
privileged source cannot be overridden by a non-
privileged user.
escape xx,yy,...
Specifies that certain characters 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 allows only
control characters to be specified. Characters that
cannot be escaped are those containing hex values 0x20
through 0x3f and 0x5e.
file name
Read options from file name. If this option is used on
the command line or in $HOME/.ppprc, the file must be
readable by the user invoking pppd. See Options Files
for a list of files that pppd always reads, regardless
of the use of this option.
init script
Run the executable or shell command specified by
script to initialize the serial line. This script
would typically use the chat(1M) program to configure
the modem to enable auto-answer. A value for this
option from a privileged source cannot be overridden
by a non-privileged user.
lock Directs pppd to create a UUCP-style lock file for the
serial device to ensure exclusive access to the dev-
ice.
mru n Set the Maximum Receive Unit (MRU) value to n. pppd
asks the peer to send packets of no more than n bytes.
Minimum MRU value is 128. Default MRU value is 1500. A
value of 296 is recommended for slow links (40 bytes
for TCP/IP header + 256 bytes of data). For IPv6, MRU
must be at least 1280.
mtu n Set the Maximum Transmit Unit (MTU) value to n. Unless
the peer requests a smaller value via MRU negotiation,
pppd requests the kernel networking code to send data
packets of no more than n bytes through the PPP net-
work interface. For IPv6, MTU must be at least 1280.
passive
Enables the "passive" option in the LCP. With this
option, pppd attempts to initiate a connection; if no
reply is received from the peer, pppd waits passively
for a valid LCP packet instead of exiting, as it would
without this option.
Options
<local_IP_address>:<remote_IP_address>
Set the local and/or remote interface IP addresses.
Either one may be omitted, but the colon is required.
The IP addresses are specified with a host name or in
decimal dot notation, for example: :10.1.2.3. The
default local address is the first IP address of the
system unless the noipdefault option is provided. The
remote address is obtained from the peer if not speci-
fied 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.
allow-fcs fcs-type
Set allowable FCS type(s) for data sent to the peer.
The fcs-type is a comma-separated list of "crc16",
"crc32", "null", or integers. By default, all known
types are allowed. If this option is specified and the
peer requests a type not listed, a LCP Configure-Nak
is sent to request only the listed types.
allow-ip address(es)
Allow peers to use the given IP address or subnet
without authenticating themselves. The parameter is
parsed in the same manner as each element of the list
of allowed IP addresses is parsed in the secrets
files. See the Authentication section more more
details.
bsdcomp nr,nt
Request that the peer compress packets that it sends
using the BSD-Compress scheme, with a maximum code
size of nr bits, and agree to compress packets sent to
the peer with a maximum code size of nt bits. If nt is
not specified, it defaults to the value given for nr.
Values in the range 9 to 15 may be used for nr and nt;
larger values provide better compression but consume
more kernel memory for compression dictionaries.
Alternatively, a value of 0 for nr or nt disables
compression in the corresponding direction. Use
nobsdcomp or bsdcomp 0 to disable BSD-Compress
compression entirely. If this option is read from a
privileged source, a nonprivileged user may not
specify a code size larger than the value from the
privileged source.
cdtrcts
Use a non-standard hardware flow control such as
DTR/CTS to control the flow of data on the serial
port. If the crtscts, nocrtscts, cdtrcts or nocdtrcts
option is not specified, the hardware flow control
setting for the serial port is left unchanged. Some
serial ports lack a true RTS output. Such serial ports
use this mode to implement true bi-directional flow
control. Note that this flow control mode does not
permit using DTR as a modem control line.
chap-interval n
If this option is given, pppd will rechallenge the
peer every n seconds.
chap-max-challenge n
Set the maximum number of CHAP challenge transmissions
to n (default 10).
chap-restart n
Set the CHAP restart interval (retransmission timeout
for challenges) to n seconds. The default is 3.
connect-delay n
Wait for up to n milliseconds after the connect script
finishes for a valid PPP packet from the peer. When
the wait period elapses or when a valid PPP packet is
received from the peer, pppd begins negotiation by
sending its first LCP packet. The default value is
1000 (1 second). A wait period applies only if the
connect or pty option is used.
datarate n
Set maximum data rate to n (in bytes per second) when
using the pty, notty, record, or socket options.
debug Enables connection debugging facilities. If this
option is given, pppd logs the contents of all control
packets sent or received in a readable form. The pack-
ets are logged through syslog with facility daemon and
level debug. This information can be directed to a
file by configuring /etc/syslog.conf appropriately.
default-asyncmap
Disable asyncmap negotiation, forcing all control
characters to be escaped for both the transmit and the
receive direction.
default-fcs
Disable FCS Alternatives negotiation entirely. By
default, no FCS Alternatives option is sent to the
peer, but the option is accepted. If this option is
specified by the peer, then LCP Configure-Reject is
sent.
default-mru
Disable MRU [Maximum Receive Unit] negotiation. With
this option, pppd uses the default MRU value of 1500
bytes for the transmit and receive directions.
deflate nr,nt,e
Request that the peer compress packets that it sends,
using the deflate scheme, with a maximum window size
of 2**nr bytes, and agree to compress packets sent to
the peer with a maximum window size of 2**nt bytes and
effort level of e (1 to 9). If nt is not specified, it
defaults to the value given for nr. If e is not speci-
fied, it defaults to 6. Values in the range 9 to 15
may be used for nr and nt; larger values provide
better compression but consume more kernel memory for
compression dictionaries. (Value 8 is not permitted
due to a zlib bug.) Alternatively, a value of 0 for nr
or nt disables compression in the corresponding direc-
tion. Use nodeflate or deflate 0 to disable deflate
compression entirely. (Note: pppd requests deflate
compression in preference to BSD-Compress if the peer
can do either.) If this option is read from a
privileged source, a nonprivileged user may not
specify a code size larger than the value from the
privileged source.
demand
Initiate the link only on demand, that is, when data
traffic is present. With this option, the remote IP
address must be specified by the user on the command
line or in an options file. pppd initially configures
and enables the interface for IP traffic without con-
necting to the peer. When traffic is available, pppd
connects to the peer and performs negotiation, authen-
tication and other actions. When completed, pppd
passes data packets across the link. The demand option
implies the persist option. If this behavior is not
desired, use the nopersist option after the demand
option. The idle and holdoff options can be used in
conjunction with the demand option.
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 could specify
domain Quotron.COM. With this configuration, pppd uses
the name porsche.Quotron.COM for accessing secrets in
the secrets file and as the default name when authen-
ticating to the peer. This option is privileged.
endpoint endpoint-value
Set the endpoint discriminator (normally used for RFC
1990 Multilink PPP operation). The endpoint-value con-
sists of a class identifier and a class-dependent
value. The class identifier is one of "null," "local,"
"IP," "MAC," "magic," "phone," or a decimal integer.
If present, the class-dependent value is separated
from the identifier by a colon (":") or period (".") .
This value may be a standard dotted-decimal IP address
for class "IP," an optionally colon-or-dot separated
hex Ethernet address for class "MAC" (must have 6
numbers), or an arbitrary string of bytes specified in
hex with optional colon or dot separators between
bytes. Although this option is available, this imple-
mentation does not support multilink.
fcs fcs-type
Set FCS type(s) desired for data sent by the peer. The
fcs-type is a comma-separated list of crc16, crc32,
null, or integers. By default, an FCS Alternatives
option is not specified, and the medium-dependent FCS
type is used. If this option is specified and the peer
sends an LCP Configure-Nak, only the listed types are
used. If none are in common, the FCS Alternatives
option is omitted from the next LCP Configure-Request
to drop back to the default.
hide-password
When logging the contents of PAP packets, this option
causes pppd to exclude the password string from the
log. This is the default.
holdoff n
Specifies how many seconds to wait before re-
initiating the link after it terminates. This option
is effective only if the persist or demand option is
used. The holdoff period is not applied if the link is
terminated because it was idle.
ident string
Set the LCP Identification string. The default value
is a version string similar to that displayed by the
--version option.
idle n
Specifies that pppd must disconnect if the link is
idle for n seconds. The link is idle when no data
packets (i.e. IP packets) are being sent or received.
Do not use this option with the persist option but
without the demand option.
ipcp-accept-local
With this option, pppd accepts the peer's idea of the
local IP address, even if the local IP address is
specified in an option.
ipcp-accept-remote
With this option, pppd accepts the peer's idea of its
remote IP address, even if the remote IP address is
specified in an option.
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 sent
before sending Configure-Rejects instead to n (default
10).
ipcp-max-terminate n
Set the maximum number of IPCP terminate-request
transmissions to n (default 3).
ipcp-restart n
Set the IPCP restart interval (retransmission timeout)
to n seconds (default 3).
ipparam string
Provides an extra parameter to the ip-up and ip-down
scripts. When this option is given, the string sup-
plied is given as the sixth parameter to those
scripts. See the Scripts section.
ipv6 <local_interface_identifier>,<remote_interface_identifier>
Set the local and/or remote 64-bit interface identif-
ier. Either one may be omitted. The identifier must be
specified in standard ASCII notation of IPv6 addresses
(for example: ::dead:beef). If the ipv6cp-use-ipaddr
option is given, the local and remote identifiers are
derived from the respective IPv4 addresses (see
above). The ipv6cp-use-persistent option can be used
instead of the ipv6 <local>,<remote> option.
ipv6cp-accept-local
Accept peer's interface identifier for the local link
identifier.
ipv6cp-max-configure n
Set the maximum number of IPv6CP Configure-Request
transmissions to n (default 10).
ipv6cp-max-failure n
Set the maximum number of IPv6CP Configure-NAKs sent
before sending Configure-Rejects instead to n (default
10).
ipv6cp-max-terminate n
Set the maximum number of IPv6CP terminate-request
transmissions to n (default 3).
ipv6cp-restart n
Set the IPv6CP restart interval (retransmission
timeout) to n seconds (default 3).
ipv6cp-use-ipaddr
If either the local or remote IPv6 address is unspeci-
fied, use the corresponding configured IPv4 address as
a default interface identifier. (This option uses the
configured addresses, not the negotiated addresses. Do
not use it with ipcp-accept-local if the local IPv6
identifier is unspecified or with ipcp-accept-remote
if the remote IPv6 identifier is unspecified.)
ipv6cp-use-persistent
Use uniquely-available persistent value for link local
address.
kdebug n
Enable debugging code in the kernel-level PPP driver.
Argument n is the sum of the following values: 1 to
enable general debug messages, 2 to request that con-
tents of received packets be printed, and 4 to request
contents of transmitted packets be printed. Messages
printed by the kernel are logged by syslogd(1M) to a
file directed in the /etc/syslog.conf configuration
file. Do not use the kdebug option to debug failed
links. Use the debug option instead.
lcp-echo-failure n
If this option is given, pppd presumes the peer to be
dead if n LCP Echo-Requests are sent without receiving
a valid LCP Echo-Reply. If this happens, pppd ter-
minates the connection. This option requires a non-
zero value for the lcp-echo-interval parameter. This
option enables pppd to terminate after the physical
connection is broken (for example, if the modem has
hung up) in situations where no hardware modem control
lines are available.
lcp-echo-interval n
If this option is given, pppd sends an LCP Echo-
Request frame to the peer every n seconds. Normally
the peer responds 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-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 sent
before starting to send Configure-Rejects instead to n
(default 10).
lcp-max-terminate n
Set the maximum number of LCP Terminate-Request
transmissions to n (default 3).
lcp-restart n
Set the LCP restart interval (retransmission timeout)
to n seconds (default 3).
linkname name
Sets the logical name of the link to name. pppd
creates a file named ppp-name.pid in /var/run contain-
ing its process ID. This is useful in determining
which instance of pppd is responsible for the link to
a given peer system. This is a privileged option.
local Do not use modem control lines. With this option, pppd
ignores the state of the CD (Carrier Detect) signal
from the modem and does not change the state of the
DTR (Data Terminal Ready) signal.
logfd n
Send log messages to file descriptor n. pppd sends log
messages to (at most) one file or file descriptor (as
well as sending the log messages to syslog), so this
option and the logfile option are mutually exclusive.
By default pppd sends log messages to stdout (file
descriptor 1) unless the serial port is open on
stdout.
logfile filename
Append log messages to the file filename (and send the
log messages to syslog). The file is opened in append
mode with the privileges of the user who invoked pppd.
login Use the system password database for authenticating
the peer using PAP, and record the user in the system
wtmp file. Note that the peer must have an entry in
the /etc/ppp/pap-secrets file and the system password
database to be allowed access.
maxconnect n
Terminate the connection after it has been available
for network traffic for n seconds (that is, n seconds
after the first network control protocol starts). An
LCP Time-Remaining message is sent when the first NCP
starts, and again when 5, 2, and 0.5 minutes are
remaining.
maxfail n
Terminate after n consecutive failed connection
attempts. A value of 0 means no limit. The default
value is 10.
modem Use the modem control lines. This option is the
default. With this option, pppd waits for the CD (Car-
rier Detect) signal from the modem to be asserted when
opening the serial device (unless a connect script is
specified), and drops the DTR (Data Terminal Ready)
signal briefly when the connection is terminated and
before executing the connect script.
ms-dns <addr>
If pppd is acting as a server for Microsoft Windows
clients, this option allows pppd to supply one or two
DNS (Domain Name Server) addresses to the clients. The
first instance of this option specifies the primary
DNS address; the second instance (if given) specifies
the secondary DNS address. If the first instance
specifies a name that resolves to multiple IP
addresses, then the first two addresses are used.
(This option is present in some older versions of pppd
under the name dns-addr.)
ms-lanman
If pppd connects as a client to a Microsoft server and
uses MS-CHAPv1 for authentication, this option selects
the LAN Manager password style instead of Microsoft
NT.
ms-wins <addr>
If pppd acts as a server for Microsoft Windows or
Samba clients, this option allows pppd to supply one
or two WINS (Windows Internet Name Services) server
addresses to the clients. The first instance of this
option specifies the primary WINS address; the second
instance (if given) specifies the secondary WINS
address. As with ms-dns, if the name specified
resolves to multiple IP addresses, then the first two
will be taken as primary and secondary.
name name
Set the name of the local system for authentication
purposes to name. This is a privileged option. With
this option, pppd uses lines in the secrets files that
have name as the second field to look for a secret to
use in authenticating the peer. In addition, unless
overridden with the user option, name is used as the
name to send to the peer when authenticating the local
system. (Note that pppd does not append the domain
name to name.)
no-accm-test
Disable use of asyncmap (ACCM) checking using LCP
Echo-Request messages. If the lcp-echo-failure is used
on an asynchronous line, pppd includes all control
characters in the first n LCP Echo-Request messages.
If the asyncmap is set incorrectly, the link drops
rather than continue operation with random failures.
This option disables that feature.
noaccomp
Disable HDLC Address/Control compression in both
directions (send and receive).
noauth
Do not require the peer to authenticate itself. This
option is privileged.
nobsdcomp
Disables BSD-Compress compression; pppd will not
request or agree to compress packets using the BSD-
Compress scheme. This option is not necessary if noccp
is specified.
noccp Disable CCP (Compression Control Protocol) negotia-
tion. This option should only be required if the peer
has bugs or becomes confused by requests from pppd for
CCP negotiation. If CCP is disabled, then BSD and
deflate compression do not need to be separately dis-
abled.
nocrtscts
Disable hardware flow control (i.e. RTS/CTS) on the
serial port. If the crtscts, nocrtscts, cdtrcts or
nocdtrcts options are not given, the hardware flow
control setting for the serial port is left unchanged.
nocdtrcts
This option is a synonym for nocrtscts. Either option
will disable both forms of hardware flow control.
nodefaultroute
Disable the defaultroute option. You can prevent non-
root users from creating default routes with pppd by
placing this option in the /etc/ppp/options file.
nodeflate
Disables deflate compression; pppd will not request or
agree to compress packets using the deflate scheme.
This option is not necessary if noccp is specified.
nodeflatedraft
Do not use Internet Draft (incorrectly assigned) algo-
rithm number for deflate compression. This option is
not necessary if noccp is specified.
nodetach
Do not detach from the controlling terminal. Without
this option, pppd forks to become a background process
if a serial device other than the terminal on the
standard input is specified.
noendpoint
Do not send or accept the Multilink Endpoint Discrimi-
nator option.
noident
Disable use of LCP Identification. LCP Identification
messages will not be sent to the peer, but received
messages will be logged. (Specify this option twice to
completely disable LCP Identification. In this case,
pppd sends LCP Code-Reject in response to received LCP
Identification messages.)
noip Disable IPCP negotiation and IP communication. Use
this option only if the peer has bugs or becomes con-
fused by requests from pppd for IPCP negotiation.
noipv6
Disable IPv6CP negotiation and IPv6 communication.
IPv6 is not enabled by default.
noipdefault
Disables the default behavior 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 must supply the local IP address during IPCP
negotiation (unless it specified explicitly on the
command line or in an options file).
nolog Do not send log messages to a file or file descriptor.
This option cancels the logfd and logfile options.
nologfd acts as an alias for this option.
nomagic
Disable magic number negotiation. With this option,
pppd cannot detect a looped-back line. Use this option
only if the peer has bugs. Do not use this option to
work around the "Serial line is looped back" error
message.
nopam This privileged option disables use of pluggable
authentication modules. If this option is specified,
pppd reverts to standard authentication mechanisms.
The default is not to use PAM.
nopcomp
Disable protocol field compression negotiation in the
receive and the transmit direction.
nopersist
Exit once a connection has been made and terminated.
This is the default unless the persist or demand
option is specified.
noplink
Cause pppd to use I_LINK instead of I_PLINK. This is
the default. When I_LINK is used, the system cleans up
terminated interfaces (even when SIGKILL is used) but
does not allow ifconfig(1M) to unplumb PPP streams or
insert or remove modules dynamically. Use the plink
option if ifconfig(1M) modinsert, modremove or unplumb
support is needed.
nopredictor1
Do not accept or agree to Predictor-1 compression.
(This option is accepted for compatibility. The imple-
mentation does not support Predictor-1 compression.)
noproxyarp
Disable the proxyarp option. If you want to prevent
users from creating proxy ARP entries with pppd, place
this option in the /etc/ppp/options file.
notty Normally, pppd requires a terminal device. With this
option, pppd allocates itself a pseudo-tty
master/slave pair and uses the slave as its terminal
device. pppd creates a child process to act as a char-
acter shunt to transfer characters between the
pseudo-tty master and its standard input and output.
Thus, pppd transmits characters on its standard output
and receives characters on its standard input even if
they are not terminal devices. This option increases
the latency and CPU overhead of transferring data over
the ppp interface as all of the characters sent and
received must flow through the character shunt pro-
cess. An explicit device name may not be given if this
option is used.
novj Disable Van Jacobson style TCP/IP header compression
in both the transmit and the receive direction.
novjccomp
Disable the connection-ID compression option in Van
Jacobson style TCP/IP header compression. With this
option, pppd does not omit the connection-ID byte from
Van Jacobson compressed TCP/IP headers, nor does it
ask the peer to do so. This option is unnecessary if
novj is specified.
pam This privileged option enables use of PAM. If this is
specified, pppd uses the pam(3PAM) framework for user
authentication with a service name of "ppp" if the
login option and PAP authentication are used. The
default is not to use PAM.
papcrypt
Indicates that pppd should not accept a password
which, before encryption, is identical to the secret
from the /etc/ppp/pap-secrets file. Use this option if
the secrets in the pap-secrets file are in crypt(3C)
format.
pap-max-authreq n
Set the maximum number of PAP authenticate-request
transmissions to n (default 10).
pap-restart n
Set the PAP restart interval (retransmission timeout)
to n seconds (default 3).
pap-timeout n
Set the maximum time that pppd waits for the peer to
authenticate itself with PAP to n seconds (0= no
limit). The default is 30 seconds.
password string
Password string for authentication to the peer.
persist
Do not exit after a connection is terminated; instead
try to reopen the connection.
plink Cause pppd to use I_PLINK instead of I_LINK. The
default is to use I_LINK, which cleans up terminated
interface (even if SIGKILL is used), but does not
allow ifconfig(1M) to unplumb PPP streams or insert or
remove modules dynamically. Use this option if
ifconfig(1M) modinsert/modremove/unplumb support is
needed. See also the plumbed option.
plugin filename
Load the shared library object file filename as a plu-
gin. This is a privileged option. Unless the filename
specifies an explicit path, /etc/ppp/plugins and
/usr/lib/inet/ppp will be searched for the object to
load in that order.
plumbed
This option indicates that pppd should find a plumbed
interface and use that for the session. If IPv4
addresses or IPv6 interface IDs or link MTU are other-
wise unspecified, they are copied from the interface
selected. This mode mimics some of the functionality
of the older aspppd implementation and may be helpful
when pppd is used with external applications that use
ifconfig(1M).
pppmux timer
Enable PPP Multiplexing option negotiation and set
transmit multiplexing timeout to timer microseconds.
privgroup group-name
Allows members of group group-name to use privileged
options. This is a privileged option. Because there is
no guarantee that members of group-name cannot use
pppd to become root themselves, you should be careful
using this option. Consider it equivalent to putting
the members of group-name in the root or sys group.
proxyarp
Add an entry to the system's Address Resolution Proto-
col (ARP) table with the IP address of the peer and
the Ethernet address of this system. When you use this
option, the peer appears to other systems to be on the
local Ethernet. The remote address on the PPP link
must be in the same subnet as assigned to an Ethernet
interface.
pty script
Specifies that the command script, and not a specific
terminal device is used for serial communication. pppd
allocates itself a pseudo-tty master/slave pair and
uses the slave as its terminal device. script runs in
a child process with the pseudo-tty master as its
standard input and output. An explicit device name may
not be given if this option is used. (Note: if the
record option is used in conjunction with the pty
option, the child process will have pipes on its stan-
dard input and output.)
receive-all
With this option, pppd accepts all control characters
from the peer, including those marked in the receive
asyncmap. Without this option, pppd discards those
characters as specified in RFC 1662. This option
should be used only if the peer has bugs, as is often
found with dial-back implementations.
record filename
Directs pppd to record all characters sent and
received to a file named filename. filename is opened
in append mode, using the user's user-ID and permis-
sions. Because this option uses a pseudo-tty and a
process to transfer characters between the pseudo-tty
and the real serial device, it increases the latency
and CPU overhead of transferring data over the PPP
interface. Characters are stored in a tagged format
with timestamps that can be displayed in readable form
using the pppdump(1M) program. This option is gen-
erally used when debugging the kernel portion of pppd
(especially CCP compression algorithms) and not for
debugging link configuration problems. See the debug
option.
remotename name
Set the assumed name of the remote system for authen-
tication purposes to name. Microsoft WindowsNT does
not provide a system name in its CHAP Challenge mes-
sages, and this option is often used to work around
this problem.
refuse-chap
With this option, pppd will not agree to authenticate
itself to the peer using standard Challenge Handshake
Authentication Protocol (CHAP). (MS-CHAP is not
affected.)
refuse-mschap
Do not agree to authenticate to peer with MS-CHAPv1.
If this option is specified, requests for MS-CHAPv1
authentication from the peer are declined with LCP
Configure-Nak. That option does not disable any other
form of CHAP.
refuse-mschapv2
Do not agree to authenticate to peer with MS-CHAPv2.
If specified, this option requests that MS-CHAPv2
authentication from the peer be declined with LCP
Configure-Nak. That option does not disable any other
form of CHAP.
refuse-pap
With this option, pppd will not agree to authenticate
itself to the peer using Password Authentication Pro-
tocol (PAP).
require-chap
Require the peer to authenticate itself using standard
CHAP authentication. MS-CHAP is not affected.
require-mschap
Require the peer to authenticate itself using MS-
CHAPv1 authentication.
require-mschapv2
Require the peer to authenticate itself using MS-
CHAPv2 authentication.
require-pap
Require the peer to authenticate itself using PAP
authentication.
show-password
When logging contents of PAP packets, this option
causes pppd to show the password string in the log
message.
silent
With this option, pppd will not transmit LCP packets
to initiate a connection until a valid LCP packet is
received from the peer. This is like the "passive"
option with older versions of pppd and is retained for
compatibility, but the current passive option is
preferred.
small-accm-test
When checking the asyncmap (ACCM) setting, pppd uses
all 256 possible values by default. See no-accm-test.
This option restricts the test so that only the 32
values affected by standard ACCM negotiation are
tested. This option is useful on very slow links.
socket host:port
Connect to given host and port using TCP and run PPP
over this connection.
sync Use synchronous HDLC serial encoding instead of asyn-
chronous. The device used by pppd with this option
must have sync support. Currently supports zs, se, and
hsi drivers.
unit n
Set PPP interface unit number to n, if possible.
updetach
With this option, pppd detaches from its controlling
terminal after establishing the PPP connection. When
this is specified, messages sent to stderr by the con-
nect script, usually chat(1M), and debugging messages
from the debug option are directed to pppd's standard
output.
usehostname
Enforce the use of the hostname with domain name
appended, if given, as the name of the local system
for authentication purposes. This overrides the name
option. Because the name option is privileged, this
option is normally not needed.
usepeerdns
Ask the peer for up to two DNS server addresses.
Addresses supplied by the peer, if any, are passed to
the /etc/ppp/ip-up script in the environment variables
DNS1 and DNS2. In addition, pppd creates an
/etc/ppp/resolv.conf file containing one or two
nameserver lines with the address(es) supplied by the
peer.
user name
Sets the name used for authenticating the local system
to the peer to name.
vj-max-slots n
Sets the number of connection slots to be used by the
Van Jacobson TCP/IP header compression and
decompression code to n, which must be between 2 and
16 (inclusive).
welcome script
Run the executable or shell command specified by
script before initiating PPP negotiation, after the
connect script, if any, has completed. A value for
this option from a privileged source cannot be over-
ridden by a non-privileged user.
xonxoff
Use software flow control, that is, XON/XOFF, to con-
trol the flow of data on the serial port.
Obsolete Options
The following options are obsolete:
+ua name
Read a PAP user name and password from the file name.
This file must have two lines for name and password.
Name and password are sent to the peer when the peer
requests PAP authentication.
+ipv6 Enable IPv6 and IPv6CP without specifying interface
identifiers.
--version
Show version number and exit.
--help
Show brief help message and exit.
EXTENDED DESCRIPTION
The following sections discuss miscellaneous features of
pppd:
Security
pppd allows system administrators to provide legitimate
users with PPP access to a server machine without fear of
compromising the security of the server or the network it
runs on. Access control is provided by restricting IP
addresses the peer may use based on its authenticated iden-
tity (if any), and through restrictions on options a non-
privileged user may use. Options that permit potentially
insecure configurations are privileged. Privileged options
are accepted only in files that are under the control of the
system administrator or when pppd is being run by root.
By default, pppd allows an unauthenticated peer to use a
given IP address only if the system does not already have a
route to that IP address. For example, a system with a per-
manent connection to the wider Internet will normally have a
default route, meaning all peers must authenticate them-
selves to set up a connection. On such a system, the auth
option is the default. Conversely, a system with a PPP link
that comprises the only connection to the Internet probably
does not possess a default route, so the peer can use virtu-
ally any IP address without authenticating itself.
Security-sensitive options are privileged and cannot be
accessed by a non-privileged user running pppd, either on
the command line, in the user's $HOME/.ppprc file, or in an
options file read using the file option. Privileged options
may be used in /etc/ppp/options file or in an options file
read using the call option. If pppd is run by the root user,
privileged options can be used without restriction. If the
/etc/ppp/options file does not exist, then only root may
invoke pppd. The /etc/ppp/options file must be created (but
may be empty) to allow ordinary non-root users to access
pppd.
When opening the device, pppd uses the invoking user's user
ID or the root UID (that is, 0), depending if the device
name was specified by the user or the system administrator.
If the device name comes from a privileged source, that is,
/etc/ppp/options or an options file read using the call
option, pppd uses full root privileges when opening the dev-
ice. Thus, by creating an appropriate file under
/etc/ppp/peers, the system administrator can allow users to
establish a PPP connection via a device that they would
not normally have access to. Otherwise pppd uses the invok-
ing user's real UID when opening the device.
Authentication
During the authentication process, one peer convinces the
other of its identity by sending its name and some secret
information to the other. During authentication, the first
peer becomes the "client" and the second becomes the
"server." Authentication names can (but are not required to)
correspond to the peer's Internet hostnames.
pppd supports four authentication protocols: the Password
Authentication Protocol (PAP) and three forms of the Chal-
lenge Handshake Authentication Protocol (CHAP). With the PAP
protocol, the client sends its name and a cleartext password
to the server to authenticate itself. With CHAP, the server
initiates the authentication exchange by sending a challenge
to the client who must respond with its name and a hash
value derived from the shared secret and the challenge.
The PPP protocol is symmetrical, meaning that each peer may
be required to authenticate itself to the other. Different
authentication protocols and names can be used for each
exchange.
By default, pppd authenticates if requested and does not
require authentication from the peer. However, pppd does not
authenticate itself with a specific protocol if it has no
secrets that can do so.
pppd stores authentication secrets in the /etc/ppp/pap-
secrets (for PAP), and /etc/ppp/chap-secrets (for CHAP)
files. Both files use the same format. pppd uses secrets
files to authenticate itself to other systems and to authen-
ticate other systems to itself.
Secrets files contain one secret per line. Secrets are
specific to a particular combination of client and server
and can only be used by that client to authenticate itself
to that server. Each line in a secrets file has a minimum of
three fields that contain the client and server names fol-
lowed by the secret. Often, these three fields are followed
by IP addresses that are used by clients to connect to a
server.
A secrets file is parsed into words, with client name,
server name and secrets fields allocated one word each.
Embedded spaces or other special characters within a word
must be quoted or escaped. Case is significant in all three
fields.
A secret beginning with an at sign ("@") is followed by the
name of a file containing the secret. An asterisk (*) as the
client or server name matches any name. When choosing a
match, pppd selects the one with the fewest wildcards.
Succeeding words on a line are interpreted by pppd as
acceptable IP addresses for that client. IP Addresses are
disallowed if they appear in lines that contain only three
words or lines whose first word begins with a hyphen ("-").
To allow any address, use "*". An address starting with an
exclamation point ("!") indicates that the specified
address is not acceptable. An address may be followed by "/"
and a number n to indicate a whole subnet (all addresses
that have the same value in the most significant n bits). In
this form, the address may be followed by a plus sign ("+")
to indicate that one address from the subnet is authorized,
based on the ppp network interface unit number in use. In
this case, the host part of the address is set to the unit
number, plus one.
When authenticating the peer, pppd chooses a secret with the
peer's name in the first field of the secrets file and the
name of the local system in the second field. The local sys-
tem name defaults to the hostname, with the domain name
appended if the domain option is used. The default can be
overridden with the name option unless the usehostname
option is used.
When authenticating to the peer, pppd first determines the
name it will use to identify itself to the peer. This name
is specified with the user option. If the user option is not
used, the name defaults to the host name of the local sys-
tem. pppd then selects a secret from the secrets file by
searching for an entry with a local name in the first field
and the peer's name in the second field. pppd will know the
name of the peer if standard CHAP authentication is used
because the peer will have sent it in the Challenge packet.
However, if MS-CHAP or PAP is being used, pppd must deter-
mine the peer's name from the options specified by the user.
The user can specify the peer's name directly with the
remotename option. Otherwise, if the remote IP address was
specified by a name, rather than in numeric form, that name
will be used as the peer's name. If that fails, pppd uses
the null string as the peer's name.
When authenticating the peer with PAP, the supplied
password is compared with data in the secrets file. If
the password and secret do not match, the password is
encrypted using crypt() and checked against the secret
again. If the papcrypt option is given, the first unen-
crypted comparison is omitted for better security, and
entries must thus be in encrypted crypt(3C) form.
If the login option is specified, the username and password
are also checked against the system password database. This
allows you to set up the pap-secrets file to enable PPP
access only to certain users, and to restrict the set of IP
addresses available to users. Typically, when using the
login option, the secret in /etc/ppp/pap-secrets would be
"", which matches any password supplied by the peer. This
makes having the same secret in two places unnecessary. When
login is used, the pam option enables access control through
pam(3PAM).
Authentication must be completed before IPCP (or other net-
work protocol) can be started. If the peer is required to
authenticate itself and fails, pppd closes LCP and ter-
minates the link. If IPCP negotiates an unacceptable IP
address for the remote host, IPCP is closed. IP packets are
sent or received only when IPCP is open.
To allow hosts that cannot authenticate themselves to con-
nect and use one of a restricted set of IP addresses, add
a line to the pap-secrets file specifying the empty string
for the client name and secret.
Additional pppd options for a given peer may be specified by
placing them at the end of the secrets entry, separated by
two dashes (--). For example
peername servername secret ip-address -- novj
Routing
When IPCP negotiation is complete, pppd informs the kernel
of the local and remote IP addresses for the PPP interface
and creates a host route to the remote end of the link that
enables peers to exchange IP packets. Communication with
other machines generally requires further modification to
routing tables and/or Address Resolution Protocol (ARP)
tables. In most cases the defaultroute and/or proxyarp
options are sufficient for this, but further intervention
may be necessary. If further intervention is required, use
the /etc/ppp/ip-up script or a routing protocol daemon.
To add a default route through the remote host, use the
defaultroute option. This option is typically used for
"client" systems; that is, end-nodes that use the PPP link
for access to the general Internet.
In some cases it is desirable to use proxy ARP, for example
on a server machine connected to a LAN, to allow other hosts
to communicate with the remote host. proxyarp instructs pppd
to look for a network interface on the same subnet as the
remote host. That is, an interface supporting broadcast and
ARP that is not a point-to-point or loopback interface and
that is currently up. 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.
When the demand option is used, the interface IP addresses
are already set at the time when IPCP comes up. If pppd can-
not negotiate the same addresses it used to configure the
interface, it changes the interface IP addresses to the
negotiated addresses. This may disrupt existing connections.
Using demand dialing with peers that perform dynamic IP
address assignment is not recommended.
Scripts
pppd invokes scripts at various stages during processing
that are used to perform site-specific ancillary processing.
These scripts may be shell scripts or executable programs.
pppd does not wait for the scripts to finish. The scripts
are executed as root (with the real and effective user-id
set to 0), enabling them to update routing tables, run
privileged daemons, or perform other tasks. Be sure that the
contents of these scripts do not compromise your system's
security. pppd runs the scripts with standard input, output
and error redirected to /dev/null, and with an environment
that is empty except for some environment variables that
give information about the link. The pppd environment vari-
ables are:
DEVICE
Name of the serial tty device.
IFNAME
Name of the network interface.
IPLOCAL
IP address for the link's local end. This is set only
when IPCP has started.
IPREMOTE
IP address for the link's remote end. This is set only
when IPCP has started.
PEERNAME
Authenticated name of the peer. This is set only if
the peer authenticates itself.
SPEED Baud rate of the tty device.
ORIG_UID
Real user-id of user who invoked pppd.
PPPLOGNAME
Username of the real user-id who invoked pppd. This is
always set.
pppd also sets the following variables for the ip-down and
auth-down scripts:
CONNECT_TIME
Number of seconds between the start of PPP negotiation
and connection termination.
BYTES_SENT
Number of bytes sent at the level of the serial port
during the connection.
BYTES_RCVD
Number of bytes received at the level of the serial
port during the connection.
LINKNAME
Logical name of the link, set with the linkname
option.
If they exist, pppd invokes the following scripts. It is not
an error if they do not exist.
/etc/ppp/auth-up
Program or script executed after the remote system
successfully authenticates itself. It is executed with
five command-line arguments: interface-name peer-name
user-name tty-device speed. Note that this script is
not executed if the peer does not authenticate itself,
for example, when the noauth option is used.
/etc/ppp/auth-down
Program or script executed when the link goes down if
/etc/ppp/auth-up was previously executed. It is exe-
cuted in the same manner with the same parameters as
/etc/ppp/auth-up.
/etc/ppp/ip-up
A program or script that is executed when the link is
available for sending and receiving IP packets (that
is, IPCP has come up). It is executed with six
command-line arguments: interface-name tty-device
speed local-IP-address remote-IP-address ipparam.
/etc/ppp/ip-down
A program or script which is executed when the link is
no longer available for sending and receiving IP pack-
ets. This script can be used for undoing the effects
of the /etc/ppp/ip-up script. It is invoked in the
same manner and with the same parameters as the ip-up
script.
/etc/ppp/ipv6-up
Similar to /etc/ppp/ip-up, except that it is executed
when the link is available for sending and receiving
IPv6 packets. Executed with six command-line argu-
ments: interface-name tty-device speed local-link-
local-address remote-link-local-address ipparam.
/etc/ppp/ipv6-down
Similar to /etc/ppp/ip-down, but executed when IPv6
packets can no longer be transmitted on the link. Exe-
cuted with the same parameters as the ipv6-up script.
EXAMPLES
Example 1: Using the auth Option
The following examples assume that the /etc/ppp/options file
contains the auth option.
pppd is commonly used to dial out to an ISP. You can do this
using the "pppd call isp" command where the
/etc/ppp/peers/isp file is set up to contain a line similar
to the following:
cua/a 19200 crtscts connect '/usr/bin/chat -f /etc/ppp/chat-isp' noauth
For this example, chat(1M) is used to dial the ISP's modem
and process any login sequence required. The /etc/ppp/chat-
isp file is used by chat and could contain the following:
ABORT "NO CARRIER"
ABORT "NO DIALTONE"
ABORT "ERROR"
ABORT "NO ANSWER"
ABORT "BUSY"
ABORT "Username/Password Incorrect"
"" "at"
OK "at&f&d2&c1"
OK "atdt2468135"
"name:" "^Umyuserid"
"word:" "qmypassword"
"ispts" "q^Uppp"
"~-^Uppp-~"
See the chat(1M) man page for details of chat scripts.
Example 2: Using pppd with proxyarp
pppd can also provide a dial-in ppp service for users. If
the users already have login accounts, the simplest way to
set up the ppp service is to let the users log in to their
accounts and run pppd as shown in the following example:
example% pppd proxyarp
Example 3: Providing a User with Access to PPP Facilities
To provide a user with access to the PPP facilities, allo-
cate an IP address for the user's machine, create an entry
in /etc/ppp/pap-secrets or /etc/ppp/chap-secrets. This
enables the user's machine to authenticate itself. For exam-
ple, to enable user "Joe" using machine "joespc" to dial in
to machine "server" and use the IP address "joespc.my.net,"
add the following entry to the /etc/ppp/pap-secrets or
/etc/ppp/chap-secrets files:
joespc server "joe's secret" joespc.my.net
Alternatively, you can create another username, for example
"ppp," whose login shell is /usr/bin/pppd and whose home
directory is /etc/ppp. If you run pppd this way, add the
options to the /etc/ppp/.ppprc file.
If your serial connection is complex, it may be useful to
escape such control characters as XON (^Q) and XOFF (^S),
using asyncmap a0000. If the path includes a telnet, escape
^] (asyncmap 200a0000). If the path includes a rlogin com-
mand, add escape ff option to the options, because rlogin
removes the window-size-change sequence [0xff, 0xff, 0x73,
0x73, followed by any 8 bytes] from the stream.
EXIT STATUS
The pppd exit status indicates errors or specifies why a
link was terminated. Exit status values are:
0 pppd has detached or the connection was successfully
established and terminated at the peer's request.
1 An immediately fatal error occurred. For example, an
essential system call failed.
2 An error was detected in the options given. For exam-
ple, two mutually exclusive options were used, or
/etc/ppp/options is missing and the user is not root.
3 pppd is not setuid-root and the invoking user is not
root.
4 The kernel does not support PPP. For example, the PPP
kernel driver is not included or cannot be loaded.
5 pppd terminated because it was sent a SIGINT, SIGTERM
or SIGHUP signal.
6 The serial port could not be locked.
7 The serial port could not be opened.
8 The connect script failed and returned a non-zero exit
status.
9 The command specified as the argument to the pty
option could not be run.
10 The PPP negotiation failed because no network proto-
cols were able to run.
11 The peer system failed or refused to authenticate
itself.
12 The link was established successfully, but terminated
because it was idle.
13 The link was established successfully, but terminated
because the connect time limit was reached.
14 Callback was negotiated and an incoming call should
arrive shortly.
15 The link was terminated because the peer is not
responding to echo requests.
16 The link was terminated by the modem hanging up.
17 The PPP negotiation failed because serial loopback was
detected.
18 The init script failed because a non-zero exit status
was returned.
19 Authentication to the peer failed.
FILES
/var/run/spppn.pid
Process-ID for pppd process on PPP interface unit n.
/var/run/ppp-name.pid
Process-ID for pppd process for logical link name (see
the linkname option).
/etc/ppp/pap-secrets
Usernames, passwords and IP addresses for PAP authen-
tication. This file should be owned by root and not
readable or writable by any other user, otherwise pppd
will log a warning.
/etc/ppp/chap-secrets
Names, secrets and IP addresses for all forms of CHAP
authentication. The /etc/ppp/pap-secrets file should
be owned by root should not readable or writable by
any other user, otherwise, pppd will log a warning.
/etc/ppp/options
System default options for pppd, read before user
default options or command-line options.
$HOME/.ppprc
User default options, read before
/etc/ppp/options.ttyname.
/etc/ppp/options.ttyname
System default options for the serial port in use;
read after $HOME/.ppprc. The ttyname component of this
filename is formed when the initial /dev/ is stripped
from the port name (if present), and slashes (if any)
are converted to dots.
/etc/ppp/peers
Directory with options files that may contain
privileged options, even if pppd was invoked by a user
other than root. The system administrator can create
options files in this directory to permit non-
privileged users to dial out without requiring the
peer to authenticate, but only to certain trusted
peers.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWpppdu |
|_____________________________|_____________________________|
| Interface Stability | Evolving |
|_____________________________|_____________________________|
SEE ALSO
chat(1M), ifconfig(1M), crypt(3C), pam(3PAM), attributes(5)
Haskin, D., Allen, E. RFC 2472 - IP Version 6 Over PPP. Net-
work Working Group. December 1998.
Jacobson, V. RFC 1144, Compressing TCP/IP Headers for Low-
Speed Serial Links. Network Working Group. February, 1990
Lloyd, B., Simpson, W. RFC 1334, PPP Authentication Proto-
cols. Network Working Group. October 1992.
McGregor, G. RFC 1332, The PPP Internet Protocol Control
Protocol (IPCP). Network Working Group. May 1992.
Rivest, R. RFC 1321, The MD5 Message-Digest Algorithm. Net-
work Working Group. April 1992
Simpson, W. RFC 1661, The Point-to-Point Protocol (PPP).
Network Working Group. July 1994.
Simpson, W. RFC 1662, HDLC-like Framing . Network Working
Group. July 1994.
NOTES
These signals affect pppd behavior:
SIGINT, SIGTERM
Terminate the link, restore the serial device settings
and exit.
SIGHUP
Terminate the link, restore the serial device settings
and close the serial device. If the persist or demand
option is specified, pppd attempts to reopen the
serial device and start another connection after the
holdoff period. Otherwise pppd exits. If received dur-
ing the holdoff period, SIGHUP causes pppd to end the
holdoff period immediately.
SIGUSR1
Toggles the state of the debug option and prints link
status information to the log.
SIGUSR2
Causes pppd to renegotiate compression. This is useful
to re-enable compression after it has been disabled as
a result of a fatal decompression error. (Fatal
decompression errors generally indicate a bug in an
implementation.)
DIAGNOSTICS
Messages are sent to the syslog daemon using facility
LOG_DAEMON. To see error and debug messages, edit the
/etc/syslog.conf file to direct the messages to the desired
output device or file, or use the updetach or logfile
options.
The debug option causes the contents of all LCP, PAP, CHAP
or IPCP control packets sent or received to be logged. This
is useful if PPP negotiation does not succeed or if authen-
tication fails.
Debugging can also be enabled or disabled by sending a
SIGUSR1 signal, which acts as a toggle to the pppd process.
Man(1) output converted with
man2html