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