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