
REQUIREMENTS

  In order to make use of the xisp package, you need to have ppp-2.2.0f
  or newer properly installed on your system. You also need to configure
  your modem for verbose result codes, as well as for reporting your
  true connection speed rather than the computer-modem connection speed.
  Connection must be reported via a 'CONNECT xxxxx' string where 'xxxxx'
  is the speed string, and a busy phone status must be indicated by
  the string 'BUSY'. To compile and install the package you need a
  properly installed X11R6 or newer, as well as the forms library (XForms
  GUI by T.C. Zhao and Mark Overmars) with version 0.81 or newer. You can
  get a copy of this library from: http://bragg.phys.uwm.edu/xforms.


GENERAL

  The xisp package implements a user-friendly interface to pppd/chat
  and provides maximum feedback from the dial-in and login phases on a
  browser screen. It also provides greater versatility in interrupting a
  call in progress and in general enhances the user's feeling of "what's
  going on", especially if he/she is not all that well acquainted with
  the intricacies of system log files. It's also much nicer to look at
  as compared to connection scripts writing output on the terminal :)
  The main application, xisp, relies on a special dialer, xispdial,
  which is spawned by pppd in order to do the dialing. For more details
  on the workings of xisp and xispdial as well as their interaction with
  pppd and chat, see the "ARCHITECTURE" section below. The other
  facility provided by xisp is that of maintaining a small data base of
  ISP's. It currently supports 8 such ISP entries. Each entry, aside
  from user account name and password, has space for 8 telephone
  numbers, two dialing parameters determining number of redials and
  inter-dialing delay, as well as 8 user customizable script lines for
  the chat program. All data base information is saved in the xisp
  resource file (.xisprc) in the user's home directory. The file size
  is a little over 3.5k. For details on the user interface look in the
  "USER INTERFACE" section below. As of version 1.3, a .xisprc file
  converter (xisprccv) is provided with each new release, for upgrading
  your .xisprc if its format was changed in this new release.


ARCHITECTURE

  The architecture of the xISP and xispdial applications, and their
  interaction with pppd and chat are depicted in the schematic
  representation below.

                                           +-------------+
                                           |             |
            +-------------+                |             |
            |             |                |             |
            |             |     Exec      \|    pppd     |
            |             |----------------|             |
            |             |               /|             |
            |             |                |             |
            |             |                +-------------+
            |             |                   /|\    |
            |     xISP    |                    |     |
            |             |                    |    \|/
            |             |  Dialing       +-------------+
            |             |  Environment  \|             |
            |             |----------------|             |
            |             |               /|             |
            |             |/               |   xispdial  |
            |             |----------------|             |
            |             |\     Named     |             |
            +-------------+      Pipe      |             |
                                           +-------------+
                                              /|\    |
                                               |     |
                                               |    \|/
                                           +-------------+
                                           |             |
                                           |    chat     |
                                           |             |
                                           +-------------+

  The way it works goes like this. When an ISP is selected in xISP,
  a dialing environment file (.xispenv) is created in the user's
  home directory. The file contains all the information needed by
  xispdial in order to complete the dial, i.e., the user account name,
  the password, the phone numbers to dial, and the script lines
  containing the special prompts used by the ISP during login. Then,
  pppd is started, with xispdial as its connect program. Then pppd
  starts xispdial, which reads the dialing environment file, stores all
  the info internally and deletes the file. xispdial then proceeds to
  make the connection using chat. All output from chat as well as any
  report messages from xispdial are conveyed to xISP via a named pipe
  residing in /tmp (.xisppipe.<username>). The link status, once a ppp
  link is set up is monitored by xisp every 15 seconds. If for some
  reason the link drops, the status on your xisp window will be updated
  in at most 15 seconds at which time the "Connect" button will be
  activated again enabling you to redial for a new connection. A future
  release will include an option for automatic redialing.


USER INTERFACE

  When started, xisp displays a form with five buttons and two menus.
  Normally, in order to commence dialing, an ISP must be selected. The
  one selected by default right after startup is the first entry in the
  list of ISP's. The "Quit" button is always activated. The other
  button activated at this time is the "Connect" button. After a
  connection is initiated, and up until a ppp link is established,
  "Connect" is deactivated while "Interrupt" is activated. After a link
  is established, "Interrupt" is deactivated and "Disconnect" is
  activated. The fifth button labeled "ARD" indicates whether or not
  automatic redialing is desired for the selected ISP. When automatic
  redialing is indeed selected, if the PPP connection drops without the
  user explicitly pressing "Disconnect", redialing occurs. The "Help"
  menu selection is self explanatory, I guess :). The "Options" menu
  contains three items, "Select ISP", "Account Data" and "Dialing Data".

  "Select ISP"
     Brings up a list of ISP's to choose from. The first time xisp is
     executed all ISP names will be blank, as indicated by the '~'
     character (I wonder where I got that idea :)). One can edit the ISP
     name by marking the entry and then pressing "Rename", or double
     clicking on the entry. Pressing "OK" returns you to the main
     program window and sets your selection as the current ISP.

  "Account Data"
     Brings up a window with three input fields. The first is the list
     of phone numbers to dial for the selected ISP, the second is the
     user account name to use, and the third is the password. More than
     one telephone numbers, and up to a total of 8, can be entered by
     separating them with the ';' character. The total internal length
     of a phone number is currently limited to 32 characters. Any
     modifications you make to any input field are entered into the
     corresponding record for the current ISP in the xisp resource file.
     A brief note on password security is in order here. The plaintext
     password entered in the "Password" input field is encoded using
     encrypt with a key saved in the xisp executable. This key is itself
     scrambled so that it is not visible in the xisp binary. Since any
     one having access to the source can eventually come up with the key
     used and potentially decode users' .xisprc entries yielding the
     plaintext ISP passwords, system administrators installing xisp are
     URGED to change the key employed. For more details, read the
     SECURITY file included with xisp distribution.

  "Dialing Data"
     Brings up a window with fields for entering the two dialing
     parameters, namely the number of redials and the inter-dialing
     delay, as well as up to eight user customizable script lines. The
     first two fields are pretty straight forward, and default values for
     both are suggested. In the third input field, in the script section
     that is, the user must enter the script lines employed by chat to
     successfully negotiate a login for the particular ISP. For syntax
     and various examples please see the chat(8) manual page. The
     following simple example should give you an idea. Let us assume
     that the ISP of interest employs a terminal server which prompts
     the user with 'Username:', then with 'password:' and then gives the
     server prompt, a single '>', at which point the user must type 'ppp'
     and press enter. The user customizable script lines for the above
     procedure would have to be:

         ername:--ername: %s
         ssword: %s
         >--> ppp

     Note the two "%s"'s in the script lines. The first one is (quite
     obviously) replaced by your user account name (by the xisp program
     when it creates the dialing environment file), and the second one
     by your password. Exactly two "%s"'s are required in your script
     lines. Entering more or less will make xisp print a message and
     abort the dial.

  The program main window includes four connection indicators. The "IP"
  indicator prints the IP address assigned to you after successfully
  establishing a ppp link. The "Status" indicator is self explanatory I
  guess :). The "Speed" indicator prints the speed as returned by the
  modem "CONNECT" message, and the "Connect Time" indicator measures
  your connection time with a resolution of five seconds. The measured
  time will remain there after disconnection, until a new dialing
  sequence is initiated.


XISPDIAL

  The script employed by xispdial for the connection is the
  concatenation of its internal script, and the user customizable script
  lines entered via xisp. The internal script used is the following:

     TIMEOUT  3
     ABORT    BUSY
     ABORT    'NO CARRIER'
     ABORT    enied
     ABORT    imeout
     ''       AT\\sDT\\s<the phone number>
     TIMEOUT  50
     CONNECT  ''
     TIMEOUT  5

  As seen above, the timeout value after connection is set to 5 seconds.
  If for some reason it takes more than that to log into a system, one
  could specify a new timeout value in the user script lines. For
  instance, in the example given in the previous section, if it takes 6
  seconds for a prompt from the terminal server in question, the user
  customizable script lines could be:

     ername:--ername: %s
     ssword: %s
     TIMEOUT 10
     >--> ppp

  allowing 10 (6 + an extra 4) seconds for receiving the '>' character.


TESTED SYSTEMS

  I have built and tested the xisp package under Linux-i386 kernel
  version 2.0.28 and 2.0.29, ppp-2.2.0f, libforms.so.0.81 with
  libX11.so.6.0 as well as libX11.so.6.1. The modem used was a
  28.8 US Robotics Sportster.


AUTHOR

  The author of xisp can be reached at:
  +------------------------------------------------+
  | Dimitrios P. Bouras    Tel.:    +30 1 968-0554 |
  | 41 Pandora Str.         FAX:          382-7900 |
  | 166 74 Athens        E-mail:    dbouras@hol.gr |
  | GREECE                       dimitri@ee.ubc.ca |
  +------------------------------------------------+

