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