Use SIGNAL not signal because the former doesn't reset the handler
[ppp.git] / README.linux
1 PPP for Linux                                             Version 2.2.0
2 =============                                                  based on
3                                                               ppp-2.2.0
4                                                                Mar 1995
5
6 Michael Callahan    callahan@maths.ox.ac.uk
7 Al Longyear         longyear@netcom.com
8
9   Contents:
10     INTRODUCTION
11     CREDITS
12     CHANGES FROM THE PREVIOUS VERSION
13     FUTURE PLANS
14     INSTALLATION
15     GENERAL NETWORK CONFIGURATION
16     CONNECTING TO A PPP SERVER
17     IF IT WORKS
18     IF IT DOESN'T WORK
19     IF IT STILL DOESN'T WORK (OR, BUG REPORTS)
20     DYNAMIC ADDRESS ASSIGNMENT
21     SETTING UP A MACHINE FOR INCOMING PPP CONNECTIONS
22     SETTING UP A MACHINE FOR INCOMING PPP CONNECTIONS WITH DYNAMIC IP
23     ADDITIONAL INFORMATION
24     DIP SUPPORT
25     CONCLUSION
26
27
28 INTRODUCTION
29
30 This file is substantially derived from the previous version for
31 the pppd process 2.2.0. Michael Callahan wrote that version. This
32 particular version was written, modified, hacked, changed, whatever,
33 by Al Longyear. If you find errors in this document, they are probably
34 mine and not Michael's.
35
36 This is a PPP driver for Linux.  It has been used by many people and
37 seems to be quite stable.  It is capable of being used either as a
38 'client'--for connecting a Linux machine to a local Internet provider,
39 for example--or as a 'server'--allowing a Linux machine with a modem
40 and an Ethernet connection to the Internet to provide dial-in PPP
41 links.  (In fact, the PPP protocol does not make the distinction
42 between client and server, but this is the way people often think
43 about it.)
44
45 The PPP protocol consists of two parts.  One is a scheme for framing
46 and encoding packets, the other is a series of protocols called LCP,
47 IPCP, UPAP and CHAP, for negotiating link options and for
48 authentication.  This package similarly consists of two parts: a
49 kernel module which handles PPP's low-level framing protocol, and a
50 user-level program called pppd which implements PPP's negotiation
51 protocols.
52
53 The kernel module assembles/disassembles PPP frames, handles error
54 detection, and forwards packets between the serial port and either the
55 kernel network code or the user-level program pppd.  IP packets go
56 directly to the kernel network code.  So once pppd has negotiated the
57 link, it in practice lies completely dormant until you want to take
58 the link down, when it negotiates a graceful disconnect.
59
60
61 CREDITS
62
63 I (MJC) wrote the original kernel driver from scratch.  Laurence
64 Culhane and Fred van Kempen's slip.c was priceless as a model (a
65 perusal of the files will reveal that I often mimicked what slip.c
66 did).  Otherwise I just implemented what pppd needs, using RFC1331 as
67 a guide.  For the most part, the Linux driver provides the same
68 interface as the free 386BSD and SunOS drivers.  The exception is that
69 Linux has no support for asynchronous I/O, so I hacked an ioctl into
70 the PPP kernel module that provides a signal when packets appear and
71 made pppd use this instead.
72
73 Al Longyear ported version 2.2 of pppd (from the free package
74 ppp-2.2.0) to Linux.  He also provided several enhancements to both
75 the kernel driver and the OS-independent part of pppd.  His
76 contributions to Linux PPP have been immense, and so this release
77 is being distributed over both our names.
78
79 The pppd program comes from the free distribution of PPP for Suns and
80 386BSD machines, maintained by Paul Mackerras.  This package lists
81 "thanks to" Brad Parker, Greg Christy, Drew D. Perkins, Rick Adams and
82 Chris Torek.
83
84 Jim Freeman added the code to support a ppp module and to dynamically
85 extend the number of ppp devices. All ppp devices listed in the Space.c
86 will be unlinked when the kernel is loaded. This feature makes the use
87 of '16 channel' support obsolete.
88
89
90
91 CHANGES FROM THE PREVIOUS VERSION
92
93 - The number of devices for the PPP device has been made dynamic. It was
94   previously configured with the default value of four devices.
95
96 - The problems dealing with other systems such as Windows NT and their
97   authenticiation has been corrected. It will now generate the proper
98   responses to allow the system to choose a valid authentication protocol.
99
100 - The kernel debug value has changed. Previously it was a level. It is now
101   a bit map with various bits meaning certain types of debug information.
102
103      0 - No debug information is generated
104      1 - Debug messages
105      2 - Log incoming packets
106      4 - Log outgoing packets
107      8 - Log tty output buffers
108     16 - Log tty input buffers
109
110   If you wish to use any combination, add the values together. For example,
111   '7' will log debug messages and incoming packages and outgoing packets.
112
113   The default setting is 0.
114
115   The simple IP trace which ppp.c performed when 'kdebug' was greater than
116   127 has been removed. You should use tcpdump for this type of trace
117   actions.
118
119 - Support is added for compression control protocol. At the present time
120   only the BSD-Compress compression protocol is supported.
121
122 - There are two queues for output frames. This avoids some problems which
123   occured with the previous version and some PPP packages which exchanged
124   echo frames with Linux.
125
126 - The echo frames are now proper. Previously, it would generate extra
127   characters and this caused some providers to not respond to the 'junk'.
128
129 - The max-echo-failure option will now properly disconnect the line.
130
131 - There are other changes which are listed in the general README file. Please
132   read that file as well for changes.
133
134 - There is no limit to the number of ppp devices which you may use. Jim Freeman
135   has added code to create them upon demand and to re-use the ones which have
136   been closed. There is no code, nor plans to write code, to remove (delete)
137   the un-used devices. So, if your system goes to a spurt and uses 3000 ppp
138   devices, it will remain at that level until you next reload the kernel.
139
140
141
142 FUTURE PLANS
143
144 The IPX support is still minimal. There is code which will only work with
145 the 1.3 version of the networking software. The pppd process will still
146 require changes to support the IPXCP and a change to the driver to properly
147 enable/disable the IPX frames. Jim Freeman is reportily working on the IPX
148 support.
149
150
151
152 INSTALLATION
153
154 This version of PPP has been tested on 1.1.x (x>=14) It will probably
155 not work on kernels much earlier than this due to a change in the
156 routing code.  If you have an earlier kernel, please upgrade.
157
158 joining the PPP channel of linux-activists:
159
160       This isn't really part of installation, but if you DO use
161       Linux PPP you should do this.  Send a message with the line
162         subscribe linux-ppp
163       contained in the body to majordomo@vger.rutgers.edu
164
165       You may use
166
167       subscribe linux-ppp myname@mail.address
168
169       if you wish the linux-ppp information sent to a different mail
170       address.
171
172       To leave the mail list, send 'unsubscribe linux-ppp' to the same
173       mail address.
174
175       You can send to the list by mailing to
176       linux-ppp@vger.rutgers.edu. This is a majordomo mailing list and
177       is unlike the earlier version on hut.fi. There is no magic header
178       required for this list. In addition, it is gated to the usenet
179       group linux.dev.ppp. You may choose to read the few messages posted
180       there.
181
182 Usenet News Groups
183
184       There are three applicable usenet news groups for the PPP code. Please
185       choose the group which applies the closest to the type of problem
186       which you are experiencing.
187
188       comp.os.linux.networking
189        - Trouble setting routes, running name services, using telnet, ftp,
190          news, etc.
191        - It will not compile.
192
193       comp.os.linux.setup
194        - Trouble installing the package from BINARIES only. This does *NOT*
195          include problems with compiling the package.
196
197       comp.protocols.ppp
198        - How do I use the package?
199        - How do I connect to .... services?
200        - Why does this not work?
201        - All other types of questions on how to use just the PPP code.
202
203       PLEASE don't assume that just because you are using PPP as your
204       network device driver that all problems with your networking are a
205       problem of PPP. PPP is *NOT* responsible for your modem disconnecting,
206       routing to other servers, running telnet, etc. Calling the problem
207       'ppp' on usenet may cause it to be ignored by the people who
208       actually work on the networking code.
209
210 Installation procedure:
211
212 The installation procedure has been totally revised for this
213 version. Due to feedback from other users, it was felt that a more
214 automated installation procedure be performed.
215
216 Use the following procedure for all kernel versions. There are six steps
217 numbered one through six. Please do them in order and not skip one.
218
219 1. Issue the command:
220
221 ./configure
222
223 from the top level directory of pppd. This is the directory which
224 contains this README.linux file. The result of this will be to build a
225 set of symbolic links to the makefiles. They should link 'Makefile' to
226 'Makefile.linux' in each of the directories.
227
228 2. Issue the command:
229
230 make kernel
231
232 from the top level directory. This will install the various include
233 files and source files into the proper directory for the linux
234 kernel. If you don't have the kernel installed in the /usr/src/kernel
235 directory then it will not work. Instead it will print a message to
236 the effect that you need to specify the kernel location on the
237 kinstall command.
238
239 The actual message will say:
240
241 There appears to be no kernel source distribution in /usr/src/linux.
242 Give the top-level kernel source directory as the argument to
243 this script.
244 usage: kinstall.sh [linux-source-directory]
245
246 If, and only if, you receive this message, do the following:
247
248    a. Change to the 'linux' directory with the command:
249
250 cd linux
251
252    b. Issue the command:
253
254 ./kinstall.sh /usr/src/linux
255
256 or use the proper location for the kernel rather than
257 /usr/src/linux. For example, if you have the kernel installed in
258 /usr1/kernel then the command would be:
259
260 ./kinstall.sh /usr1/kernel
261
262 The script will validate that the kernel is properly installed into
263 that directory and check the level of the kernel. The installation
264 will not be accepted if your kernel is too early.
265
266 The installation procedure will copy only the files which are
267 needed. It will not replace any file which should not be
268 replaced. Please don't second-guess the installation script and
269 attempt to do the procedure on your own. There are some very subtle
270 dependencies and if you are not careful, the installation will not
271 work.
272
273 You are free to run the installation script as many times as you
274 wish. The additional executions will only change the files which have
275 not been changed.
276
277 3. Build the kernel.
278
279 You must rebuild the kernel with this package. The driver is totally
280 new and will not work with the older daemon and the newer daemon will
281 not work with the older kernel driver. If you don't know how to build
282 a kernel, then you should read the README file in the kernel source
283 directory.
284
285 If you wish module support then you need to have the 'modules-1.1.87'
286 package installed as the minimum version. Earlier versions of the module
287 support will not work properly.
288
289 Instructions on building the kernel with modules are given in the
290 README.modules in the kernel source directory.
291
292 4. Build the programs.
293
294 The programs are built next. The command to build the programs is fairly
295 simple. Just issue the command:
296
297 make
298
299 from the top level directory where this README.linux file is located.
300
301 5. Install the programs.
302
303 You may use the command
304
305 make install
306
307 to install the various programs. They will be installed into the
308 /usr/lib/ppp directory. You may not like this directory for the
309 executables. The directory name is called BINDIR and is set in the
310 file 'linux/Makefile.linux'.
311
312 6. Reboot to the new kernel.
313
314 After building the new kernel, you will need to actually use it. Reboot
315 the Linux system and you may then use the new pppd program.
316
317 7. Load optional modules.
318
319 If you are using loadable modules for the ppp or bsd compression then
320 you must load them after the kernel has been started. The following
321 relative order must be maintained.
322
323 Sequence    Module      Description
324    1        slhc.o      VJ header compression
325    2        ppp.o       PPP driver
326    3        bsd_comp.o  BSD compression for PPP's compression protocol.
327
328 You may elect not to load the BSD compression module if you desire. There
329 is a controversy regarding a Motorola software patent and while it is
330 believed that this code does not infringe upon the patent, it is however
331 an optional component.
332
333 In addition, if memory is a premium, do not run the BSD compression. It
334 may take large amounts of memory (up to 2.6 meg) for high compression
335 lengths to hold the compression dictionaries.
336
337 Without the BSD compression module, the PPP driver will not accept PPP's
338 compression control protocol for BSD compression.
339
340
341
342 GENERAL NETWORK CONFIGURATION
343
344 Since many people don't use the Linux networking code at all until
345 they get a PPP link, this section describes generally what's needed to
346 get things running.  In principle none of this is special to PPP.  For
347 more details, you should consult the relevant Linux HOWTOs.  If you
348 already understand network setup, you can skip this section.
349
350 The first file that requires attention is the rc script that does
351 network configuration at boot time, called /etc/rc.net or
352 /etc/rc.d/rc.net.{1,2} or something similar, depending on your Linux
353 distribution.  This file should 'ifconfig' the loopback interface lo,
354 and should add an interface route for it.  These lines might look
355 something like this:
356
357         $CONFIG lo 127.0.0.1
358         $ROUTE add loopback
359 or
360         /sbin/ifconfig lo 127.0.0.1
361         /sbin/route add 127.0.0.1
362
363 However, it should *not* config an ethernet card or install any other
364 routes (unless you actually have an ethernet card, in which case I'll
365 assume you know what to do).  Many distributions will provide scripts
366 that expect you to have an ethernet card.
367
368 You also need to decide whether you want to allow incoming
369 telnet/ftp/finger, etc.  If so, you should have the rc startup script
370 run the 'inetd' daemon.
371
372 Next, you should set up /etc/hosts to have two lines.  The first
373 should just give the loopback or localhost address and the second
374 should give your own host name and the IP address your PPP connection
375 will use.  For example:
376
377      127.0.0.1   loopback localhost                    # useful aliases
378      192.1.1.17  billpc.president.whitehouse.gov bill  # my hostname
379      192.1.1.23  chelseapc.president.whitehouse.gov chelseapc
380
381 where my IP address is 192.1.1.17 and my hostname is
382 billpc.president.whitehouse.gov.  (Not really, you understand.)  If
383 your PPP server does dynamic IP address assignment, give a guess as to
384 an address you might get (see also "Dynamic Address Assignment"
385 below).
386
387 Finally, you need to configure the domain name system by putting
388 appropriate lines in /etc/resolv.conf .  It should look something like
389 this:
390
391      domain     president.whitehouse.gov
392      search     president.whitehouse.gov  whitehouse.gov
393      nameserver 192.1.2.1
394      nameserver 192.1.2.10
395
396 Assuming there are nameservers at 192.1.2.1 and 192.1.2.10, then when
397 you get connected with PPP, you can reach hosts whose full names are
398 'hillarypc.president.whitehouse.gov' and 'chelseapc.whitehouse.gov' by
399 the names 'hillarypc' and 'chelseapc'.  You can probably find out the
400 right domain name to use and the IP numbers of nameservers from
401 whoever's providing your PPP link.
402
403
404
405 CONNECTING TO A PPP SERVER
406
407 To use PPP, you invoke the pppd program with appropriate options.
408 Everything you need to know is contained in the pppd(8) manual page.
409 However, it's useful to see some examples:
410
411 Example 1: A simple dial-up connection.
412
413 Here's a command for connecting to a PPP server by modem.
414
415   pppd connect 'chat -v "" ATDT5551212 CONNECT "" ogin: ppp word: whitewater' \
416       /dev/cua1 38400 debug crtscts modem defaultroute 192.1.1.17
417
418 Going through pppd's options in order:
419    connect 'chat etc...'  This gives a command to run to contact the
420     PPP server.  Here the supplied 'chat' program is used to dial a
421     remote computer.  The whole command is enclosed in single quotes
422     because pppd expects a one-word argument for the 'connect' option.
423     The options to 'chat' itself are:
424
425          -v            verbose mode; log what we do to syslog
426          ""            don't wait for any prompt, but instead...
427          ATDT5551212   dial the modem, then
428          CONNECT       wait for answer
429          ""            send a return (null text followed by usual return)
430          ogin: ppp word: whitewater    log in.
431
432    /dev/cua1     specify the callout serial port cua1
433    38400         specify baud rate
434    debug         log status in syslog
435    crtscts       use hardware flow control between computer and modem
436                     (at 38400 this is a must)
437    modem         indicate that this is a modem device; pppd will hang up the
438                     phone before and after making the call
439    defaultroute  once the PPP link is established, make it the default
440                     route; if you have a PPP link to the Internet this
441                     is probably what you want
442
443    192.1.1.17  this is a degenerate case of a general option
444         of the form  x.x.x.x:y.y.y.y  .  Here x.x.x.x is the local IP
445         address and y.y.y.y is the IP address of the remote end of the
446         PPP connection.  If this option is not specified, or if just
447         one side is specified, then x.x.x.x defaults to the IP address
448         associated with the local machine's hostname (in /etc/hosts),
449         and y.y.y.y is determined by the remote machine.  So if this
450         example had been taken from the fictional machine 'billpc',
451         this option would actually be redundant.
452
453 pppd will write error messages and debugging logs to the syslogd
454 daemon using the facility name "daemon". These messages may already be
455 logged to the console or to a file like /usr/adm/messages; consult
456 your /etc/syslog.conf file to see. If you want to make all pppd
457 messages go to the console, add the line
458
459    daemon.*                                     /dev/console
460            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
461            This is one or more tabs. Do not use spaces.
462
463 to syslog.conf; make sure to put one or more TAB characters between
464 the two fields.
465
466 Example 2: Connecting to PPP server over hard-wired link.
467
468 This is a slightly more complicated example.  This is the script I run
469 to make my own PPP link, which is over a hard-wired Gandalf link to an
470 Ultrix machine running Morningstar PPP.
471
472   pppd connect /etc/ppp/ppp-connect defaultroute noipdefault debug \
473       kdebug 0 /dev/cua0 9600
474
475 Here /etc/ppp/ppp-connect is the following script:
476   #!/bin/sh
477   /etc/ppp/sendbreak
478   chat -v -t60 "" \; "service :" blackice ogin: callahan word: PASSWORD \
479       black% "stty -echo; ppp" "Starting PPP now"  && sleep 5
480
481 This sends a break to wake up my terminal server, sends a semicolon
482 (which lets my terminal server do autobaud detection), then says we
483 want the service "blackice".  It logs in, waits for a shell prompt
484 ("black%"), then starts PPP.  The -t60 argument sets the timeout to a
485 minute, since things here are sometimes very slow.
486
487 The "&& sleep 5" causes the script to pause for 5 seconds, unless chat
488 fails in which case it exits immediately.  This is just to give the
489 PPP server time to start (it's very slow).  Also, the "stty -echo"
490 turned out to be very important for me; without it, my pppd would
491 sometimes start to send negotiation packets before the remote PPP
492 server had time to turn off echoing.  The negotiation packets would
493 then get sent back to my local machine, be rejected (PPP is able to
494 detect loopback) and pppd would fail before the remote PPP server even
495 got going.  The "stty -echo" command prevents this confusion.  This
496 kind of problem should only ever affect a *very* few people who
497 connect to a PPP server that runs as a command on a slow Unix machine,
498 but I wanted to mention it because it took me several frustrating
499 hours to figure out.
500
501 The pppd options are mostly familiar.  Two that are new are
502 "noipdefault" and "kdebug 1".  "noipdefault" tells pppd to ask the
503 remote end for the IP address to use; this is necessary if the PPP
504 server implements dynamic IP address assignment as mine does (i.e., I
505 don't know what address I'll get ahead of time).  "kdebug 1" sets the
506 kernel debugging level to 1, enabling slightly chattier messages from
507 the ppp kernel code.
508
509 Anyway, assuming your connection is working, you should see chat dial
510 the modem, then perhaps some messages from pppd (depending on your
511 syslog.conf setup), then some kernel messages like this:
512
513         ppp: channel ppp0 mtu changed to 1500
514         ppp: channel ppp0 open
515         ppp: channel ppp0 going up for IP packets!
516
517 (These messages will only appear if you gave the option "kdebug 1" and
518 have kern.info messages directed to the screen.)  Simultaneously, pppd
519 is also writing interesting things to /usr/adm/messages (or other log
520 file, depending on syslog.conf).
521
522
523 IF IT WORKS
524
525 If you think you've got a connection, there are a number of things you
526 can do to test it.
527
528 First, type
529
530         /sbin/ifconfig
531
532      (ifconfig may live elsewhere, depending on your distribution.)
533 This should show you all the network interfaces that are 'UP'.  ppp0
534 should be one of them, and you should recognize the first IP address
535 as your own and the "P-t-P address" (or point-to-point address) the
536 address of your server.  Here's what it looks like on my machine:
537
538 lo        Link encap Local Loopback  
539           inet addr 127.0.0.1  Bcast 127.255.255.255  Mask 255.0.0.0
540           UP LOOPBACK RUNNING  MTU 2000  Metric 1
541           RX packets 0 errors 0 dropped 0 overrun 0
542           TX packets 0 errors 0 dropped 0 overrun 0
543
544 ppp0      Link encap Point-to-Point Protocol
545           inet addr 192.76.32.2  P-t-P 129.67.1.165  Mask 255.255.255.0
546           UP POINTOPOINT RUNNING  MTU 1500  Metric 1
547           RX packets 33 errors 0 dropped 0 overrun 0
548           TX packets 42 errors 0 dropped 0 overrun 0
549
550 Now, type
551
552         ping z.z.z.z
553
554 where z.z.z.z is the address of your name server.  This should work.
555 Here's what it looks like for me:
556
557   waddington:~$ ping 129.67.1.165
558   PING 129.67.1.165 (129.67.1.165): 56 data bytes
559   64 bytes from 129.67.1.165: icmp_seq=0 ttl=255 time=268 ms
560   64 bytes from 129.67.1.165: icmp_seq=1 ttl=255 time=247 ms
561   64 bytes from 129.67.1.165: icmp_seq=2 ttl=255 time=266 ms
562   ^C
563   --- 129.67.1.165 ping statistics ---
564   3 packets transmitted, 3 packets received, 0% packet loss
565   round-trip min/avg/max = 247/260/268 ms
566   waddington:~$
567
568 Try typing:
569
570         netstat -nr
571
572 This should show three routes, something like this:
573
574 Kernel routing table
575 Destination     Gateway         Genmask         Flags Metric Ref Use    Iface
576 129.67.1.165    0.0.0.0         255.255.255.255 UH    0      0        6 ppp0
577 127.0.0.0       0.0.0.0         255.0.0.0       U     0      0        0 lo
578 0.0.0.0         129.67.1.165    0.0.0.0         UG    0      0     6298 ppp0
579
580 If your output looks similar but doesn't have the destination 0.0.0.0
581 line (which refers to the default route used for connections), you may
582 have run pppd without the 'defaultroute' option.
583
584 At this point you can try telnetting/ftping/fingering whereever you
585 want, bearing in mind that you'll have to use numeric IP addresses
586 unless you've set up your /etc/resolv.conf correctly.
587
588
589 IF IT DOESN'T WORK
590
591 If you don't seem to get a connection, the thing to do is to collect
592 'debug' output from pppd.  To do this, make sure you run pppd with the
593 'debug' option, and put the following two lines in your
594 /etc/syslog.conf file:
595
596     daemon.*                                    /dev/console
597     daemon.*                                    /usr/adm/ppplog
598
599 This will cause pppd's messages to be written to the current virtual
600 console and to the file /usr/adm/ppplog.  Note that the left-hand
601 field and the right-hand field must be separated by at least one TAB
602 character.  After modifying /etc/syslog.conf, you must execute the
603 command 'kill -HUP <pid>' where <pid> is the process ID of the
604 currently running syslogd process to cause it to re-read the
605 configuration file.
606
607 Some messages to look for: 
608   - "pppd[NNN]: Connected..." means that the "connect" script has
609     completed successfully.  
610   - "pppd[NNN]: sent [LCP ConfReq"... means that pppd has attempted to
611     begin negotiation with the remote end.  
612   - "pppd[NNN]: recv [LCP ConfReq"... means that pppd has received a
613     negotiation frame from the remote end.
614   - "pppd[NNN]: ipcp up" means that pppd has reached the point where
615     it believes the link is ready for IP traffic to travel across it.
616
617 If you never see a "recv" message then there may be serious problems
618 with your link.  (For example, the link may not be passing all 8
619 bits.)  If that's the case, it would be useful to collect a debug log
620 which contains all the bytes being passed between your computer and
621 the remote PPP server.  To do this, alter your syslog.conf lines to
622 look like this
623
624     daemon.*,kern.*                             /dev/console
625     daemon.*,kern.*                             /usr/adm/ppplog
626
627 and HUP the syslog daemon as before.  Then, run pppd with the option
628 "kdebug 25".  Whatever characters arrive over the PPP terminal line
629 will appear in the debugging output.
630
631 Occasionally you may see a message like
632
633    ppp_toss: tossing frame, reason = 4
634
635 The PPP code is throwing away a packet ("frame") from the remote
636 server because of a serial overrun.  This means your CPU isn't able to
637 read characters from the serial port as quickly as they arrive; the
638 best solution is to get a 16550A serial chip, which gives the CPU some
639 grace period.  Reasons other than 4 indicate other kinds of serial
640 errors, which should not occur.
641
642 During the initial connection sequence, you may see one or more
643 messages which indicate "bad fcs".  This refers to a checksum error in
644 a received PPP frame, and usually occurs at the start of a session
645 when the peer system is sending some "text" messages, such as "hello
646 this is the XYZ company".  Messages of "bad fcs" once the link is
647 established and the routes have been added are not normal and indicate
648 transmission errors or noise on the telephone line.
649
650
651 IF IT STILL DOESN'T WORK (OR, BUG REPORTS)
652
653 If you're still having difficulty, send the linux-ppp list a bug
654 report. It is extremely important to include as much information as
655 possible; for example:
656
657  - the version number of the kernel you are using
658  - the version number of Linux PPP you are using
659  - the exact command you use to start the PPP session
660  - log output from a session run with the 'debug' option, captured
661    using daemon.*,kern.* in your syslog.conf file
662  - the type of PPP peer that you are connecting to (eg, Xyzzy Corp
663    terminal server, Morningstar PPP software, etc)
664  - the kind of connection you use (modem, hardwired, etc...)
665
666
667 DYNAMIC ADDRESS ASSIGNMENT
668
669 You can use Linux PPP with a PPP server which assigns a different IP
670 address every time you connect. This action is automatically performed
671 when you don't have a local IP address.
672
673   pppd connect 'chat -v "" ATDT5551212 CONNECT "" ogin: ppp word: whitewater' \
674       /dev/cua1 38400 noipdefault debug crtscts modem defaultroute
675
676 The noipdefault, added to the above example, suppresses the attempts
677 of pppd to deduce its own IP address by looking it up in the
678 /etc/hosts file. Since the process does not have an IP address, one
679 will be assigned to it from the configuration file on the remote
680 system.
681
682 Sometimes you may get an error message like "Cannot assign requested
683 address" when you use a Linux client (for example, "talk").  This
684 happens when the IP address given in /etc/hosts for our hostname
685 differs from the IP address used by the PPP interface.  The solution
686 is to use ifconfig ppp0 to get the interface address and then edit
687 /etc/hosts appropriately.
688
689
690
691 SETTING UP A MACHINE FOR INCOMING PPP CONNECTIONS
692
693 Suppose you want to permit another machine to call yours up and start
694 a PPP session.  This is possible using Linux PPP.
695
696 One way is to create an account named, say, 'ppp', with the login
697 shell being a short script that starts pppd.  For example, the passwd
698 entry might look like this:
699
700   ppp:(encrypted password):102:50:PPP client login:/home/ppp:/usr/sbin/pppd
701
702 In addition, you would edit the file ~ppp/.ppprc to have the following
703 pieces of information:
704
705 -detach
706 modem
707 crtscts
708 lock
709 :192.1.2.23
710
711 Here we will insist that the remote machine use IP address 192.1.2.23,
712 while the local PPP interface will use the IP address associated with
713 this machine's hostname in /etc/hosts.  The '-detach' option is required
714 for a server. It tells the pppd process not to terminate until the modem
715 is disconnected. Should it fork, the init process would restart the getty
716 process and the this would cause a severe conflict over the port.
717
718 The 'modem' option indicates that the connection is via a switched circuit
719 (using a modem) and that the pppd process should monitor the DCD signal
720 from the modem.
721
722 The 'crtscts' option tells the pppd process to use hardware RTS/CTS flow
723 control for the modem.
724
725 The 'lock' option tells pppd to lock the tty device. This will use the UUCP
726 style locking file in the lock directory.
727
728 This setup is sufficient if you just want to connect two machines so
729 that they can talk to one another.  If you want to use Linux PPP to
730 connect a single machine to an entire network, or to connect two
731 networks together, then you need to arrange for packets to be routed
732 from the networks to the PPP link.  Setting up a link between networks
733 is beyond the scope of this document; you should examine the routing
734 options in the manual page for pppd carefully and find out about
735 routed, etc.
736
737 Let's consider just the first case.  Suppose you have a Linux machine
738 attached to an Ethernet, and you want to allow its PPP peer to be able
739 to communicate with hosts on that Ethernet.  To do this, you should
740 have the remote machine use an IP address that would normally appear
741 to be on the local Ethernet segment and you should give the 'proxyarp'
742 option to pppd on the server.  Suppose, for example, we have this
743 setup:
744
745  192.1.2.23                        192.1.2.17
746 +-----------+      PPP link       +----------+
747 | chelseapc | ------------------- |  billpc  |
748 +-----------+                     +----------+
749                                         |           Ethernet 
750                             ----------------------------------- 192.1.2.x 
751
752 Here the PPP and Ethernet interfaces of billpc will have IP address
753 192.1.2.17.  (It's OK for one or more PPP interfaces on a machine to
754 share an IP address with an Ethernet interface.)  There is an
755 appropriate entry in /etc/passwd on billpc to allow chelseapc to call
756 in. It will run pppd when the user signs on to the system and pppd will
757 take the options from the user option file.
758
759 In addition, you would edit the file ~ppp/.ppprc to have the following
760 piece of information:
761
762 -detach
763 modem
764 crtscts
765 lock
766 192.1.2.17:192.1.2.23
767 proxyarp
768
769 When the link comes up, pppd will enter a "proxy arp" entry for
770 chelseapc into the arp table on billpc.  What this means effectively
771 is that billpc will pretend to the other machines on the 192.1.2.x
772 Ethernet that its Ethernet interface is ALSO the interface for
773 chelseapc (192.1.2.23) as well as billpc (192.1.2.17).  In practice
774 this means that chelseapc can communicate just as if it was directly
775 connected to the Ethernet.
776
777
778
779 SETTING UP A MACHINE FOR INCOMING PPP CONNECTIONS WITH DYNAMIC IP
780
781 The use of dynamic IP assignments is not much different from that
782 using static IP addresses. Rather than putting the IP address into the
783 single file ~ppp/.ppprc, you would put the IP address for each of the
784 incoming terminals into the /etc/ppp/options.tty files. ('tty' is the
785 name of the tty device. For example /etc/ppp/options.ttyS0 is used for
786 the /dev/ttyS0 device.)
787
788 To each of the serial devices, you would attach a modem. To the
789 modems, attach the telephone lines. Place all of the telephone lines
790 into a hunt group so that the telephone system will select the
791 non-busy telephone and subsequently, the modem. By selecting the
792 modem, the user will select a tty device and the tty device will
793 select the IP address. Run a getty process against the tty device such
794 as /dev/ttyS0.
795
796 (The general consensus among the users is that you should *not* use
797 the agetty process to monitor a modem. Use either getty_ps' uugetty
798 process or mgetty from the mgetty+sendfax package.)
799
800
801 SECURITY CONCERNS ABOUT INCOMING PPP CONNECTIONS
802
803 The following security should be considered with the ppp connections.
804
805 1. Never put the pppd program file into the /etc/shells file. It is not
806 a legal shell for the general user. In addition, if the shell is missing
807 from the shells file, the ftpd process will not allow the user to access
808 the system via ftp. You would not want Joe Hacker using the ppp account
809 via ftp.
810
811 2. Ensure that the directory /etc/ppp is owned by 'root' and permits
812 only write access to the root user.
813
814 3. The files /etc/ppp/options must be owned by root and accessible only
815 from that user. Never permit any other user access to this file.
816
817 4. The files /etc/ppp/ip-up and /etc/ppp/ip-down will be executed by the
818 pppd process while it is root. Ensure that these files are writable only
819 from the root user.
820
821 5. If you use an incoming PPP connection, you should do the following as
822 the root user:
823
824 a) Invalidate the files for rhosts and forward
825 rm -f     ~ppp/.rhosts ~ppp/.forward
826 touch     ~ppp/.rhosts ~ppp/.forward
827 chmod 444 ~ppp/.rhosts ~ppp/.forward
828
829 b) Prevent users from sending mail to the user 'ppp'.
830
831 This is best performed by creating a system alias 'ppp' and have it
832 point to the name "THIS_USER_CANNOT_RECEIVE_MAIL". It has no special
833 meaning other than the obvious one.
834
835 For sendmail, the sequence is fairly easy. Edit the /etc/aliases file
836 and add the line:
837
838 ppp:THIS_USER_CANNOT_RECEIVE_MAIL
839
840 Then run the sendmail program with the option '-bi' to rebuild the
841 alias database.
842
843 c) Secure the ppp file properly.
844 chown root ~ppp/.ppprc
845 chmod 444  ~ppp/.ppprc
846
847 You may wish to extend the security by creating a group 'ppp' and putting
848 the ppp user into that group, along with the binaries for pppd and pppstats.
849 Then you may secure the binaries so that they are executable from the owner
850 (which should be root) and the group only. All other users would be denied
851 all access to the files and executables.
852
853 d) Prevent the motd file from being sent to the ppp user.
854 touch ~ppp/.hushlogin
855 chown root ~ppp/.hushlogin
856 chmod 444  ~ppp/.hushlogin
857
858
859 ADDITIONAL INFORMATION
860
861 Besides this document, additional information may be found in:
862
863 - The file README in the source package
864 - The PPP-HOWTO on sunsite.unc.edu
865 - The Net-2-HOWTO on sunsite.unc.edu
866 - The Network Administration Guide published by O'Rielly and Associates
867
868 Please consult these sources of information should you have questions
869 about the program. If you still can not find your answer then ask either
870 the usenet news groups or the mail list.
871
872
873
874 DIP SUPPORT
875
876 The dip program used by Linux is not directly supported by the PPP
877 package as such. Please don't ask the PPP porting group questions
878 about dip. It does work in two areas.
879
880 1. If you use it as a parameter to 'connect' then you can use the scripting
881    language and establish the connection. You would use the standard set of
882    PPP options.
883
884 2. dip-3.3.7m-uri and later versions support a 'mode ppp' function
885    which will invoke the pppd program. That is all that it does. It will
886    not pass any parameters to pppd other than its required '-detach' to
887    allow dip to detect the normal termination of pppd.
888
889    The following information comes from John Phillips in an article which he
890    posted to comp.os.linux.setup.
891
892 Assuming that you already know how dip supports SLIP, these points 
893 are relative to a working SLIP set-up.
894
895 1.  You need dip-3.3.7m-uri, and, of course, PPP compiled into the
896 kernel.
897
898 2.  Make sure pppd is where dip thinks it is: /usr/lib/ppp/pppd, or 
899 make a link from there to where pppd really is.  (Or re-compile dip 
900 to tell it where pppd is on your system - see pathnames.h).
901
902 3.  The key differences between the dip script for PPP, compared to one 
903 for SLIP are:
904
905     a.  Use "mode PPP" instead of "mode SLIP"
906
907     b.  Don't set certain options such as mtu and default - these are set 
908     by pppd from the file /etc/ppp/options.  Mine looks like this:
909
910         crtscts
911         modem
912         defaultroute
913         asyncmap 0x00000000
914         mru 576
915         mtu 576
916
917     The actual parameters and values may depend on your IP supplier 
918     and his set-up.
919
920     c. Tell your IP supplier's start-up code to use ppp, not slip:  I
921     use "send nolqm,idle=240\n" instead of "send slip,idle=240,mru=576\n" 
922     at the "protocol: " prompt.  ("nolqm" asks for ppp without the line 
923     quality monitoring protocol, which is not - I think - supported in 
924     Linux PPP.)  This prompt may be different (or absent) with another 
925     IP supplier.
926
927     d. You don't need "get $local <name>", since the ppp protocol 
928     negotiates this at start-up.  You still need "get $remote <name>".  
929     (This may also vary with IP supplier - you may need to set some 
930     more parameters in /etc/ppp/options to work with yours - see "man 
931     pppd" for details of the options supported by pppd.)
932
933 4.  The dip script will exit after dialling and starting up pppd.  When 
934 ppp negotiation is completed and IP comes up, pppd runs /etc/ppp/ip-up.  
935 This file can contain things you want to run when the network comes up 
936 (e.g. running the mail queue).
937
938 5.  When IP goes down (e.g. after you close down the link with "dip -k"), 
939 pppd runs /etc/ppp/ip-down, which can contain things you want to do on 
940 close-down.
941
942
943
944 CONCLUSION
945
946 Good luck!
947
948 Al and Michael