add demand.o
[ppp.git] / ppp.texi
1 \input texinfo @c -*-texinfo-*-
2 @setfilename ppp.info
3 @settitle PPP
4
5 @iftex
6 @finalout
7 @end iftex
8
9 @ifinfo
10 @format
11 START-INFO-DIR-ENTRY
12 * PPP: (ppp).                   Point-to-Point Protocol.
13 END-INFO-DIR-ENTRY
14 @end format
15
16 @titlepage
17 @title PPP-2.x Users' Guide
18 @author by Paul Mackerras
19 @end titlepage
20
21 @node Top, Introduction, (dir), (dir)
22
23 @ifinfo
24 This file documents how to use the ppp-2.x package to set up network
25 links over serial lines with the Point-to-Point Protocol.
26
27 @end ifinfo
28
29 @menu
30 * Introduction::                Basic concepts of the Point-to-Point
31                                 Protocol and the ppp-2.x package.
32 * Installation::                How to compile and install the software.
33 * Configuration::               How to set up your system for
34                                 establishing a link to another system.
35 * Security::                    Avoid creating security holes.
36 * Compression::                 Using compression of various kinds
37                                 to improve throughput.
38 @end menu
39
40 @node Introduction, Installation, Top, Top
41 @chapter Introduction
42
43 The Point-to-Point Protocol (PPP) is the protocol of choice for
44 establishing network links over serial lines.  This package (ppp-2.x)
45 provides an implementation of PPP which supports the Internet Protocols
46 (TCP/IP, UDP/IP, etc.) and which runs on a range of Unix workstations.
47 The protocols in the PPP family are produced by the Point-to-Point
48 Working Group of the Internet Engineering Task Force, and are specified
49 in RFC (Request for Comments) documents, available by anonymous FTP from
50 several sites.
51
52 A typical use of PPP is to provide a network connection, via a pair of
53 modems and a telephone connection, from one system to a second system
54 which has a permanent link to the Internet.  When this network
55 connection is established, the first system is then also connected to
56 the Internet.  It can establish connections with any other Internet
57 host.  Users can then use a wide range of network-based applications on
58 the first system, such as telnet, ftp, rlogin, email, WWW browsers, sup,
59 or X clients and servers.
60
61 Features of PPP include:
62 @itemize @bullet
63 @item
64 Multi-protocol support.  The PPP packet encapsulation includes a
65 protocol field, allowing packets from many different protocols to be
66 multiplexed across a single link.
67 @item
68 Negotiation of link characteristics.  During link establishment, the two
69 systems negotiate about the link configuration parameters, such as the
70 IP addresses of each end of the link.
71 @item
72 Authentication.  Optionally, each system can be configured to require the
73 other system to authenticate itself.  In this way, access can be
74 restricted to authorized systems.
75 @item
76 Transparency.  On asynchronous serial lines, PPP can be configured to
77 transmit certain characters as a two-character escape sequence.
78 @item
79 Compression.  PPP includes support for various kinds of compression to
80 be applied to the packets before they are transmitted.
81 @end itemize
82
83 The ppp-2.x software consists of two parts:
84
85 @itemize @bullet
86
87 @item
88 Kernel code, which establishes a network interface and passes packets
89 between the serial port, the kernel networking code and the PPP daemon
90 (@file{pppd}).  This code is implemented using STREAMS modules on
91 Solaris 2, SunOS 4.x, AIX 4.1 and OSF/1, and as a tty line discipline
92 under Ultrix, NextStep, NetBSD, FreeBSD, and Linux.
93
94 @item
95 The PPP daemon (@file{pppd}), which negotiates with the peer to
96 establish the link and sets up the ppp network interface.  Pppd includes
97 support for authentication.  It can authenticate itself to the other
98 system and/or require the other system to authenticate itself, so that
99 you can control which other systems may make a PPP connection and what
100 IP addresses they may use.
101 @end itemize
102
103 @menu
104 * PPP Concepts::                Basic concepts and terms used with PPP.
105 * PPP packet format::           How data is packaged up for transmission.
106 * LCP negotiation::             The parameters which are negotiated
107                                 using the Link Control Protocol.
108 * IPCP negotiation::            The parameters which are negotiated
109                                 using the IP Control Protocol.
110 @end menu
111
112 @node PPP Concepts, PPP packet format, Introduction, Introduction
113 @section PPP Concepts
114
115 To use PPP to provide a network connection between two machines, there
116 must be some way that a stream of bytes, or characters, can be passed
117 from one to the other, in both directions independently.  We refer to
118 this as the ``serial link''.  Very often the serial link involves
119 asynchronous communications ports and modems, but other kinds of serial
120 link are possible.
121
122 The serial link must transmit (at least) 8 bits per character; PPP
123 cannot work over a serial link which transmits only 7 bits per
124 character.  However, it need not transmit all byte values transparently. 
125 PPP has a mechanism to avoid sending certain characters if it is known
126 that the some element of the serial link interprets them specially.  For
127 example, the DC1 and DC3 ASCII characters (control-Q and control-S) may
128 be trapped by a modem if it is set for ``software'' flow control.  PPP
129 can send these characters as a two-character ``escape'' sequence.  The
130 set of characters which are to be transmitted as an escape sequence is
131 represented in an ``async control character map'' (ACCM).  The ``async''
132 part refers to the fact that this facility is used for asynchronous
133 serial links.  For synchronous serial connections, the HDLC bit-stuffing
134 procedure is used instead.
135
136 The two systems connected by the serial link are called ``peers''.  When
137 we are talking from the point of view of one of the systems, the other
138 is often referred to as ``the peer''.  Sometimes we may refer to one
139 system as a ``client'' and the other as a ``server''.  This distinction
140 refers mainly to the way the serial link is set up; usually the client
141 is the peer that initiates the connection, for example by dialling the
142 server with its modem.
143
144 During the lifetime of a PPP connection, it proceeds through several
145 phases:
146
147 @enumerate
148 @item
149 Serial link establishment.  In this phase, the serial link is set up and
150 PPP protocol software is attached to each end of the serial link.  The
151 precise steps involved in doing this vary greatly, depending on the
152 nature of the serial link.  For the common case of modems connected
153 through the telephone network, this involves first sending commands to
154 the modem to cause it to dial the remote system.  When the remote system
155 answers, the local system usually has to supply a username and password,
156 and then issue a command to invoke PPP software on the remote system.
157 The ``chat'' program supplied with ppp-2.x provides a way to automate a
158 dialog with the modem and the remote system.  This phase is not
159 standardized; it is outside the scope of the PPP protocol
160 specifications.
161
162 @item
163 Link Control Protocol (LCP) negotiation.  In this phase, the peers send
164 LCP packets to each other to negotiate various parameters of the
165 connection, such as the ACCM to be used in each direction, whether
166 authentication is required, and whether or not to use various forms of
167 compression.  When the peers reach agreement on these parameters, LCP is
168 said to be ``up''.
169
170 @item
171 Authentication.  If one (or both) of the peers requires the other
172 peer to authenticate itself, that occurs next.  If one of the peers
173 cannot successfully authenticate itself, the other peer terminates the
174 link.
175
176 @item
177 Network Control Protocol (NCP) negotiation.  PPP can potentially support
178 several different network protocols, although IP is the only network
179 protocol (NP) supported by the ppp-2.x package.  Each NP has an
180 associated NCP defined for it, which is used to negotiate the specific
181 parameters which affect that NP.  For example, the IP Control Protocol
182 (IPCP) is used to negotiate the IP addresses for each end of the link,
183 and whether the TCP header compression method described by Van Jacobsen
184 in RFC 1144 (``VJ compression'') is to be used.
185
186 @item
187 Network communication.  When each NCP has successfully negotiated the
188 parameters for its NP, that NCP is said to be ``up''.  At that point,
189 the PPP link is made available for data traffic from that NP.  For
190 example, when IPCP comes up, the PPP link is then available for carrying
191 IP packets (which of course includes packets from those protocols which
192 are layered above IP, such as TCP, UDP, etc.)
193
194 @item
195 Termination.  When the link is no longer required, it is terminated.
196 Usually this involves an exchange of LCP packets so that one peer can
197 notify the other that it is shutting down the link, enabling both peers
198 to shut down in an orderly manner.  But of course there are occasions
199 when the link terminates because the serial link is interrupted, for
200 example, when a modem loses carrier and hangs up.
201
202 @end enumerate
203
204 PPP is defined in several RFC (Request For Comments) documents, in
205 particular RFCs 1661, 1662, and 1334.  IPCP is defined in RFC 1332.
206 Other RFCs describe the control protocols for other network protocols
207 (e.g., DECnet, OSI, Appletalk).  RFCs are available by anonymous FTP
208 from several sites including nic.ddn.mil, nnsc.nsf.net, nic.nordu.net,
209 ftp.nisc.sri.com, and munnari.oz.au.
210
211 @node PPP packet format, LCP negotiation, PPP Concepts, Introduction
212 @section PPP packet format
213
214 PPP transmits packets over the serial link using a simple encapsulation
215 scheme.  First, a two-byte PPP Protocol field is inserted before the
216 data to be sent.  The value in this field identifies
217 which higher-level protocol (either a network protocol such as IP or a
218 PPP control protocol such as LCP) should receive the data in the packet.
219 By default, a one-byte Address field with the value 0xFF, and a one-byte
220 Control field with the value 0x03, are inserted before the PPP Protocol
221 field (apparently this is supposed to provide compatibility with HDLC,
222 in case there is a synchronous to asynchronous converter in the serial
223 link).
224
225 On slow serial links, these fields can be compressed down to one byte in
226 most cases.  The PPP Address and Control fields are compressed by simply
227 omitting them (``address/control compression'').  The PPP Protocol field
228 values are chosen so that bit 0 (the least-significant bit) of the first
229 (most significant) byte is always 0, and bit 0 of the second byte is
230 always 1.  The PPP Protocol field can be compressed by omitting the
231 first byte, provided that it is 0 (``protocol compression'').  The
232 values for this field are assigned so that the first byte is zero for
233 all of the commonly-used network protocols.  For example, the PPP
234 Protocol field value for IP is 0x21.
235
236 For asynchronous serial links, which do not provide any packet framing
237 or transparency, a further encapsulation is used as follows.  First a
238 16-bit Frame Check Sequence (FCS) is computed over the packet to be
239 sent, and appended as two bytes to the end of the packet.
240
241 Then each byte of the packet is examined, and if it contains one of the
242 characters which are to be escaped, it is replaced by a two byte
243 sequence: the 0x7d character '}', followed by the character with bit 5
244 inverted.  For example, the control-C character (0x03) could be replaced
245 by the two-byte sequence 0x7d, 0x23 ('}#').  The 0x7d and 0x7e ('~')
246 characters are always escaped, and the 0x5e ('^') character may not be
247 escaped.
248
249 Finally, a ``flag'' character (0x7e, '~') is inserted at the beginning
250 and end of the packet to mark the packet boundaries.  The initial flag
251 may be omitted if this packet immediately follows another packet, as the
252 ending flag for the previous packet can serve as the beginning flag of
253 this packet.
254
255 @node LCP negotiation, IPCP negotiation, PPP packet format, Introduction
256 @section LCP negotiation
257
258 The LCP negotiation process actually involves two sets of negotiations,
259 one for each direction of the PPP connection.  Thus A will send B
260 packets (``Configure-Requests'') describing what characteristics A would
261 like to have apply to the B -> A direction of the link, that is, to the
262 packets that A will receive.  Similarly B will send A packets describing
263 the characteristics it would like to have apply to the packets it will
264 be receiving.  These characteristics need not necessarily be the same in
265 both directions.
266
267 The parameters which are negotiated for each direction of the connection
268 using LCP are:
269
270 @itemize @bullet
271 @item
272 Maximum Receive Unit (MRU): indicates the maximum packet size which we
273 are prepared to receive (specifically the maximum size of the
274 data portion of the packet).  The default value is 1500, but on
275 slow serial links, smaller values give better response.  The choice of
276 MRU is discussed below (see xxx).
277
278 @item
279 Async Control Character Map (ACCM): indicates the set of control
280 characters (characters with ASCII values in the range 0 - 31) which we
281 wish to receive in escaped form.  The default is that the sender should
282 escape all characters in the range 0 - 31.
283
284 @item
285 Authentication Protocol: indicates which protocol we would like the peer
286 to use to authenticate itself.  Common choices are the Password
287 Authentication Protocol (PAP) and the Cryptographic Handshake
288 Authentication Protocol (CHAP).
289
290 @item
291 Quality Protocol: indicates which protocol which we would like the peer
292 to use to send us link quality reports.  The ppp-2.x package does not
293 currently support link quality reports.
294
295 @item
296 Magic Number: a randomly-chosen number, different from the peer's magic
297 number.  If we persistently receive our own magic number in the peer's
298 configure-request packets, then we can conclude that the serial link is
299 looped back.
300
301 @item
302 Protocol Field Compression: indicates that we wish the peer to compress
303 the PPP Protocol field to one byte, where possible, in the packets it
304 sends.
305
306 @item
307 Address/Control Field Compression: indicates that we wish the peer to
308 compress the PPP Address/Control fields (by simply omitting them) in the
309 packets it sends.
310 @end itemize
311
312 @node IPCP negotiation,  , LCP negotiation, Introduction
313 @section IPCP negotiation
314
315 The IPCP negotiation process is very similar to the LCP negotiation
316 process, except that of course different parameters are negotiated.
317 The parameters which are negotiated using IPCP are:
318
319 @itemize @bullet
320 @item
321 IP Address: the IP address (32-bit host IP number) which we plan to use
322 as the local address for our end of the link.
323
324 @item
325 TCP header compression: indicates (a) that we wish the peer to compress
326 the TCP/IP headers of TCP/IP packets that it sends, using the Van
327 Jacobson algorithm as described in RFC1144; (b) the maximum slot ID that
328 we wish the peer to use, and (c) whether we are prepared to accept
329 packets with the slot ID field compressed (omitted).
330
331 With Van Jacobson (VJ) compression, the receiver and transmitter (for
332 one direction of the connection) both keep a table, with a certain
333 number of ``slots'', where each slot holds the TCP/IP header of the most
334 recently transmitted packet for one TCP connection.  If a packet is to
335 be transmitted for a TCP connection which does not have a slot currently
336 allocated, the VJ scheme will allocate one of the slots and send the
337 entire TCP/IP header, together with the slot number.  For many packets,
338 there will be a slot already allocated for the TCP connection, and the
339 VJ scheme will then often be able to replace the entire TCP/IP header
340 with a much smaller compressed header (typically only 3 - 7 bytes)
341 describing which fields of the TCP/IP header have changed, and by how
342 much.  If there are many more active connections than slots, the
343 efficiency of the VJ scheme will drop, because it will not be able to
344 send compressed headers as often.
345
346 Usually the compressed header includes a one-byte slot index, indicating
347 which TCP connection the packet is for.  It is possible to reduce the
348 header size by omitting the slot index when the packet has the same slot
349 index as the previous packet.  However, this introduces a danger if the
350 lower levels of the PPP software can sometimes drop damaged packets
351 without informing the VJ decompressor, as it may then assume the wrong
352 slot index for packets which have the slot index field omitted.  With
353 the ppp-2.x software, however, the probability of this happening is
354 generally very small (see xxx).
355
356 @end itemize
357
358 @node Installation, Configuration, Introduction, Top
359 @chapter Installation
360
361 Because ppp-2.x includes code which must be incorporated into the
362 kernel, its installation process is necessarily quite heavily
363 system-dependent.  In addition, you will require super-user privileges
364 (root access) to install the code.
365
366 Some systems provide a ``modload'' facility, which allows you to load
367 new code into a running kernel without relinking the kernel or
368 rebooting.  Under Solaris 2, SunOS 4.x, Linux, AIX 4.1, OSF/1 and
369 NextStep, this is the recommended (or only) way to install the kernel
370 portion of the ppp-2.x package.
371
372 Under the remaining supported operating systems (NetBSD, FreeBSD,
373 Ultrix), it is necessary to go through the process of creating a new
374 kernel image and reboot.  (Note that NetBSD and FreeBSD have a modload
375 facility, but ppp-2.x is currently not configured to take advantage of
376 it.)
377
378 Detailed installation instructions for each operating system are
379 contained in the README files in the ppp-2.x distribution.  In general,
380 the process involves executing the commands @samp{./configure},
381 @samp{make} and (as root) @samp{make install} in the ppp-2.x
382 distribution directory.  (The Linux port requires the installation of
383 some header files before compiling; see README.linux for details.)
384
385 @node Configuration, Security, Installation, Top
386 @chapter Configuration
387
388 Once the ppp-2.x software is installed, you need to configure your
389 system for the particular PPP connections you wish to allow.  Typically,
390 the elements you need to configure are:
391
392 @itemize @bullet
393 @item
394 How the serial link is established and how pppd gets invoked.
395 @item
396 Setting up syslog to log messages from pppd to the console and/or
397 system log files.
398 @item
399 Pppd options to be used.
400 @item
401 Authentication secrets to use in authenticating us to the peer
402 and/or the peer to us.
403 @item
404 The IP addresses for each end of the link.
405 @end itemize
406
407 In most cases, the system you are configuring will either be a
408 @dfn{client} system, actively initiating a PPP connection on user
409 request, or it will be a @dfn{server} system, passively waiting for
410 connections from client systems.  Other arrangements are possible, but
411 the instructions in this system assume that you are configuring either a
412 client or a server.
413
414 These instructions also assume that the serial link involves a serial
415 communications port (that is, a tty device), since pppd requires a
416 serial port.
417
418 @menu
419 * Client machines::  
420 * Server machines::  
421 * Setting up syslog::           
422 * Pppd options::                
423 * Authentication secrets files::  
424 * IP Addresses::                
425 @end menu
426
427 @node Client machines, Server machines, Configuration, Configuration
428 @section Client machines
429
430 On a client machine, the way that the user requests that a connection be
431 established is by running pppd, either directly or through a shell
432 script.  Pppd should be given the name of the serial port to use as an
433 option.  In this mode, pppd will fork and detach itself from its
434 controlling terminal, so that the shell will return to its prompt.  (If
435 this behaviour is not desired, use the -detach option.)
436
437 Usually, the connect option should also be used.  The connect option
438 takes an argument which is a command to run to establish the serial link
439 and invoke PPP software on the remote machine.  This command is run with
440 its standard input and standard output connected to the serial port.
441 Giving the connect option to pppd also has the side-effect of causing
442 pppd to open the serial port without waiting for the modem carrier
443 detect signal.
444
445 The process of establishing the serial link often involves a dialog.  If
446 the serial port is connected to a modem, we first need to send some
447 commands to the modem to configure it and dial the remote system.  Often
448 there is then a dialog with the remote system to supply a username and
449 password.  The @file{chat} program supplied with the ppp-2.x package is
450 useful for automating such dialogs.  Chat uses a @dfn{script} consisting
451 of alternately strings to expect to receive on the serial port, and
452 strings to send on the serial port.  The script can also specify strings
453 which indicate an error and abort the dialog.
454
455 @node Server machines, , Client machines, Configuration
456 @section Server machines
457
458 There are generally three ways in which a server machine can be set up
459 to allow client machines to establish a PPP link:
460
461 @enumerate
462 @item
463 Client machines log in as regular users (often via a serial port
464 connected to a modem, but possibly through a telnet or rlogin session)
465 and then run pppd as a shell command.
466 @item
467 Client machines log in using a username whose login shell is pppd
468 or a script which runs pppd.
469 @item
470 Client machines connect to a serial port which has a pppd running
471 permanently on it (instead of a "getty" or other program providing a
472 login service).
473 @end enumerate
474
475 Method 1 is very simple to set up, and is useful where existing users of
476 a system have remote machines (for example at home) from which they want
477 to establish a PPP connection from time to time.  Methods 2 and 3
478 possibly have a security advantage in that they do not allow PPP client
479 systems access to a shell.  Method 2 allows regular logins and PPP
480 connections on the same port, while with method 3, would-be crackers may
481 well be frustrated (unless they speak fluent PPP).
482
483 With any of these methods, I strongly recommend that you configure PPP
484 to require authentication from the client, by including the `auth'
485 option in the /etc/ppp/options file.
486
487 @node Setting up syslog, , Server machines, Configuration
488 @section Setting up syslog
489
490 Pppd uses the @file{syslog} facility to report information about the
491 state of the connection, as does @file{chat}.  It is useful to set up
492 syslog to print some of these messages on the console, and to record
493 most of them to a file.  The messages from pppd are logged with facility
494 @samp{daemon} and one of three levels:
495 @itemize @bullet
496 @item
497 @samp{notice} for messages about important events such as the
498 connection becoming available for IP traffic and the local and remote IP
499 addresses in use.
500 @item
501 @samp{info} for messages about less important events, such as
502 detecting a modem hangup.
503 @item
504 @samp{debug} for messages which are of use in working out why the
505 connection is not working properly.
506 @end itemize
507
508 The messages from chat are logged with facility @samp{local2} and level
509 @samp{debug}.
510
511 Syslog is controlled by the syslog configuration file
512 @file{/etc/syslog.conf}.  Generally the standard configuration will log
513 facility @samp{daemon} messages with level @samp{notice} and above to a
514 system log file such as @file{/var/log/syslog} (the name may vary on
515 different systems).  I find it useful to have the notice level messages
516 from pppd displayed on the console, and all messages from pppd and chat
517 logged to a file such as @file{/etc/ppp/log}.  To achieve this,
518 find the line in /etc/syslog.conf which has /dev/console
519 on the right-hand side, and add `daemon.notice' on the left.  This
520 line should end up something like this:
521
522 @example
523 *.err;kern.debug;auth.notice;mail.crit;daemon.notice    /dev/console
524 @end example
525
526 And add a line like this:
527
528 @example
529 daemon,local2.debug                                     /etc/ppp/log
530 @end example
531
532 The space between the left and right hand sides is one or more tabs, not
533 spaces, and there are no tabs or spaces at the beginning of the line.
534
535 You will need to create an empty @file{/etc/ppp/log} file; syslogd will
536 not create it.  Once you have modified @file{/etc/syslog.conf}, you need
537 to either reboot or notify syslogd to re-read the file.  On most
538 systems, you notify syslogd by sending it a SIGHUP signal.  Syslogd's
539 process ID is usually stored in a file such as @file{/etc/syslogd.pid}
540 or @file{/var/run/syslog.pid}.  Thus you can notify syslogd to re-read
541 the file by executing a command such as:
542
543 @example
544 kill -HUP `cat /etc/syslogd.pid`
545 @end example
546
547 @node Pppd options, , Setting up syslog, Configuration
548 @section Pppd options
549
550 @node Authentication secrets files, , Pppd options, Configuration
551 @section Authentication secrets files
552
553 @node IP Addresses,  , Authentication secrets files, Configuration
554 @section IP Addresses
555
556 @node Security, Compression, Configuration, Top
557 @chapter Security
558
559 @node Compression,  , Security, Top
560 @chapter Compression
561
562 @bye