`pppd`

Point-to-Point protocol daemon

Syntax:

pppd [options]

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

By default, an asyncmap of 0 is negotiated; the peer doesn't escape control characters. 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.

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).

ccp

Enable CCP (Compression Control Protocol) negotiation. This protocol is disabled by default.

+chap

Require the peer to authenticate itself using CHAP (Challenge-Handshake Authentication Protocol) authentication. Default is no authentication required (usually a server option).

confstr

Write the server-supplied nameserver address to the _CS_RESOLVE configuration string (the default).

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).

crtscts

Set hardware flow control (on by default).

debug

Write messages in the system log. In order to capture the log messages, you need to have syslogd running. This option increases the log mask to LOG_DEBUG. The default log mask 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).

demand

Initiate the link only on demand, i.e. when data traffic is present. With this option, the remote IP address must be specified by the user on the command line or in an options file. pppd will initially configure the interface and enable it for IP traffic without connecting to the peer. When traffic is available, pppd will connect to the peer and perform negotiation, authentication, etc. When this is completed, pppd will commence passing data packets (i.e. IP packets) across the link.

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.

endpoint [epdisc]

Sets the endpoint discriminator sent by the local machine to the peer during multilink negotiation to [epdisc]. The default is to use the MAC address of the first ethernet interface on the system, if any, otherwise the IPv4 address corresponding to the hostname, if any, provided it is not in the multicast or locally-assigned IP address ranges, or the localhost address. The endpoint discriminator can be the string null or of the form type:value, where type is a decimal number or one of the strings local, IP, MAC, magic, or phone. The value of type in decimal being 1 for local, 2 for IP, 3 for MAC, 4 for magic and 5 for phone. The value is an IP address in dotted-decimal notation for the IP type, or a string of bytes in hexadecimal, separated by periods or colons for the other types.

idle n

Disconnect if the link is idle for n seconds.

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. You can specify the IP addresses 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.

logfd filedes

Send log messages to this file descriptor.

logfile filename

Append log messages to this file.

login

Use both system password database and /etc/ppp/pap-secrets file to allow access. The peer is authenticated by the system password database using PAP.

mp or multilink

Enables the use of PPP multilink support.

mpshortseq

Enables the use of short (12-bit) sequence numbers in multilink headers, as opposed to 24-bit sequence numbers. This option only has effect if multilink is enabled (see the multilink option).

mrru n

Sets the Maximum Reconstructed Receive Unit (MRRU) to n. The MRRU is the maximum size for a received packet on a multilink bundle, and is analogous to the MRU for the individual links. This option only effect if multilink is enabled (see the multilink option).

mru n

Set the MRU (Maximum Receive Unit) value to n.

ms-dns nameserver_ip

Allow the peer to request a nameserver (usually a server option). You can specify up to two nameserver IPs. For example:

  ms-dns 10.0.0.1  ms-dns 10.0.0.2

or,

  ms-dns primary-ns.sample.com ms-dns secondary-ns.sample.com

The default is not to allow peer request.

mtu n

Set the MTU (Maximum Transmit Unit) value to n.

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).

noccp

Disable CCP (Compression Control Protocol) negotiation.

noconfstr

Don't write the server-supplied nameserver address to the _CS_RESOLVE configuration string.

nocrtscts (or -crtscts)

Clear hardware flow control.

nodetach

Don't detach from the controlling terminal (daemon).

nolog

Don't send log messages to any file.

nologfd

Don't send log messages to any file descriptor.

nompshortseq

Disables the use of short (12-bit) sequence numbers in the PPP multilink protocol, forcing the use of 24-bit sequence numbers. This option has any effect if multilink is enabled.

noresconf

Don't write the server-supplied nameserver address to /etc/resolv.conf file (the default).

novj

Disable Van Jacobson style TCP/IP header compression in both transmit and receive directions.

novjccomp

Disable the connection-ID compression option in Van Jacobon style TCP/IP header compression. With this option, pppd will not omit the connection-ID byte frm Van Jacobson compressed TCP/IP headers, nor ask the peer to do so.

+pap

Require the peer to authenticate itself using PAP (Password Authentication Protocol). The default is no authentication required (usually a server option).

passive

Stay until the peer talks to us.

persist

Don't exit after a connection is terminated. Try to reopen the connection.

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 not to 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).

resconf

Write the server-supplied nameserver address to the /etc/resolv.conf file.

speed

Set the baud rate to speed. The default is the current baud rate.

+stdinsecret

Read PAP or CHAP secrets from standard input. If you use this option, you need to specify explicitly a serial device on the command line.

tty_name

Communicate over the named device. Usually, this is a serial device such as /dev/ser1. The default is to use the current controlling terminal.

updetach

Detach from the controlling terminal after the interface is configured.

usefd filedes

Use this file descriptor to send or receive pppd packets instead of opening a tty_name.

usepeerdns

Require the peer to provide a nameserver address. Default is not require.

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.

useuserdns nameserver_IP

Specify the nameserver to use. This overrides any nameservers provided by the server.

vj

Enable Van jacobson style TCP/IP header compression in both transmit and receive directions. The default is disabling VJ compressed.

xonxoff

Set software flow control.

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:

a method for encapsulating datagrams over serial links
an extensible Link Control Protocol (LCP)
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 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:

/etc/ppp/options
/etc/ppp/options. device
~/.ppprc

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. You can include whitespace 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 4 words in the order: client, server, secret, ip allowed. Any following words on the same line are taken to be a list of acceptable IP addresses for that client. If there are only 4 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. If the secret is @login, and login is specified, then the secret is checked with the system password database. 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)

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 terminates the link (by closing LCP). If IPCP negotiates an unacceptable IP address for the remote host, IPCP is 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 informs 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 enables 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 is 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:

All the following scripts must have execute permission as well as the following line as their first line to run:

#!/bin/sh

/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:

interface-name
tty-device
speed
local-IP-address
remote-IP-address

This program or script is executed with the same real and effective user ID as pppd, that is, at least the effective user ID and possibly the real user ID are 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.

If usepeerdns option is used, then DNS1 and DNS2 environment parameters are set for primary and secondary nameserver IP address and passed into the script.

/etc/ppp/ip-down

A program or script that is executed when the link is no longer available for sending and receiving IP packets. You can use this script to undo the effects of the /etc/ppp/ip-up script. It's invoked with the same parameters as the ip-up script; the same security considerations apply, since it's 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:

interface-name
peer-name
user-name
tty-device
speed

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.

The /etc/ppp/auth-up is a server-side script. Therefore you must specify +pap (or +chap) option to run this script. It essentially authenticates the remote system.

/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.

The /etc/ppp/auth-down is a server-side script. Therefore you must specify +pap (or +chap) option to run this script. It essentially authenticates the remote system.

/etc/ppp/pap-secrets

User names, 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 attempts to restore the serial device settings and then exits.
MS-CHAP: Authentication support is client-side only. It can be used to authenticate ourselves, but not the peer.