pppd(8)pppd(8)NAMEpppd - Point-to-Point Protocol (PPP) daemon
SYNOPSIS
/usr/sbin/pppd [tty_name] [speed] [options]
FREQUENTLY USED OPTIONS
Communicates over the named device. The string /dev/ is prepended if
necessary. If no device name is given or if the name of the control‐
ling terminal is given, pppd uses the controlling terminal, and does
not fork to put itself in the background. This option is privileged if
you specify the noauth option. Sets the baud rate to speed. Sets the
async character map to map. This map describes those control charac‐
ters that cannot be successfully received over the serial line. The
pppd daemon asks the peer to send these characters as a 2-byte escape
sequence. The argument is a 32-bit hexadecimal 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 is negotiated
for the receive direction; the peer then escapes all control charac‐
ters. To escape transmitted characters, use the escape option.
Requires the peer to authenticate itself before allowing network pack‐
ets to be sent or received. Reads options from the /etc/ppp/peers/name
file. This file may contain privileged options, such as noauth, even
if pppd is not being run by root. The name string may not begin with a
slash (/) or include two dots (..) as a pathname component. See the
Options File section for a description of the format. Uses the exe‐
cutable 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. This option is privileged if you specify
the noauth option. Uses hardware flow control (RTS/CTS) to control the
flow of data on the serial port. If neither crtscts nor nocrtscts is
specified, the hardware flow control setting for the serial port is not
changed. Disables hardware flow control (RTS/CTS) on the serial port.
If neither the crtscts nor the -crtscts option is given, the hardware
flow control setting for the serial port is not changed. Same as
nocrtscts, but its use is deprecated. Adds a default route to the sys‐
tem routing tables, using the peer as the gateway, when IPCP negotia‐
tion is successfully completed. This entry is removed when the PPP con‐
nection is broken. This option is privileged if you specify the node‐
faultroute option. This option is for IPv4 only. Runs 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. Spec‐
ifies 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 speci‐
fied as a list of hexadecimal 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. Reads options from file f. See the Options Files sec‐
tion for a description of the format. Specifies that pppd should use a
UUCP-style lock on the serial device to ensure exclusive access to the
device. Sets the MRU (Maximum Receive Unit) value to n for negotia‐
tion. The pppd daemon will ask the peer to send packets of no more
than n bytes. For IPv4 connections, the minimum MRU value is 128, but
it is best to set the value to 296 (40 bytes for TCP/IP header and 256
bytes of data). The MRU value in the default PPP options file is 296.
For IPv6 connections, the minimum MRU value is 1298, but it is
best to set the value to 1500. If IPv6 is enabled in the kernel,
PPP automatically configures an IPv6 address whether you intend
to use it or not. Therefore, if IPv6 is enabled in the kernel,
you must set an MRU value of 1298 or higher, or specify the
noip6 option if you do not intend to use IPv6 over the PPP link.
Sets the interface netmask to n, a 32-bit netmask in dotted-dec‐
imal notation (for example, 255.255.255.0). If specified, the
value is ORed with the default netmask. The default netmask is
based on the negotiated remote IPv4 address, appropriate for the
class of remote IPv4 address and ORed with netmasks for other
network interfaces (not point-to-point) that are on the same
network. This flag is for IPv4 only. If specified for IPv6, it
is ignored. Disables hardware flow control (RTS/CTS) on the
serial port. If neither the crtscts nor the nocrtscts option is
given, the hardware flow control setting for the serial port is
not changed. 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 for a valid LCP packet
from the peer (instead of exiting, as it does without this
option). With this option, pppd does 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).
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. The
pppd daemon provides the basic LCP, authentication support, and NCPs
for establishing and configuring the Internet Protocol Version 4 (IPv4)
(called the IP Control Protocol, IPCP) and the Internet Protocol Ver‐
sion 6 (IPv6) (called the IP6 Control Protocol, IP6CP).
OPTIONS
Sets the local or remote interface IPv4 addresses, or both. Either one
may be omitted. The IPv4 addresses can be specified with a host name
or in decimal dot notation (for example, 150.234.56.78). The default
local address is the (first) IPv4 address of the system (unless the
noipdefault option is given). The remote address is obtained from the
peer if not specified in any option. Thus, in simple cases, this
option is not required. If a local or remote IPv4 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 or ipcp-accept-
remote options are given, respectively. Does not request or allow
negotiation of any options for LCP and IPCP (use default values).
IP6CP negotiation is not affected by this flag. Same as noaccomp, but
its use is deprecated. Same as default-asyncmap, but its use is depre‐
cated. Same as asyncmap n, but its use is deprecated. Requests the
peer to compress all packets that it sends, using the BSD-Compress
scheme, with a maximum code size of nr bits, and agrees to compress all
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 give better com‐
pression but consume more kernel memory for compression dictionaries.
Alternatively, a value of 0 for nr or nt disables compression in the
corresponding direction. Same as nobsdcomp, but its use is deprecated.
Same as require-chap, but its use is deprecated. Same as refuse-chap,
but its use is deprecated. If this option is given, pppd challenges
the peer every n seconds. Sets the maximum number of CHAP challenge
transmissions to n (default 10). Sets the CHAP restart interval
(retransmission timeout for challenges) to n seconds (default 3). Same
as debug, but its use is deprecated. Enables connection debugging
facilities. 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 local2 and level debug. This
information can be directed to a file by setting up /etc/syslog.conf
appropriately (see syslog.conf(4)). Disables asyncmap negotiation (use
the default asyncmap, that is, escape all control characters for both
the transmit and receive directions). Disables MRU (Maximum Receive
Unit) negotiation. The pppd daemon uses the default, that is, 1500
bytes for both the transmit and receive directions. Requests 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. 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 give better compres‐
sion but consume more kernel memory for compression dictionaries.
Alternatively, a value of 0 for nr or nt disables compression in the
corresponding direction. Use nodeflate or deflate 0 to disable Deflate
compression entirely. (Note: pppd requests Deflate compression in pref‐
erence to BSD-Compress if the peer can do either.) Initiates the link
only when IPv4 data traffic is present (on demand). With this option,
the remote IPv4 address must be specified by the user on the command
line or in an options file. The pppd daemon initially configures the
interface and enables it for IPv4 traffic without connecting to the
peer. When traffic is available, pppd connects to the peer and per‐
forms negotiation, authentication, and other operations. When this is
completed, pppd begins passing data packets (IPv4 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 are also useful in con‐
junction with the demand option. Same as nodetach, but its use
is deprecated. Appends 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. Specifies the amount of time (in
seconds) to wait before re-initiating the link after it termi‐
nates. This option only has any effect if you specify either
the persist or demand option. The holdoff period is not applied
if the link was terminated because it was idle. Specifies that
pppd should disconnect if the link is idle for n seconds. The
link is idle when no data packets (IPv4 packets) are being sent
or received. Note: If you use this option with the persist
option, you must also specify the demand option. If you specify
the active-filter option, data packets that are rejected by the
specified activity filter also count as the link being idle.
Same as noip, but its use is deprecated. With this option, pppd
accepts the peer's idea of our local IPv4 address, even if the
local IPv4 address was specified in an option. With this
option, pppd accepts the peer's idea of its (remote) IPv4
address, even if the remote IPv4 address was specified in an
option. Sets the maximum number of IPCP configure-request
transmissions to n (default 10). Sets the maximum number of
IPCP configure-NAKs returned before starting to send configure-
Rejects instead to n (default 10). Sets the maximum number of
IPCP terminate-request transmissions to n (default 3). Sets the
IPCP restart interval (retransmission timeout) to n seconds
(default 3). Specifies a character string that you can pass as
the sixth parameter to the ip-up, ip-down, ip6-up, and ip6-down
scripts. Sets the tentative local (l) interface identifier to
use in the IP6CP configure-request. If the interface identifier
requested by the peer is the same as the interface identifier
sent in the configure-request by pppd, a CONFNAK message is sent
to the peer with a suggested interface identifier, r.
Both l and r are 64-bit numbers that may be: decimal, octal
(must have a leading 0), or hexadecimal (must have leading 0x).
Enables debugging code in the kernel-level PPP driver. The
argument n is a number that is the sum of the following values:
1 (enables general debug messages), 2 (requests that the con‐
tents of received packets be printed), and 4 (requests that the
contents of transmitted packets be printed). 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 hap‐
pens, pppd terminates 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 (for example, the modem has
hung up) in situations where no hardware modem control lines are
available. If this option is given, pppd sends 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. Sets the maximum number
of LCP configure-request transmissions to n (default 10). Sets
the maximum number of LCP configure-NAKs returned before start‐
ing to send configure-Rejects instead to n (default 10). Sets
the maximum number of LCP terminate-request transmissions to n
(default 3). Sets the LCP restart interval (retransmission
timeout) to n seconds (default 3). Does not use the modem con‐
trol 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. Uses the system
password database for authenticating the peer using PAP. Termi‐
nates the connection after it has been available for network
traffic for n seconds (n seconds after the first network control
protocol comes up). Same as nomagic, but its use is deprecated.
Uses the modem control lines. This option is the default. With
this option, pppd waits for the CD (Carrier Detect) signal from
the modem to be asserted when opening the serial device (unless
a connect script is specified), and it drops the DTR (Data Ter‐
minal Ready) signal briefly when the connection is terminated
and before executing the connect script. Same as default-mru,
but its use is deprecated. 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. (This option was present in some older versions of
pppd under the name dns-addr.) If pppd is acting 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. Sets the MTU
(Maximum Transmit Unit) value to n. Unless the peer requests a
smaller value using MRU negotiation, pppd will request that the
kernel networking code send data packets of no more than n bytes
through the PPP network interface. Sets the name of the local
system for authentication purposes to name. This is a privi‐
leged option. If specified, pppd will search for name in the
second field in the secrets files and will use that secret to
authenticate the peer. Unless overridden with the user option,
name will be sent to the peer when authenticating the local sys‐
tem to the peer. The pppd command does not append the domain
name to name. Disables Address/Control compression in both
directions (send and receive). Does not require the peer to
authenticate itself. This option is privileged if the auth
option is specified in the /etc/ppp/options file. Disables BSD-
Compress compression; pppd will not request or agree to compress
packets using the BSD-Compress scheme. Disables CCP (Compres‐
sion Control Protocol) negotiation. Use this option only if the
peer is unreliable and gets confused by requests from pppd for
CCP negotiation. Disables the defaultroute option. If you want
to prevent users from creating default routes with pppd, include
this option in the /etc/ppp/options file. This flag is for IPv4
only. Disables Deflate compression; pppd will not request or
agree to compress packets using the Deflate scheme. Does not
detach from the controlling terminal. If you do not specify
this option, if a serial device other than the terminal on the
standard input is specified, pppd will fork to become a back‐
ground process. Disables IPv4. The IPCP protocol parameters
are not negotiated on the interface. Use this option if you
want to disable IPv4 over PPP. Disables IPv6. The IP6CP proto‐
col parameters are not negotiated on the interface. Use this
option if you want to disable IPv6 over PPP. Disables the
default behavior when no local IPv4 address is specified, which
is to determine (if possible) the local IPv4 address from the
hostname. With this option, the peer must supply the local IPv4
address during IPCP negotiation, unless it is specified explic‐
itly on the command line or in an options file. Disables magic
number negotiation. With this option, pppd cannot detect a
looped-back line. Use this option only with unreliable peers.
Disables protocol field compression negotiation in both the
receive and transmit direction. Exits once a connection has
been made and terminated. This is the default unless you spec‐
ify the persist or demand option. Does not accept or agree to
Predictor-1 compression. Disables the proxyarp option. If you
want to prevent users from creating proxy ARP entries with pppd,
put this option in the <filename> /etc/ppp/options</filename>
file. Disables Van Jacobson-style IPv4 header compression in
both the transmit and receive directions.
Van Jacobson compression is not supported for this implementa‐
tion of IPv6 over PPP. Disables connection-ID compression
option in the Van Jacobson-style header compression. If you
specify this option, pppd will neither omit the connection-ID
byte from Van Jacobson compressed TCP/IP headers nor ask the
peer to do so. Same as the passive option, but its use is dep‐
recated. Same as the require-pap option, but its use is depre‐
cated. Same as the refuse-pap option, but its use is depre‐
cated. Indicates that all secrets in the /etc/ppp/pap-secrets
file used for checking the identity of the peer are encrypted.
The pppd daemon should not accept a password that (before
encryption) is identical to the secret from the /etc/ppp/pap-
secrets file. Sets the maximum number of PAP authenticate-
request transmissions to n (default 10). Sets the PAP restart
interval (retransmission timeout) to n seconds (default 3).
Sets the maximum time that pppd will wait for the peer to
authenticate itself with PAP to n seconds (0 means no limit).
Same as the nopcomp option, but its use is deprecated. Do not
exit after a connection is terminated. Instead, try to reopen
the connection. Requests that the peer compress frames that it
sends using Predictor-1 compression and agrees to compress
transmitted frames with Predictor-1, if requested. This option
has no effect unless the kernel driver supports Predictor-1 com‐
pression. Adds an entry to this system's ARP (Address Resolu‐
tion Protocol) table with the IPv4 address of the peer and the
Ethernet address of this system. The peer will appear to other
systems on the local Ethernet as though it is physically con‐
nected the the local Ethernet. Does not agree to authenticate
to the peer using CHAP. Does not agree to authenticate to the
peer using PAP. Sets the assumed name of the remote system for
authentication purposes to n. Requires the peer to authenticate
itself using CHAP (Challenge Handshake Authentication Protocol)
authentication. Requires the peer to authenticate itself using
PAP. With this option, pppd will not transmit LCP packets to
initiate a connection until a valid LCP packet is received from
the peer (as with the passive option with older versions of
pppd). Agrees to authenticate using PAP (Password Authentica‐
tion 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
obsolete. Enforces the use of the hostname as the name of the
local system for authentication purposes (overrides the name
option). Sets the user name to use for authenticating this
machine with the peer using PAP to u. Same as the novj option,
but its use is deprecated. 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 (inclu‐
sive). Runs the executable or shell command specified by script
before initiating PPP negotiation, after the connect script (if
any) has completed. This option is privileged if you specify
the noauth option. Uses software flow control (XON/XOFF) to
control the flow of data on the serial port.
Options Files
Options can be taken from files as well as the command line. The pppd
daemon reads options from the files /etc/ppp/options, ~/.ppprc, and
/etc/ppp/options.ttyname, in this order, before looking at the command
line. However, the command-line options are scanned to determine the
terminal name before reading the options.ttyname file. In forming the
name of the options.ttyname file, the initial /dev/ prefix is removed
and any remaining slash characters (/) are replaced with dots.
An options file is parsed into a series of words, delimited by white‐
space. Whitespace can be included in a word by enclosing the word in
double quotation marks ("). A backslash (\) quotes any character that
follows it. A hash mark (#) starts a comment, which continues until the
end of the line. There are no restrictions on using the file option or
call option within an options file.
You can create and edit options files with the SysMan Menu utility.
Or, you can copy the options file template, /etc/ppp.common/options, to
the /etc/ppp directory and manually edit the new file with a text edi‐
tor.
Note
The /etc/ppp/options file must exist and must be readable by pppd; oth‐
erwise, the daemon will not run. Set the file permissions so that only
root has write access.
Security
The pppd daemon provides system administrators with sufficient access
control so that legitimate users can have PPP access to a server
machine without fear of compromising the security of the server or the
network. In part this is provided by the /etc/ppp/options file, into
which the administrator can place options to require authentication
whenever pppd is run, and in part by the PAP and CHAP secrets files,
into which the administrator can restrict the set of IPv4 addresses
that individual users may use.
You should set up pppd by placing the auth option in the
/etc/ppp/options file. If users want to use pppd to dial out to a peer
that will refuse to authenticate itself (such as an Internet service
provider), the system administrator should create an options file under
/etc/ppp/peers containing the noauth option, the name of the serial
port to use, and the connect option (if required), plus any other
appropriate options. In this way, pppd can be set up to allow non-
privileged users to make unauthenticated connections only to trusted
peers.
As indicated previously, some security-sensitive options are privi‐
leged. This means that they may not be used by an ordinary non-privi‐
leged user running a setuid-root pppd, either on the command line, in
the user's ~/.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 being run by
the root user, privileged options can be used without restriction.
Authentication
Authentication is the process whereby one peer convinces the other of
its identity. This involves the first peer (the client) sending its
name to the other (the server), together with some kind of secret
information that could only come from the genuine authorized user of
that name. The client has a name by which it identifies itself to the
server, and the server also has a name by which it identifies itself to
the client. Generally, the genuine client shares some secret (or pass‐
word) with the server, and authenticates itself by proving that it
knows that secret. Very often the names used for authentication corre‐
spond to the Internet hostnames of the peers, but this is not essen‐
tial.
At present, pppd supports two authentication protocols: the Password
Authentication Protocol (PAP) and the Challenge Handshake Authentica‐
tion Protocol (CHAP). PAP involves the client sending its name and a
cleartext password to the server to authenticate itself. In contrast,
the server initiates the CHAP authentication exchange by sending a
challenge to the client (the challenge packet includes the server's
name). The client must respond with a response that includes its name
plus a hash value derived from the shared secret and the challenge, in
order to prove that it knows the secret.
The PPP protocol is symmetrical. It allows both peers to require the
other to authenticate itself. That way, two separate and independent
authentication exchanges will occur. The two exchanges could use dif‐
ferent authentication protocols, and in principle, could use different
names in the two exchanges.
The default behavior 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 for that protocol.
The pppd daemon stores secrets for use in authentication in secrets
files (/etc/ppp/pap-secrets for PAP and /etc/ppp/chap-secrets for
CHAP). Both secrets files have the same format. The secrets files can
contain secrets for pppd to use in authenticating itself to other sys‐
tems, as well as secrets for pppd to use when authenticating other sys‐
tems to itself.
Each line in a secrets file contains one secret. A given secret is
specific to a particular combination of client and server - it can only
be used by that client to authenticate itself to that server. Each
line contains at least 3 words, in the following order:
client server secret
If any words follow the secret on the same line, they are the IPv4
addresses that the specified client may use when connecting to the
specified server.
If there are only 3 words on the line or if the first word is a dash
(-), all IPv4 addresses are disallowed. To allow any address, use an
asterisk (*). If a word starts with an exclamation point (!), the spec‐
ified address is not acceptable. An address may be followed by a slash
(/) and a number n, to indicate a whole subnet (all addresses that have
the same value in the most significant n bits). Note that case is sig‐
nificant in the client and server names and in the secret.
If the secret starts with an at sign (@), anything following it is
assumed to be the name of a file from which to read the secret. An
asterisk (*) as the client or server name matches any name. When
selecting a secret, pppd takes the best match (the match with the
fewest wildcards).
Note
The use of IPv6 addresses in a secrets file is not supported.
A secrets file contains secrets for use in authenticating other hosts
and secrets that we use for authenticating ourselves to others. When
pppd is authenticating the peer (checking the peer's identity), it
chooses a secret with the peer's name in the first field and the name
of the local system in the second field. The name of the local system
defaults to the hostname with the domain name appended, if the domain
option is used. This default can be overridden with the name option,
except when the usehostname option is used.
When pppd is choosing a secret to use in authenticating itself to the
peer, it first determines what name it is going to use to identify
itself to the peer. This name can be specified by the user with the
user option. If this option is not used, the name defaults to the name
of the local system, determined as described in the previous paragraph.
Then, pppd looks for a secret with this name in the first field and the
peer's name in the second field. The daemon will know the name of the
peer if CHAP authentication is being used because the peer will have
sent it in the challenge packet. However, if PAP is being used, pppd
will have to determine 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. Failing that, pppd will use the null string as the peer's
name.
When authenticating ourselves using PAP, the supplied password is
first compared with the secret from the secrets file. If the password
does not match the secret, the password is encrypted using crypt and
checked against the secret again. Therefore, secrets for authenticat‐
ing the peer can be stored in encrypted form. If the papcrypt option
is given, the first (unencrypted) comparison is omitted for better
security.
If the login option was specified, the user name and password are also
checked against the system password database. Thus, the system admin‐
istrator can set up the<filename> pap-secrets</filename> file to allow
PPP access only to certain users and to restrict the set of IPv4
addresses that each user can use. Typically, when using the login
option, the secret in /etc/ppp/pap-secrets would be "", to avoid the
need to have the same secret in two places.
Authentication must be satisfactorily completed before IPCP (or any
other Network Control Protocol) can be started. If authentication
fails, pppd terminates the link (by closing LCP). If IPCP negotiates
an unacceptable IPv4 address for the remote host, IPCP closes. IPv4
packets can only be sent or received when IPCP is open.
In some cases, you might want to allow some hosts that cannot authenti‐
cate themselves to connect and use one of a restricted set of IPv4
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 that specifies the empty string for the client and pass‐
word, it is possible to allow restricted access to hosts that refuse to
authenticate themselves.
IPv4 Routing
When IPCP negotiation is completed successfully, pppd will inform the
kernel of the local and remote IPv4 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 IPv4 packets. Communica‐
tion with other machines generally requires further modification to
routing tables or ARP (Address Resolution Protocol) tables. In some
cases this will be done automatically through the actions of the gated
or routed daemons, but in most cases some further intervention is
required. Use the /etc/ppp/ip-up script for any manual IPv4 routing
changes.
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 communi‐
cate 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 IPv4 address of the remote host and the hardware address
of the network interface found.
When the demand option is used, the interface IPv4 addresses have
already been set at the point when IPCP comes up. If pppd has not been
able to negotiate the same addresses that it used to configure the
interface (for example when the peer is an ISP that uses dynamic IP
address assignment), pppd has to change the interface IPv4 addresses to
the negotiated addresses. This may disrupt existing connections, and
the use of demand dialing with peers that do dynamic IPv4 address
assignment is not recommended.
IPv6 Routing
When IP6CP negotiation is completed successfully, IPv6 initialization
of the ppp interface adds routes to the link-local unicast (fe80::/10)
and the multicast (ff02::/10) prefixes through the interface.
If the system is running as router and the ppp interface is specified
in the ip6rtrd configuration file, the system sends router advertise‐
ments to the remote host (peer) over the PPP link and activates RIPng
for the PPP link, depending on the options specified for the ppp inter‐
face in the ip6rtrd configuration file.
If the system is running as a host, IPv6 initialization adds a default
route to the link. Unless other routes are specified, all destinations
are considered to be on link. (See the Neighbor Discovery specifica‐
tion, RFC 2461.) The nd6hostd daemon sends router solicitations on the
PPP link. If the remote system is a router, nd6hostd parses the router
advertisements that it receives and configures default routes to the
router.
NOTES
The following signals have the specified effect when sent to the pppd
process: Cause pppd to terminate the link (by closing LCP), restore the
serial device settings, and exit. This signal causes pppd to terminate
the link, restore the serial device settings, and close the serial
device. If the persist option has been specified, pppd tries to reopen
the serial device and start another connection. Otherwise, pppd exits.
Toggles the state of the debug option. Causes pppd to renegotiate com‐
pression. This can be useful to re-enable compression after it has
been disabled as a result of a fatal decompression error. With the BSD
Compress scheme, fatal decompression errors generally indicate a severe
implementation error.
DIAGNOSTICS
Messages are sent to the syslogd daemon using facility LOG_LOCAL2. To
see the error and debug messages, 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 is useful if the PPP negotiation does not succeed. If debugging
is enabled at compile time, the debug option causes additional debug‐
ging messages to be logged.
Debugging can also be toggled on and off by sending a SIGUSR1 to the
pppd process.
EXAMPLES
Examples 4 and 5 assume that the /etc/ppp/options file contains the
auth option. If you want to connect the serial ports of two machines
and there is no getty daemon running on the serial ports, issue a com‐
mand similar to the following on each machine: pppd /dev/ttya 9600 pas‐
sive If you want to connect the serial ports of two machines and one
machine has a getty daemon running, you can log in to that machine from
the other machine using the kermit or the tip command, and issue the
following command: pppd passive
Then, exit from the communications program (making sure the con‐
nection is not dropped), and issue a command similar to the fol‐
lowing: pppd /dev/ttya 9600 You can automate the process of log‐
ging in to another machine and starting pppd by using the con‐
nect option to run the chat command. For example: pppd /dev/ttya
38400 connect 'chat "login:" "username" "Password:" "password"
"% " "exec pppd passive"'
Note
Running chat in this way leaves the password visible in the
parameter list of pppd and chat. A common use of pppd is to
dial out to an Internet Service Provider (ISP). To do this,
enter a command similar to the following: # pppd call isp
The call option reads other pppd options from the specified
file. In this example, the system administrator has created a
file called isp in the /etc/ppp/peers directory that contains
connection options specific to the ISP he intends to contact.
This file could contain the following lines:
ttyS0 19200 crtscts connect '/usr/sbin/chat -v -f /etc/ppp/chat-
isp' noauth
As a result, the chat command dials the ISP's modem and executes
the login sequence, as dictated by the chat-isp script. The
/etc/ppp/chat-isp file could contain the following script:
ABORT "NO CARRIER" ABORT "NO DIALTONE" ABORT "ERROR" ABORT "NO
ANSWER" ABORT "BUSY" ABORT "Username/Password Incorrect" "" "at"
OK "at&d0&c1" OK "atdt2468135" "name:" "^Umyuserid" "word:"
"\\qmypassword" "ispts" "\\q^Uppp" "~-^Uppp-~"
See chat(8) for more information about chat scripts. You can
also use pppd to 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 (installed setuid-root) with the following command:
pppd proxyarp
To allow a user to use the PPP facilities, you need to allocate
an IP address for that user's machine and create an entry in
/etc/ppp/pap-secrets or /etc/ppp/chap-secrets (depending on
which authentication method the PPP implementation on the user's
machine supports), so that the user's machine can authenticate
itself. For example, if Joe has a machine called "joespc" that
is to be allowed to dial in to the machine called "server" and
use the IP address joespc.my.net, you would add an entry like
this to /etc/ppp/pap-secrets or /etc/ppp/chap-secrets:
joespc server "joe's secret" joespc.my.net
Alternatively, you can create a username called (for example)
"ppp", whose login shell is pppd and whose home directory is
/etc/ppp. Options to be used when pppd is run this way can be
put in /etc/ppp/.ppprc.
If your serial connection is more complicated than a piece of
wire, you might 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 session, you probably should escape ^] as well
(asyncmap 200a0000). If the path includes an rlogin session ,
you need to use the escape ff option on the end that is running
the rlogin command, since many rlogin implementations are not
transparent; they remove the sequence 0xff, 0xff, 0x73, 0x73,
followed by any 8 bytes, from the stream.
FILES
Process ID for pppd process on ppp interface unit n. A program or
script that is executed after the remote system successfully authenti‐
cates itself. It is executed with the parameters interface-name peer-
name user-name tty-device speed and with its standard input, output and
error redirected to /dev/null. This program or script is executed with
the real and effective user-IDs set to root, and with an empty environ‐
ment. (Note that this script is not executed if the peer does not
authenticate itself, for example when the noauth option is used.) A
program or script that is executed when the link goes down, if
/etc/ppp/auth-up was previously executed. It is executed in the same
manner with the same parameters as /etc/ppp/auth-up. A program or
script that is executed when the link is available for sending and
receiving IPv4 packets (IPCP is up). It is executed with the parame‐
ters interface-name tty-device speed local-IP-address remote-IP-address
and with its standard input, output and error streams redirected to
/dev/null.
This program or script is executed with the same real and effec‐
tive 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 and run privileged daemons (for
example, sendmail). Be careful that the contents of the
/etc/ppp/ip-up and /etc/ppp/ip-down scripts do not compromise
your system's security.
This program or script is executed with an empty environment, so
you must either specify a PATH or use full pathnames. A program
or script which is executed when the link is no longer available
for sending and receiving IPv4 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. A program or script that is
executed when the link is available for sending and receiving
IPv6 packets (IP6CP is up). It is executed with the parameters
interface-name tty-device speed::local-IPv6-interfaceID::remote-
IPv6-interfaceID and with its standard input, output and error
streams redirected to /dev/null.
This program or script is executed with the same real and effec‐
tive 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 (for
example, sendmail). Be careful that the contents of the
/etc/ppp/ip6-up and /etc/ppp/ip6-down scripts do not compromise
your system's security. A program or script that is executed
when the link is no longer available for sending and receiving
IPv6 packets. This script can be used for undoing the effects
of the /etc/ppp/ip6-up script. It is invoked with the same
parameters as the ip6-up script, and the same security consider‐
ations apply. Usernames, passwords and IP addresses for PAP
authentication. This file should be owned by root and not read‐
able or writable by any other user. The pppd daemon logs a
warning if these conditions are not true. Names, secrets and IP
addresses for CHAP authentication. This file should be owned by
root and not readable or writable by any other user. The pppd
daemon logs a warning if these conditions are not true. System
default options for pppd (which are read before user default
options or command-line options). You can use the /etc/ppp.com‐
mon/options file as a template for this file. Note that the
/etc/ppp/options file must exist and must be readable by pppd;
otherwise, the daemon will not run. Set the file permissions so
that only root has write access. User default options (which
are read before /etc/ppp/options.ttyname). You can use the
/etc/ppp.common/options file as a template for this file. Sys‐
tem default options for the serial port being used (which are
read after ~/.ppprc). In forming the name of the options.tty‐
name file, the initial /dev/ prefix is removed and any remaining
slash characters (/) are replaced with dots. You can use the
/etc/ppp.common/options file as a template for these files. A
directory containing 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 direc‐
tory to permit non-privileged users to dial out without requir‐
ing the peer to authenticate, but only to certain trusted peers.
SEE ALSO
Commands: chat(8), ip6rtrd(8), pppstats(8)
Network: ppp_manual_setup(7)
Network Administration: Connections
RFC 1144, Jacobson, V., Compressing TCP/IP Headers for Low-speed Serial
Links, 1990 February.
RFC 1321, Rivest, R., The MD5 Message-Digest Algorithm, 1992 April.
RFC 1332RFC1332, McGregor, G., The PPP Internet Protocol Control Proto‐
col (IPCP), 1992 May (obsoletes RFC1172).
RFC 1334RFC1334, Lloyd, B.; Simpson, W.A., PPP Authentication Proto‐
cols, 1992 October.
RFC 1570RFC1570, Simpson, W.A., PPP LCP Extensions, 1994 January.
RFC 1661RFC1661, Simpson, W.A., The Point-to-Point Protocol (PPP), 1994
July (obsoletes RFC1548, RFC1331, RFC1171).
RFC 1662RFC1662, Simpson, W.A., PPP in HDLC-like Framing, 1994 July
(obsoletes RFC1549).
RFC 2461RFC 2461, Narten, T.; Nordmark, E.; Simpson W. A., Neighbor
Discovery for IP version 6 (IPV6)
RFC 2472, Haskin, D., and Allen, E., IP Version 6 over PPP
ACKNOWLEDGEMENTS
Greg Christy, Brad Clements, Karl Fox, Brad Parker (brad@fcr.com), Drew
Perkins, Steve Tate (srt@cs.unt.edu)
pppd(8)