
INSTALLATION

  In order to install the "ready to run" binary xisp package follow
  the steps outlined below.

    1. Edit the Makefile and make sure that all paths defined in the
       variables therein correspond to the proper paths for your system.
       The following is a list of variables defined in Makefile with
       some brief explanations:

          PREFIX: base directory path for installed files

       X11PREFIX: base X11 directory path

       MODEM_DEV: the serial device (serial port) your modem is attached
                  to (e.g. "modem" for /dev/modem, "ttyS0 for COM1, "ttyS1"
                  for COM2, etc.). Since a peer information file (read
                  sections (2) and (4) below) needs to be installed for
                  each modem on your machine, setting this variable
                  correctly is an easy way of creating your default
                  modem peer file automatically when you do "make install".
                  Files for additional serial ports can be easily created
                  by copying/modifying the file generated automatically by
                  this Makefile

      MODEM_PATH: on some operating systems you might have to change this;
                  for example, under Solaris-2.x, the path to serial port
                  devices is not /dev, but /dev/cua; in such a case, and for
                  serial port A, the MODEM_DEV variable (above) should be
                  set to "a", and MODEM_PATH to "/dev/cua/$(MODEM_DEV)".

          BINX11: where to install the xisp binary

        USRLOCAL: where to install the xisprccv and xispid utilities

       USRLIBPPP: where to install the xispterm and xispdial utilities
                  used by xisp

          MANDIR: where to install the xisp manual page

          ETCPPP: where the ppp scripts can be found by xisp (normally
                  /etc/ppp, read your pppd(8) manual page to make sure).

      INSTPPPDIR: where to install ip-up and ip-down; both are installed
                  by default, and any existing scripts are saved as
                  *.bak; comment-out the lines in Makefile to prevent
                  this from happening; read below for details.
                  Additionally, appropriately modified versions of the
                  peer information files "xisp.peers.device" and
                  "xisp.peers.dialer" are installed in subdirectory
                  "peers" in the directory specified by this Makefile
                  variable; existing peer information files are saved as
                  *.bak. The default value for INSTPPPDIR is usually the
                  same as for ETCPPP, but if you don't want to overwrite
                  your current ppp scripts, set this to another path.

         DESTDIR: root path for installation; most probably you don't
                  need to edit this variable

           GROUP: group ownership for xisp, xispdial, xispterm, xisprccv
                  and xispid; used to implement selective permissions for
                  xisp; read section "PERMISSIONS" below for details

         INSTALL: your install program (normally set to "install"); can be
                  used for accommodating special installation tools, e.g.
                  for the Slackware Linux distribution it can be specified
                  as: INSTALL = pkginstall install -c

       The rest of the variables most probably do not need any editing;
       if you need to modify something more for your system even though a
       Makefile section for your case exists, please do drop me a line.

    2. Make sure that your /etc/ppp/options file (or wherever else pppd
       keeps its default-options file), as well as your .ppprc file (read
       the pppd(8) manual page for details), do not include the -detach
       option, or any other option in conflict with any of the options
       supported by xisp. If you're not sure of what to do, leave this
       file the way it is and check it *last* if things go persistently
       wrong. Just in case you're contemplating deleting the pppd default
       options file /etc/ppp/options altogether, note that it is *REQUIRED*
       by pppd; if it can't find it, it will exit with error.
       If your pppd version is 2.3.x or later, then instead of modifying
       /etc/ppp/options, edit file xisp.peers.device, the per-modem-device
       xisp peer information file installed by default by "make install"
       in /etc/ppp/peers. Please do not delete any lines from this file
       as all are required for proper xisp operation, while adding any
       extra pppd options you might need (typically you wouldn't need
       to add options to this file). With regards to the default options
       set for pppd 2.3.x (i.e. the default contents of /etc/ppp/options),
       the only one recommended for proper xisp operation is the "auth"
       option. The "lock" option is not required as it is specified by
       xisp on pppd command line, and the "usehostname" option interferes
       with xisp's operation when using CHAP authenticated ISP accounts.

    3. Run "make install".
       In order to make use of the DNS capabilities implemented in xisp,
       "make install" automatically installs the ip-up.xisp and
       ip-down.xisp scripts supplied, as ip-up and ip-down respectively,
       while keeping back-up copies of your old scripts, if any. If you
       don't want that to happen, comment-out the appropriate lines in
       the Makefile, prior to running "make install". For details on this
       matter, read the "IP-UP/-DOWN SCRIPTS" section below.
       "make install" also installs the default peer information file,
       /etc/ppp/peers/xisp_modem. If you plan to use serial devices other
       than the default "/dev/modem", make sure you add peer information
       files for each one, by following the detailed comments included in
       /etc/ppp/peers/xisp_modem.

    4. The  first time you start xisp, go to Options->Paths Setup and
       adjust the xisp paths according to where you installed the xisp
       components, and also according to information specific to your
       system with regards to your PPP installation. For details, from
       within xisp read the appropriate section in Help->General.

    5. Read the following two sections (at least :)) to complete tasks
       related to user access permissions.


PERMISSIONS

  You will note that xisp, xispdial, xispterm, xisprccv and xispid
  binaries are installed with mode 750 and owned by root and group uucp
  ("dialout" for Debian Linux or "root" for Red Hat Linux). This is so
  that system administrators can implement selective permission for xisp,
  by giving access only to users which are also members of the uucp (or
  dialout, or root) group. The modem device, as well as pppd and chat
  should also have access permissions allowing uucp (or dialout, or root)
  group processes running xisp, xispdial and xispterm to use them. In
  other words, if the above sounds like a good idea, and if your system
  is not already setup that way, go to wherever you have pppd and chat
  and do:
                    --------------- put "dialout" here, for Debian,
                   |                or "root" for Red Hat Linux
                  \|/
       chown root:uucp pppd chat
       chmod 4550 pppd <----------- the '4' ahead of the '550' on this
       chmod 550 chat               line enables permission for normal
                                    users (i.e. users other than root)
                                    to use pppd and consequently xisp,
                                    by making the pppd binary suid root.

  +----------------------------------------------------------------------+
  | NOTE: If you give users other than members of group uucp (or dialout |
  |       or root) execute permission for pppd and/or xisp, the ip-up    |
  |       and ip-down scripts supplied with xisp will NOT RUN for these  |
  |       users, as this would have a serious impact on system security. |
  |       Please read file SECURITY for details on this matter.          |
  +----------------------------------------------------------------------+

  After doing the above, you might also go to /dev and do:

                    --------------- put "dialout" here, for Debian,
                   |                or "root" for Red Hat Linux
                  \|/
       chown root:uucp modem
       chmod 660 modem

  where "modem" is your modem port device (usually ttyS[0,1,2,..]).
  Don't perform the above on the symbolic link pointing to your modem
  device if that's how things are set up on your system, but to the
  device file itself (i.e., if you have /dev/modem -> /dev/ttyS1 for
  example, use "ttyS1" in place of "modem" for the above commands.

  Remember that when using pppd version 2.3.x or later, each serial
  device with a modem connected to it which you wish to use with xisp,
  needs a peer information file of its own. Please read the comments
  in the default peer information file /etc/ppp/peers/xisp_modem (or
  the template file xisp.peers.device in xisp's source distribution)
  for detailed instructions.

  Finally edit /etc/group (or the NIS/NIS+ group database) and add
  the users you want to give access to xisp, to the list of uucp (or
  "dialout" for Debian Linux, or "root" for Red Hat Linux) group
  members.


IP-UP/-DOWN SCRIPTS

  Default ip-up (ip-ip.xisp) and ip-down (ip-down.xisp) scripts are
  supplied with this distribution for use with pppd. If you need to
  use the DNS capabilities in xisp, you *MUST* install the supplied
  ip-up and ip-down scripts. To modify them further for performing
  tasks like, for example, downloading mail or news on a per ISP basis,
  read the comments therein and edit them to suit your needs. If you
  need to do this on a user basis (rather than having these tasks run
  as root) you can make use of the .xisp-up and .xisp-down files in
  each user's home directory. Read the xisp(1) manual page for details.
  Both .xisp-up and .xisp-down are called with the same arguments as
  ip-up and ip-down. Read the comments in the supplied .xisp-up and
  .xisp-down skeleton files for helpful instructions.

  The installation automatically keeps backup copies of your old ip-up
  and ip-down scripts. If your pppd looks for them in a directory other
  than /etc/ppp, change the ETCPPP Makefile variable appropriately.
  Their access permissions once installed correspond to:

                ----------------- automatically adjusted by Makefile to
               |                  the value selected for variable GROUP
               |                  (see explanations for the Makefile
               |                  variables in paragraph (1) above)
              \|/
   chown root:uucp ip-up ip-down
   chmod 750 ip-up ip-down


UPGRADE CONVERTER

  As of xisp version 1.3 a resource control file (.xisprc) converter is
  also included in the distribution. This utility does not only understand
  the .xisprc format for the immediately previous xisp version, but all
  version formats from xisp-1.2 and onwards. To convert your old .xisprc
  file to the latest version, run xisprccv with no arguments.


PHONE COMPANIES (PTTs)

  Since xisp-2.4, the phone companies' tariff information can be entered
  in a special ASCII data base maintained by xisp. The first time xisp is
  run, it creates this data base and populates it with the phone company
  information built in to it. If you wish to contribute an entry to the
  ones known by xisp, simply enter the company information using xisp's
  PTT editor, and then e-mail the company's section from your


EPILOGUE

  If you encounter any problems, or find any bugs, please report them
  to the e-mail address listed at the end of the README file, or in the
  "Help->About" form.  I would appreciate any feedback, suggestions or
  enhancements you might have :)

  Enjoy,

  Dimitri

