
+--------------+
| REQUIREMENTS |
+--------------+

  In order to make use of the xisp package, you need the following:

   1. pppd-2.2.0f or newer properly installed on your system

   2. configure your modem for verbose result codes (this can be done,
      e.g. for a US Robotics Sportster, from within xisp by adding the
      "V1" command to the modem init command - details below)

   3. if possible, configure your modem for reporting true connection
      speed rather than the computer-modem connection speed (i.e. the
      DTE<->DCE interface speed -- check your modem docs for the "AT"
      commands for both)

   4. modem connection speed must be reported via a string like
      'CONNECT xxxxx' or 'CARRIER xxxxx' where 'xxxxx' is the speed
      report string

   5. a busy phone status must be reported by the modem via the
      string 'BUSY'.

  To compile and install this package from the source distribution, you
  need a properly installed X11R6 (or XFree86-3.1.2) or newer, as well as
  the forms library (XForms GUI by T.C. Zhao and Mark Overmars) version
  0.89 or later. You can get a copy of this library at:

                http://world.std.com/~xforms

  You can find a mirror in:

                http://world.std.com/~xforms/ftp/mirror.html

  You'll also need a copy of the XPM library (libXpm version 3.4f or
  later).  If you don't have it already (most, if not all, Linux
  distributions install it by default), get it from your favorite public
  FTP site.


+---------+
| 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, adding the capability of 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 two small
  databases, one for ISPs and one for phone companies (PTTs). The
  implementation supports a variable (but upper bounded) number of records
  for both databases. Each ISP entry, aside from user account name and
  password, supports 8 telephone numbers (tried sequentially when dialing),
  individual PTT selection, a multitude of dialing parameters, sixteen user
  customizable script lines for the chat program, and a wealth of pppd
  options to cover most communication needs. All ISP database information
  is saved in the xisp resource control file (.xisprc) in the user's home
  directory. The phone company database supports all (known) PTT attributes
  applicable while logging phone-call costs, and saves its information in
  a separate file, in sub-directory .xisplogs, in the user's home directory.

  For details on the user interface look in the "USER INTERFACE" section
  below.
  
  The .xisprc file converter (xisprccv) provided with the distribution,
  understands all ISP data base formats beginning with xisp version 1.2,
  and can be used to upgrade an old .xisprc file to the latest xisp
  version. xisprccv provided with version 2.7 also tries to convert old
  PTT log files to accommodate the changes in the logging file format
  introduced with xisp-2.7.


+--------------+
| ARCHITECTURE |
+--------------+

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

                                 +-------------+
                                 |             |       +-------------+
   +-------------+               |             |       |             |
   |             |               |             | Exec \|  ip-up/     |
   |             |     Exec     \|    pppd     |-------|  -down and  |
   |             |---------------|             |      /|  children   |
   |             |              /|             |       |             |
   |             |               |             |       +-------------+
   |             |               +-------------+              | Output
   |             |                  /|\    | Exec             | 
   |    X-ISP    |                   |     |                  | 
   |    main     |           --------|-----|------------------
   |  interface  |          |        |     | 
   |             |          |   Stat |    \|/
   |             |   Named  |    +-------------+
   |             |/  Pipe  \|/   |             |       +-------------+
   |             |----------o----|             |/ Stat |             |
   |             |\        /|\   |             |-------|             |
   |             |          |   \|   xispdial  |\     \|  xispterm   |
   |             |---------------|             |-------|             |
   |             | Dialing  |   /|             | Exec /|             |
   +-------------+ Environ- |    |             |       +-------------+
          |        ment     |    +-------------+          /|\    |
          | Exec            |       /|\    | Script        |     |
          |                 |        |     |               |     |
          |                 |        |     |               | I/O |
          |                 |        |     |               |     |
         \|/                | Output |    \|/              |     |
   +-------------+          |    +-------------+           |    \|/
   |             |          |    |             |       +-------------+
   | ~/.xisp-up/ |  Output  |    |             |/      |             |
   |  -down and  |----------     |             |-------|             |
   |  children   |               |    chat     |\ I/O \|    MODEM    |
   |             |               |             |-------|             |
   +-------------+               |             |      /|             |
                                 |             |       +-------------+
                                 +-------------+


  The way it works goes like this. When an ISP is selected in xISP, a
  dialing environment is created in the environment variable XISPDIAL,
  or in a special environment file in the user's home directory (the
  second option is used with pppd binaries compiled which the option to
  discard environment information).  The environment 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 starts xispdial, which reads the dialing environment from the
  XISPDIAL environment variable (or from $HOME/.xispenv).  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 (by default) in /tmp (.xisppipe.<username>).

  After connection, and in the case that a manual login window is
  selected, 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 DNS support via
  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. The ip-up/ip-down scripts supplied with xisp 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, xisp has the added capability
  of executing script 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, 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.

  In the case that PAP (using the pap-secrets file) is selected (your
  only PAP option for pppd version >= 2.3.x), the username and remote-
  name specified within xisp are passed on to pppd via the 'user' and
  'remotename' options, while if CHAP (using the chap-secrets file) is
  selected, host and remote-host names are passed to pppd via the 'name'
  and 'remotename' pppd options. For both PAP and CHAP, 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).
 
  If PAP via the +ua pppd option is selected for password authentication
  (pppd version 2.2.x ONLY), xisp passes the username and password to
  pppd using 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.

  If pppd version 2.3.x or later is used with xisp, special option files
  called "xisp_<device>" (where <device> stands for your modem serial
  port(s)) must be installed in directory /etc/ppp/peers, and xisp starts
  pppd with the additional option "call xisp_<device>". The default peer
  information file generated when installing xisp is "xisp_modem" and
  corresponds to the "/dev/modem" special device. Read the "PPPD 2.3.x/
  2.4.x PEER FILES" section below for details.


+----------------+
| USER INTERFACE |
+----------------+

  When started, xisp displays a form with three 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 ISPs, or the one set as "Default ISP" from
  within the "Accounts" form. All defined ISPs appear in the drop list
  for quick selection. The only button activated at this time is the
  "Connect" button. After a connection is initiated, and 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 "Help" menu selection is self explanatory, I guess :). The "File"
  menu contains three items, "Options...", "Enable hints" (or "Disable
  hints" if you have previously enabled them) and "Exit".  When xisp is
  run for the first time, hints are enabled for helping inexperienced
  users with setting up their ISP accounts. These hints are basically a
  compilation of FAQs which have found their way to my mailbox over the
  past few years. They can be disabled either via the command-line option
  "-nohints", or the "File" menu (as above). The "Options..." selection
  brings up a window with five tabbed folders named "Accounts", "Dialing/
  Login", "MODEM", "TCP/IP Options" and "Program Paths".


  "Accounts"
     Brings up a list of ISP accounts to choose from, allowing editing
     of their properties. It also contains five input fields, two drop-
     down choice lists, one set of check buttons, one set of radio buttons,
     and four action buttons.

     The first time xisp is executed all ISP names will be blank. One may
     add an ISP entry by pressing the "Add" button. You can also create
     new entries by selecting existing entries, copying them by pressing
     the "Copy" button, and pasting them by pressing the "Paste" button.
     When adding or pasting entries, the new entry is always appended to
     the existing list of ISPs.

     Edit the ISP name by double-clicking on an entry in the list. 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. If you desire automatic re-dialing of
     dropped PPP connections to the selected ISP, enable the "Re-dial
     dropped links" check-button.

     Note that, contrary to the default ISP selection, auto-dialing and
     redialing of dropped links are per-ISP attributes.

     The first of five input fields contains a semicolon (';') separated
     list of phone numbers to dial for the selected ISP, the second holds
     the user account name to use, and the third the password. The radio
     buttons enable use of password authentication via PAP or CHAP, both
     via the pap-secrets and chap-secrets pppd files.

     PAP without using the pap-secrets file (i.e. via the +ua pppd option)
     is supported only for pppd version 2.2.x. Since this option was
     removed starting with pppd version 2.3.x, this selection will be
     marked as unavailable when using xisp with pppd version 2.3.0 or
     later.

     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 option. Note that when any one of two available
     authentication methods is selected, any user script lines entered
     via the "Dialing/Login" menu, are ignored.

     The two drop-down lists allow selection of PTT and Zone for the
     selected ISP. There is only one constraint to keep in mind here: if
     total connection time and cost logging is desired, all PTTs selected
     for the ISPs in use *MUST* charge in the same currency, as indicated
     by the currency name in the "Currency:" input field on the
     "PTT Editor" form.

     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/Login"
     Brings up a form with fields for entering the four dialing
     parameters, namely the number of dialing tries, the inter-dialing
     delay and the maximum time to wait for modem connection, as well as
     a network connectivity parameter and up to sixteen user defined
     script lines.

     It also enables the launching of a manual login window after a
     connection is established, the size of which can be specified via
     the "Terminal columns:" and "rows:" input fields, or enables ISP
     server call-back and editing of up to sixteen user defined call-
     back script lines.

     A manual login terminal window can also be enabled for the call-back
     connection, independently of the one selected for the dial-in phase.
     All numeric input fields are straight forward; the default values
     should be adequate for most cases.

     The sub-form for editing the call-back script is activated by
     pressing the "Call-back Options" button, which is enabled only
     if you specify that the "ISP server will call back" via the
     corresponding radio button. This form also includes a field for
     entering the time to wait for the call-back connection, a terminal
     size if a manual terminal login is selected for the call-back phase,
     or a telephone number (that is, our phone number) to be called by
     a Un*x or NT-RAS call-back server (this last option requires a
     patched version of the pppd daemon -- check section "NT-RAS CALL-
     BACK SUPPORT" below for details).

     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)
     program. Here the user must enter the script lines used by chat to
     successfully negotiate a login for the particular ISP. Dial-in/call-
     back script lines are not used when manual login or authenticated
     (PAP,CHAP) 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 when xisp
     creates the dialing environment, and "%P" by your password.

     The "--" in the first expect string defines what is called a "sub-
     expect/sub-send" pair. This is explained in detail in the chat
     manual page, but a brief explanation goes like this: the chat
     program will timeout if it does not receive an expect string after
     a user defined (default is 45 seconds, but xispdial's default resets
     this to 5 seconds) period; in such case, rather than aborting it
     might be appropriate to send something to the other end and then
     wait again for the same or a new expect string. The characters to
     send if chat times out are enclosed in dash ('-') characters; if no
     characters are defined (i.e. a "--" sequence is used), only the
     ending carriage return is sent. Coming back to the above example, the
     first expect string tells chat to do the following: wait for "ername:"
     and if you don't get it in 5 seconds (xispdial's default), send a
     carriage return and wait again for "ername:". If a second timeout
     occurs, chat aborts, xispdial terminates and xisp returns to the
     disconnected state.

     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. All special escape characters
     supported by chat(8) (e.g. \n, \r etc.) can be entered in either
     the the "expect" or the "send" portion of a script line.
     special escape



  "MODEM"
     Brings up a form with nine input fields and five sets of radio
     buttons. The "Device" input field is for selecting the special
     device file for the modem port, /dev/modem being the default.
     The input field named "Reset" contains the modem reset string, the
     field named "Init" enables customization of the modem initialization
     string (before dialing), and the "Connect String" field allows
     modification of the string by which the modem employed reports the
     connection speed.

     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. when using a USR modem, an "M0" to disable the
     speaker during modem operation. xispdial appends an "H0" to the user
     defined initialization string.

     Note that in order for xisp to work properly, the modem must be
     configured for verbose result strings (as opposed to numeric result
     codes). For most modems this is the default; if that is not the
     case for the one you are using, consult with the user's manual for
     the appropriate command. For example, most USR modems return verbose
     result strings when you include "V1" in the "Init" string. In such
     case, the complete "Init" string would be "AT V1".

     You can use command sequences which begin with '\' in both the modem
     "Reset" and "Init" strings, but you have to prepend them with an
     extra '\'; e.g. if you want to enter "AT \N2" in the modem init
     string, you need to enter "AT \\N2" in the "Init:" input field.

     The string used for modem connection speed reporting is by default
     assumed to be "CONNECT", another popular choice being "CARRIER".
     The sets of radio buttons enable selection of modem port (i.e.
     DCE<->DTE interface) speed (an arbitrary user-defined speed is
     also provided), port flow control used (hardware or software),
     dialing mode (tone, pulse, ISDN) and type of 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 "SW Compression" section allows you to choose one of two
     compression methods available, or to turn compression off completely.
     Note that "BSD" compression will only work of your PPP subsystem
     was built to support it; on ix86 Linux systems this happens if you
     build PPP support as a kernel module. The "Level" input field is
     the transmit and receive compression level as explained in the
     pppd(8) manual page; xisp's default value is 12.

     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 best suit your needs.


  "TCP/IP Options"
     Brings up a form with eight input fields and five sets of radio
     buttons. With the exception of the DNS support, all remaining fields
     in this form are related to 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 details on these paremeters, when you need to change
     their values.

     The three radio buttons under "DNS support" enable automatic (ISP-
     assigned) or manual DNS activation on a per ISP basis, via the ip-up
     and ip-down scripts.

     In manual mode, a primary and (possibly) a secondary DNS server
     can be defined. 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. If you don't want to define a
     secondary DNS server, just leave the input field empty.

     Enabling DNS support will instruct xisp to do two things:

     a. 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 ISP name string entered via the "Accounts" form, the
        primary and (possibly) secondary DNS server IP addresses entered
        via the corresponding input fields, as well as the resolver
        default domain, if it is activated.

     b. Second, 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 xisp's 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.


  "Program Paths"
     Enables editing the paths to the:

     a.  pppd daemon,
     b.  location where pppd saves its process ID files,
     c.  location where pppd creates the lock file for the modem device,
     d.  chat program,
     e.  xispdial and xispterm helper programs and
     f.  location where xisp shall create/maintain the named pipe node
         used for communicating with its components.
 
     All six paths are entered in corresponding input fields. For the
     first 5, the "Default" button restores the path to its built-in
     default value specified during compilation. The "Status:" field
     beside each one of the first 5 entries will contain "OK" if the
     program binaries are indeed found in the specified path and/or if
     the specified directories exist, or "Error" otherwise.

     IMPORTANT NOTE: the last path, i.e. the path to the named-pipe
     node, should *NOT* be on an NFS mounted filesystem.


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

  "Options..."
     Brings up a form with  two sets of radio buttons, two drop-down
     choice lists, three buttons for manipulating phone company (PTT)
     parameters and an information display browser.

     The radio buttons for the "OnLine Counter", enable selection
     of either "Time (HH:MM:SS)", or "Call charges" in the currency
     selected for the correponding PTT, 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 "No" is selected, two logging files are kept. One keeps
     track of the total time (in seconds) spent online as well as the
     total cost for connection phone calls. In xisp versions prior to
     2.7, total cost was saved only for PTTs charging per time interval;
     for PTTs charging "by unit" the total number of units was saved
     instead. The change was necessary in order to support per ISP PTT
     selection. 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
     the logging period is changed, or a PTT which charges at a
     different currency is selected, 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 one of the charging zone from the zones
     defined for each PTT. The "Edit PTT" button brings up the PTT
     editor form for the selected PTT. This editor has its own help
     text, describing the usage of all supported PTT information fields,
     and explaining how user information is employed by the PTT tariff
     calculation engine. This help text is also included here, in section
     "PTT Editor" below.

     The "Add PTT" button creates a new phone company entry in file
     $HOME/.xisplogs/xispPTTs, prompting the user for the new PTT name,
     and then starting the PTT editor. The "Remove PTT" button removes
     the PTT entry currently selected. The information browser displays
     a brief report on charging method and costs for all zones and
     time-of-day categories defined for the currently selected PTT.
     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 displays a bar chart of costs for each corresponding
     period, and a pie chart with the yearly cost breakdown per period.

     The bar chart uses dark cyan color for the periods prior to the
     current one, white for the current period and yellow 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. The pie chart employs
     alternating yellow and dark cyan colors for clarity; the slice
     corresponding to the current period is white.

     Note that this menu option is active only if connection logs have
     been enabled from "Logging->Options...".


  "PTT Editor"
     This form enables editing the phone company information maintained
     by xisp. With the exception of the first three input fields (the
     PTT name, the number of charging zones defined for this PTT and
     the number of tariff categories per zone), all information is split
     up in three sections. Section "PTT charges" includes general
     information on PTT charging method and currency. Section "Zone
     information" enables editing the names and attributes of charging
     zones for the selected PTT. Last, "Category rules" enables editing
     the tariff categories (or otherwise termed "rules") for each zone.
     Tariff categories are comprised of a (complex attribute) rule and a
     cost value. If the rule applies, then the cost value is applied.
     The application of a rule depends on whether or not the attributes
     for this rule apply to the current calendar date and/or time. Note
     that the PTT tariff calculation engine in xisp searches zone
     categories in a first to last sequence, and applies THE FIRST
     matching rule ONLY. This should be kept in mind when writing and/or
     modifying category rules for a PTT entry. In the following
     paragraphs, the functionality of each field on the PTT editor form
     is described. Also note that in the text below, the "|" character
     is used as a short-hand for the word "or".

     General:
     --------

     PTT name:
       Enables changing the name string for the selected PTT.

     Charging zones:
       Used to specify the number of charging zones supported by the
       selected PTT entry.

     Categories/zone:
       Specifies the number of tariff categories (or rules) for each
       charging zone.
     

     PTT charges:
     ------------

     By unit:
       Specifies that the selected PTT charges its customers by a
       "unit" which costs a fixed amount of money. The rate (in seconds)
       at which such units are charged changes according to tariff rules.

     Minimum units:
       The minimum number of units charged for a call. This should not
       be confused with the "quantization" used by PTTs which charge
       "by unit". I.e. if the selected PTT charges a minimum of one unit
       per phone-call, don't put "1" in this input field, as this will
       result in 2 units being recorded by xisp for every short call
       you make. The PTT charges you with a single unit even if you don't
       consume the time corresponding to one unit during your short call.

     Per minute:
       Specifies that the selected PTT charges its customers by the
       minute. This also implies that the quantization in time
       measurement (and consequently charging) by the PTT is set to 60
       seconds. I.e. even even if your call lasts 23 seconds, you'll be
       charged for one minute.

     Minimum cost:
       This field is enabled both for "Per minute" and "Per second(s)"
       charging schemes. It specifies the minimum amount of money charged
       by the selected PTT for each phone-call. This minimum charge may
       correspond to a certain amount of time in a linear relationship
       fashion, or it may not (i.e. minimum charge-time is non linear --
       also see the "Zone Information" section).

     Per second(s):
       Specifies that the selected PTT charges its customers by a fixed
       number of seconds.

     Period:
       The charging period in number of seconds for "Per second(s)"
       charging schemes.

     Price/(unit|minute):
       The price in local currency for either each "unit", or for one
       minute if the charging scheme is "Per minute" or "Per second(s)".

     Currency:
       The local currency string for the selected PTT.

     Decimal digits for bill printouts:
       The number of decimal digits desired for saving/printing billing
       information in xisp's forms and log files.

     Currency placement:
       Specify "Left" or "Right" for the desired location of the
       currency string when printing out PTT charges.


     Zone information:
     -----------------

     Zone:
       Use this browser to select a zone for browsing/editing its
       information, by clicking on a line. Double-click to edit the zone
       name.

     Default tariff:
       Specifies the default tariff. For "By unit" charging schemes
       it is measured in seconds per unit. For "Per minute" and "Per
       second(s)" charging schemes, it is measured in the currency
       specified in the "Currency" field, per minute.

     Minimum charge time length:
       This field is defined only for "Per minute" and "Per second(s)"
       charging schemes. It specifies the fixed amount of time for which
       the "Minimum cost" applies. This can either be "Linear", in which
       case the "Minimum cost" lasts for time equal to the ratio of its
       cost value over 60, times its "Price/minute", or "Non-linear", in
       which case a fixed time length can be specified for each zone.

     Length for this zone (seconds):
       When the "Minimum charge time length" is non-linear, the "Minimum
       cost" shall last for the specified number of seconds, when the
       selected charging zone is in effect. As expected, this field is
       defined only for "Per minute" and "Per second(s)" charging
       schemes.
     
     Extra discount for this zone:
       Specifies whether or not there is any special discount for the
       selected zone. If "Yes", the discount specified in "Discount" as
       a percentage of the full charge, will be applied if the phone-
       call start time is not between the specified starting and ending
       period within the 24-hour day. This field is not defined for "By
       unit charging schemes".


     Category rules:
     ---------------

     Category number:
       Using this counter, select the category (or otherwise "rule")
       number which you wish to browse or edit.

     Category type:
       Specifies the type of the selected rule. "Weekday-special" and
       "Weekend-special" are used to specify reduced tariffs for dates
       during the calendar year, usually falling between two holiday
       dates, or within a holiday season. An example could be the
       weekend between Christmas and New Year's eve. "Holiday-absolute"
       is used for fixed holiday dates in the calendar year, like for
       example, national holidays. "Holiday-relative" is used for
       specifying holidays relative to (Catholic) Easter Sunday which
       is specified with index number "0". Good Friday is specified as
       "-2" while Pentecost as "50".

     Apply zone discount:
       Allows or disallows application of "Discount" (from "Zone
       information" above) to this rule. This facility is not defined
       for "By unit" charging schemes.

     Zero minimum charge time length:
       Allows inhibiting application of the minimum charge time length
       to this rule. This is for accommodating cases whereby "Minimum
       cost" is applied to each phone-call WITHOUT being linked to a
       specified charge time length, i.e. when the selected PTT charges
       "Minimum cost" as a base and adds to it the amount corresponding
       to the time the call lasts. This facility is not defined for "By
       unit" charging schemes.

     Rule tariff:
       Specifies the rule tariff. For "By unit" charging schemes it
       is measured in seconds per unit. For "Per minute" and "Per
       second(s)" charging schemes it is measured in the currency
       specified in the "Currency" field, per minute.

     Rule date:
       For "Holiday-absolute" specifies the calendar date only. For
       "Weekday-special" and "Weekend-special" you also need to specify
       the "End date", as the "Calendar date" is the starting date in
       this case. For "Holiday-relative", specify the relative date in
       the "Day relative to Easter Sunday" field.

     Rule start time and Rule end time:
       The starting and ending time during which the selected rule
       applies. Note that the time interval includes the "Rule start
       time" but not the "Rule end time", i.e. for specifying that a
       rule applies from 08:00:00 to 10:59:59 inclusive, start time
       would be entered as 08:00:00 and ending time as 11:00:00. This
       follows standard PTT conventions with regards to changes in
       tariff as a function of time within the 24-hour day.


  The main window includes one status and three connection indicators.
  The status indicator indicates the current interface state. There are
  four distinct states: "OFF-LINE" for "disconnected", "XISPDIAL"
  indicating that dialing is in progress, "CARRIER" indicating that
  the modem has connected successfully, and "ON-LINE" when network
  connectivity has been established.
  The "Assigned IP Address:" indicator prints the IP address assigned
  to your PPP interface after successfully establishing a link. The
  "Modem Speed:" indicator prints the speed as returned by the modem
  connection-speed string, 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
  visible 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.


+---------+
| SIGNALS |
+---------+

  The following signals have the specified effect when sent to the xisp
  process using the kill(1) command:

   SIGINT,SIGTERM: The xisp process is terminated and the PPP link is
                   disconnected.

   SIGUSR1:        If xisp is in the disconnected state, sending it this
                   signal is equivalent to pressing the "Connect" button.
                   If xisp is either dialing or in the connected state,
                   this signal has no effect.

   SIGUSR2:        If xisp is dialing, sending it this signal is
                   equivalent to pressing the "Interrupt" button, and if
                   xisp is in the connected state, it is equivalent to
                   pressing "Disconnect". If xisp is in the disconnected
                   state, this signal has no effect.

  Look in contrib/README and contrib/.fvwm2rc.add for an example on how
  this feature could be used to control xisp from a window-manager menu.


+----------+
| 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 str>  \c 
     TIMEOUT        5
     \r             \c

  The "connect str" is the string returned by your modem upon connection
  (it's "CONNECT" for a US Robotics Sportster, but it might be the word
  "CARRIER" for your modem; please consult with your modem's user manual).
  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.
  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>
     RING           ATA
     TIMEOUT        30
     <connect str>  \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 "RING"
  from the modem, to make it pick up the phone and try to connect to the
  server dialing back, waiting at most 30 seconds for the modems to
  negotiate connection speed, and then to use the login procedure
  specified 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! 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 directory /usr/lib/ppp, 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 via an ATD
  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. A "manual" option
  implementing the above shall be added to xisp in the near future.


+----------+
| XISPRCCV |
+----------+

  xisprccv is a .xisprc file converter for all versions since xisp-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. Since xisp version 2.7 it also
  attempts to convert total cost logging files to the new (post xisp-2.7)
  format.


+-----------------------------+
| PPPD 2.3.x/2.4.x PEER FILES |
+-----------------------------+

  To accommodate the changes in pppd versions 2.3.x and later for which
  bidirectional authentication is turned on by default (as specified by
  default use of the "auth" option in directory /etc/ppp/options),
  special peer information files called "xisp_<device>" (where <device>
  stands for your modem serial port(s) without the "/dev/" prefix) are
  installed by xisp in directory /etc/ppp/peers. In these files,
  bidirectional authentication is turned off via the "noauth" pppd
  option. However, this has the following two side effects: it makes the
  modem device file specification, and the use of the "connect" pppd
  option, privileged options. For resolving the former, the modem device
  is specified in each "xisp_<device>" peer file, while for the latter,
  a "call xisp_dialer" option in each "xisp_<device>" file, reads-in the
  second special peer file which sets xisp's dedicated dialer. When the
  modem device is changed from within xisp's "MODEM" form, or when the
  path to xispdial is changed in the "Program Paths" form, hints (if
  enabled) inform the user that he/she should check whether the
  appropriate "xisp_<device>" file exists, or that the path to xispdial
  is correctly defined in "xisp_dialer", respectively.
  When xisp starts pppd 2.3.x/2.4.x, it does so using the option "call
  xisp_<device>", where "<device>" is the modem device entered in the
  "MODEM" form, without the "/dev/" prefix. The default peer information
  file generated when installing xisp is "xisp_modem" and it corresponds
  to the "/dev/modem" special device.  In summary:

  - If you change the location of the xispdial binary, make sure you edit
    /etc/ppp/peers/xisp_dialer and update the path to xispdial.

  - If you install a new modem on a serial device on your system, make
    a copy of your existing "xisp_<device>" file for the new device, and
    the edit it to update the device name.

  Both "xisp_modem" and "xisp_dialer", installed by default in directory
  /etc/ppp/peers, contain helpful comments to aid you in editing their
  contents; xisp will prompt you with suggestions (when hints are enabled)
  on when that needs to be done.


+--------------------------+
| NT-RAS CALL-BACK SUPPORT |
+--------------------------+

  In order for NT-RAS call-back to work you need:

  1. To have a patched version of pppd which includes support for NT-RAS
     call-back. Patches exist for relatively old (e.g. 2.2.0f), as well
     as for recent (e.g. 2.3.x/2.4.x) versions of pppd. The xisp source
     distribution includes a patch for pppd-2.2.0f in subdirectory
     ./contrib; the patch for version 2.3.x/2.4.x is included in the
     official pppd source distribution (files README.cbcp and
     README.mschap80 include all necessary information/instructions).

  2. If the NT box is part of a domain and your account is a domain
     (as opposed to a local) account, then the user name both in xisp's
     "User/Name:" input field ("Accounts" form), and in pppd's
     /etc/ppp/chap-secrets file, must include the domain name.
     Assuming for example that the domain name is "MYDOMAIN" and the
     user name is "dbouras", the "User/Name:" input field must contain:

                          MYDOMAIN\dbouras

    while the "Remotename:" input field may contain the word:

                                ras

    In such a case, the /etc/ppp/chap-secrets file must contain
    the following two entries:

                MYDOMAIN\\dbouras  ras  my_password
                ras  MYDOMAIN\\dbouras  my_password

    NOTES: - the double backslash between NT domain name and user
             account name above is NOT a typogrpahical mistake; it
             needs to be that way in file /etc/ppp/chap-secrets.
             Contrary to this, in xisp's "User/Name:" input field
             you need ONLY ONE backslash

           - the remote name "ras" can be anything you choose
             since it is ignored at the NT side. However, it must
             be the same in the "Remotename:" input field in xisp's
             "Accounts" form, and in the two lines in file
             /etc/ppp/chap-secrets.

  3. If your NT account is local to the RAS server (and it has dial-in
     privileges), then you don't need to specify the domain name in
     xisp's "User/Name:" input field, nor in file /etc/ppp/chap-secrets.
     In such a case and for the above example, the entries in file
     /etc/chap-secrets would be:

                     dbouras  ras  my_password
                     ras  dbouras  my_password

    while the "User/Name:" input field should contain simply the account
    name "dbouras".

  NT-RAS call-back support was introduced with xisp version 2.6 and it
  was tested both with pppd-2.2.0f and pppd-2.3.5.


+----------------+
| TESTED SYSTEMS |
+----------------+

  I have personally built and tested xISP under Linux-ix86 kernel
  versions 2.0.28 - 2.0.35, as well as 2.2.3 - 2.2.19, and 2.4.3 -
  2.4.9, pppd-2.2.0f, pppd-2.3.5 up to pppd-2.3.11, and pppd-2.4.0,
  libforms.so.0.89 with X11R6 libX11.so.6.0 as well as X11R6.1/X11R6.3
  libX11.so.6.1. The various modems used included two US Robotics
  Sportster models, one at 28,800 Baud and one supporting 56 kBaud
  (V90), as well as an assortment of Rockwell chipset based internal
  and external OEM modems, at 33.6 and 56 kBaud. xISP versions 2.2 and
  later were also tested under SunOS-4.1.4, pppd-2.2, libforms.so.0.89
  with X11R6 libX11.so.4.20 and X11R6.1/X11R6.3 libX11.so.4.30.
  Versions 2.5 and later were additionally tested under Solaris-2.[5678]
  (Sparc and ix86) pppd-2.3.5, libforms.so.0.89 with X11R6 libX11.so.4.20,
  using two US Robotics Sportster modems, a 14,400 Baud and a 33,600
  Baud model.


+--------+
| AUTHOR |
+--------+

  The author of xisp can be reached at:
 +-------------------------+----------------------------------------------+
 | Dimitrios P. Bouras     |  Voice: +30 210 895-6380 or +30 210 895-3552 |
 | 27 El. Venizelou St.    | E-Mail: dbouras@hol.gr, d.bouras@ieee.org    |
 | GR-16673 Athens, GREECE |    Web: http://users.hol.gr/~dbouras         |
 +-------------------------+----------------------------------------------+

