# 
# $Id: INSTALL,v 1.22 1998/02/17 09:51:44 mdejonge Exp $
#
#   $Source: /home/mdejonge/CVS/projects/modem/INSTALL,v $
# $Revision: 1.22 $
#    Author: Merijn de Jonge
#     Email: mdejonge@wins.uva.nl
# 
#  
# 
# This file is part of the modem communication package.
# Copyright (C) 1996-1998  Merijn de Jonge
# 
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
# 
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
# 
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
# 
# 
# 
This file contains installation instructions for the modem package.
Configuration of the system consist of an automatic part using GNU
autoconf and a manual part where several configuration files have to
be created. 

Notes:
The modem package requires an identd server to run. If you don't have an
identd server you can ftp pidentd from:
   ftp://ftp.lysator.liu.se/pub/ident/servers 
To be able to use ppp (a script for establishing and maintaining a ppp
connection) you have to have pppd installed. pppd can be ftp'ed from:
   ftp://cs.anu.edu.au/pub/software/ppp/ 

A sample ppp options file is located in ./samples/ppp-options. pppd
uses a lock file to lock the device that it has been. Write permisson
to the directory where lock files are stored (/var/lock on Redhat
systems) is required for pppd to work. On some systems pppd is not
installed setuid root (as is done by default during the installation
of pppd). On these systems pppd might fail to work because pppd can't
create a lock file. This can be corrected by making pppd setuid root.

The clients included in the modem package can use one of three widget
sets (Motif, Xt or Tcl/Tk) or it can use a text interface (without
any dialogs). Tcl version 7.4 and Tk version 4.0 or above are
required to use the Tcl/Tk interface. It seems that lesstif can be
used for the motif widget set but I did not test it myself.

Installation instructions:

 1) Decide which widget set (Xt, Tcl/Tk or Motif the default) to use
    and run the configuration script ./configure:
    
    for Xt:
       ./configure --with-xt
    for Tcl/Tk:
       ./configure --with-tk
    for Motif:
       ./configure or ./configure --with-motif
    To use the text interface:
       ./configure --with-text
    
    When the libraries are in a non-standard location you can specify
    the location to ./configure. 
    
    for example to specify that the Tcl/Tk widget set is stored under
    /opt/tcltk you can run ./configure as follows:
       ./configure --with-tk=/opt/tcltk

    Type "./configure --help" to get a list of all available options or
    refer to ./INSTALL.configure for more information about using
    ./confgure

 2) If you want to install the help files in a different location, you
    should manually edit the variable HELP_DIR in ./make.config to
    point to the directory where you want the help files to be
    installed. See below for details on configuring HELP_URL in
    modem_defs.h

 3) Manually edit ./modem_defs.h. See below for instructions.

 4) Manually Edit
       ./scripts/ppp.src            Script to establish a ppp connection.
       ./scripts/xcomm.src          Serial communication program.
       ./scripts/verify_number.src  Script that verifies user's
                                    permission to dial a number.
       ./scripts/verify_user.src    Script that verifies user's
                                    permission to use a modem device.

    Details about configuring these scripts are included in the
    scripts.

 5) Type "make" to compile the modem package.

 6) When everything compiles ok, type "make install" and "make
    install.man" to install the binaries and man pages.
    Please mail me (mdejonge@wins.uva.nl) when something went wrong.
    If you want to install the help files you also have to give the
    command make install.help_pages

 7) edit /etc/services:
    You should define a name for the modemd service and a port to use
    for tcp and udp.

    let
       'modemd' be the name of the service,
       '12345'  be the port used for tcp,
       '12345'  be the port used for udp.
    as defined in modem_defs.h (see below), then add:
       modemd   12345/tcp
       modemd   12345/udp
    to /etc/services.

    When no modemd entries can be found, the software generates a
    warning message and will use a default port (defined at compile
    time (TCP_DEFAULT_PORT and UDP_DEFAULT_PORT, see below).

 8) Update your system to start the modemd server automaticly at
    startup:

    For example on a Linux system add the following to rc.multi:
    
       if [ -x /usr/local/sbin/modemd ]
       then
          /usr/local/sbin/modemd
       fi
  
    On a Redhat system and on a Solaris 2.x system you can use the
    ./samples/modemd.startup.* scripts to start modemd automatically
    during startup.
    On Redhat:
       copy ./samples/modemd.startup.redhat to /etc/rc.d/init.d/modemd and
       /make a link to etc/rc.d/rc3.d/S20modemd:
          cp ./samples/modemd.startup.redhat /etc/rc.d/init.d/modemd 
          ln /etc/rc.d/init.d/modemd /etc/rc.d/rc3.d/S20modemd
    On Solaris 2.x:
       copy ./samples/modemd.startup.solaris to /etc/init.d/modemd and make
       a link to /etc/rc3.d/S20modemd:
          cp ./samples/modemd.startup.solaris /etc//init.d/modemd
          ln /etc/init.d/modemd /etc/rc3.d/S20modemd

 9) Create configuration files
    -modemd server configuration file with name and path as defined
     with MODEMD_CONFIG_FILE (usually: /etc/modemd.conf). For an
     example see ./samples/modemd.conf. See modemd.conf(5) for
     details.
    -modem configuration file with file and path as defined in
     modemd.conf (or as defined with MODEM_CONF_FILE in modem_defs.h,
     see below). For an example see ./samples/modems.conf. See
     modems.conf(5) for details.
    -modem commands configuration file with path and name as defined
     in modemd.conf (or as defined with MODEM_COMMANDS in
     modem_defs,h, see below). For an example see
     ./samples/modem_commands. See modem_commands(5) for details.
    -[optional] Create a personal phone book with name and path as
     defined with PHONEBOOK in modem_defs.h (usually ~/.phonebook). 
     For an example see ./samples/phonebook. See phonebook(5) for
     details.

10) Test it out:
    -To start a terminal session with your favorite BBS type:
        xcomm [phone book entry] (e.g., xcomm mybbs)
    -if you have pppd installed, type:
        ppp [phone book entry] (e.g., ppp xs4all)
     Look in ./samples/ppp-options for a sample ppp options file.

Below an explanation of the settings in modem_defs.h. Items marked
with "*" can be overruled in the main configuration file modemd.conf.
These items are used only when they are not defined in modemd.conf.

Section Communication:
TCP_DEFAULT_PORT    Port to use for tcp communication.
TCP_SERVICE         Service to use for tcp communication.
UDP_DEFAULT_PORT    Port to use for udp communication.
UDP_SERVICE         Service to use for udp communication.

MODEM_SERVER        Address used to find modemd server on the net. 
                    Usually this would be the broadcast address of your
                    network.  This address can be over ruled by
                    defining the environment variable MODEM_SEVER.
SERVER_TIMEOUT      After this time (in seconds) consider all modemd
                    servers down.
CLIENT_TIMEOUT      A client who is not connected and did not use the
                    modem for this period of time (in minutes) will be
                    disconnected.  This prevents a client from
                    allocating all modem resources without using them.

Section Server:
MODEMD_CONFIG_FILE  Location of main configuration file.
* SERVER_DIR        Directory where server runs. During initialization,
                    the server changes to this directory.
* ACCESS_LOG_FILE   This item defines the name and path of the access
                    log file (can be defined relative to SERVER_DIR:
                    e.g., ./access.log). The server writes information
                    about users connected to the modemd server to this
                    file.
* ERROR_LOG_FILE    This item defines the name and path of the error
                    log file (can be defined relative to SERVER_DIR:
                    e.g., ./error.log). All server errors are written to
                    this file.
* ACCOUNT_LOG_FILE  This item  defines the name and path of the file
                    with accounting information (can be defined
                    relative to SERVER_DIR: e.g., ./account.log).
* SERVER_LOCK_FILE  This item defines the name and path of the lock
                    file to use. The server uses a lock file to avoid
                    multiple copies of the server (can be defined
                    relative to SERVER_DIR: e.g., ./modemd.pid).
* VERIFY_USER       This item defines the name and path of a program that 
                    verifies whether or not a user has permission to use a
                    modem.
* VERIFY_NUMBER     This item defines the name and path of a program that
                    verifies whether or not a user is allowed to dial the
                    specified number.
* SERVER_UMASK      This item defines the umask to use. For safety reasons,
                    the server sets this umask to prevent problems that might
                    arise from incorrect mode specifications.

Section Modem:                  

* MODEM_CONFIG_FILE This item defines the name and path of the file
                    with modem settings. This file contains information
                    about port settings for each available modem.
* MODEM_COMMANDS    This item defines the name and path of the file
                    with modem commands. For each type of modem you can
                    specify the available modem commands in this file.
MODEM_ENV_VAR       Environment variable set to the pseudo terminal
                    used for communication with the modem.
DEF_MODEM_TYPE      Default modem type. Used when no type is specified
                    for a modem in MODEM_CONFIG_FILE.
ATTN                Default command used to switch the mode from Data
                    Mode to Command Mode. Can be redefined in
                    MODEM_COMMANDS.
RSET                Default command used to reset modem. Can be
                    redefined in MODEM_COMMANDS.
INIT                Default initialization command. Can be redefined in
                    MODEM_COMMANDS.
DIAL                Default command to start dialing. Can be redefined
                    in MODEM_COMMANDS.
HANGUP              Default command to hang up the modem. Can be
                    redefined in MODEM_COMMANDS.
                  
Section Modem locking:
_PATH_LOCKD       This item defines the path where lock files are stored.
_UID_UUCP         This item defines the user who owns the lock files.

Section Personal settings:
PHONEBOOK         This item defines the name and path of the personal
                  phone book.
Section Help:
HELP_URL          Url to location where help files are stored. This can be
                  a file url when files are stored locally or on nfs
                  mounted disks. For example: 
                     file:/usr/local/share/modem

                  The directory part of this URL
                  (/usr/local/share/modem in the example above)
                  should correspond to HELP_DIR as defined in
                  make.config.  When the help files are stored on a
                  www server, you can define HELP_URL as an url to
                  that www server. For example:
                     http://myhost.mydomain/modem
   
# 
# EOF INSTALL
# 
