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