     START-INFO-DIR-ENTRY
     * PPP: (ppp).                   Point-to-Point Protocol.
     END-INFO-DIR-ENTRY

This file documents how to use the ppp-2.x package to set up network links over serial lines with the Point-to-Point Protocol.

Introduction
************

The Point-to-Point Protocol (PPP) is the protocol of choice for establishing network links over serial lines.  This package (ppp-2.x) provides an implementation of PPP which supports the Internet Protocols (TCP/IP, UDP/IP, etc.) and which runs on a range of Unix workstations.

A typical use of PPP is to provide a network connection, via a modem, between a workstation and an Internet Service Provider (ISP).  When this connection is established, the workstation is connected to the internet, and applications running on the workstation can then make connections to other hosts anywhere on the internet.  This package can be used at either or both ends of such a link.

Features of PPP include:

  * Multi-protocol support.  The PPP packet encapsulation includes a protocol field, allowing packets from many different protocols to be multiplexed across a single link.

  * Negotiation of link characteristics.  During link establishment, the two systems negotiate about the link configuration parameters, such as the IP addresses of each end of the link.

  * Authentication.  Optionally, each system can be configured to require the other system to authenticate itself.  In this way, access can be restricted to authorized systems.

  * Transparency.  On asynchronous serial lines, PPP can be configured to transmit certain characters as a two-character escape sequence.

  * Compression.  PPP includes support for various kinds of compression to be applied to the packets before they are transmitted.

The ppp-2.x software consists of two parts:

  * Kernel code, which establishes a network interface and passes packets between the serial port, the kernel networking code and the PPP daemon (pppd).  This code is implemented using STREAMS modules on Solaris 2, SunOS 4.x, AIX 4.1 and OSF/1, and as a tty line discipline under Ultrix, NextStep, NetBSD, FreeBSD, and Linux.

  * The PPP daemon (pppd), which negotiates with the peer to establish the link and sets up the ppp network interface.  Pppd includes support for authentication.  It can authenticate itself to the other system and/or require the other system to authenticate itself, so that you can control which other systems may make a PPP connection and what IP addresses they may use.

PPP Concepts
============

To use PPP to provide a network connection between two machines, there must be some way that a stream of bytes, or characters, can be passed from one to the other, in both directions independently.  We refer to this as the ``serial link''.  Very often the serial link involves asynchronous communications ports and modems, but other kinds of serial link are possible.

The serial link must transmit (at least) 8 bits per character; PPP cannot work over a serial link which transmits only 7 bits per character.  However, it need not transmit all byte values transparently. PPP has a mechanism to avoid sending certain characters if it is known that the some element of the serial link interprets them specially.  For example, the DC1 and DC3 ASCII characters (control-Q and control-S) may be trapped by a modem if it is set for ``software'' flow control.  PPP can send these characters as a two-character ``escape'' sequence.  The set of characters which are to be transmitted as an escape sequence is represented in an ``async control character map'' (ACCM).  The ``async'' part refers to the fact that this facility is used for asynchronous serial links.  For synchronous serial connections, the HDLC bit-stuffing procedure is used instead.

The two systems connected by the serial link are called ``peers''.  When we are talking from the point of view of one of the systems, the other is often referred to as ``the peer''.  Sometimes we may refer to one system as a ``client'' and the other as a ``server''.  This distinction refers mainly to the way the serial link is set up; usually the client is the peer that initiates the connection, for example by dialling the server with its modem.

During the lifetime of a PPP connection, it proceeds through several phases:

 1. Serial link establishment.  In this phase, the serial link is set up and PPP protocol software is attached to each end of the serial link.  The precise steps involved in doing this vary greatly, depending on the nature of the serial link.  For the common case of modems connected through the telephone network, this involves first sending commands to the modem to cause it to dial the remote system.  When the remote system answers, the local system usually has to supply a username and password, and then issue a command to invoke PPP software on the remote system. The ``chat'' program supplied with ppp-2.x provides a way to automate a dialog with the modem and the remote system.  This phase is not standardized; it is outside the scope of the PPP protocol specifications.

 2. Link Control Protocol (LCP) negotiation.  In this phase, the peers send LCP packets to each other to negotiate various parameters of the connection, such as the ACCM to be used in each direction, whether authentication is required, and whether or not to use various forms of compression.  When the peers reach agreement on these parameters, LCP is said to be ``up''.

 3. Authentication.  If one (or both) of the peers requires the other peer to authenticate itself, that occurs next.  If one of the peers cannot successfully authenticate itself, the other peer terminates the link.

 4. Network Control Protocol (NCP) negotiation.  PPP can potentially support several different network protocols, although IP is the only network protocol (NP) supported by the ppp-2.x package.  Each NP has an associated NCP defined for it, which is used to negotiate the specific parameters which affect that NP.  For example, the IP Control Protocol (IPCP) is used to negotiate the IP addresses for each end of the link, and whether the TCP header compression method described by Van Jacobsen in RFC 1144 (``VJ compression'') is to be used.

 5. Network communication.  When each NCP has successfully negotiated the parameters for its NP, that NCP is said to be ``up''.  At that point, the PPP link is made available for data traffic from that NP.  For example, when IPCP comes up, the PPP link is then available for carrying IP packets (which of course includes packets from those protocols which are layered above IP, such as TCP, UDP, etc.)

 6. Termination.  When the link is no longer required, it is terminated. Usually this involves an exchange of LCP packets so that one peer can notify the other that it is shutting down the link, enabling both peers to shut down in an orderly manner.  But of course there are occasions when the link terminates because the serial link is interrupted, for example, when a modem loses carrier and hangs up.

The protocols in the PPP family are produced by the Point-to-Point Working Group of the Internet Engineering Task Force, and are specified in RFC (Request for Comments) documents, available by anonymous FTP from several sites.

PPP is defined in several RFCs, in particular RFCs 1661, 1662, and 1334.  IPCP is defined in RFC 1332. Other RFCs describe the control protocols for other network protocols (e.g., DECnet, OSI, Appletalk).  RFCs are available by anonymous FTP from several sites including nic.ddn.mil, nnsc.nsf.net, nic.nordu.net, ftp.nisc.sri.com, and munnari.oz.au.

PPP packet format
=================

PPP transmits packets over the serial link using a simple encapsulation scheme.  First, a two-byte PPP Protocol field is inserted before the data to be sent.  The value in this field identifies which higher-level protocol (either a network protocol such as IP or a PPP control protocol such as LCP) should receive the data in the packet. By default, a one-byte Address field with the value 0xFF, and a one-byte Control field with the value 0x03, are inserted before the PPP Protocol field (apparently this is supposed to provide compatibility with HDLC, in case there is a synchronous to asynchronous converter in the serial link).

On slow serial links, these fields can be compressed down to one byte in most cases.  The PPP Address and Control fields are compressed by simply omitting them (``address/control compression'').  The PPP Protocol field values are chosen so that bit 0 (the least-significant bit) of the first (most significant) byte is always 0, and bit 0 of the second byte is always 1.  The PPP Protocol field can be compressed by omitting the first byte, provided that it is 0 (``protocol compression'').  The values for this field are assigned so that the first byte is zero for all of the commonly-used network protocols.  For example, the PPP Protocol field value for IP is 0x21.

For asynchronous serial links, which do not provide any packet framing or transparency, a further encapsulation is used as follows.  First a 16-bit Frame Check Sequence (FCS) is computed over the packet to be sent, and appended as two bytes to the end of the packet.

Then each byte of the packet is examined, and if it contains one of the characters which are to be escaped, it is replaced by a two byte sequence: the 0x7d character '', followed by the character with bit 5 inverted.  For example, the control-C character (0x03) could be replaced by the two-byte sequence 0x7d, 0x23 ('#').  The 0x7d and 0x7e ('~') characters are always escaped, and the 0x5e ('^') character may not be escaped.

Finally, a ``flag'' character (0x7e, '~') is inserted at the beginning and end of the packet to mark the packet boundaries.  The initial flag may be omitted if this packet immediately follows another packet, as the ending flag for the previous packet can serve as the beginning flag of this packet.

LCP negotiation
===============

The LCP negotiation process actually involves two sets of negotiations, one for each direction of the PPP connection.  Thus A will send B packets (``Configure-Requests'') describing what characteristics A would like to have apply to the B -> A direction of the link, that is, to the packets that A will receive.  Similarly B will send A packets describing the characteristics it would like to have apply to the packets it will be receiving.  These characteristics need not necessarily be the same in both directions.

The parameters which are negotiated for each direction of the connection using LCP are:

  * Maximum Receive Unit (MRU): indicates the maximum packet size which we are prepared to receive (specifically the maximum size of the data portion of the packet).  The default value is 1500, but on slow serial links, smaller values give better response.  The choice of MRU is discussed below (see xxx).

  * Async Control Character Map (ACCM): indicates the set of control characters (characters with ASCII values in the range 0 - 31) which we wish to receive in escaped form.  The default is that the sender should escape all characters in the range 0 - 31.

  * Authentication Protocol: indicates which protocol we would like the peer to use to authenticate itself.  Common choices are the Password Authentication Protocol (PAP) and the Cryptographic Handshake Authentication Protocol (CHAP).

  * Quality Protocol: indicates which protocol which we would like the peer to use to send us link quality reports.  The ppp-2.x package does not currently support link quality reports.

  * Magic Number: a randomly-chosen number, different from the peer's magic number.  If we persistently receive our own magic number in the peer's configure-request packets, then we can conclude that the serial link is looped back.

  * Protocol Field Compression: indicates that we wish the peer to compress the PPP Protocol field to one byte, where possible, in the packets it sends.

  * Address/Control Field Compression: indicates that we wish the peer to compress the PPP Address/Control fields (by simply omitting them) in the packets it sends.

IPCP negotiation
================

The IPCP negotiation process is very similar to the LCP negotiation process, except that of course different parameters are negotiated. The parameters which are negotiated using IPCP are:

  * IP Address: the IP address (32-bit host IP number) which we plan to use as the local address for our end of the link.

  * TCP header compression: indicates (a) that we wish the peer to compress the TCP/IP headers of TCP/IP packets that it sends, using the Van Jacobson algorithm as described in RFC1144; (b) the maximum slot ID that we wish the peer to use, and (c) whether we are prepared to accept packets with the slot ID field compressed (omitted).

     With Van Jacobson (VJ) compression, the receiver and transmitter (for one direction of the connection) both keep a table, with a certain number of ``slots'', where each slot holds the TCP/IP header of the most recently transmitted packet for one TCP connection.  If a packet is to be transmitted for a TCP connection which does not have a slot currently allocated, the VJ scheme will allocate one of the slots and send the entire TCP/IP header, together with the slot number.  For many packets, there will be a slot already allocated for the TCP connection, and the VJ scheme will then often be able to replace the entire TCP/IP header with a much smaller compressed header (typically only 3 - 7 bytes) describing which fields of the TCP/IP header have changed, and by how much.  If there are many more active connections than slots, the efficiency of the VJ scheme will drop, because it will not be able to send compressed headers as often.

     Usually the compressed header includes a one-byte slot index, indicating which TCP connection the packet is for.  It is possible to reduce the header size by omitting the slot index when the packet has the same slot index as the previous packet.  However, this introduces a danger if the lower levels of the PPP software can sometimes drop damaged packets without informing the VJ decompressor, as it may then assume the wrong slot index for packets which have the slot index field omitted.  With the ppp-2.x software, however, the probability of this happening is generally very small (see xxx).

Installation
************

Because ppp-2.x includes code which must be incorporated into the kernel, its installation process is necessarily quite heavily system-dependent.  In addition, you will require super-user privileges (root access) to install the code.

Some systems provide a ``modload'' facility, which allows you to load new code into a running kernel without relinking the kernel or rebooting.  Under Solaris 2, SunOS 4.x, Linux, OSF/1 and NextStep, this is the recommended (or only) way to install the kernel portion of the ppp-2.x package.

Under the remaining supported operating systems (NetBSD, FreeBSD, Ultrix), it is necessary to go through the process of creating a new kernel image and reboot.  (Note that NetBSD and FreeBSD have a modload facility, but ppp-2.x is currently not configured to take advantage of it.)

Detailed installation instructions for each operating system are contained in the README files in the ppp-2.x distribution.  In general, the process involves executing the commands ./configure, make and (as root) make install in the ppp-2.x distribution directory.  (The Linux port requires the installation of some header files before compiling; see README.linux for details.)

Configuration
*************

Once the ppp-2.x software is installed, you need to configure your system for the particular PPP connections you wish to allow.  Typically, the elements you need to configure are:

  * How the serial link is established and how pppd gets invoked.

  * Setting up syslog to log messages from pppd to the console and/or system log files.

  * Pppd options to be used.

  * Authentication secrets to use in authenticating us to the peer and/or the peer to us.

  * The IP addresses for each end of the link.

In most cases, the system you are configuring will either be a client system, actively initiating a PPP connection on user request, or it will be a server system, passively waiting for connections from client systems.  Other arrangements are possible, but the instructions in this system assume that you are configuring either a client or a server.

These instructions also assume that the serial link involves a serial communications port (that is, a tty device), since pppd requires a serial port.

Client machines
===============

On a client machine, the way that the user requests that a connection be established is by running pppd, either directly or through a shell script.  Pppd should be given the name of the serial port to use as an option.  In this mode, pppd will fork and detach itself from its controlling terminal, so that the shell will return to its prompt.  (If this behaviour is not desired, use the -detach option.)

Usually, the connect option should also be used.  The connect option takes an argument which is a command to run to establish the serial link and invoke PPP software on the remote machine.  This command is run with its standard input and standard output connected to the serial port. Giving the connect option to pppd also has the side-effect of causing pppd to open the serial port without waiting for the modem carrier detect signal.

The process of establishing the serial link often involves a dialog.  If the serial port is connected to a modem, we first need to send some commands to the modem to configure it and dial the remote system.  Often there is then a dialog with the remote system to supply a username and password.  The chat program supplied with the ppp-2.x package is useful for automating such dialogs.  Chat uses a script consisting of alternately strings to expect to receive on the serial port, and strings to send on the serial port.  The script can also specify strings which indicate an error and abort the dialog.

Server machines
===============

There are generally three ways in which a server machine can be set up to allow client machines to establish a PPP link:

 1. Client machines log in as regular users (often via a serial port connected to a modem, but possibly through a telnet or rlogin session) and then run pppd as a shell command.

 2. Client machines log in using a username whose login shell is pppd or a script which runs pppd.

 3. Client machines connect to a serial port which has a pppd running permanently on it (instead of a "getty" or other program providing a login service).

Method 1 is very simple to set up, and is useful where existing users of a system have remote machines (for example at home) from which they want to establish a PPP connection from time to time.  Methods 2 and 3 possibly have a security advantage in that they do not allow PPP client systems access to a shell.  Method 2 allows regular logins and PPP connections on the same port, while with method 3, would-be crackers may well be frustrated (unless they speak fluent PPP).

With any of these methods, I strongly recommend that you configure PPP to require authentication from the client, by including the `auth' option in the /etc/ppp/options file.

Setting up syslog
=================

Pppd uses the syslog facility to report information about the state of the connection, as does chat.  It is useful to set up syslog to print some of these messages on the console, and to record most of them to a file.  The messages from pppd are logged with facility daemon and one of three levels:

  * notice for messages about important events such as the connection becoming available for IP traffic and the local and remote IP addresses in use.

  * info for messages about less important events, such as detecting a modem hangup.

  * debug for messages which are of use in working out why the connection is not working properly.

The messages from chat are logged with facility local2 and level debug.

Syslog is controlled by the syslog configuration file /etc/syslog.conf.  Generally the standard configuration will log facility daemon messages with level notice and above to a system log file such as /var/log/syslog (the name may vary on different systems).  I find it useful to have the notice level messages from pppd displayed on the console, and all messages from pppd and chat logged to a file such as /etc/ppp/log.  To achieve this, find the line in /etc/syslog.conf which has /dev/console on the right-hand side, and add `daemon.notice' on the left.  This line should end up something like this:

     *.err;kern.debug;auth.notice;mail.crit;daemon.notice    /dev/console

And add a line like this:

     daemon,local2.debug                                     /etc/ppp/log

The space between the left and right hand sides is one or more tabs, not spaces, and there are no tabs or spaces at the beginning of the line.

You will need to create an empty /etc/ppp/log file; syslogd will not create it.  Once you have modified /etc/syslog.conf, you need to either reboot or notify syslogd to re-read the file.  On most systems, you notify syslogd by sending it a SIGHUP signal.  Syslogd's process ID is usually stored in a file such as /etc/syslogd.pid or /var/run/syslog.pid.  Thus you can notify syslogd to re-read the file by executing a command such as:

     kill -HUP `cat /etc/syslogd.pid`

Pppd options
============

Authentication secrets files
============================

IP Addresses
============

Security
********

Compression
***********