Section A.2. The PPP Daemon

The PPP Daemon (pppd) is a freely available implementation of the Point-to-Point Protocol (PPP) that runs on many Unix systems. Examples of configuring and using pppd are covered in Chapter 6. The syntax of the pppd command is:

pppd[device] [speed] [options]

device is the name of the serial port over which the PPP protocol operates and speed is the transmission speed of that port in bits per second. The complexity of this command comes not from these simple parameters but from the large number of options that it supports. There are so many options, in fact, that they are often stored in a file. There are three options files that can be used with pppd: the /etc/ppp/options file, which is used to set systemwide pppd options; the ~/.ppprc file, which is used by an individual to set personal pppd options; and the /etc/ppp/options.device file, which sets options for a serial device, e.g., /etc/ppp/options.cua0 sets options for cua0. The order of precedence for options is that those specified in the /etc/ppp/options.device file are the highest priority, followed by those defined on the command line, then those in the ~/.ppprc file, and, finally, those defined in the /etc/ppp/options file. Some options that relate to system security, once defined in the /etc/ppp/options file, cannot be overridden by the user through the command line or the ~/.ppprc file. The system administrator can override any option set by the user by setting the option in the /etc/ppp/options.device file.

The following list contains all of the pppd options except those that do not relate to TCP/IP:

local_IP_address: remote_IP_address

Defines static local and remote IP addresses. Either address may be omitted. For example, 172.16.25.3: defines only the local address, while :172.16.25.12 defines only the remote address. The default local address is the IP address associated with the local system's hostname.

active-filter filter-expression

Defines a packet filter that determines which packets are regarded as link activity. Packets that pass through the filter reset the idle timer or cause the link to initialize when it is in demand-dial mode. The kernel and pppd must be compiled with PPP_FILTER defined.

allow-ip address

Systems using the specified IP address, which can identify individual hosts or entire networks, do not need to be authenticated.

asyncmap map

Defines the ASCII control characters that must be sent as two-character escape sequences. The first 32 ASCII characters are control characters. map is a 32-bit hex number with each bit representing a control character. Bit 0 (00000001) represents the character 0x00; bit 31 (80000000) represents the character 0x1f. If a bit is on in map, the character represented by that bit must be sent as an escape sequence. If no asyncmap option is specified, all control characters are sent as escape sequences.

auth

Requires the use of an authentication protocol. See Chapter 6 for a discussion of the authentication protocols CHAP and PAP.

bsdcomp receive, transmit

Enables the BSD-Compress scheme to compress packets. The maximum code word length used to compress packets accepted by this host is receive bits long. The maximum code word length used to compress packets sent by this host is transmit bits long. Acceptable code word length is 9 to 15 bits. Disable compression when receiving or transmitting by placing a 0 in receive or transmit, respectively.

call name

Reads options from a file named /etc/ppp/peers/name.

cdtrcts

Tells pppd that the modem uses nonstandard hardware flow control based on the DTR and CTS signals.

chap-interval

Tells the system to use the Challenge Handshake Authentication Protocol (CHAP) to reauthenticate the remote system every n seconds.

chap-max-challenge n

Tells the system to send the CHAP challenge to the remote system a maximum of n times until the remote system responds. The default is 10.

chap-restart n

Tells the system to wait n seconds before retransmitting a CHAP challenge when the remote system fails to respond. The default is 3 seconds.

connect script

Invokes a script to create the serial connection. Any scripting language can be used, but chat is the most common. See Chapter 6 for an example of using connect to invoke an inline chat script.

connect-delay n

Waits n milliseconds after the connect script finishes for a valid PPP packet from the remote system.

crtscts

Enables hardware flow control (RTS/CTS).

debug

Logs all control packets sent or received using syslogd with facility daemon and level debug. The debug option can also be written as -d.

default-asyncmap

Disables asyncmap negotiation, forcing all control characters to be escaped.

default-mru

Disables Maximum Receive Unit negotiation and uses a default MRU of 1500 bytes.

defaultroute

Defines the PPP link as the default route. The route is removed when the connection is closed.

deflate nr, nt

Tells pppd to request Deflate packet compression. nr is the maximum receive window size expressed as a power of 2; i.e., if nr is 8, the receive window is 2 to the 8 (or 256) bytes. nt defines the maximum transmit window size expressed as a power of 2. If nt is not specified, it defaults to the value given for nr.

demand

Places the link in dial-on-demand mode. The network connection is made when network traffic is present.

disconnect script

Invokes a script to gracefully shut down the serial connection. Any scripting language can be used, but chat is the most common.

domain name

Defines the name of the local domain. Use this if hostname does not return a fully qualified name for the local system.

escape x,x,...

Specifies characters that should be transmitted as two-character escape sequences. The characters are specified in a comma-separated list of hex numbers. Any character except 0x20 - 0x3f and 0x5e can be escaped.

endpoint epdisc

Defines the endpoint discriminator sent to the remote system during multilink negotiation. The default endpoint discriminator is the MAC address of the first Ethernet interface or, if no Ethernet is found, the system's IP address. epdisc is defined in the form type:value, where type is one of the keywords local, IP, MAC, magic, or phone, and value is either an IP address in dotted-decimal notation for the IP type, the name of an Ethernet interface for the MAC type, or a string of colon-separated hexadecimal bytes for the other types. Multilink is available only on Linux systems.

file file

Defines another options file, where file is the name of the new file. Options are normally read for /etc/ppp/options, ~/.ppprc, the command line, and /etc/ppp/options.device. See the description of these files earlier in this section.

hide-password

Hides the password string when logging the contents of Password Authentication Protocol (PAP) packets.

holdoff n

Waits n seconds before restarting the link after the link terminates.

idle n

Disconnects the link if no data packets are sent or received for n seconds.

init script

Executes script to initialize the serial line.

ipcp-accept-local

Tells the system to use the local IP address provided by the remote server even if it is defined locally.

ipcp-accept-remote

Tells the system to use the remote IP address provided by the remote server even if it is defined locally.

ipcp-max-configure n

Tells the system to send the IPCP configure-request packet a maximum of n times. The default is 10.

ipcp-max-failure n

Tells the system to accept up to n IPCP configure-NAKs before sending a configure-reject. The default is 10.

ipcp-max-terminate n

Tells the system to send no more than n IPCP terminate-request packets without receiving an acknowledgment. The default is 3.

ipcp-restart n

Tells the system to wait n seconds before resending an IPCP configure-request packet. The default is 3.

ipparam string

Passes string to the ip-up and ip-down scripts. /etc/ppp/ip-up is a shell script executed by pppd when the link comes up. /etc/ppp/ip-down is a shell script executed by pppd when the link is brought down.

ipv6 local_interface_identifier, remote_interface_identifier

Sets the local and remote 64-bit interface identifier using standard IPv6 ASCII address notation. If no identifiers are defined, the system creates a random identifier. (See also the ipv6cp-use-ipaddr and the ipv6cp-use-persistent options.)

ipv6cp-max-configure n

Send a maximum of n IPv6CP configure-request packets. The default is 10.

ipv6cp-max-failure n

Accept a maximum of n IPv6CP configure-NAK packets. The default is 10.

ipv6cp-max-terminate n

Send a maximum of n IPv6CP terminate-request packets. The default is 3.

ipv6cp-restart n

Wait n seconds before resending an IPv6CP configure-request packet. The default is 3 seconds.

ipv6cp-use-ipaddr

Use the system's IPv4 address as the IPv6 local interface identifier.

ipv6cp-use-persistent

Use the system's unique persistent identifier as the IPv6 local interface identifier. Most systems do not support persistent identifiers.

kdebug n

Enables kernel-level debugging. n is 1 to print general debugging messages, 2 to print received packets, and 4 to print transmitted packets.

ktune

Tells the system to allow pppd to alter kernel settings. For example, on a Linux system, pppd could enable IP forwarding by setting /proc/sys/net/ipv4/ip_forward to 1 if allowed to do so.

lcp-echo-failure n

Tells the system to terminate the connection if no reply is received to n LCP echo-requests. Normally, echo-requests are not used for this purpose because "link down" conditions are determined by the modem hardware.

lcp-echo-interval n

Tells the system to wait n seconds before sending another LCP echo-request when the remote system fails to reply.

lcp-max-configure n

Tells the system to send the LCP configure-request packet a maximum of n times. The default is 10.

lcp-max-failure n

Tells the system to accept up to n LCP configure-NAKs before sending a configure-reject. The default is 10.

lcp-max-terminate n

Tells the system to send no more than n LCP terminate-request transmissions without receiving an acknowledgment. The default is 3.

lcp-restart n

Tells the system to wait n seconds before resending an LCP configure-request packet. The default is 3.

linkname name

Sets the logical name of the link to name. pppd writes its process ID into a file named ppp-name.pid in either /var/run or /etc/ppp. This maps each instantiation of pppd to a specific link.

local

Tells the system to ignore the DCD (Data Carrier Detect) and DTR (Data Terminal Ready) modem control lines.

lock

Tells the system to use a UUCP-style lock file to ensure that pppd has exclusive access to the serial device.

logfd n

Logs messages to file descriptor n.

logfile filename

Appends messages to the log file identified by filename.

login

Tells the system to use the /etc/passwd file to authenticate PAP users. Records the login in the wtmp file.

maxconnect n

Sets the maximum connection time to n seconds. After n seconds, the connection is terminated even if it is active.

maxfail n

Stop attempting to connect to the remote system after n consecutive connection attempt failures. The default value is 10 attempts.

modem

Tells the system to use the DCD (Data Carrier Detect) and DTR (Data Terminal Ready) modem control lines; wait for the DCD signal before opening the serial device; and drop the DTR signal when terminating a connection.

mp

This is an alias for the multilink option. See multilink.

mpshortseq

Use short, 12-bit sequence numbers in multilink headers instead of the standard 24-bit sequence numbers.

mrru n

Sets the Maximum Reconstructed Receive Unit (MRRU) to n bytes. The MRRU is the maximum packet size that can be received on a multilink bundle. The value is analogous to MRU on other media.

mru n

Sets the Maximum Receive Unit (MRU) to n bytes. MRU is used to tell the remote system the maximum packet size the local system can accept. The minimum is 128. The default is 1500.

ms-dns address

Supplies Domain Name System addresses to Microsoft Windows clients.

ms-wins address

Supplies Windows Internet Name Services (WINS) server addresses to Microsoft Windows clients.

mtu n

Sets the Maximum Transmission Unit (MTU) to n bytes. MTU defines the maximum length of a packet that can be sent. The smaller of the local MTU and the remote MRU is used to define the maximum packet length.

multilink

Enables the multilink protocol, which allows multiple physical connections to be bundled together as one logical link. This is used to increase the bandwidth to a remote system. For example, two modem connections to a single remote system could be viewed as a single multilink bundle to give twice the bandwidth of one modem connection. This option is currently available only with Linux.

name name

Tells the system to use name as the name of the local system for authentication purposes.

netmask mask

Defines the subnet mask.

noaccomp

Disables Address/Control compression negotiation.

noauth

Allows unauthenticated access.

nobsdcomp

Disables BSD-Compress compression.

noccp

Disables Compression Control Protocol (CCP) negotiation.

nocrtscts

Disables all types of hardware flow control.

nodtrcts

Disables all types of hardware flow control.

nodefaultroute

Prevents users from creating a default route using the defaultroute option.

nodeflate

Disables Deflate compression.

nodetach

Prevents pppd from running as a background process. See the example in Chapter 6.

noendpoint

Tells the system not to send or accept Multilink endpoint discriminators.

noip

Disables the IPCP and IP protocols.

noipv6

Disables IPv6CP negotiation and IPv6 communication.

noipdefault

Instructs the system not to use hostname to determine the local IP address. The address must be obtained from the remote system or explicitly set by an option.

noktune

Prevents pppd from changing kernel values.

nolog

Disables logging.

nomagic

Disables magic number negotiation.

nomp

Disables the multilink protocol.

nompshortseq

Disables the use of short, 12-bit sequence numbers in the multilink protocol.

nomultilink

Disables the multilink protocol.

nopcomp

Disables protocol field compression negotiation. By default, protocol field compression is not used. Setting this option means that even if the remote end requests it, it will not be used.

nopersist

Terminates when the connection is made. This is the default.

nopredictor1

Tells the system not to use Predictor-1 compression.

noproxyarp

Disables the proxyarp option, preventing users from creating proxy ARP entries with pppd.

notty

Causes pppd to transmit characters to standard output and receive them on standard input. This option increases latency and overhead.

novj

Disables Van Jacobson header compression.

novjccomp

Disables the connection-ID compression option in Van Jacobson header compression.

papcrypt

Instructs the system not to accept passwords that are identical to those in the /etc/ppp/pap-secrets file because the ones in the file are encrypted. Therefore the transmitted password should not match an entry in the pap-secrets file until it is also encrypted.

pap-max-authreq n

Tells the system to transmit no more than n PAP authenticate-requests if the remote system does not respond. The default is 10.

pap-restart n

Tells the system to wait n seconds before retransmitting a PAP authenticate-request. The default is 3 seconds.

pap-timeout n

Tells the system to wait no more than n seconds for the remote system to authenticate itself. When n is 0, there is no time limit.

pass-filter filter-expression

Defines a packet filter that determines which packets can be sent or received over the PPP link. Packets that do not pass through the filter are silently discarded. filter-expression is defined using the syntax of tcpdump.

passive

Tells the system to wait for a Link Control Protocol (LCP) packet from the remote system even if that system does not reply to the initial LCP packet sent by the local system. Without this option, the local system aborts the connection when it does not receive a reply. The passive option can also be written as -p.

persist

Tells the system to reopen the connection if it was terminated by a SIGHUP signal.

plugin filename

Loads a shared library object as a "plugin" to pppd.

predictor1

Tells the system to ask the remote system to use Predictor-1 compression.

privgroup group-name

Allows all members of the group group-name to use privileged options.

proxyarp

Tells the system to enable proxy ARP. This adds a proxy ARP entry for the remote system to the local system's ARP table.

pty script

Identifies a script that is run as a child process and used as the communications source in lieu of a terminal device. If used in conjunction with the record option, the child process will have pipes on its standard input and output.

receive-all

Tells the system to accept all control characters from the remote system, even those that should be discarded according to the standard asyncmap handling defined in RFC 1662.

record filename

Tells the system to log every character sent and received to filename.

remotename name

Tells the system to use name as the remote system's name for authentication purposes.

refuse-chap

Disables the use of CHAP. This is a bad idea.

refuse-pap

Disables the use of PAP.

require-chap

Requires the use of CHAP.

require-pap

Requires the use of PAP.

show-password

Shows the password when PAP packets are logged.

silent

Tells the system to wait for an LCP packet from the remote system. Do not send the first LCP packet.

sync

Tells the system to use synchronous HDLC physical layer protocols instead of the default asynchronous protocol.

updetach

Tells the system to detach from the controlling terminal after the connection is made.

usehostname

Disables the name option, forcing the local hostname to be used for authentication purposes.

usepeerdns

Asks the remote system to provide up to two DNS server addresses. The provided addresses are passed up to the /etc/ppp/ip-up script in the environment variables DNS1 and DNS2. Additionally, pppd uses the addresses to create nameserver lines in a file named /etc/ppp/resolv.conf.

user username

Tells the system to use username for PAP authentication when challenged by a remote host.

vj-max-slots n

Tells the system to use n connection slots for Van Jacobson header compression. n must be a number from 2 to 16.

welcome script

Execute script before initiating PPP negotiation.

xonxoff

Enables software flow control (XON/XOFF).

Several of the options listed above concern PPP security. One of the strengths of PPP is its security. The Challenge Handshake Authentication Protocol (CHAP) is the preferred PPP security protocol. The Password Authentication Protocol (PAP) is less secure and is only provided for compatibility with less capable systems. The usernames, IP addresses, and secret keys used for these protocols are defined in the /etc/ppp/chap-secrets file and the /etc/ppp/pap-secrets file. Chapter 6 shows the format of these files and describes their use.

It is very important that the directory /etc/ppp and its contents not be world- or group-writable. Modifications to the chap-secrets, pap-secrets, or options files could compromise system security. In addition, the script files /etc/ppp/ip-up and /etc/ppp/ip-down may run with root privilege. If pppd finds a file with the name ip-up in the /etc/ppp directory, it executes it as soon as the PPP connection is established. The ip-up script is used to modify the routing table, process the sendmail queue, or do other tasks that depend on the presence of the network connection. The ip-down script is executed by pppd after the PPP connection is closed and is used to terminate processes that depend on the link. Clearly these scripts and the /etc/ppp directory must be protected.

A.2.1 Signal Processing

pppd handles the following signals:

SIGUSR1

This signal toggles debugging on or off. The first SIGUSR1 signal received by pppd turns on debugging and begins logging diagnostic messages through syslogd with facility set to daemon and level set to debug. The second SIGUSR1 signal turns off debugging and closes the log file. See the debug option described previously.

SIGUSR2

This signal causes pppd to renegotiate compression. It has limited applicability because it is needed only to restart compression after a fatal error has occurred. Most people close the PPP connection and open a new one after a fatal error.

SIGHUP

This signal closes the PPP connection, returns the serial device to its normal operating mode, and terminates pppd. If the persist option is specified, pppd opens a new connection instead of terminating.

SIGINT

This signal, or the SIGTERM signal, closes the PPP connection, returns the serial device to its normal operating mode, and terminates pppd. The persist option has no effect.