
INSTALLATION

  Before you can compile and install xisp from this source distribution,
  you need to make sure that you have a properly installed copy of the
  XForms GUI library, version 0.89 or later. The URLs from which you
  could download XForms are listed in the first paragraph of file README.

  In order to install the 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:

                      =================================
                        Compilation/installation vars
                      =================================

          PREFIX: base directory path for installed files

       X11PREFIX: base X11 directory path

          INCX11: path to X11 include files

          LIBX11: path to X11 libraries

        INCFORMS: where the forms.h include file is installed

        LIBFORMS: where the libforms.so.0.89 library is installed

       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

         SBINDIR: path to the chat and pppd binaries

          VARRUN: path to where pppd writes its ppp?.pid files (read
                  your pppd(8) manual page for this one)

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

         OPTSDIR: where to install the options.xisp file; note that
                  this file is *not* installed by default; install it
                  manually or uncomment the installation lines in
                  Makefile if you so desire; read the first paragraph
                  below these explanations for the Makefile variables
                  for details

          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.

      PPPDLCKDIR: path to lock files created by pppd for the modem device
                  currently in use; these are pre-adjusted for the each
                  supported operating system and shouldn't need tweeking;
                  however, if you find that your case is different, please
                  do drop me a line.

         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

        GCCFLAGS: the gcc compilation flags

       EXTRADEFS: extra defines needed for the platform and/or version
                  of C library xisp is being compiled under

       EXTRALIBS: extra libraries needed when linking the xisp binary
                  (also platform and/or C library specific)

         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

                      =================================
                        Program configuration options
                      =================================

        XPMIMAGE: the XPM icon used by xisp; you have three static icon
                  options and one animated sequence option which requires
                  enabling ANIMATE -- read below.

         ANIMATE: if defined, the animated icon sequence will be used
                  instead of the static icon defined via XPMIMAGE; only a
                  single image sequence option is available (if you create
                  a nifty sequence that you think is worthwhile sharing,
                  please do send it over :))

         USESENV: by default, dialing environment is passed to xispdial via
                  the XISPENV variable; if you prefer to use the old style
                  environment file instead, or if your version of pppd
                  discards all environment information (this happens to be
                  the case for Solaris-2.5 and later, or SunOS 4.1.x),
                  comment out this definition.

        XISPUSER: selecting the second option for these three variables,
        SHAREALL  will enable you to install a shared xisp binary; this
        SHAREOBJ  basically means that all users will be using the same
                  xisp configuration and logging files (comes handy when
                  e.g. all are using the same ISP account and you want
                  to keep phone-call cost logs in one place).


       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.

       - If for some obscure reason your pppd was built with the option
         for not generating $(RUNDIR)/ppp?.pid files when active, simply
         delete the RUNPATH variable from the Makefile, in order to make
         use of alternative code implemented in xisp for retrieving pppd's
         PID number.

       - Pick the icon you desire from those available, according to the
         colors you have available on your colormap. If you have a few
         extra colors to spare, try the XPM animation option.

       - As of version 1.7 of xisp, the pppd options file options.xisp is
         no longer necessary. However, if such a file is indeed found, it
         is used by xisp's invocation of pppd. If you need to use some
         pppd option not available from within xisp, that's certainly the
         place to put it in. Right now, the sample options.xisp file
         contains a single pppd option line (noipdefault). Since it is
         no longer installed by default, install it if and whenever you
         need it. If you have options.xisp from some previous version of
         xisp, please delete it. Furthermore note that since xisp version
         2.5p3, if your pppd version is 2.3.x or later (you can find that
         out by doing a "pppd --version"), instead of using options.xisp,
         you can add any additional options you require in any or all peer
         information files "xisp_<modem device file>"; such a peer file
         is installed by default in /etc/ppp/peers when you do "make
         install"; read the next paragraph for details.

    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".

    4. If you are building a shared xisp binary (XISPUSER, SHAREALL and
       SHAREOBJ Makefile variables -- read "Program configuration options"
       in section 1 above), create the user name defined by XISPUSER and
       a home directory for it.

    5. If all has gone well, 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.

    6. 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
  $HOME/.xisplogs/xispPTTs ASCII data base file.


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 have made an effort to document the code as much as
  possible so that it should be fairly readable, and hence easily modifiable
  by others. A little note here on editing the sources: the tabstop used for
  all files is 4 (i.e. "set tabstop=4" in vi). I would appreciate any
  feedback, suggestions or enhancements you might have :)

  Enjoy,

  Dimitri

