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