pppd

point-to-point protocol daemon

Syntax:

pppd [options]

Options:

asyncmap map
Set the async character map to map. This map describes which control characters cannot be successfully received over the serial line. The pppd utility will ask the peer to send these characters as a 2-byte escape sequence. The argument is a 32-bit hex number with each bit representing a character to escape. Bit 0 (00000001) represents the character 0x00; bit 31 (80000000) represents the character 0x1f or ^_.

By default, an asyncmap of 0 is negotiated; the peer will not escape control characters. If multiple asyncmap options are given, the values are ``ORed'' together. If no asyncmap option is given, no async character map will be negotiated for the receive direction; the peer will then escape all control characters.

auth
Require the peer to authenticate using PAP or CHAP. The authentication protocol negotiated depends on what the client supports and what secrets we have (usually a server option).
connect p
Use the executable or shell command specified by p to set up the serial line. This script would typically use the ``chat'' program to dial the modem and start the remote ppp session. By default, there's no script - ppp assumes the line is already set up (usually a client option).
+chap
Require the peer to authenticate itself using CHAP (Challenge-Handshake Authentication Protocol) authentication. Default is no authentication required (usually a server option).
debug
Log messages to the syslogd daemon. This option will increase the logmask to LOG_DEBUG. The default logmask is LOG_INFO.
defaultroute
Add a default route to the system routing tables, using the peer as the gateway. The default is to not add a route (usually a client option).
disconnect p
Run the executable or shell command specified by p after pppd has terminated the link. This script could, for example, issue commands to the modem to cause it to hang up if hardware modem control signals were not available. By default, there's no script.
local_IP_address:remote_IP_address
Set the local and/or remote interface IP addresses. Either one may be omitted, but the : must be present to distinguish the local from the remote address. The IP addresses can be specified with a hostname or in decimal dot notation (e.g. 150.234.56.78). The default local address is the hostname of the system. The default remote address is NULL (unknown). Usually, both are set by the server.
login
Used for authentication (PAP only!). Requires a name:secret pair to map into a user:passwd pair in the system password database. The default is to not check the password database. With this option, a pap-secrets file is optional.
ms-dns nameserver_ip
Allow the peer to request a nameserver (usually a server option). Up to two nameserver IP's can be specified, for example:

ms-dns primary ms-dns secondary
    

The default is to not allow peer request.

name n
Set the name of the local system for authentication purposes to n. The default is the hostname.
netmask n
Set the interface netmask to n, a 32-bit netmask in ``decimal dot'' notation (e.g. 255.255.255.0). The default depends on the class of the IP address (usually a server option).
+pap
Require the peer to authenticate itself using PAP (Password Authentication Protocol). The default is no authentication required (usually a server option).
proxyarp
Add an entry to this system's ARP (Address Resolution Protocol) table with the IP address of the peer and the Ethernet address of this system. The default is to not add an ARP entry (usually a server option).
remotename n
Set the assumed name of the remote system for authentication purposes to n. The default is NULL (unknown).
require-ns
Require the peer to provide a nameserver address. Default is not require.
speed
Set the baud rate to speed. The default is the current baud rate.
tty_name
Communicate over the named device. Usually, this will be a serial device such as /dev/ser1. The default is to use the current controlling terminal.
user n
Set the name of the local system for authenticating this host with the peer to n. Usually, this is a client option - it overrides the name option. The default is the hostname.

Description:

The pppd daemon is used to establish TCP/IP serial connections using the point-to-point protocol (PPP). The protocol consists of three parts:

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

Options files

Options can be taken from files as well as the command line. Before looking at the command line, the pppd utility reads options from these files:

The device is the name of pppd's controlling terminal. For example, if the terminal is /dev/ser2, the options file would be /etc/ppp/options.ser2.

An options file is parsed into a series of words delimited by whitespace. Whitespace can be included in a word by enclosing the word in quotes ("). A backslash (\) quotes the next character. A pound sign (#) starts a comment, which continues until the end of the line.

Authentication

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

The default behavior of pppd is to agree to authenticate if requested, and to not require authentication from the peer. But pppd won't agree to authenticate itself with a particular protocol if it has no secrets that could be used to do so.

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

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

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



if we are authenticating ourselves and the user option is given,
	then use the user option

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

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

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

Note: When authenticating ourselves, the user option overrides the name option, so that the local name is set to the user option.

The remote name is set as follows:

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

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

else the remote name is the null string ""

PAP-specific

Secrets are selected from the PAP secrets file as follows:



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

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

When authenticating the peer with PAP, a secret of "" matches any password supplied by the peer. If the password doesn't match the secret, the password is encrypted using crypt() and checked against the secret again; thus secrets for authenticating the peer can be stored in encrypted form.

If the login option was specified, the username and password are also checked against the system password database. The system administrator can therefore set up the pap-secrets file to allow PPP access only to certain users and to restrict the set of IP addresses that each user can use.

CHAP-specific

Secrets are selected from the CHAP secrets file as follows:



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

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

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

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

Routing

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

Sometimes it's 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 (e.g. on a server machine connected to a LAN) in order to allow other hosts to communicate with the remote host. The proxyarp option causes pppd to look for a network interface on the same subnet as the remote host (an interface supporting broadcast and ARP, which is up and not a point-to-point or loopback interface). If such a network interface is found, pppd creates a permanent, published ARP entry with the IP address of the remote host and the hardware address of the network interface found.

Diagnostics

Messages are sent to the syslogd daemon using LOG_LOCAL2. To see the error and debug messages, you'll need to edit your /etc/syslog.conf file to direct the messages to the desired output device or file.

The debug option causes the contents of all control packets (i.e. LCP, PAP, CHAP or IPCP packets) sent or received to be logged. This can be useful if the PPP negotiation doesn't succeed.

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

Files:

/var/run/pppn.pid
Process ID for pppd process on PPP interface unit n.
/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 these parameters:

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 allows the script to be used to manipulate routes, run privileged daemons (e.g. sendmail), etc. Be careful that the contents of the /etc/ppp/ip-up and /etc/ppp/ip-down scripts don't compromise your system's security.

The primary-nameserv-IP-address and secondary-nameserv-IP-address parameters are only valid when the require_ns option is specified.

/etc/ppp/ip-down
A program or script that is executed when the link is no longer available for sending and receiving IP packets. This script can be used for undoing the effects of the /etc/ppp/ip-up script. It is invoked with the same parameters as the ip-up script; the same security considerations apply, since it is executed with the same effective and real user IDs as pppd.
/etc/ppp/auth-up
A program or script executed after the remote system successfully authenticates itself. The script is executed with these parameters:

The same security considerations of the /etc/ppp/ip-up script apply, since it's executed with the same effective and real user IDs as pppd.


Note: The /etc/ppp/auth-up script isn't executed if the peer didn't authenticate itself.

/etc/ppp/auth-down
A program or script executed when the link goes down if /etc/ppp/auth-up was previously executed. It's executed in the same manner and with the same parameters as /etc/ppp/auth-up.
/etc/ppp/pap-secrets
Usernames, passwords, and IP addresses for PAP authentication.
/etc/ppp/chap-secrets
Names, secrets, and IP addresses for CHAP authentication.
/etc/ppp/options
System default options for pppd; these are read before user default options or command-line options.
/etc/ppp/options.device
Device default options for pppd; these are read before user default options or command-line options.
~/.ppprc
User default options; these are read before command-line options.

Caveats:

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

SIGINT, SIGTERM
These signals cause pppd to terminate the link (by closing LCP), restore the serial device settings, and exit.
SIGHUP
Indicates that the physical layer has been disconnected; pppd will attempt to restore the serial device settings and then exit.
MS-CHAP
Authentication support is client-side only. It can be used to authenticate ourselves, but not the peer.

See also:

RFC 1144, RFC 1321, RFC 1332, RFC 1334, RFC 1549, RFC 1661, RFC 1662

Section on ``Setting up a PPP serial link'' in the Serial Network Configuration chapter in this guide.