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