.\"	$Id$
.\"
.\" HylaFAX Facsimile Software
.\"
.\" Copyright (c) 1990-1996 Sam Leffler
.\" Copyright (c) 1991-1996 Silicon Graphics, Inc.
.\" HylaFAX is a trademark of Silicon Graphics
.\" 
.\" Permission to use, copy, modify, distribute, and sell this software and 
.\" its documentation for any purpose is hereby granted without fee, provided
.\" that (i) the above copyright notices and this permission notice appear in
.\" all copies of the software and related documentation, and (ii) the names of
.\" Sam Leffler and Silicon Graphics may not be used in any advertising or
.\" publicity relating to the software without the specific, prior written
.\" permission of Sam Leffler and Silicon Graphics.
.\" 
.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, 
.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY 
.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  
.\" 
.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR
.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,
.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF 
.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 
.\" OF THIS SOFTWARE.
.\"
.if n .po 0
.ds Fx \fIHyla\s-1FAX\s+1\fP
.TH FAXADDMODEM 8 "May 12, 1996"
.SH NAME
faxaddmodem \- configure a modem for use with \*(Fx
.SH SYNOPSIS
.B /usr/sbin/faxaddmodem
[
.B \-s
.I speed
] [
.B \-f
] [
.I tty
]
.SH DESCRIPTION
.I faxaddmodem
is an interactive shell script that does the
necessary setup work to configure
a modem for use by the \*(Fx software.
To enable use of the configured modem one must either use the
.IR faxmodem (8)
program or configure the
.IR init (8)
program to startup a
.IR faxgetty (8)
process for the newly configured modem.
In either case the
.IR faxq (8)
program must also be running if outbound services are to be provided.
.PP
If the serial port name is not specified on the command line
.I faxaddmodem
will prompt for it.
.PP
The configuration work done by
.I 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 
.I 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.
.PP
Many aspects of configuring a modem are operating system-specific;
.I faxaddmodem
uses a collection of support routines and parameters
that are generated by the
.IR faxsetup (8)
program.
If 
.I faxsetup
has not been run on a machine prior to running then
.I faxaddmodem
will abort.
.PP
.I 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
.I faxaddmodem
deduces the type of modem attached to the specified serial
port and then sets up the configuration parameters using a set of
.I 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,
.I faxaddmodem
will work from a comprehensive template of parameters that can be
edited either during or after the installation process.
.PP
.I 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
.B \-s
option.
.PP
Because
.I 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
.B \-f
option is used, then the system's
.IR fuser (1)
command will be invoked to ensure that faxaddmodem is the only
process using the modem.
.PP
Finally, note that an installation can be safely aborted at any
time by hitting the interrupt key.
.I faxaddmodem
delays making installation-related changes until after everything
has been setup.
.SH OPTIONS
.TP 10
.BI \-s " speed"
Communicate with the modem at a fixed
.IR speed ;
this may be any value recognized by the
.IR stty (1)
command.
.TP 10
.B \-f
Use the
.IR fuser (1)
command for exclusive access to the device.
.SH "PROTOTYPE CONFIGURATION FILES"
.I faxaddmodem
uses prototype configuration files that have been
created for known modems.
These prototype files are kept in the
.B config
subdirectory and, by convention, have names
that identify a brand or type of modem and the
.SM DTE-DCE
flow control scheme the prototype files configures.
The
.IR faxaddmodem (8)
program that is used to configure a modem for use with
\*(Fx 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
``\s-1ATI0\s+1''
and the response from the command
``\s-1ATI3\s+1''
are used to select a prototype configuration file, while for Class 2
modems the manufacturer and model as returned by
``\s-1AT+FMFR?\s+1'' and ``\s-1AT+FMDL?\s+1'', respectively, are
used (or ``\s-1AT+FMI?\s+1'' and ``\s-1AT+FMM?\s+1'' for
Class 2.0 and Class 2.1 modems).
.PP
A Class 1 prototype configuration file is identified for use by
.I faxaddmodem
by searching for a comment of the form:
.nf
.sp .5
\fC# CONFIG:CLASS1:144:.*:RTSCTS: Manufacturer='AT&T' Model=Dataport\fR
.sp .5
.fi
In this example ``144'' is the product ID code for an \s-1AT&T\s+1 DataPort
modem, ``.*'' is a regular expression matched against the result string
returned by the ``\s-1ATI3\s+1'' command,
and ``\s-1RTSCTS\s+1'' indicates the modem is configured to
use hardware flow control during fax operation.
The remainder of the line is evaluated by the
.IR 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).
.PP
Class 2, 2.0, and 2.1 prototype configuration files match the string
``\fImanufacturer\fP-\fImodel\fP-\fIflowcontrol\fP'' against a
.IR sh (1)
glob pattern specified in the configuration file, where
.I manufacturer
and
.I model
are the strings returned by querying the modem and
.I flowcontrol
is either ``\s-1RTSCTS\s+1'' for hardware flow control or
``\s-1XONXOFF\s+1'' for software flow control.
For example:
.sp .5
\fC# CONFIG: CLASS2: ZyXEL*-RTSCTS\fR
.br
\fC# CONFIG: CLASS2.0: USRobotics*-XONXOFF\fR
.sp .5
are configuration comments that appear in the prototype file for
a \s-1ZyXEL 1496E\s+1 with Class 2 support, and for a US Robotics Courier
modem with Class 2.0 firmware.
.PP
The
.I faxaddmodem
program merges server-specific configuration parameters
into a prototype configuration according to comments
placed in the prototype file.
All lines between ``\s-1BEGIN-SERVER\s+1'' and ``\s-1END-SERVER\s+1''
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.
.SH FILES
.ta \w'/var/spool/hylafax/etc/setup.modem    'u
.nf
/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	\s-1SVR4 UUCP\s+1 lockfile name generator
.fi
.PP
Consult
.IR hylafax-server (5)
for a complete discussion of the structure and
content of the spooling area.
.SH "SEE ALSO"
.IR hylafax-server (5),
.IR hylafax-config (5),
.IR faxsetup (8),
.IR faxq (8),
.IR faxgetty (8),
.IR faxmodem (8),
.IR faxconfig (8),
.IR faxsend (8)