NAME
faxaddmodem - configure a modem for use with HylaFAX
SYNOPSIS
/usr/sbin/faxaddmodem [ -s speed ] [ -f ] [ tty ]
DESCRIPTION
faxaddmodem is an interactive shell script that does the necessary
setup work to configure a modem for use by the HylaFAX software. To
enable use of the configured modem one must either use the faxmodem(8)
program or configure the init(8) program to startup a faxgetty(8)
process for the newly configured modem. In either case the faxq(8)
program must also be running if outbound services are to be provided.
If the serial port name is not specified on the command line
faxaddmodem will prompt for it.
The configuration work done by faxaddmodem falls into two main areas:
creating the necessary files to run a facsimile server process, and
defining the contents of the configuration database file. The hylafax-
config (5) manual page has an in-depth description of the contents of
the configuration file and should be consulted when installing a modem.
Many aspects of configuring a modem are operating system-specific;
faxaddmodem uses a collection of support routines and parameters that
are generated by the faxsetup(8) program. If faxsetup has not been run
on a machine prior to running then faxaddmodem will abort.
faxaddmodem can be used to install a new modem or re-configure an
existing modem. In the latter case it will propagate all the server-
related configuration parameters from the existing configuration file
to the new configuration file. These parameter include items such as
the phone number, area code, and tracing control parameters. Modem-
related configuration parameters are, however, not propagated. Instead
faxaddmodem deduces the type of modem attached to the specified serial
port and then sets up the configuration parameters using a set of
prototype configuration files that have been tested with like modems.
If a modem is to be installed for which there is no existing prototype
file, faxaddmodem will work from a comprehensive template of parameters
that can be edited either during or after the installation process.
faxaddmodem deduces the type of modem attached to the serial port by
sending commands to the modem at a fixed speed. By default, this speed
is deduced by sending commands to the modem at successively decreasing
speeds until a valid response is received. Alternatively, a fixed
speed can be specified from the command line with the -s option.
Because faxaddmodem needs to read and write the modem that is to be
installed it will not proceed with an installation if the modem is
locked for use by another process. If the modem is not locked and the
-f option is used, then the system's fuser(1) command will be invoked
to ensure that faxaddmodem is the only process using the modem.
Finally, note that an installation can be safely aborted at any time by
hitting the interrupt key. faxaddmodem delays making installation-
related changes until after everything has been setup.
OPTIONS
-s speed Communicate with the modem at a fixed speed; this may be any
value recognized by the stty(1) command.
-f Use the fuser(1) command for exclusive access to the device.
PROTOTYPE CONFIGURATION FILES
faxaddmodem uses prototype configuration files that have been created
for known modems. These prototype files are kept in the config
subdirectory and, by convention, have names that identify a brand or
type of modem and the DTE-DCE flow control scheme the prototype files
configures. The faxaddmodem(8) program that is used to configure a
modem for use with HylaFAX selects a prototype configuration file using
information retrieved from the modem and comments embedded in the
prototype files. For Class 1 and Class 1.0 modems the product ID code
returned by the command ``ATI0'' and the response from the command
``ATI3'' are used to select a prototype configuration file, while for
Class 2 modems the manufacturer and model as returned by ``AT+FMFR?''
and ``AT+FMDL?'', respectively, are used (or ``AT+FMI?'' and
``AT+FMM?'' for Class 2.0 and Class 2.1 modems).
A Class 1 prototype configuration file is identified for use by
faxaddmodem by searching for a comment of the form:
# CONFIG:CLASS1:144:.*:RTSCTS: Manufacturer='AT&T' Model=Dataport
In this example ``144'' is the product ID code for an AT&T DataPort
modem, ``.*'' is a regular expression matched against the result string
returned by the ``ATI3'' command, and ``RTSCTS'' indicates the modem is
configured to use hardware flow control during fax operation. The
remainder of the line is evaluated by the sh(1) and used to specify the
modem's manufacturer and model (since Class 1 modems do not have
standard commands to query this information).
Class 2, 2.0, and 2.1 prototype configuration files match the string
``manufacturer-model-flowcontrol'' against a sh(1) glob pattern
specified in the configuration file, where manufacturer and model are
the strings returned by querying the modem and flowcontrol is either
``RTSCTS'' for hardware flow control or ``XONXOFF'' for software flow
control. For example:
# CONFIG: CLASS2: ZyXEL*-RTSCTS
# CONFIG: CLASS2.0: USRobotics*-XONXOFF
are configuration comments that appear in the prototype file for a
ZyXEL 1496E with Class 2 support, and for a US Robotics Courier modem
with Class 2.0 firmware.
The faxaddmodem program merges server-specific configuration parameters
into a prototype configuration according to comments placed in the
prototype file. All lines between ``BEGIN-SERVER'' and ``END-SERVER''
comments are placed with the appropriate server configuration
parameters. Note that this means modem-related configuration
parameters must be placed outside this area of the file.
FILES
/var/spool/hylafax/etc/setup.cache master configuration parameters
/var/spool/hylafax/etc/setup.modem modem-related configuration support
/var/spool/hylafax/config prototype configuration files
/usr/sbin/ondelay program to open device without waiting for carrier
/usr/sbin/lockname SVR4 UUCP lockfile name generator
Consult hylafax-server(5) for a complete discussion of the structure
and content of the spooling area.
SEE ALSO
hylafax-server(5), hylafax-config(5), faxsetup(8), faxq(8),
faxgetty(8), faxmodem(8), faxconfig(8), faxsend(8)
May 12, 1996