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