pppd(8) System Manager's Manual pppd(8)
NAME
pppd - 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
characters 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
characters. To escape transmitted characters, use the escape option. Requires the peer to authenticate itself before allowing network
packets 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 com-
ponent. See the Options File section for a description of the format. Uses the executable or shell command specified by p to set up the
serial line. This script would typically use the chat program to dial the modem and start the remote PPP session. This option is privi-
leged 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 system routing tables, using the peer as
the gateway, when IPCP negotiation is successfully completed. This entry is removed when the PPP connection is broken. This option is
privileged if you specify the nodefaultroute 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. Specifies that certain characters should be escaped on transmission (regardless of whether the peer
requests them to be escaped with its async control character map). The characters to be escaped are specified as a list of 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 section 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 negotiation. The pppd dae-
mon will ask the peer to send packets of no more than n bytes. The minimum MRU value is 128 for IPv4 and 1298 for IPv6. The default MRU
value is 1500. A value of 296 is recommended for slow, IPv4 links (40 bytes for TCP/IP header + 256 bytes of data). Sets the interface
netmask to n, a 32-bit netmask in dotted-decimal 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
Version 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 deprecated. 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 compression but consume more kernel memory for compression dic-
tionaries. 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 con-
nection 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 con-
trol 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 8 to 15 may be used for nr and nt; larger
values give better compression but consume more kernel memory for compression dictionaries. Alternatively, a value of 0 for nr or nt dis-
ables compression in the corresponding direction. 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.) 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 performs 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 conjunction 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 terminates. 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 pack-
ets (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 trans-
missions 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 config-
ure-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 gen-
eral debug messages), 2 (requests that the contents of received packets be printed), and 4 (requests that the contents of transmit-
ted packets be printed). If this option is given, pppd presumes the peer to be dead if n LCP echo-requests are sent without receiv-
ing a valid LCP echo-reply. If this happens, 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 starting 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 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. Uses the system password database for authenticat-
ing the peer using PAP. Terminates 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 Terminal Ready) signal briefly when the connec-
tion 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 sec-
ondary 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 privileged 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 system 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. Dis-
ables CCP (Compression 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 spec-
ify 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 protocol 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 nego-
tiation, unless it is specified explicitly 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 specify 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 implementation 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 deprecated. Same as the
require-pap option, but its use is deprecated. Same as the refuse-pap option, but its use is deprecated. 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 compres-
sion. Adds an entry to this system's ARP (Address Resolution 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 connected 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 (Chal-
lenge 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 Authentication Protocol) if requested by the peer,
and use the data in file p for the user and password to send to the peer. The file contains the remote user name, followed by a new-
line, 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 (inclusive). Runs
the executable or shell command specified by script before initiating PPP negotiation, after the connect script (if any) has com-
pleted. 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 whitespace. 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.
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 privileged. 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 password) with the server, and authenticates itself by proving that it
knows that secret. Very often the names used for authentication correspond 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 different 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
systems, as well as secrets for pppd to use when authenticating other systems 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 spec-
ified 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 specified 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 significant 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
administrator 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 authenticate 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 password, 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 commu-
nicate 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
interface 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 destina-
tions are considered to be on link. (See the Neighbor Discovery specification, 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 compression. 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
If you want to connect the serial ports of two machines and there is no getty running on the serial ports, issue a command similar to the
following on each machine: pppd /dev/ttya 9600 passive If one machine has a getty running, you can log in to the machine from another
machine using kermit or tip, 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 following: pppd /dev/ttya 9600 The process of logging in to the other machine
and starting pppd can be automated by using the connect option to run chat, for example: pppd /dev/ttya 38400 connect 'chat "login:"
"username" "Password:" "password" "% " "exec pppd passive"'
Note
Running chat in this way leaves the password visible in the parameter list of pppd and chat.
The following examples assume that the /etc/ppp/options file contains the auth option.
A common use of pppd is to dial out to an Internet Service Provider (ISP). To do this, enter: # pppd call isp
In order for this to succeed, the system administrator must previously set up an /etc/ppp/peers/isp file with the following parameters:
ttyS0 19200 crtscts connect '/usr/sbin/chat -v -f /etc/ppp/chat-isp' noauth
In this example, we are using chat to dial the ISP's modem and go through any logon sequence required. The /etc/ppp/chat-isp file contains
the script used by chat; it could contain the following:
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 the 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 may need to arrange for some control characters to be escaped. In
particular, it is often useful to escape XON (^Q) and XOFF (^S), using asyncmap a0000. If the path includes a telnet, you probably should
escape ^] as well (asyncmap 200a0000). If the path includes an rlogin, you need to use the escape ff option on the end that is running the
rlogin client, 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
environment. (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 man-
ner with the same parameters as /etc/ppp/auth-up. A program or script that is executed when the link is available for sending and receiv-
ing IPv4 packets (IPCP is up). It is executed with the parameters 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 effective user-ID as pppd, that is, at least the effective user-ID and
possibly the real user-ID will be root. This is so that it can be used to manipulate routes and run privileged daemons (for exam-
ple, 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 effective user-ID as pppd, that is, at least the effective user-ID and
possibly the real user-ID will be root. This is so that it can be used to manipulate routes, run privileged daemons (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 secu-
rity. 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 considerations apply. Usernames, passwords and IP addresses for PAP 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.
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 (read before user
default options or command-line options). User default options (read before /etc/ppp/options.ttyname). System default options for
the serial port being used (read after ~/.ppprc). In forming the name of the options.ttyname file, the initial /dev/ prefix is
removed and any remaining slash characters (/) are replaced with dots. A directory containing options files that may contain privi-
leged 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 requiring the peer to authenticate, but only to certain trusted peers.
SEE ALSO
Commands: chat(8), ip6rtrd(8), pppstats(8)
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 Protocol (IPCP), 1992 May (obsoletes RFC1172).
RFC 1334RFC1334, Lloyd, B.; Simpson, W.A., PPP Authentication Protocols, 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)