
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 (this can be done from within xisp
  by adding the "V1" command to the modem init command - details below),
  and if possible, for reporting your true connection speed rather than
  the computer-modem connection speed (i.e. the DTE<->DCE interface).
  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.86 or later. You can get a
  copy of this library at: 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, as well as a manual login terminal window. 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 she/he is not all that well acquainted with the intricacies of
  system log files. Furthermore, it incorporates a mechanism to log ISP
  connections and calculate/store phone-call costs. 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 perform the dialing,
  and a "bare bones" terminal interface, xispterm. For more details on
  the workings of xisp, xispdial and xispterm, 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 dialing
  tries and inter-dialing delay, eight user customizable script lines for
  the chat program, and a wealth of dialing and pppd options to cover
  most communication needs. All data base information is saved in the
  xisp resource control file (.xisprc) in the user's home directory. For
  details on the user interface look in the "USER INTERFACE" section
  below. As of version 1.9, the .xisprc file converter (xisprccv)
  provided with, the distribution, understands all data base formats
  beginning with version 1.2.


ARCHITECTURE

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

                                     +-------------+
                                     |             |     +----------+
      +-------------+                |             |     |          |
      |             |                |             |    \| ip-up/   |
      |             |     Exec      \|    pppd     |-----| -down &  |
      |             |----------------|             |    /| children |
      |             |               /|             |     |          |
      |             |                |             |     +----------+
      |             |                +-------------+           |
      |             |                   /|\    |               | 
      |     xISP    |            --------|-----|---------------
      |             |           |        |    \|/
      |             |    Named  |    +-------------+
      |             |/   Pipe  \|/   |             |/    +----------+
      |             |----------------|             |-----|          |
      |             |\               |             |\    |          |
      |             |               \|   xispdial  |    \| xispterm |
      |             |----------------|             |-----|          |
      |             |  Dialing      /|             |    /|          |
      +-------------+  Environment   |             |     +----------+
                                     +-------------+       /|\   |
                                        /|\    |            |    |
                                         |     |            |    |
                                         |    \|/           |    |
                                     +-------------+        |   \|/
                                     |             |/    +----------+
                                     |             |-----|          |
                                     |             |\    |          |
                                     |    chat     |    \|  MODEM   |
                                     |             |-----|          |
                                     |             |    /|          |
                                     |             |     +----------+
                                     +-------------+


  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, for example, 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. pppd then
  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>). After connection, and in the
  case that a manual login window is selected as desirable via xisp,
  xispdial starts xispterm, giving it control of the modem. The user
  can then login manually, and at the end to choose whether to complete
  successfully or to abort the connection. When a PPP interface is set
  up, and in the case that the ip-up/ip-down feature is used (read the
  pppd(8) manual page for detailed information on ip-up/ip-down), all
  output from ip-up and/or ip-down as well as from any processes spawned
  by them (read the ip-up and ip-down example scripts distributed with
  xisp) appears on the xisp browser window. Furthermore, as of version
  2.1, the supplied ip-up/ip-down scripts include DNS server selection
  capabilities on a per ISP basis, manipulating /etc/resolv.conf with
  DNS information passed on by xisp. In addition to ip-up/ip-down support,
  and as of version 2.3, xisp has the added capability of executing files
  .xisp-up or .xisp-down in the user's home directory, if they exist when
  the PPP link is setup or torn down respectively. Details on their use
  are included in the sample.xisp-up and sample.xisp-down files supplied
  with the xisp distribution. 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. If automatic redialing is
  selected, xisp will attempt to restore the connection by redialing the
  selected ISP. If PAP is selected for password authentication, xisp
  passes the username and password to pppd using the +ua option, via the
  .xisppap temporary file in the user's home directory. This file is
  generated just prior to launching pppd and is deleted after pppd forks
  to put itself in the background, hence remaining in the user's home
  directory for only a split second on a lightly loaded system. In the
  case that PAP-S (PAP using the pap-secrets file) is selected, only the
  username specified within xisp is passed on to pppd via the 'user'
  option, while if CHAP-S (CHAP using the chap-secrets file) is selected,
  no user information is passed to pppd. For both PAP-S and CHAP-S,
  appropriate entries must exist in files pap-secrets and chap-secrets
  respectively (read the pppd(8) manual page for syntax and details on
  their use).


USER INTERFACE

  When started, xisp displays a form with five buttons, three menus and
  a drop-choice list. 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, or the one set as "Default ISP" from
  within the "ISP Information" form. All defined ISP's appear in the drop
  list, for quick selection. 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 five items, "ISP Information", "Account Information",
  "Dialing and Login", "Communication Options" and "TCP/IP Options".

  "ISP Information"
     Brings up a list of ISP's to pick from and/or edit. The first time
     xisp is executed all ISP names will be blank, as indicated by a '~'
     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. The selected ISP can be set as the default
     selection upon xisp startup, by enabling the "Default ISP" check-
     button. If you want xisp to dial this ISP entry automatically after
     it starts up, enable the "Auto-dial upon startup" check-button.
     Note that, contrary to the default ISP selection, auto-dialing is
     a per-ISP attribute. Pressing "OK" returns you to the program main
     window and sets your selection as the current ISP.

  "Account Information"
     Brings up a window with five input fields, and a set of four radio
     buttons. The first input field contains 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. The radio buttons enable the
     use of password authentication using PAP, PAP using pap-secrets
     (PAP-S) and CHAP using chap-secrets (CHAP-S). Note that simple PAP
     (without using the pap-secrets file) is supported via the +ua pppd
     version 2.2 option. Since this option has been removed from pppd in
     version 2.3, this selection will be marked as unavailable when using
     xisp with pppd version 2.3. The fourth input field contains the
     argument to the 'user' or 'name' argument to pppd, and the fifth
     contains the argument to the 'remotename' pppd argument. Note here
     that when any one of three available authentication methods is
     selected, the manual login option or any user script lines entered
     via the "Dialing and Login" menu, are ignored. In the phone number
     input field, more than one telephone numbers, and up to a total of
     8 can be entered by separating them with the semicolon (';')
     character. The total length of each phone number is currently
     limited to 32 characters.  A brief note on password security is in
     order here. The plaintext password entered in the "Password" input
     field is encoded using encrypt(3) 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 the xisp
     distribution.

  "Dialing and Login"
     Brings up a window with fields for entering the three dialing
     parameters, namely the number of dialing tries, the inter-dialing
     delay and the maximum time to wait for modem connection, as well
     as up to eight user customizable script lines. It also enables the
     launching of a manual login window after a connection is
     established, or enables ISP server call-back and editing of up to
     eight user customizable call-back script lines.  The first three
     input fields are pretty straight forward, and default values for
     all are suggested. The sub-form for editing the call-back script is
     activated by pressing the "Options" button. This form also includes
     a field for entering the time to wait for the call-back connection.
     The script section, both for dial-in and call-back, is divided into
     "Expect:" and "Send:" sections, as used by the call to the chat(8)
     command. Here the user must enter the script lines employed by chat
     to successfully negotiate a login for the particular ISP. Dial-in
     and call-back lines are not used when manual login or authenticated
     (PAP/PAP-S/CHAP-S) login is selected. However, it is possible to
     use call-back with authenticated login. For detailed script-line
     syntax and various examples please read 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 expect-send pairs for
     the above procedure would be:

        Expect:            Send:

        ername:--ername:   %U
        ssword:            %P
        >-->               ppp

     Note the special "%U" and "%P" variables in the script lines. "%U"
     is (quite obviously) replaced by your user account name (by the
     xisp program when it creates the dialing environment file), and "%P"
     by your password. A maximum of one "%U" and one "%P" can exist in
     either section (expect or send) of each script line. Entering more
     will make xisp print a message and abort the dial. Important
     "inside" note: xispdial architecture is such that the script lines
     passed from xisp are used as part of a printf(3) function format.
     Thus, any non regular characters you need to pass to chat must be
     escaped by preceding them with the '\' character. Furthermore,
     following printf(3) syntax, the '%' special character is passed as
     '%%'. As an example, if you want to pass chat a carriage return
     character \r, you would have to enter it as \\r in the xisp script
     line. Note that since version 1.9 of xisp, when the script lines
     were divided into "Expect:" and "Send:" sections, you no longer
     need to enclose commands including spaces with single quotes. As an
     example, if at the end of the login session you start PPP using the
     command "ppp /compress", in versions prior to 1.9 you would need
     to enclose the command in single quotes and enter your script line
     as ">--> 'ppp /compress'" in the above example. For versions 1.9
     and later this is not necessary, as expect-send pairs are
     automatically quoted before being passed on to chat.

  "Communication Options"
     Brings up a window with seven input fields and five sets of radio
     buttons. The "Device" input field is for selecting the special
     device file referring to the modem port, /dev/modem being the
     default. The input field named "Reset" contains the modem reset
     string, while that named "Init" enables customization of the
     modem initialization string (before dialing). The default reset
     string is "ATZ" which should work with most modems. The default
     initialization string is a simple "AT" command, to which you could
     add, e.g. with a USR modem, an "M0" to disable the speaker during
     modem operation. Note that xispdial appends an "H0" to the user
     defined initialization string. The sets of radio buttons enable
     selection of modem port (i.e. DCE<->DTE interface) speed, port flow
     control used (hardware or software), dialing mode (tone or pulse)
     and BSD software compression. The "Dialing extras" input field
     allows defining extra command characters (up to 8 in total) to be
     inserted between "AT" and "D" when dialing. The "Level" input field
     is the transmit and receive compression level as explained in the
     pppd(8) manual page, having a default value of 12. Note, however,
     that the PPP employed has to have BSD compression support for this
     option to have any effect, which for Linux happens only if you build
     PPP support as a kernel module. The last two input fields enable
     selection of the asyncmap and escape options provided by pppd; see
     the pppd(8) manual page for details on their function. The vast
     majority of dialup setups won't need the escape parameter, and that
     is the reason why it is off by default. The value of asyncmap, on
     the other hand, is automatically adjusted by your selection of flow
     control, i.e. whenever you change flow control type, the default
     value for asyncmap is inserted in the input field. Although the two
     default values should be adequate for general use, you can modify
     them further, to suit your needs.

  "TCP/IP Options"
     Brings up a window with seven input fields and four sets of radio
     buttons. With the exception of the primary and secondary DNS server
     entries, all remaining fields in this form are options which should
     only be changed if you understand their function; the default values
     are what you would need for your typical ISP connection. Please
     refer to the pppd(8) manual page for reading details on the function
     of these parameters, when you need to change their values. The last
     set of radio buttons enables support of the ip-up and ip-down
     scripts, allowing  the user to enter IP addresses for a primary and
     (possibly) a secondary DNS server. The ip-up and ip-down scripts
     normally reside in /etc/ppp, and are automatically invoked by pppd
     when the link is set-up and torn-down respectively. Enabling this
     option will instruct xisp to do two things. Firstly, to call pppd
     with the extra option 'ipparam', passing a string as a sixth
     argument to ip-up and ip-down; this string contains the name of the
     pipe node from which xisp reads xispdial output, the description
     string entered in the "ISP Information" menu item, and the primary
     (and possibly secondary) DNS server IP addresses entered via the
     corresponding input fields. Secondly, to read extra input from the
     named pipe node, after xispdial terminates, effectively writing any
     output from ip-up and ip-down to the xisp browser. The ip-up and
     ip-down scripts provided with xisp, must be installed in /etc/ppp
     for the xisp DNS settings to have any effect. Both ip-up and
     ip-down include user customizable sections for performing tasks
     like, for example, downloading mail or news, on a per ISP basis.

  The "Logging" menu contains two items, "Logging Options" and
  "Statistics".

  "Logging Options"
     Brings up a window with  two sets of radio buttons, two drop
     choice lists, and an information display browser. The radio button
     set for the "OnLine Counter", enables selection of either "time in
     seconds" or "call charge" in local currency, as display option on
     the main program window. The other set of radio buttons enables
     selection of the logging period, affecting the file names of log
     files in the xisp logging directory $HOME/.xisplogs. Unless "None"
     is selected, two logging files are kept. One keeps track of the
     total time (in seconds) spent online as well as the total number of
     units charged (in the case when the chosen phone company charging
     method is "per minute" rather than "in units", this number is the
     total cost instead). The other log file keeps ISP connection logs
     for the desired logging period. The first file has the base name
     "xispcost" and suffixes of ".W<week number>", ".<abbr. month>"
     or ".B<month-pair number>", depending on whether "Weekly", "Monthly"
     or "Bimonthly" logging is selected. The second log file has base
     name "xisplog" and the same suffix as the first one. As an
     example, for date "Fri Sep 26 17:08:39 EET DST 1997", the suffixes
     would be ".W39", ".Sep" or ".B5" corresponding to "Weekly",
     "Monthly" or "Bimonthly" logging periods. Whenever the phone
     company and/or the logging period is changed, the old log file
     is renamed to <the old name>.bak, and a new one is created.
     The two drop choice lists are for selecting one of the supported
     phone companies and the charging zone from the zones defined for
     that company. The information browser displays information on
     charging method and costs for all zones and time-of-day categories
     defined. These categories are simply different charging tariffs
     used by the phone company for different times of day and night.

  "Statistics"
     Displays time/cost information collected in the xispcost.* files,
     according to the logging period selected. It displays the number of
     online seconds and total cost for each period on a text browser,
     and also makes a bar chart of costs for each corresponding period.
     The chart uses yellow color for the periods prior to the current
     one, white for the current period and dark cyan for the remaining
     periods up to the end of the current year. These remaining periods
     are assumed to belong to cost information collected during the
     previous year. For this reason, two different total time and cost
     values are calculated and displayed on the text browser, one for
     the periods up to and including the current one, and one for the
     remaining periods to the end of the year. Note that this menu
     option is active only if connection logs have been enabled from
     "Logging Options".
     

  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 "Time On-Line"/"Call Charges"
  indicator measures your connection time or charges with a resolution
  of five seconds. The measured time (or sum of charges) will remain
  there after disconnection, until a new dialing sequence is initiated.
  The IP address can be selected for later pasting in some other window
  by clicking the left mouse button on the IP readout. Clicking again
  deselects it.


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    'NO DIALTONE'
     ABORT    enied
     ABORT    imeout
     ''       'AT <dial extras>D<dialing method> <the phone number>'
     TIMEOUT  <maximum wait for connection>
     CONNECT  \c 
     TIMEOUT  5
     \r       \c

  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 expect-send pairs could be:

     Expect:            Send:

     ername:--ername:   %U
     ssword:            %P
     TIMEOUT            10
     >-->               ppp

  allowing 10 (6 + an extra 4) seconds for receiving the '>' character.
  And a point not stressed enough: xispdial architecture is such that the
  script lines passed from xisp are used as part of a printf(3) function
  format. Thus, any non regular characters you need to pass to chat must
  be escaped by preceding them with the '\' character. As an example, if
  you want to pass chat a carriage return character \r, you would have to
  enter it as \\r in the xisp script line. If call-back is selected, the
  following script is appended to the concatenation of user customizable
  script lines and a modified version of the internal script:

     TIMEOUT  <delay for call-back connection>
     CONNECT  \c
     TIMEOUT  5
     \r       \c

  And following that, the user call-back script lines are appended to it.
  This instructs chat to wait the user-specified delay time for a second
  connect from the server as it dials back, and then to use the login
  procedure described in the call-back script. The dial-in internal
  script is modified by deleting the

     ABORT    'NO CARRIER'

  expect-send pair, since the carrier drops when the remote side hangs-up
  prior to calling back.


XISPTERM

   xispterm is a stripped-down version of a terminal emulation program
  which is used by xispdial as a manual login window. It only understands
  the backspace (^H) and kill (^U) control characters, but it gets the
  job done! Also note that it can also be used independently as a quick
  pppd dialer as follows. Stick all your pppd options in a file, and then
  invoke pppd with xispterm as dialer and your file as the options file.
  If, for example, you saved the options in a file called "myopts", and
  xispterm resides in the directory /usr/lib/ppp/xispterm, the command
  line to invoke pppd would be:

             pppd file myopts connect /usr/lib/ppp/xispterm

  Then, you could talk directly to your modem, dial a number with an AT
  command, once connected you would login to your ISP and start PPP on
  the remote end, and then you would press the "Continue" button to tell
  pppd that all is OK for setting up the link. Pressing "Abort" would
  terminate pppd and your connection along with it.


XISPRCCV

   xisprccv is a .xisprc file converter for version 1.2 and up to the
  current version, and it is run without arguments. Before performing the
  upgrade, it creates a backup copy of the user's .xisprc file in her/his
  home directory, with a '-V.R' suffix, where 'V' is the version and 'R'
  the revision number.


TESTED SYSTEMS

  I have built and tested the xisp package under Linux-ix86 kernel
  version 2.0.28, 2.0.29 and 2.0.30, ppp-2.2.0f, libforms.so.0.86 with
  X11R6 libX11.so.6.0 as well as X11R6.1 and X11R6.3 libX11.so.6.1. The
  modem used was a 28.8 US Robotics Sportster. Versions 2.2 and later
  were also tested under SunOS-4.1.4, ppp-2.2, libforms.so.0.86 with
  X11R6 libX11.so.4.20 and X11R6.1 libX11.so.4.30.


AUTHOR

  The author of xisp can be reached at:
 +---------------------+-------------------------------------------+
 | Dimitrios P. Bouras |          Tel.: +30 1 968-0554 or 894-1320 |
 | 41 Pandora Str.     |  FAX: +30 1 382-7900 "Attention: Dimitri" |
 | 166 74 Athens       | E-mail: dbouras@hol.gr, dimitri@ee.ubc.ca |
 | GREECE              |         Web: http://users.hol.gr/~dbouras |
 +---------------------+-------------------------------------------+

