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