updates from Steve Perkins
[ppp.git] / NeXT / INSTALL
1                 PPP-2.3 for systems running NeXTSTEP
2                 ====================================
3
4
5 Authoritative information can be found at:
6
7   WWW site:     http://www.thoughtport.com:8080/PPP/ 
8   FTP site:     ftp://ftp.thoughtport.com/pub/next/ppp
9   Mirror FTP:   ftp://ftp.duq.edu/pub/next/ppp/
10   Mirror FTP:   ftp://ftp.NMR.EMBL-Heidelberg.DE/pub/next/ppp/
11
12 If you have questions or problems, please visit the WWW site
13 for FAQ and mailing list information.
14
15 NEW: If you want to submit a bug report, use the new MailBug.app
16      provided in this directory.  You will need to install it as
17      you would any package.  If you don't have email access, please
18      use bug submission form on the WWW site.
19
20 If you use this software and are pleased with its performance, you are
21 encouraged to make a donation to support continued development.  50%
22 of all donations go to charity.  For more information, please see:
23   http://www.thoughtport.com:8080/PPP/donations.html
24
25
26
27 NeXT Specific Installation Instructions
28 =======================================
29
30 The procedure for an initial installation and for an upgrade are very
31 similar. However, if this is the first time you are installing PPP,
32 there are a few extra steps that you must do for the initial setup.
33 They will be described later in this document.
34
35 Making the source files
36 =========================
37
38 To install on a computer running NeXTSTEP:
39
40  1) Read this file completely through before you start.
41
42  2) If you are on an HP-PA system, read the file
43     ./NeXT/hppa/README.hppa and install the serial
44     driver patch.  Successfull installation of this
45     patch will require a reboot of your machine.  HPPA
46     is not supported.
47
48  3) If you have previously installed a SLIP package, comment out
49     the slip configuration code in /etc/rc.local and reboot your
50     machine.  SLIP and PPP _should_ interoperate but for initial
51     testing it is best to remove SLIP.
52
53  4) If you are using Intel, you _must_ get the latest NeXT serial
54     drivers from NeXTAnswers.  You need both the serial and ttyport
55     drivers (version 3.33 or later).  Install these according to
56     the directions.  PPP-2.3 is optimized to work with 
57     the NeXT drivers.   It will work with the Mux driver, but
58     that driver has been known to cause panics with PPP.
59
60  5) If you plan in using tcpdump to monitor packets, you must
61     enable the Berkley Packet Filter code.  Edit ./NeXT/Makefile
62     and make sure the '-DNBPFILTER' option is defined in DFLAGS.
63     WARNING: If you choose to use BPF, you must make sure that you
64     compile _AND LOAD_ the bpf_reloc LKS _BEFORE_ you load the
65     ppp_reloc LKS.  Also, make sure you read the installation file in
66     ./NeXT/bpf.  You will need to create a few special device files in
67     /dev/.
68
69     If you don't want to compile in this code, please make sure that
70     '-DBPFILTER' is _not_ defined in the ./NeXT/Makefile DFLAGS.
71
72  6) Type ./configure in the top level PPP directory.  This will set
73     up some necessary links.
74
75  7) If you have developer 3.2, you need to use the old version of
76     chat.c.  Perform:
77       a) cd to the chat directory
78       b) backup chat.c (mv chat.c chat.c.orig)
79       c) use the old chat (mv chat.c.3.2 chat.c)
80
81  8) Edit ./Makefile and set the installation directories.
82     If you change the ETCDIR you will need to modify pathnames in
83     pppd/pathnames.h. I recommend keeping it set to /etc/ppp. 
84     If you don't specifically like that directory, you may
85     also change the Makefile directory and put a link in /etc/ppp
86     that points to the proper place.
87
88     You will also want to set the -arch flags to the appropriate
89     architectures.  Leaving it blank will default to your current
90     architecture.
91
92  9) Do a:
93       make 
94
95  10) If you are satisfied with the results, then as root, type:
96       make install
97
98
99 If you are performing an upgrade, you are done after successfully
100 making and installing the latest release.  All you need to do is to
101 reboot your machine so that the new loadable kernel server (LKS) is
102 loaded. Make sure you remember to edit /etc/rc.local and add the code
103 to load the bpf_reloc LKS (if you enabled BPF support).  You should be
104 able to start the upgraded PPP just like normal.  If this doesn't
105 work, see the "Troubleshooting" section later on.
106
107 Also, you might want to compare the ip-up and ip-down scripts in 
108 the ./NeXT/Examples directory with those you have installed in
109 /etc/ppp/ip-up and /etc/ppp/ip-down.  Most things included in the
110 examples should be in any installation.
111
112
113 Extra Steps for Initial Configuration 
114 =====================================
115
116 If this is the initial installation of PPP, there are several system
117 administration steps that must be performed.  These only need to be
118 done once.  These steps do not need to be re-performed for an upgrade.
119
120 1) Before PPP can successfully run, a module called the loadable
121    kernel server (LKS) must be linked into the system.  This is 
122    something that must be done each time the computer boots up.
123  
124    So that you don't have to do this by hand each time the machine
125    boots, you should modify a file called /etc/rc.local.  Since 
126    this is a system file, you must be root to perform the
127    modification.
128
129    This file contains code that is run each time the machine is
130    started.  This is the standard place where "local" modifications 
131    are made to the system.  First, make a backup copy of /etc/rc.local
132    (maybe named /etc/rc.local.prePPP).  It will be available in case
133    you accidentally mess up the file.  Then, using vi or your favorite
134    editor, place the following lines (not includeing the ==...==
135    separators ;) somewhere near the end of the file /etc/rc.local:
136  
137 ======================================================================
138 #
139 # Load the Berkley Packet Filter LKS
140 # This must be done before PPP.  Comment this out
141 # if you disabled BPF. If you use BPF, you _must_ 
142 # load it before the PPP LKS.  If you chaged pathnames
143 # in the Makefile, make sure the appropriate paths are
144 # used below.
145 #
146 if [ -f /usr/local/bpf/reloc/bpf_reloc ]; then
147        /usr/etc/kl_util -a /usr/local/bpf/reloc/bpf_reloc
148 fi
149
150
151 # Load the selected version of the PPP-2.2 loadable
152 # kernel server (LKS).
153 #     
154 if [ -f /usr/local/ppp/reloc/ppp_reloc ]; then
155         /usr/etc/kl_util -a /usr/local/ppp/reloc/ppp_reloc > /dev/console 2>&1
156         (echo -n ' ppp')        > /dev/console
157 fi
158 ======================================================================
159
160   If you choose not to use BPF, then comment out the first lines
161   of code by adding the '#' mark in front of them (similar to the 
162   comment lines that are already in place).  All three lines
163   (including the 'if' and 'fi') need to be commented.
164
165   This code will now be executed next time you reboot your machine.
166   You can verify that this was executed by checking  the output of
167   /usr/adm/messages upon a successful reboot.  There should be a
168   section of output that says the PPP-2.2 LKS was successfully loaded.
169
170
171 2) The default Makefile paths place PPP files  in a directory called
172    /usr/local/ppp.  There are several subdirectories under this
173    directory.  However, these directories are not part of the standard
174    UNIX Path.  The UNIX Path is a list of directories that UNIX searches 
175    when it is trying to find a command.  There are two solutions
176    to fix the problem.  You may either add specific PPP directories to
177    the current path (must be done for each individual user), or you
178    may add important files to a directory that is already in the
179    standard path.  I believe the second approach is the better
180    solution.  
181
182    This step is optional, but highly recommended.  As root,
183    execute the following commands to add important files
184    to directories that are already in the Standard UNIX path:
185
186    /bin/mkdirs -o root -g wheel -m 755 /usr/local/bin /usr/local/man/man8
187    ln -s /usr/local/ppp/bin/* /usr/local/bin
188    ln -s /usr/local/ppp/man/man8/* /usr/local/man/man8
189
190    To get the man program to understand that you have added some pages
191    to the /usr/local/man directory, you need to make sure that the
192    environment variable MANPATH includes the /usr/local/man entry.  In
193    my .cshrc file (in my home directory) I have an entry that looks like:
194       setenv MANPATH "/usr/local/man:/usr/man:.:.."
195    See 'man man' for more information.
196
197    Once these commands are executed, the programs pppd, pppstats, and
198    chat (along with their respective man pages) will become available
199    to you from the command line.  However, before you can immediately
200    see them, you may need to log out and log back in.
201  
202
203 3) Once you start trying to make PPP connections, it is important
204    to have access to the logging information that PPP generates. This
205    will allow you to follow the progress of PPP and will aid in
206    diagnosing problems.  The user level process 'pppd' outputs
207    logging information by using the standard UNIX syslog facility.
208    Part of this facility allows you to select how much (i.e.
209    what level of verbosity) and where (i.e. to which file) this
210    information will be placed.  While the following step is optional,
211    it is highly recommended.
212
213    As root, make a backup copy of /etc/syslog.conf.  You may wish
214    to call it /etc/syslog.conf.prePPP.  If you run into problems with
215    the system logging error messages, you can replace /etc/syslog.conf
216    with the original, reboot, and then you should be back to normal.
217
218    Now, as root, use vi or your favorite editor to edit the file
219    /etc/syslog.conf.  You need to add the line:
220
221        local2.debug             /usr/adm/ppp2.2.log
222
223    It is _imperative_ that you place a <tab> character
224    between the level "local2.debug" and the file name
225    "/usr/adm/ppp2.2.log.  Do _not_ use spaces. If your
226    editor converts tab characters to spaces, you need to
227    use a different editor.  Also beware of cutting and pasting
228    between buffers.  Sometimes a tab will be converted to spaces
229    during that operation. Below is the actual contents of
230    my /etc/syslog.conf:
231
232 ======================================================================
233 local2.debug                                    /usr/adm/ppp2.2.log
234 *.err;kern.debug;auth.notice                    /dev/console
235 kern.debug;daemon,auth.notice;*.err;mail.crit   /usr/adm/messages
236 mark.debug,daemon.info                          /usr/adm/messages
237 lpr.debug                                       /usr/adm/lpd-errs
238 mail.info                                       /usr/spool/mqueue/syslog
239
240 *.alert;kern.err;daemon.err                     operator
241 *.alert                                         root
242
243 *.emerg                                         *
244 ======================================================================
245
246    Once you have modified /etc/syslog.conf, you then need to perform
247    one more step.  You need to actually create an empty logging file.
248    This step is necessary because if syslog does not see the file, it
249    will not create it.  So, removing the file is a handy way to turn
250    off the logging.  To create an empty logging file, as root execute:
251         touch /usr/adm/ppp2.2.log
252
253    Upon a successful reboot, logging will be enabled for pppd
254    (remember to specify the 'debug' option to pppd to get reasonable 
255    information sent to the logging file).
256
257 4) You should copy a few files to a new directory.  Part of the
258    installation process creates a new directory (or link)
259    called /etc/ppp/. Further, it creates an empty file called
260    /etc/ppp/options. An empty options file is the bare minimum of what
261    is necessary. However, the directory ./NeXT/Examples contains
262    several files that are useful in almost any setup.  It is
263    recommended that you perform the following steps to place better
264    files in the directory /etc/ppp.  As user root, perform the
265    following commands.  It assumes you are in the PPP distribution
266    directory:
267
268      cp NeXT/Examples/options /etc/ppp/options
269      cp NeXT/Examples/ip-up.example /etc/ppp/ip-up
270      cp NeXT/Examples/ip-down.example /etc/ppp/ip-down
271      /usr/etc/chown root.wheel /etc/ppp/options /etc/ppp/ip-up /etc/ppp/ip-down
272      chmod 644 /etc/ppp/options
273      chmod  511 /etc/ppp/ip-up /etc/ppp/ip-down
274  
275
276 5) If you have a standalone machine, it is necessary for you to make
277    sure your system is configured to correctly support a network.  The
278    following steps will help in correctly configuring your machine.
279    Please note, if you do not have a standalone machine (i.e. you are
280    on a local network), you need to speak with your system
281    administrator to determine the proper configuration for your
282    machine.  In most cases, a machine correctly configured for a
283    network will not need to perform the steps listed here. The
284    following only applies to standalone machines.
285
286    It is suggested that you reboot your machine _before_ you start 
287    these procedures.  This is to verify that you successfully
288    completed the previous steps and that your machine does indeed
289    reboot.  If it doesn't, you should replace /etc/rc.local with the
290    backup copy and reboot.  Then, determine why your modifications
291    failed.  After successfully rebooting, you are ready to move on to 
292    these steps.
293
294    As root, make a backup copy of /etc/hostconfig.  You might
295    name it /etc/hostconfig.prePPP.  If, after the following steps, you
296    run into problems booting your machine, you may replace
297    /etc/hostconfig with the backup and you should be able to
298    successfully reboot.
299
300    Start up the HostManager.app (under /NextAdmin).  After
301    successfully entering the root password, you should get the
302    HostManager Menu.  Select the "Local..." menu option to get the
303    main window.  Modify it as follows: 
304
305            For "NetInfo Binding", select "use local domain only"
306            and make sure the box for "Readable only by local net" 
307            is checked.
308
309            For "Hostname", fill in your host name as appropriate.  Do
310            _not_ add the domain name.  For example, use "sidney"
311            rather than "sidney.cps.msu.edu". 
312
313            For "NIS Domain Name", select "None"
314
315            For "Internet Address", use the provided IP address
316            (probably 192.42.172.1) unless your system administrator has
317            assigned you your own unique IP address.  In this case,
318            reverify that you are a standalone machine.  Please
319            note... if your PPP service provider has assigned you an
320            IP address, do _NOT_ use that address here.  That address
321            will be used later.  Use whatever address is already in
322            the display.
323
324            For "Broadcast Address", select "Default"
325         
326            For "Time Standard", select "Ignore Network Time"
327
328            For "Netmask", select "Default"
329
330            For "Router", select "None"
331
332   When this is complete, click the "Set" button.   You will then have
333   the option to reboot or to skip the reboot.  Choose the appropriate 
334   action.  It is suggested that you reboot immediately and verify that
335   your system does indeed reboot (and behave as normal).  If it
336   doesn't, replace /etc/hostconfig with the backup copy and then
337   reboot.  Once you are back up, determine the problem with your
338   configuration. 
339
340   Please note that this description is generic and will work in most
341   cases.  There are lots of variations that people can and will need 
342   to make. Your network administrator will be able to provide you with
343   the correct details for your particular site.
344
345 Congratulations!  You have successfully installed PPP and are now
346 ready to start up a connection.  See the section "Initial Testing" for
347 steps to verify that PPP works on your system.  
348
349
350 Initial Testing
351 ===============
352
353 One of the most notoriously difficult portions of getting PPP links up
354 and running involves writing the script that automatically dials your
355 modem, connects to the peer, and starts the remote ppp process.  Once
356 you are connected to the peer, each PPP process will start
357 communications and things become much easier.
358
359 Before you dive into script writing, there is a simpler solution that
360 will allow you to test the ppp portion.  Once this works, getting the
361 dial scripts to work is a matter of sheer determination!
362
363 The mechanism is this... use a communications package (tip or kermit
364 are good choices) to manually dial the modem and log into the remote
365 server.  There, manually start up the pppd process (the remote
366 process, once started, will probably print some garbage on the screen.
367 You can ignore this). Once this is done, you can exit the
368 communications process (to free up the device it is using).  Then,
369 start your local pppd on the same device.  The pppd processes will
370 then start communicating.  The premise is that you manually perform
371 the operations that you would like your dial script to automatically
372 perform.  Once you _know_ ppp works, you can spend time on the dial
373 scripts.
374
375 Please note, you _must_ exit from your communications program before
376 you start your local pppd.  If you find that when you exit, your modem
377 immediately hangs up, you need to instruct the modem to ignore DTR.
378 There is an AT command that will do this (AT&D on Supra), but you will
379 need to check your modem manual to determine the correct command.
380
381 If you are planning on using kermit, Stephane I. Matis
382 <petergun@vectrex.login.qc.ca>, has supplied this excellent definition
383 that you may place inside your .kermrc file to help with PPP testing:
384 ----------------------------------------------------------------------
385 set term byte 8
386
387 # define pppd 
388 define pppd -
389         !pppd < \v(line) > \v(line) defaultroute
390 ----------------------------------------------------------------------
391
392 To use this, add the above to your ~/.kermrc file (minus the
393 '---...---' separators).  Then start kermit.  After you have started
394 the remote PPP server by hand and you see garbage being printed on the
395 screen, return back to your local kermit prompt and execute the
396 command 'do pppd'.  In this particular circumstance, you will not need
397 to exit completely from kermit.
398
399 Before you start initial testing, you may want to read the pppd man
400 page.  This will allow you to familiarize yourself with the some of
401 the options available to you for starting your local pppd.
402
403 Of particular interest for most people is the 'defaultroute' option to
404 pppd.  If you have a standalone machine, then all your foreign traffic
405 must go to the peer.  Adding the 'defaultroute' option to pppd
406 instructs pppd to set your system up in such a manner.
407
408
409 Determining if the link is actually up
410 ======================================
411
412 There are several ways to determine if the link has actaully been
413 established.  I will go through some of them.
414
415 1) You may look at the pppd log file (typically
416    /usr/adm/ppp2.2.log).  If you see lines that look similar to:
417
418     Jan 11 23:13:38 sidney2b pppd[2141]: local  IP address 35.9.12.55
419     Jan 11 23:13:38 sidney2b pppd[2141]: remote IP address 35.9.10.13
420
421    You are probably up.
422
423 2) You may check the status of the PPP interface.  Using the command:
424      /usr/etc/ifconfig ppp0
425
426    You should see that the interface is UP and that there are valid
427    IP addresses assigned to it (0.0.0.0 is not valid).  Here is an
428    example of what you might see:
429
430         ppp0: flags=51<UP,POINTOPOINT,RUNNING>
431                 inet 35.9.12.104 --> 35.9.10.14 netmask ff000000 
432
433 3) You may check the routing.  When the connection comes up, you
434    should get at least one route to the new interface.  If you
435    specified 'defaultroute' to pppd, you should also see a default
436    route.  The command for checking routes is 'netstat -rn'.  Here
437    is an example of what you might see:
438
439         Routing tables
440         Destination      Gateway            Flags     Refs     Use  Interface
441         35.9.10.32       35.9.15.107        UH          0        0  ppp0
442         127.0.0.1        127.0.0.1          UH         12     2636  lo0
443         35.9.15.107      127.0.0.1          UH          0        0  lo0
444         default          35.9.10.32         UG          2        6  ppp0
445         192.42.172       192.42.172.1       U          15     8872  en0
446
447
448   In the above case, the peer is 35.9.10.32 and my local machine has
449   been assigned 35.9.15.107.  All foreign traffic goes through the
450   default route to the peer.
451
452   If you don't have an ethernet card installed on your system, you
453   will not have an 'en0' interface.
454    
455   
456 The routing issue is important.  Discussion of this issue is outside
457 the scope of these instructions, but I thought it might be beneficial
458 to list a few other important tools that may help you out.  The man
459 pages can give more details:
460   /usr/etc/ping           - send packets to an IP address or hostname
461   traceroute              - Show the route to a particular machine
462
463 The IP address that you use can be negotiated automatically in PPP.
464 Unlike SLIP, you do not have to specify an IP address when the link is
465 brought up.  If no address is specified as an argument to pppd, then
466 PPP will negotiate the address with the peer.  This is the preferred
467 mechanism of operation.  Probably the only time you should specify an
468 IP address as an argument to pppd is if you are assigned your own IP
469 address by your system administrator.  Otherwise, sit back and let PPP
470 do the work for you.  If you are assigned an address by your PPP
471 provider, that address does _NOT_ go in the hostconfig.app or netinfo.
472 Instead, you provide that IP address as a command line option to pppd
473 when you start it up.  See the pppd man page for details on specifying
474 a fixed IP address.
475
476
477 A Typical PPP Session
478 =====================
479
480 A tyipcal PPP session begins when you log into your system.  From a
481 terminal window, you will run your dial script by typing its name at
482 the prompt.  If you use the Workspace manager, you can double click on
483 the scripts icon.  This will start the chat process that will dial the
484 modem and log into the remote system.  It will then turn control over
485 to pppd.  If your script is successful (as described in the
486 "Determining if the link is actually up" section), you will be all
487 set.  All your apps, OmniWeb, FTP, telnet, etc should work.
488
489 Once you are through using the connection, you can close down the PPP
490 link by executing the ppp down script.  Again, this can be done by
491 typing the name of the pppdown script in a terminal window, or double
492 clicking on the appropriate icon in the Workspace manager.  At this
493 point, ppp will terminate the phone connection and pppd will die off.
494
495 You may start and kill the ppp session as many times as you like while
496 you are logged on.  However, if you do not kill the PPP session, it
497 will not die once you log out (unless you use the idle timer option to
498 pppd).  Thus your telephone will remain off the hook and your computer
499 will remain connected to the net until you log back in and shut down
500 the connection.  Turning off the computer will obviously close the
501 connection.
502
503
504 Name Resolution
505 ===============
506
507 Once you have a ppp connection up, you may notice that your machine
508 will not be able to resolve the names of machines to their IP
509 addresses.  You can check this by trying to telnet to a machine outside
510 your local domain.  If "telnet <IP address of machine>" is successful,
511 but "telnet <machinename>" is not, then your name resolution is not
512 configured correctly. The fix is to edit the file /etc/resolv.conf.
513 This file contains two important items.  The first is your domain
514 name.  This is the name that is automatically tacked on to a computer
515 name if you don't specify the complete name.  For example if my domain
516 is 'cps.msu.edu' and I say 'telnet sidney', the computer will try
517 'telnet sidney.cps.msu.edu' (although, it will not print this name on
518 the command line).
519
520 The second thing is a list of name servers.  These should be local to
521 your ppp provider.  Your network administrator will be able to provide
522 you with the appropriate addresses. There are default name servers to
523 use in case the local provider is not responding.  An example file
524 might look like:
525
526 ----------------------------------------------------------------------
527 domain cps.msu.edu
528
529 #
530 # Insert local name servers here
531 #
532
533
534 #
535 # MSU name servers 
536 #
537 nameserver 35.8.2.41
538 nameserver 35.8.2.41
539 nameserver 128.247.160.56
540
541 #
542 # Other servers -- hopefully something will work if needed
543 #shadooby.cc.umich.edu
544 nameserver 35.1.1.91
545 #ns.nasa.gov
546 nameserver 128.102.16.10
547 ----------------------------------------------------------------------
548
549 You will need to reboot your computer for the new nameservers to take
550 effect.
551
552
553 Making startup and shutdown scripts
554 ===================================
555
556 By this time, I'm assuming that PPP has been successfully installed.
557 However, there are a few more steps that you must perform so that
558 using PPP (now and with future upgrades) will be convenient and easy.
559 These steps are optional, but they are highly recommended.
560
561 Make scripts 'pppup' and 'pppdown' that bring up and shutdown PPP
562 connections.  There are a number of example scripts that you can copy
563 and modify.  Reading the man page for 'chat' will help you understand
564 these scripts. You should note that once these scripts are made, you
565 probably won't need to change them for future upgrades to PPP.
566
567 One note that you should be VERY careful about.  These file are shell
568 scripts.  This means that the contents are executed in a shell just as
569 if you had typed them in by hand.  You must make sure that any
570 characters that are treated specially by the shell (such as < > | \ )
571 are inside quotation marks ("").  Otherwise, they will be interpreted
572 by the shell in a manner that is probably to your dislike.  For
573 example, if your peer sends you a prompt like MSUnet> you must add it
574 to the chat portion of your script like "MSUnet>".
575
576 In order to ensure that these scripts are not removed or modified when
577 new versions of PPP are installed, you should copy all important
578 scripts into a new directory.  I suggest /usr/local/ppp/scripts.  This
579 directory will not be modified during installation. Further, as you
580 did earlier for the important binaries, you may want to add important
581 scripts to a directory that is in the default UNIX Search Path.  The
582 mechanism for doing this is as follows.  Suppose you have a script
583 'pppup' (found in /usr/local/ppp/scripts) that you want to be
584 available on your command line.  You could execute the commands:
585   /bin/mkdirs -o root -g wheel -m 755 /usr/local/bin
586   ln -s /usr/local/ppp/scripts/pppup /usr/local/bin
587
588 Once you log out and log back in, this script will be available.  If
589 you want to be able to call this script from a non-root account, you
590 need to modify the permission on the file to make it suid root.
591 Please note that this can be a potential security hazard.  See your
592 system administrator for more details.
593
594 As mentioned above, of particular interest for most people is the
595 'defaultroute' option to pppd.  If you have a standalone machine, then
596 all your foreign traffic must go to the peer.  Remember to add the
597 'defaultroute' option to pppd in your startup scripts if necessary (or
598 place it in the /etc/ppp/options file).
599
600 Troubleshooting
601 ===============
602
603 Any time that you have a bug report, please use the included
604 MailBug.app (in the NeXT directory) to submit an electronic report.
605 If you don't have email capability, please see the WWW site and use
606 the bug report form found there.  Please remember to include your 
607 hardware type and the LKS version number in all reports.  This number
608 may be found in the file /usr/adm/messages (once the LKS has been
609 installed). Also, for most questions, it is best to append a copy of
610 the /usr/adm/ppp2.2.log file.
611
612 If you do have troubles, please see the FAQ on:
613   http://www.thoughtport.com:8080/PPP/
614
615 Here are a few of the more common problems that this FAQ addresses:
616
617 ======================================================================
618 1) pppd bombs out with an error similar to:
619  Jan 26 14:46:25 localhost pppd[256]: Connected...
620  Jan 26 14:46:26 localhost pppd[256]: ioctl(PPPIOCGUNIT): Inappropriate ioctl for device
621  Jan 26 14:46:26 localhost pppd[256]: Exit.
622
623 There are two things that can cause this error.  The most common error
624 is that you are using the innappropriate device for communication to
625 your modem.  You should be using /dev/cufa or /dev/cufb.  Second, the
626 Loadable Kernel Server (LKS) and the user level daemon (pppd) must be
627 of the same version.  While unusual, the error above can be the result
628 of using the wrong Loadable Kernel Server (LKS) with pppd (or vice
629 versa).  Some versions of PPP installed the LKS (ppp_reloc) in
630 /usr/lib/kern_loader/ppp and some in /usr/local/ppp/reloc.  The second
631 is going to be the standard place for installation from now on.
632
633 Solution: Make sure that you are using the appropriate device for
634 communications with your modem.  Further, make sure that your
635 /etc/rc.local is loading the correct version of the LKS and make sure
636 you are really calling the correct pppd for use with the LKS that you
637 loaded. 
638 ======================================================================
639
640 2) PPP works fine, but when the link is up, netinfo sleeps when you
641    try to print or send mail.
642
643 This problem is typically a result of an improper routing setup on the
644 PPP client (your host).  When PPP starts up, it will dynamically
645 negotiate an IP address for use on the PPP interface (usually ppp0).
646 If you don't specify an IP address to pppd, then the address will
647 usually be provided by the peer.  It may change each time that you
648 bring up a PPP link.  If you did specify an IP address, pppd will
649 attempt to use that address first.  If that fails, it will try to get
650 an address from the peer.  Either way, the PPP interface usually has a
651 new IP address.  The routing problem can result when trying to access
652 your local host (and netinfo) on the IP address that was dynamically
653 negotiated.
654
655 Solution: The solution is straightforward.  You must add a route from
656 the IP address that your PPP interface uses to the special loopback IP
657 address 127.0.0.1.  The 'route' command will allow you to do this.
658 For instance, if you are assigned the address 35.8.74.211 during PPP
659 negotiation, you can add the needed route by\7fentering (as the user
660 root):
661
662   /usr/etc/route add 35.8.74.211 127.0.0.1 0
663
664 This route needs to be added each time the link comes up.  However,
665 one problem with hard coding this command into /etc/ppp/ip-up is that
666 you may get a different IP address each time the link comes
667 up. Fortunately, Bill Bereza <berezaw@river.it.gvsu.edu> submitted
668 this nice script clip that can be pasted into /etc/ppp/ip-up.  This
669 will create the correct route entry for you automatically.  Place this
670 in /etc/ppp/ip-up:
671
672     /usr/etc/route add $4 127.0.0.1 0
673
674 You will also want to add this little clip to /etc/ppp/ip-down:                                 <br>
675
676    /usr/etc/route delete $4 127.0.0.1
677
678 This removes the route when your link goes down.
679
680 ======================================================================
681
682 3) People who are trying to set up a NeXT as a PPP server that
683    they dial into often complain that they can make a connection, but
684    the remote machine can only ping the server.  No other packets
685    work.
686
687 Check out the 'proxyarp' option to pppd.  Servers (connected to their
688 LAN) must proxyarp for the remote address (i.e. the address of the
689 machine dialing in).
690
691 ======================================================================
692
693 4) Your pppd/chat dials the modem but you cannot get a negotiation
694    to start.  The /usr/adm/ppp2.2.log file shows something similar
695    to:
696
697   Mar 13 12:02:41 crystal pppd[243]: sent [LCP ConfReq id=0x1 <pcomp> <accomp>]
698   Mar 13 12:02:44 crystal pppd[243]: sent [LCP ConfReq id=0x1 <pcomp> <accomp>]
699   Mar 13 12:02:47 crystal pppd[243]: sent [LCP ConfReq id=0x1 <pcomp> <accomp>]
700   Mar 13 12:02:51 crystal pppd[243]: sent [LCP ConfReq id=0x1 <pcomp> <accomp>]
701   Mar 13 12:02:54 crystal pppd[243]: sent [LCP ConfReq id=0x1 <pcomp> <accomp>]
702   Mar 13 12:02:57 crystal pppd[243]: sent [LCP ConfReq id=0x1 <pcomp> <accomp>]
703   Mar 13 12:03:00 crystal pppd[243]: sent [LCP ConfReq id=0x1 <pcomp> <accomp>]
704   Mar 13 12:03:03 crystal pppd[243]: sent [LCP ConfReq id=0x1 <pcomp> <accomp>]
705   Mar 13 12:03:06 crystal pppd[243]: sent [LCP ConfReq id=0x1 <pcomp> <accomp>]
706   Mar 13 12:03:09 crystal pppd[243]: sent [LCP ConfReq id=0x1 <pcomp> <accomp>]
707   Mar 13 12:03:12 crystal pppd[243]: LCP: timeout sending Config-Requests
708   Mar 13 12:03:12 crystal pppd[243]: Connection terminated.
709   Mar 13 12:03:12 crystal pppd[243]: Serial link is not 8-bit clean:
710   Mar 13 12:03:12 crystal pppd[243]: All received characters had bit 7 set to 0
711
712 Discussion: This is a common problem.  It is typically the result of a
713 failure to properly start the remote PPP process.  The problem arises
714 since the local PPP starts sending packets as soon as chat
715 exits. Since there is no remote PPP process running to interpret the
716 packets, the remote command line interpreter starts sending error
717 messages for each received packet (considered garbage to the remote
718 CLI).  Thus, your local PPP process is receiveing error message text
719 instead of the expected PPP packets.  Since error message text is
720 usually ascii (values < 127) PPP believes that the link is not 8-bit
721 clean.
722
723 Solution: Make sure you add the '-v' option to chat (in your dial
724 script) and then check the output of /usr/adm/ppp2.2.log to see why
725 chat failed to start the remote PPP process.
726
727
728
729 ======================================================================
730
731 5) NXHosting applications over PPP fails.  I don't know why this 
732    happens.  Rest assured, that I and others do have it working.
733    The most obvious things to check are that you have your system set
734    up as a public window server.  Also, make sure that you reset the
735    nmserver in /etc/ppp/ip-up (see the example ip-up file).  If it
736    still doesn't work, you might want to add your peer to your
737    /etc/hosts.equiv file.  I don't know if that has anything to do
738    with it or not, but I don't know why some people can't NXHost
739    and others can.
740
741
742 Updates
743 =======
744
745 You may want to join the mailing list for PPP.  This will keep
746 you informed of new releases and will provide an arena for discussing
747 problems with the NeXT specific PPP port.  To add yourself to the list
748 (or for any other administrative requests), send an email message to:
749         listproc@listproc.thoughtport.com
750 with no subject and message body consisting of:
751         subscribe nextppp Stephen J. Perkins
752 (please use your own name ;). To send mail to all the participants on
753 the list, address your messages to:
754        nextppp@listproc.thoughtport.com
755
756 If you want announcements only, there is a second "announcements only"
757 list.  To subscribe to this, you may use the alternate body:
758         subscribe nextppp-announce Stephen J. Perkins
759 You don't need to subscribe to both.  All announcements are forwarded
760 to the regular list.
761
762 Security
763 ========
764
765 Security issues are not dealt with in this document.  Please
766 note that the pppd file is installed suid root.  This is a potential
767 security hazard.
768
769
770 Noted bugs
771 ==========
772
773 There have been various problems reported when trying to install LKSs
774 the way NeXT intended (i.e. placing them in /usr/lib/kern_loader/* and
775 modifying /etc/kern_loader.conf). The main problem seems to be that
776 after modifying /etc/iftab, /etc/rc.net (on NSFIP) will not correctly
777 configure the interfaces.  This means that booting under NSFIP will
778 hang. So, for the time, it is suggested that you install the package
779 manually and load the LKS in /etc/rc.local.
780
781
782 Modem Configuration
783 ===================
784
785 It is important to use hardware flow control if you use a high speed
786 modem. On my supra V.32bis modem, the command to use Hardware Flow
787 Control is 'AT&K3'.
788
789 Also, you will probably want to set your modem so that when the DTR is
790 dropped, the modem will disconnect.  On my modem the command is
791 'AT&D2' This setting disables auto-answer so if you want to allow
792 dialins, you must read your modem manual to determine the correct
793 setting.
794
795
796 Obtaining the Software by Electronic Mail
797 -----------------------------------------
798
799 Do not send me requests for the software; they will be ignored
800 (without response).  If you cannot use FTP at all, there is a service
801 called "ftpmail" available from decwrl.dec.com: you can send e-mail to
802 this machine and it will use FTP to retrieve files for you and send
803 you the files back again via e-mail.  To find out more about the
804 ftpmail service, send a message to "ftpmail@decwrl.dec.com" whose body
805 consists of the single line "help".
806
807
808 Thanks Stephen J. Perkins