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