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