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