Update 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.peak.org/next/ppp/
8   WWW mirror:   http://www.thoughtport.com:8080/PPP/
9
10   FTP site:     ftp://next-ftp.peak.org/pub/next/apps/internet/ppp/dev
11   FTP Mirror:   ftp://ftp.NMR.EMBL-Heidelberg.DE/pub/next/ppp/
12
13 If you have questions or problems, please visit the WWW site
14 for FAQ and mailing list information.
15
16 NEW: If you want to submit a bug report, please
17      use the bug submission form on the WWW site.
18
19 If you use this software and are pleased with its performance, you are
20 encouraged to make a donation to support continued development.  50%
21 of all donations go to charity.  For more information, please see:
22   http://www.thoughtport.com:8080/cgi-bin/PPP/donation
23
24
25 NeXT Specific Installation Instructions
26 =======================================
27
28 The procedure for an initial installation and for an upgrade are very
29 similar. However, if this is the first time you are installing PPP,
30 there are a few extra steps that you must do for the initial setup.
31 They will be described later in this document.
32
33 Making the source files
34 =========================
35
36 To install on a computer running NeXTSTEP:
37
38  1) Read this file completely through before you start.
39
40  2) If you are on an HP-PA system, read the file
41     ./NeXT/hppa/README.hppa and install the serial
42     driver patch.  Successfull installation of this
43     patch will require a reboot of your machine.  HPPA
44     is no longer supported.
45
46  3) If you have previously installed a SLIP package, comment out
47     the slip configuration code in /etc/rc.local and reboot your
48     machine.  SLIP and PPP _should_ interoperate but for initial
49     testing it is best to remove SLIP.
50
51  4) If you are using Intel OS version 3.3, you _must_ get the latest
52     NeXT serial drivers from NeXTAnswers.  You need both the serial
53     and ttyport drivers (version 3.33 or later).  Install these
54     according to the directions.  PPP-2.3 is optimized to work with 
55     the NeXT drivers.   It will work with the Mux driver (especially
56     beneficial for OS versions prior to 3.3), but that driver has been
57     known to cause panics with PPP.  If you use OS 4.x you can use the
58     drivers that came with the system.
59
60  5) Type ./configure in the top level PPP directory.  This will set
61     up some necessary links.
62
63  6) If you have developer 3.2, you need to use the old version of
64     chat.c.  Perform:
65       a) cd to the chat directory
66       b) backup chat.c (mv chat.c chat.c.orig)
67       c) use the old chat (mv chat.c.3.2 chat.c)
68
69  7) Edit ./Makefile and set the installation directories.
70     If you change the ETCDIR you will need to modify pathnames in
71     pppd/pathnames.h. I recommend keeping it set to /etc/ppp. 
72     If you don't specifically like that directory, you may
73     also change the Makefile directory and put a link in /etc/ppp
74     that points to the proper place. 
75
76     You will also want to set the -arch flags to the appropriate
77     architectures.  Leaving it blank will default to your current
78     architecture. 
79
80  9) Do a:
81       make 
82
83  10) If you are satisfied with the results, then as root, type:
84       make install
85
86
87 If you are performing an upgrade, you are done after successfully
88 making and installing the latest release.  All you need to do is to
89 reboot your machine so that the new loadable kernel server (LKS) is
90 loaded.  You should be able to start the upgraded PPP just like
91 normal.  If this doesn't work, see the "Troubleshooting" section later
92 on.
93
94 Also, you might want to compare the ip-up and ip-down scripts in 
95 the ./NeXT/Examples directory with those you have installed in
96 /etc/ppp/ip-up and /etc/ppp/ip-down.  Most things included in the
97 examples should be in any installation.
98
99
100 Extra Steps for Initial Configuration 
101 =====================================
102
103 If this is the initial installation of PPP, there are several system
104 administration steps that must be performed.  These only need to be
105 done once.  These steps do not need to be re-performed for an upgrade.
106
107 1) Before PPP can successfully run, a module called the loadable
108    kernel server (LKS) must be linked into the system.  This is 
109    something that must be done each time the computer boots up.
110  
111    So that you don't have to do this by hand each time the machine
112    boots, you should modify a file called /etc/rc.local.  Since 
113    this is a system file, you must be root to perform the
114    modification.
115
116    This file contains code that is run each time the machine is
117    started.  This is the standard place where "local" modifications 
118    are made to the system.  First, make a backup copy of /etc/rc.local
119    (maybe named /etc/rc.local.prePPP).  It will be available in case
120    you accidentally mess up the file.  Then, using vi or your favorite
121    editor, place the following lines (not includeing the ==...==
122    separators ;) somewhere near the end of the file /etc/rc.local:
123  
124 ======================================================================
125
126 # Load the selected version of the PPP-2.3 loadable
127 # kernel server (LKS).
128 #     
129 if [ -f /usr/local/ppp/reloc/ppp_reloc ]; then
130         /usr/etc/kl_util -a /usr/local/ppp/reloc/ppp_reloc > /dev/console 2>&1
131         (echo -n ' ppp')        > /dev/console
132 fi
133 ======================================================================
134
135   This code will now be executed next time you reboot your machine.
136   You can verify that this was executed by checking the output of
137   /usr/adm/messages upon a successful reboot.  There should be a
138   section of output that says the PPP-2.3 LKS was successfully loaded.
139
140
141 2) The default Makefile paths place PPP files  in a directory called
142    /usr/local/ppp.  There are several subdirectories under this
143    directory.  However, these directories are not part of the standard
144    UNIX Path.  The UNIX Path is a list of directories that UNIX searches 
145    when it is trying to find a command.  There are two solutions
146    to fix the problem.  You may either add specific PPP directories to
147    the current path (must be done for each individual user), or you
148    may add important files to a directory that is already in the
149    standard path.  I believe the second approach is the better
150    solution.  
151
152    This step is optional, but highly recommended.  As root,
153    execute the following commands to add important files
154    to directories that are already in the Standard UNIX path:
155
156    /bin/mkdirs -o root -g wheel -m 755 /usr/local/bin /usr/local/man/man8
157    ln -s /usr/local/ppp/bin/* /usr/local/bin
158    ln -s /usr/local/ppp/man/man8/* /usr/local/man/man8
159
160    To get the man program to understand that you have added some pages
161    to the /usr/local/man directory, you need to make sure that the
162    environment variable MANPATH includes the /usr/local/man entry.  In
163    my .cshrc file (in my home directory) I have an entry that looks like:
164       setenv MANPATH "/usr/local/man:/usr/man:.:.."
165    See 'man man' for more information.
166
167    Once these commands are executed, the programs pppd, pppstats, and
168    chat (along with their respective man pages) will become available
169    to you from the command line.  However, before you can immediately
170    see them, you may need to log out and log back in.
171  
172 3) Once you start trying to make PPP connections, it is important
173    to have access to the logging information that PPP generates. This
174    will allow you to follow the progress of PPP and will aid in
175    diagnosing problems.  The user level process 'pppd' outputs
176    logging information by using the standard UNIX syslog facility.
177    Part of this facility allows you to select how much (i.e.
178    what level of verbosity) and where (i.e. to which file) this
179    information will be placed.  While the following step is optional,
180    it is highly recommended.
181
182    As root, make a backup copy of /etc/syslog.conf.  You may wish
183    to call it /etc/syslog.conf.prePPP.  If you run into problems with
184    the system logging error messages, you can replace /etc/syslog.conf
185    with the original, reboot, and then you should be back to normal.
186
187    Now, as root, use vi or your favorite editor to edit the file
188    /etc/syslog.conf.  You need to add the line:
189
190        local2.debug             /usr/adm/pppd.log
191
192    It is _imperative_ that you place a <tab> character
193    between the level "local2.debug" and the file name
194    "/usr/adm/pppd.log.  Do _not_ use spaces. If your
195    editor converts tab characters to spaces, you need to
196    use a different editor.  Also beware of cutting and pasting
197    between buffers.  Sometimes a tab will be converted to spaces
198    during that operation. Below is the actual contents of
199    my /etc/syslog.conf:
200
201 ======================================================================
202 local2.debug                                    /usr/adm/pppd.log
203 *.err;kern.debug;auth.notice                    /dev/console
204 kern.debug;daemon,auth.notice;*.err;mail.crit   /usr/adm/messages
205 mark.debug,daemon.info                          /usr/adm/messages
206 lpr.debug                                       /usr/adm/lpd-errs
207 mail.info                                       /usr/spool/mqueue/syslog
208
209 *.alert;kern.err;daemon.err                     operator
210 *.alert                                         root
211
212 *.emerg                                         *
213 ======================================================================
214
215    Once you have modified /etc/syslog.conf, you then need to perform
216    one more step.  You need to actually create an empty logging file.
217    This step is necessary because if syslog does not see the file, it
218    will not create it.  So, removing the file is a handy way to turn
219    off the logging.  To create an empty logging file, as root execute:
220         touch /usr/adm/pppd.log
221
222    Upon a successful reboot, logging will be enabled for pppd
223    (remember to specify the 'debug' option to pppd to get reasonable 
224    information sent to the logging file).
225
226
227 4) You should copy a few files to a new directory.  Part of the
228    installation process creates a new directory (or link)
229    called /etc/ppp/. Further, it creates an empty file called
230    /etc/ppp/options. An empty options file is the bare minimum of what
231    is necessary. However, the directory ./NeXT/Examples contains
232    several files that are useful in almost any setup.  It is
233    recommended that you perform the following steps to place better
234    files in the directory /etc/ppp.  As user root, perform the
235    following commands.  It assumes you are in the PPP distribution
236    directory:
237
238      cp NeXT/Examples/options.example /etc/ppp/options
239      cp NeXT/Examples/ip-up.example /etc/ppp/ip-up
240      cp NeXT/Examples/ip-down.example /etc/ppp/ip-down
241      /usr/etc/chown root.wheel /etc/ppp/options /etc/ppp/ip-up /etc/ppp/ip-down
242      chmod 644 /etc/ppp/options
243      chmod  511 /etc/ppp/ip-up /etc/ppp/ip-down
244
245
246 Congratulations!  You have successfully installed PPP and are now
247 ready to start up a connection.  See the section "Initial Testing" for
248 steps to verify that PPP works on your system.  
249
250
251 Initial Testing
252 ===============
253
254 One of the most notoriously difficult portions of getting PPP links up
255 and running involves writing the script that automatically dials your
256 modem, connects to the peer, and starts the remote ppp process.  Once
257 you are connected to the peer, each PPP process will start
258 communications and things become much easier.  Several frontends are
259 available that help ease this problem.  See:
260   http://www.peak.org/next/ppp/NeXT_PPP_Frontends.html
261 for more information on those.  If you want or need to go the
262 scripting route, then please read on.
263
264 Before you dive into script writing, there is a simpler solution that
265 will allow you to test the ppp portion.  Once this works, getting the
266 dial scripts to work is a matter of sheer determination!
267
268 The mechanism is this... use a communications package (tip or kermit
269 are good choices) to manually dial the modem and log into the remote
270 server.  There, manually start up the pppd process (the remote
271 process, once started, will probably print some garbage on the screen.
272 You can ignore this). Once this is done, you can exit the
273 communications process (to free up the device it is using).  Then,
274 start your local pppd on the same device.  The pppd processes will
275 then start communicating.  The premise is that you manually perform
276 the operations that you would like your dial script to automatically
277 perform.  Once you _know_ ppp works, you can spend time on the dial
278 scripts.
279
280 Please note, you _must_ exit from your communications program before
281 you start your local pppd.  If you find that when you exit, your modem
282 immediately hangs up, you need to instruct the modem to ignore DTR.
283 There is an AT command that will do this (AT&D on Supra), but you will
284 need to check your modem manual to determine the correct command.
285
286 If you are planning on using kermit, Stephane I. Matis
287 <petergun@vectrex.login.qc.ca>, has supplied this excellent definition
288 that you may place inside your .kermrc file to help with PPP testing:
289 ----------------------------------------------------------------------
290 set term byte 8
291
292 # define pppd 
293 define pppd -
294         !pppd < \v(line) > \v(line) defaultroute
295 ----------------------------------------------------------------------
296
297 To use this, add the above to your ~/.kermrc file (minus the
298 '---...---' separators).  Then start kermit.  After you have started
299 the remote PPP server by hand and you see garbage being printed on the
300 screen, return back to your local kermit prompt and execute the
301 command 'do pppd'.  In this particular circumstance, you will not need
302 to exit completely from kermit.
303
304 Before you start initial testing, you may want to read the pppd man
305 page.  This will allow you to familiarize yourself with the some of
306 the options available to you for starting your local pppd.
307
308 Of particular interest for most people is the 'defaultroute' option to
309 pppd.  If you have a standalone machine, then all your foreign traffic
310 must go to the peer.  Adding the 'defaultroute' option to pppd
311 instructs pppd to set your system up in such a manner.
312
313
314 Determining if the link is actually up
315 ======================================
316
317 There are several ways to determine if the link has actaully been
318 established.  I will go through some of them.
319
320 1) You may look at the pppd log file (typically
321    /usr/adm/pppd.log).  If you see lines that look similar to:
322
323     Jan 11 23:13:38 sidney2b pppd[2141]: local  IP address 35.9.12.55
324     Jan 11 23:13:38 sidney2b pppd[2141]: remote IP address 35.9.10.13
325
326    You are probably up.
327
328 2) You may check the status of the PPP interface.  Using the command:
329      /usr/etc/ifconfig ppp0
330
331    You should see that the interface is UP and that there are valid
332    IP addresses assigned to it (0.0.0.0 is not valid).  Here is an
333    example of what you might see:
334
335         ppp0: flags=51<UP,POINTOPOINT,RUNNING>
336                 inet 35.9.12.104 --> 35.9.10.14 netmask ff000000 
337
338 3) You may check the routing.  When the connection comes up, you
339    should get at least one route to the new interface.  If you
340    specified 'defaultroute' to pppd, you should also see a default
341    route.  The command for checking routes is 'netstat -rn'.  Here
342    is an example of what you might see:
343
344         Routing tables
345         Destination      Gateway            Flags     Refs     Use  Interface
346         35.9.10.32       35.9.15.107        UH          0        0  ppp0
347         127.0.0.1        127.0.0.1          UH         12     2636  lo0
348         35.9.15.107      127.0.0.1          UH          0        0  lo0
349         default          35.9.10.32         UG          2        6  ppp0
350         192.42.172       192.42.172.1       U          15     8872  en0
351
352
353   In the above case, the peer is 35.9.10.32 and my local machine has
354   been assigned 35.9.15.107.  All foreign traffic goes through the
355   default route to the peer.
356
357   If you don't have an ethernet card installed on your system, you
358   will not have an 'en0' interface.
359    
360   
361 The routing issue is important.  Discussion of this issue is outside
362 the scope of these instructions, but I thought it might be beneficial
363 to list a few other important tools that may help you out.  The man
364 pages can give more details:
365   /usr/etc/ping           - send packets to an IP address or hostname
366   traceroute              - Show the route to a particular machine
367
368 The IP address that you use can be negotiated automatically in PPP.
369 Unlike SLIP, you do not have to specify an IP address when the link is
370 brought up.  If no address is specified as an argument to pppd, then
371 PPP will negotiate the address with the peer.  This is the preferred
372 mechanism of operation.  Probably the only time you should specify an
373 IP address as an argument to pppd is if you are assigned your own IP
374 address by your system administrator.  Otherwise, sit back and let PPP
375 do the work for you.  If you are assigned an address by your PPP
376 provider, that address does _NOT_ go in the hostconfig.app or netinfo.
377 Instead, you provide that IP address as a command line option to pppd
378 when you start it up.  See the pppd man page for details on specifying
379 a fixed IP address.
380
381
382 A Typical PPP Session
383 =====================
384
385 A tyipcal PPP session begins when you log into your system.  From a
386 terminal window, you will run your dial script by typing its name at
387 the prompt.  If you use the Workspace manager, you can double click on
388 the scripts icon.  This will start the chat process that will dial the
389 modem and log into the remote system.  It will then turn control over
390 to pppd.  If your script is successful (as described in the
391 "Determining if the link is actually up" section), you will be all
392 set.  All your apps, OmniWeb, FTP, telnet, etc should work.  Please
393 note that pppd itself will not appear to do anything but sit there.
394
395 Once you are through using the connection, you can close down the PPP
396 link by executing the ppp down script.  Again, this can be done by
397 typing the name of the pppdown script in a terminal window, or double
398 clicking on the appropriate icon in the Workspace manager.  At this
399 point, ppp will terminate the phone connection and pppd will die off.
400
401 You may start and kill the ppp session as many times as you like while
402 you are logged on.  However, if you do not kill the PPP session, it
403 will not die once you log out (unless you use the idle timer option to
404 pppd).  Thus your telephone will remain off the hook and your computer
405 will remain connected to the net until you log back in and shut down
406 the connection.  Turning off the computer will obviously close the
407 connection.
408
409
410 Name Resolution
411 ===============
412
413 Once you have a ppp connection up, you may notice that your machine
414 will not be able to resolve the names of machines to their IP
415 addresses.  You can check this by trying to telnet to a machine outside
416 your local domain.  If "telnet <IP address of machine>" is successful,
417 but "telnet <machinename>" is not, then your name resolution is not
418 configured correctly. The fix is to edit the file /etc/resolv.conf.
419 This file contains two important items.  The first is your domain
420 name.  This is the name that is automatically tacked on to a computer
421 name if you don't specify the complete name.  For example if my domain
422 is 'cps.msu.edu' and I say 'telnet sidney', the computer will try
423 'telnet sidney.cps.msu.edu' (although, it will not print this name on
424 the command line).
425
426 The second thing is a list of name servers.  These should be local to
427 your ppp provider.  Your network administrator will be able to provide
428 you with the appropriate addresses and you should use those, not the
429 ones listed below.  An example file might look like:
430
431 ----------------------------------------------------------------------
432 domain cps.msu.edu
433
434 #
435 # Insert local name servers here
436 #
437
438
439 #
440 # MSU name servers 
441 #
442 nameserver 35.8.2.41
443 nameserver 35.8.2.41
444 nameserver 128.247.160.56
445
446 ----------------------------------------------------------------------
447
448 You will need to reboot your computer for the new nameservers to take
449 effect.
450
451
452 Making startup and shutdown scripts
453 ===================================
454
455 By this time, I'm assuming that PPP has been successfully installed.
456 However, there are a few more steps that you must perform so that
457 using PPP (now and with future upgrades) will be convenient and easy.
458 These steps are optional, but they are highly recommended.
459
460 Make scripts 'pppup' and 'pppdown' that bring up and shutdown PPP
461 connections.  There are a number of example scripts that you can copy
462 and modify.  Reading the man page for 'chat' will help you understand
463 these scripts. You should note that once these scripts are made, you
464 probably won't need to change them for future upgrades to PPP.
465
466 One note that you should be VERY careful about.  These file are shell
467 scripts.  This means that the contents are executed in a shell just as
468 if you had typed them in by hand.  You must make sure that any
469 characters that are treated specially by the shell (such as < > | \ )
470 are inside quotation marks ("").  Otherwise, they will be interpreted
471 by the shell in a manner that is probably to your dislike.  For
472 example, if your peer sends you a prompt like MSUnet> you must add it
473 to the chat portion of your script like "MSUnet>".
474
475 In order to ensure that these scripts are not removed or modified when
476 new versions of PPP are installed, you should copy all important
477 scripts into a new directory.  I suggest /usr/local/ppp/scripts.  This
478 directory will not be modified during installation. Further, as you
479 did earlier for the important binaries, you may want to add important
480 scripts to a directory that is in the default UNIX Search Path.  The
481 mechanism for doing this is as follows.  Suppose you have a script
482 'pppup' (found in /usr/local/ppp/scripts) that you want to be
483 available on your command line.  You could execute the commands:
484   /bin/mkdirs -o root -g wheel -m 755 /usr/local/bin
485   ln -s /usr/local/ppp/scripts/pppup /usr/local/bin
486
487 Once you log out and log back in, this script will be available.  If
488 you want to be able to call this script from a non-root account, you
489 need to modify the permission on the file to make it suid root.
490 Please note that this can be a potential security hazard.  See your
491 system administrator for more details.
492
493 As mentioned above, of particular interest for most people is the
494 'defaultroute' option to pppd.  If you have a standalone machine, then
495 all your foreign traffic must go to the peer.  Remember to add the
496 'defaultroute' option to pppd in your startup scripts if necessary (or
497 place it in the /etc/ppp/options file).
498
499 Troubleshooting
500 ===============
501
502 Any time that you have a bug report, please use the included
503 MailBug.app (in the NeXT directory) to submit an electronic report.
504 If you don't have email capability, please see the WWW site and use
505 the bug report form found there.  Please remember to include your 
506 hardware type and the LKS version number in all reports.  This number
507 may be found in the file /usr/adm/messages (once the LKS has been
508 installed). Also, for most questions, it is best to append a copy of
509 the /usr/adm/pppd.log file.
510
511 If you do have troubles, please see the FAQ on:
512   http://www.peak.org/next/ppp/
513
514
515 Updates
516 =======
517
518 You may want to join the mailing list for PPP.  This will keep
519 you informed of new releases and will provide an arena for discussing
520 problems with the NeXT specific PPP port.  To add yourself to the list
521 (or for any other administrative requests), send an email message to:
522         majordomo@peak.org
523 with no subject and message body consisting of:
524         subscribe nextppp 
525 (please use your own name ;). To send mail to all the participants on
526 the list, address your messages to:
527        nextppp@peak.org
528
529 If you want announcements only, there is a second "announcements only"
530 list.  To subscribe to this, you may use the alternate body:
531         subscribe nextppp-announce 
532 You don't need to subscribe to both.  All announcements are forwarded
533 to the regular list.
534
535 Security
536 ========
537
538 Security issues are not dealt with in this document.  Please
539 note that the pppd file is installed suid root.  This is a potential
540 security hazard.
541
542
543 Noted bugs
544 ==========
545
546 There have been various problems reported when trying to install LKSs
547 the way NeXT intended (i.e. placing them in /usr/lib/kern_loader/* and
548 modifying /etc/kern_loader.conf). The main problem is that if users
549 have a bad copy of the LKS, the system will panic and will be unable
550 to boot. So, for the time, it is suggested that you install the package
551 manually and load the LKS in /etc/rc.local as directed above.
552
553
554 Modem Configuration
555 ===================
556
557 It is important to use hardware flow control if you use a high speed
558 modem. On my supra V.32bis modem, the command to use Hardware Flow
559 Control is 'AT&K3'.
560
561 Also, you will probably want to set your modem so that when the DTR is
562 dropped, the modem will disconnect.  On my modem the command is
563 'AT&D2' This setting disables auto-answer so if you want to allow
564 dialins, you must read your modem manual to determine the correct
565 setting.
566
567
568 Obtaining the Software by Electronic Mail
569 -----------------------------------------
570
571 Do not send me requests for the software; they will be ignored
572 (without response).  If you cannot use FTP at all, there is a service
573 called "ftpmail" available from decwrl.dec.com: you can send e-mail to
574 this machine and it will use FTP to retrieve files for you and send
575 you the files back again via e-mail.  To find out more about the
576 ftpmail service, send a message to "ftpmail@decwrl.dec.com" whose body
577 consists of the single line "help".
578
579
580 Thanks
581
582 Stephen J. Perkins