install

unix and linux net driver

		PPP-2.3 for systems running NeXTSTEP
                ====================================


Authoritative information can be found at:

  WWW site:     http://www.peak.org/next/ppp/
  WWW mirror:   http://www.thoughtport.com:8080/PPP/

  FTP site:     ftp://next-ftp.peak.org/pub/next/apps/internet/ppp/dev
  FTP Mirror:   ftp://ftp.NMR.EMBL-Heidelberg.DE/pub/next/ppp/

If you have questions or problems, please visit the WWW site
for FAQ and mailing list information.

NEW: If you want to submit a bug report, please
     use the bug submission form on the WWW site.

If you use this software and are pleased with its performance, you are
encouraged to make a donation to support continued development.  50%
of all donations go to charity.  For more information, please see:
  http://www.thoughtport.com:8080/cgi-bin/PPP/donation


NeXT Specific Installation Instructions
=======================================

The procedure for an initial installation and for an upgrade are very
similar. However, if this is the first time you are installing PPP,
there are a few extra steps that you must do for the initial setup.
They will be described later in this document.

Making the source files
=========================

To install on a computer running NeXTSTEP:

 1) Read this file completely through before you start.

 2) If you are on an HP-PA system, read the file
    ./NeXT/hppa/README.hppa and install the serial
    driver patch.  Successfull installation of this
    patch will require a reboot of your machine.  HPPA
    is no longer supported.

 3) If you have previously installed a SLIP package, comment out
    the slip configuration code in /etc/rc.local and reboot your
    machine.  SLIP and PPP _should_ interoperate but for initial
    testing it is best to remove SLIP.

 4) If you are using Intel OS version 3.3, you _must_ get the latest
    NeXT serial drivers from NeXTAnswers.  You need both the serial
    and ttyport drivers (version 3.33 or later).  Install these
    according to the directions.  PPP-2.3 is optimized to work with 
    the NeXT drivers.   It will work with the Mux driver (especially
    beneficial for OS versions prior to 3.3), but that driver has been
    known to cause panics with PPP.  If you use OS 4.x you can use the
    drivers that came with the system.

 5) Type ./configure in the top level PPP directory.  This will set
    up some necessary links.

 6) If you have developer 3.2, you need to use the old version of
    chat.c.  Perform:
      a) cd to the chat directory
      b) backup chat.c (mv chat.c chat.c.orig)
      c) use the old chat (mv chat.c.3.2 chat.c)

 7) Edit ./Makefile and set the installation directories.
    If you change the ETCDIR you will need to modify pathnames in
    pppd/pathnames.h. I recommend keeping it set to /etc/ppp. 
    If you don't specifically like that directory, you may
    also change the Makefile directory and put a link in /etc/ppp
    that points to the proper place. 

    You will also want to set the -arch flags to the appropriate
    architectures.  Leaving it blank will default to your current
    architecture. 

 9) Do a:
      make 

 10) If you are satisfied with the results, then as root, type:
      make install


If you are performing an upgrade, you are done after successfully
making and installing the latest release.  All you need to do is to
reboot your machine so that the new loadable kernel server (LKS) is
loaded.  You should be able to start the upgraded PPP just like
normal.  If this doesn't work, see the "Troubleshooting" section later
on.

Also, you might want to compare the ip-up and ip-down scripts in 
the ./NeXT/Examples directory with those you have installed in
/etc/ppp/ip-up and /etc/ppp/ip-down.  Most things included in the
examples should be in any installation.


Extra Steps for Initial Configuration 
=====================================

If this is the initial installation of PPP, there are several system
administration steps that must be performed.  These only need to be
done once.  These steps do not need to be re-performed for an upgrade.

1) Before PPP can successfully run, a module called the loadable
   kernel server (LKS) must be linked into the system.  This is 
   something that must be done each time the computer boots up.
 
   So that you don't have to do this by hand each time the machine
   boots, you should modify a file called /etc/rc.local.  Since 
   this is a system file, you must be root to perform the
   modification.

   This file contains code that is run each time the machine is
   started.  This is the standard place where "local" modifications 
   are made to the system.  First, make a backup copy of /etc/rc.local
   (maybe named /etc/rc.local.prePPP).  It will be available in case
   you accidentally mess up the file.  Then, using vi or your favorite
   editor, place the following lines (not includeing the ==...==
   separators ;) somewhere near the end of the file /etc/rc.local:
 
======================================================================
# 
# Load the selected version of the PPP-2.3 loadable
# kernel server (LKS).
#     
if [ -f /usr/local/ppp/reloc/ppp_reloc ]; then
	/usr/etc/kl_util -a /usr/local/ppp/reloc/ppp_reloc > /dev/console 2>&1
	(echo -n ' ppp')	> /dev/console
fi
======================================================================

  This code will now be executed next time you reboot your machine.
  You can verify that this was executed by checking the output of
  /usr/adm/messages upon a successful reboot.  There should be a
  section of output that says the PPP-2.3 LKS was successfully loaded.


2) The default Makefile paths place PPP files  in a directory called
   /usr/local/ppp.  There are several subdirectories under this
   directory.  However, these directories are not part of the standard
   UNIX Path.  The UNIX Path is a list of directories that UNIX searches 
   when it is trying to find a command.  There are two solutions
   to fix the problem.  You may either add specific PPP directories to
   the current path (must be done for each individual user), or you
   may add important files to a directory that is already in the
   standard path.  I believe the second approach is the better
   solution.  

   This step is optional, but highly recommended.  As root,
   execute the following commands to add important files
   to directories that are already in the Standard UNIX path:

   /bin/mkdirs -o root -g wheel -m 755 /usr/local/bin /usr/local/man/man8
   ln -s /usr/local/ppp/bin/* /usr/local/bin
   ln -s /usr/local/ppp/man/man8/* /usr/local/man/man8

   To get the man program to understand that you have added some pages
   to the /usr/local/man directory, you need to make sure that the
   environment variable MANPATH includes the /usr/local/man entry.  In
   my .cshrc file (in my home directory) I have an entry that looks like:
      setenv MANPATH "/usr/local/man:/usr/man:.:.."
   See 'man man' for more information.

   Once these commands are executed, the programs pppd, pppstats, and
   chat (along with their respective man pages) will become available
   to you from the command line.  However, before you can immediately
   see them, you may need to log out and log back in.
 
3) Once you start trying to make PPP connections, it is important
   to have access to the logging information that PPP generates. This
   will allow you to follow the progress of PPP and will aid in
   diagnosing problems.  The user level process 'pppd' outputs
   logging information by using the standard UNIX syslog facility.
   Part of this facility allows you to select how much (i.e.
   what level of verbosity) and where (i.e. to which file) this
   information will be placed.  While the following step is optional,
   it is highly recommended.

   As root, make a backup copy of /etc/syslog.conf.  You may wish
   to call it /etc/syslog.conf.prePPP.  If you run into problems with
   the system logging error messages, you can replace /etc/syslog.conf
   with the original, reboot, and then you should be back to normal.

   Now, as root, use vi or your favorite editor to edit the file
   /etc/syslog.conf.  You need to add the line:

       local2.debug		/usr/adm/pppd.log

   It is _imperative_ that you place a <tab> character
   between the level "local2.debug" and the file name
   "/usr/adm/pppd.log.  Do _not_ use spaces. If your
   editor converts tab characters to spaces, you need to
   use a different editor.  Also beware of cutting and pasting
   between buffers.  Sometimes a tab will be converted to spaces
   during that operation. Below is the actual contents of
   my /etc/syslog.conf:

======================================================================
local2.debug					/usr/adm/pppd.log
*.err;kern.debug;auth.notice			/dev/console
kern.debug;daemon,auth.notice;*.err;mail.crit	/usr/adm/messages
mark.debug,daemon.info				/usr/adm/messages
lpr.debug					/usr/adm/lpd-errs
mail.info					/usr/spool/mqueue/syslog

*.alert;kern.err;daemon.err			operator
*.alert						root

*.emerg						*
======================================================================

   Once you have modified /etc/syslog.conf, you then need to perform
   one more step.  You need to actually create an empty logging file.
   This step is necessary because if syslog does not see the file, it
   will not create it.  So, removing the file is a handy way to turn
   off the logging.  To create an empty logging file, as root execute:
        touch /usr/adm/pppd.log

   Upon a successful reboot, logging will be enabled for pppd
   (remember to specify the 'debug' option to pppd to get reasonable 
   information sent to the logging file).


4) You should copy a few files to a new directory.  Part of the
   installation process creates a new directory (or link)
   called /etc/ppp/. Further, it creates an empty file called
   /etc/ppp/options. An empty options file is the bare minimum of what
   is necessary. However, the directory ./NeXT/Examples contains
   several files that are useful in almost any setup.  It is
   recommended that you perform the following steps to place better
   files in the directory /etc/ppp.  As user root, perform the
   following commands.  It assumes you are in the PPP distribution
   directory:

     cp NeXT/Examples/options.example /etc/ppp/options
     cp NeXT/Examples/ip-up.example /etc/ppp/ip-up
     cp NeXT/Examples/ip-down.example /etc/ppp/ip-down
     /usr/etc/chown root.wheel /etc/ppp/options /etc/ppp/ip-up /etc/ppp/ip-down
     chmod 644 /etc/ppp/options
     chmod  511 /etc/ppp/ip-up /etc/ppp/ip-down


Congratulations!  You have successfully installed PPP and are now
ready to start up a connection.  See the section "Initial Testing" for
steps to verify that PPP works on your system.  


Initial Testing
===============

One of the most notoriously difficult portions of getting PPP links up
and running involves writing the script that automatically dials your
modem, connects to the peer, and starts the remote ppp process.  Once
you are connected to the peer, each PPP process will start
communications and things become much easier.  Several frontends are
available that help ease this problem.  See:
  http://www.peak.org/next/ppp/NeXT_PPP_Frontends.html
for more information on those.  If you want or need to go the
scripting route, then please read on.

Before you dive into script writing, there is a simpler solution that
will allow you to test the ppp portion.  Once this works, getting the
dial scripts to work is a matter of sheer determination!

The mechanism is this... use a communications package (tip or kermit
are good choices) to manually dial the modem and log into the remote
server.  There, manually start up the pppd process (the remote
process, once started, will probably print some garbage on the screen.
You can ignore this). Once this is done, you can exit the
communications process (to free up the device it is using).  Then,
start your local pppd on the same device.  The pppd processes will
then start communicating.  The premise is that you manually perform
the operations that you would like your dial script to automatically
perform.  Once you _know_ ppp works, you can spend time on the dial
scripts.

Please note, you _must_ exit from your communications program before
you start your local pppd.  If you find that when you exit, your modem
immediately hangs up, you need to instruct the modem to ignore DTR.
There is an AT command that will do this (AT&D on Supra), but you will
need to check your modem manual to determine the correct command.

If you are planning on using kermit, Stephane I. Matis
<[e-mail]>, has supplied this excellent definition
that you may place inside your .kermrc file to help with PPP testing:
----------------------------------------------------------------------
set term byte 8

# define pppd