fix up prototypes; let sysdep stuff make device non-blocking
[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 and X clients and servers.
60
61 Features of PPP include:
62 @itemize
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 (pppd).  This code is implemented using STREAMS modules on Solaris 2,
91 SunOS 4.x, AIX 4.1 and OSF/1, and as a tty line discipline under Ultrix,
92 NextStep, NetBSD, FreeBSD, and Linux.
93
94 @item
95 The PPP daemon (@code{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 LCP negotiates.
107 * IPCP negotiation::            The parameters which IPCP negotiates.
108 @end menu
109
110 @node PPP Concepts, , Introduction, Introduction
111 @section PPP Concepts
112
113 Establishing a PPP link involves communication between two systems.  The
114 two systems are called ``peers''.  When we are talking from the point of
115 view of one of the systems, the other is often referred to as ``the
116 peer''.  Although we may sometimes refer to one system as a ``client''
117 and the other as a ``server'', this distinction is not made in the PPP
118 protocols.
119
120 PPP requires the use of a communications medium which transmits a stream
121 of characters, with 8 bits per character.  We will refer to this as the
122 ``serial link''.  Most often, this involves a standard asynchronous
123 serial port on each of the peers, connected via modems and telephone
124 lines.  Many other types of serial link can be used, for example a
125 synchronous ISDN connection, or even a telnet session over the Internet.
126 The serial link must be full duplex, that is, capable of transmitting
127 characters independently in both directions at once, and it must
128 transmit 8 bits per character; PPP cannot work over a serial link which
129 transmits only 7 bits per character.
130
131 PPP has a mechanism to avoid sending certain characters if it is known
132 that the some element of the serial link interprets them specially.  For
133 example, the DC1 and DC3 ASCII characters (control-Q and control-S) may
134 be trapped by a modem if it is set for ``software'' flow control.  PPP
135 can send these characters as a two-character ``escape'' sequence.  The
136 set of characters which are to be transmitted as an escape sequence is
137 represented in an ``async control character map'' (ACCM).  The ``async''
138 part refers to the fact that this facility is used for asynchronous
139 serial links.  For synchronous serial connections, the HDLC bit-stuffing
140 procedure is used instead.
141
142 During the lifetime of a PPP connection, it proceeds through several
143 phases:
144
145 @enumerate
146 @item
147 Serial link establishment.  In this phase, the serial link is set up and
148 PPP protocol software is attached to each end of the serial link.  The
149 precise steps involved in doing this vary greatly, depending on the
150 nature of the serial link, but typically it involves first sending
151 commands to a modem to cause it to dial the remote system.  When the
152 remote system answers, the local system usually has to supply a username
153 and password, and then issue a command to invoke PPP software on the
154 remote system.  The ``chat'' program supplied with ppp-2.x provides a
155 way to automate a dialog with the modem and the remote system.  This
156 phase is not standardized; it is outside the scope of the PPP protocol
157 specifications.
158
159 @item
160 Link Control Protocol (LCP) negotiation.  In this phase, the peers send
161 LCP packets to each other to negotiate various parameters of the
162 connection, such as the ACCM to be used in each direction, whether
163 authentication is required, and whether or not to use various forms of
164 compression.  When the peers reach agreement on these parameters, LCP is
165 said to be ``up''.
166
167 @item
168 Authentication.  If one (or both) of the peers requires the other
169 peer to authenticate itself, that occurs next.  If one of the peers
170 cannot successfully authenticate itself, the other peer terminates the
171 link.
172
173 @item
174 Network Control Protocol (NCP) negotiation.  PPP can potentially support
175 several different network protocols, although IP is the only network
176 protocol (NP) supported by the ppp-2.x package.  Each NP has an
177 associated NCP defined for it, which is used to negotiate the specific
178 parameters which affect that NP.  For example, the IP Control Protocol
179 (IPCP) is used to negotiate the IP addresses for each end of the link,
180 and whether the TCP header compression method described by Van Jacobsen
181 in RFC 1144 is to be used.
182
183 @item
184 Network communication.  When each NCP has successfully negotiated the
185 parameters for its NP, that NCP is said to be ``up''.  At that point,
186 the PPP link is made available for data traffic from that NP.  For
187 example, when IPCP comes up, the PPP link is then available for carrying
188 IP packets (which of course includes packets from those protocols which
189 sit above IP, such as TCP, UDP, etc.)
190
191 @item
192 Termination.  When the link is no longer required, it is terminated.
193 Usually this involves an exchange of LCP packets so that one peer can
194 notify the other that it is shutting down the link, enabling both peers
195 to shut down in an orderly manner.  But of course there are occasions
196 when the link terminates because the serial link is interrupted, for
197 example, when a modem loses carrier and hangs up.
198
199 @end enumerate
200
201 PPP is defined in several RFC (Request For Comments) documents, in
202 particular RFCs 1661, 1662, and 1334.  IPCP is defined in RFC 1332.
203 Other RFCs describe the control protocols for other network protocols
204 (e.g., DECnet, OSI, Appletalk).  RFCs are available by anonymous FTP
205 from several sites including nic.ddn.mil, nnsc.nsf.net, nic.nordu.net,
206 ftp.nisc.sri.com, and munnari.oz.au.
207
208 @node PPP packet format, , PPP Concepts, Introduction
209 @section PPP packet format
210
211 PPP transmits packets over the serial link using a simple encapsulation
212 scheme.  First, a two-byte PPP Protocol field is inserted before the
213 beginning of the data to be sent.  The value in this field identifies
214 which higher-level protocol (either a network protocol such as IP or a
215 PPP control protocol such as LCP) should receive the data in the packet.
216 By default, a one-byte Address field with the value 0xFF, and a one-byte
217 Control field with the value 0x03, are inserted before the PPP Protocol
218 field (apparently this is supposed to provide compatibility with HDLC,
219 in case there is a synchronous to asynchronous converter in the serial
220 link).
221
222 On ``slow'' serial links, these fields can be compressed down to one
223 byte in most cases.  The PPP Address and Control fields are compressed
224 by simply omitting them.  The PPP Protocol field values are chosen so
225 that bit 0 (the least-significant bit) of the first (most significant)
226 byte is always 0, and bit 0 of the second byte is always 1.  The PPP
227 Protocol field can be compressed by omitting the first byte provided
228 that it is 0.  The values for this field are assigned so that the first
229 byte is zero for all of the commonly-used network protocols.  For
230 example, the PPP Protocol field value for IP is 0x21.
231
232 For asynchronous serial links, which do not provide any packet framing
233 or transparency, a further encapsulation is used as follows.  First a
234 16-bit Frame Check Sequence (FCS) is computed over the packet to be
235 sent, and appended as two bytes to the end of the packet.
236
237 Then each byte of the packet is examined, and if it contains one of the
238 characters which are to be escaped, it is replaced by a two byte
239 sequence: the 0x7d character '}', followed by the character with bit 5
240 inverted.  For example, the control-C character (0x03) could be replaced
241 by the two-byte sequence 0x7d, 0x23 ('}#').  The 0x7d and 0x7e ('~')
242 characters are always escaped (and the 0x5e ('^') character may not be
243 escaped).
244
245 Finally, a ``flag'' character (0x7e, '~') is inserted at the beginning
246 and end of the packet to mark the packet boundaries.  The initial flag
247 may be omitted if this packet immediately follows another packet, as the
248 ending flag for the previous packet can serve as the beginning flag of
249 this packet.
250
251 @node LCP negotiation, , PPP packet format, Introduction
252 @section LCP negotiation
253
254 The LCP negotiation process actually involves two sets of negotiations,
255 one for each direction of the PPP connection.  Thus A will send B
256 packets (``Configure-Requests'') describing what characteristics A would
257 like to have apply to the B -> A direction of the link, that is, to the
258 packets that A will receive.  Similarly B will send A packets describing
259 the characteristics it would like to have apply to the packets it will
260 be receiving.  These characteristics need not necessarily be the same in
261 both directions.
262
263 The parameters which are negotiated for each direction of the connection
264 using LCP are:
265
266 @itemize
267 @item
268 Maximum Receive Unit (MRU): indicates the maximum packet size which we
269 are prepared to receive (specifically the maximum size of the
270 data portion of the packet).  The default value is 1500, but on
271 slow serial links, smaller values give better response.  The choice of
272 MRU is discussed below (see xxx).
273
274 @item
275 Async Control Character Map (ACCM): indicates the set of control
276 characters (characters with ASCII values in the range 0 - 31) which we
277 wish to receive in escaped form.  The default is that the sender should
278 escape all characters in the range 0 - 31.
279
280 @item
281 Authentication Protocol: indicates which protocol we would like the peer
282 to use to authenticate itself.  Common choices are the Password
283 Authentication Protocol (PAP) and the Cryptographic Handshake
284 Authentication Protocol (CHAP).
285
286 @item
287 Quality Protocol: indicates which protocol which we would like the peer
288 to use to send us link quality reports.  The ppp-2.x package does not
289 currently support link quality reports.
290
291 @item
292 Magic Number: a randomly-chosen number, different from the peer's magic
293 number.  If we persistently receive our own magic number in the peer's
294 configure-request packets, then we can conclude that the serial link is
295 looped back.
296
297 @item
298 Protocol Field Compression: indicates that we wish the peer to compress
299 the PPP Protocol field to one byte, where possible, in the packets it
300 sends.
301
302 @item
303 Address/Control Field Compression: indicates that we wish the peer to
304 compress the PPP Address/Control fields (by simply omitting them) in the
305 packets it sends.
306 @end itemize
307
308 @node IPCP negotiation,  , LCP negotiation, Introduction
309 @section IPCP negotiation
310
311 The IPCP negotiation process is very similar to the LCP negotiation
312 process, except that of course different parameters are negotiated.
313 The parameters which are negotiated using IPCP are:
314
315 @itemize
316 @item
317 IP Address: the IP address (32-bit host IP number) which we plan to use
318 as the local address for our end of the link.
319
320 @item
321 TCP header compression: indicates (a) that we wish the peer to compress
322 the TCP/IP headers of TCP/IP packets that it sends, using the Van
323 Jacobson algorithm as described in RFC1144; (b) the maximum slot ID that
324 we wish the peer to use, and (c) whether we are prepared to accept
325 packets with the slot ID field compressed (omitted).
326
327 With Van Jacobson (VJ) compression, the receiver and transmitter (for
328 one direction of the connection) both keep a table, with a certain
329 number of ``slots'', where each slot holds the TCP/IP header of the most
330 recently transmitted packet for one TCP connection.  If a packet is to
331 be transmitted for a TCP connection which does not have a slot currently
332 allocated, the VJ scheme will allocate one of the slots and send the
333 entire TCP/IP header, together with the slot number.  For many packets,
334 there will be a slot already allocated for the TCP connection, and the
335 VJ scheme will then often be able to replace the entire TCP/IP header
336 with a much smaller compressed header (typically only 3 - 7 bytes)
337 describing which fields of the TCP/IP header have changed, and by how
338 much.  If there are many more active connections than slots, the
339 efficiency of the VJ scheme will drop, because it will not be able to
340 send compressed headers as often.
341
342 Usually the compressed header includes a one-byte slot index, indicating
343 which TCP connection the packet is for.  It is possible to reduce the
344 header size by omitting the slot index when the packet has the same slot
345 index as the previous packet.  However, this introduces a danger if the
346 lower levels of the PPP software can sometimes drop damaged packets
347 without informing the VJ decompressor, as it may then assume the wrong
348 slot index for packets which have the slot index field omitted.  With
349 the ppp-2.x software, however, the probability of this happening is
350 generally very small (see xxx).
351
352 @end itemize
353
354 @node Installation, Configuration, Introduction, Top
355 @chapter Installation
356
357 Because ppp-2.x includes code which must be incorporated into the
358 kernel, its installation process is necessarily quite heavily
359 system-dependent.  In addition, you will require super-user privileges
360 (root access) to install the code.
361
362 Some systems provide a ``modload'' facility, which allows you to load
363 new code into a running kernel without relinking the kernel or
364 rebooting.  Under Solaris 2, SunOS 4.x, Linux, AIX 4.1, OSF/1 and
365 NextStep, this is the recommended (or only) way to install the kernel
366 portion of the ppp-2.x package.
367
368 Under the remaining supported operating systems (NetBSD, FreeBSD,
369 Ultrix), it is necessary to go through the process of creating a new
370 kernel image and reboot.  (Note that NetBSD and FreeBSD have a modload
371 facility, but ppp-2.x is currently not configured to take advantage of
372 it.)
373
374 @node Configuration, Security, Installation, Top
375 @chapter Configuration
376
377 @node Security, Compression, Configuration, Top
378 @chapter Security
379
380 @node Compression,  , Security, Top
381 @chapter Compression
382
383 @bye