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