<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<TITLE>
Server Setup and Basic Configuration
</TITLE>
</HEAD>
<BODY>
<BASEFONT SIZE=4>
<B><FONT SIZE="+3">S</FONT>ERVER
<FONT SIZE="+2">S</FONT>ETUP AND
<FONT SIZE="+2">B</FONT>ASIC
<FONT SIZE="+2">C</FONT>ONFIGURATION</B>
<BASEFONT SIZE=3>
<HR SIZE=4>
HylaFAX is composed of <I>client</I> and <I>server</I> applications.
Client applications are programs that normal users invoke to send
facsimile, query the status of facsimile servers, etc.
Server applications are programs that reside <EM>only on the machine
where the fax modems are present</EM>.
HylaFAX is distributed so that the normal <TT>make install</TT>
step done after <A HREF="building.html#Building">the software is built</A>
will install both client and server applications.
Client-only systems require a slightly different procedure that is
discussed in the next chapter on
``<A HREF="setup-client.html">Client Setup</A>.''
This chapter discusses setting up a server machine for use.
<P>
A system acting as a HylaFAX server usually runs at least two
server processes: the HylaFAX scheduler process <I>faxq</I>
and the client-server protocol process <I>hfaxd</I>.
Server systems may also use the HylaFAX front-door process <I>faxgetty</I>
to monitor each modem on the system and possibly receive incoming
facsimile calls.
A send-only system would run faxq and hfaxd but
(probably) not faxgetty.
A system that was not going to use the transmit capabilities
would not run faxq.
<P>
In addition to the server processes that operate all the time
HylaFAX comes with two programs that
are intended to be run periodically.
The <I>faxqclean</I> program is responsible for purging unwanted
files from the spooling area on a server and the <I>faxcron</I>
script monitors the spooling area and performs routine maintenance
tasks such as truncating log files.
These programs are usually invoked by the system <I>cron</I> program.
<P>
The remainder of this chapter discusses the
basic steps required to setup a HylaFAX server machine:
<OL>
<LI><A HREF="#Software">Install the HylaFAX software.</A>
<LI><A HREF="#Modem">Select a facsimile modem for use.</A>
<LI><A HREF="#Check">Check your modem is functional.</A>
<LI><A HREF="#FlowControl">Select a flow control scheme to use for facscimile communication.</A>
<LI><A HREF="#Device">Select a TTY device to use.</A>
<LI><A HREF="#faxsetup">Use <I>faxsetup</I> to configure a server machine.</A>
<LI><A HREF="#faxaddmodem">Use <I>faxaddmodem</I> to configure modems.</A>
<LI><A HREF="#Starting">Startup outbound service.</A>
<LI><A HREF="#Inbound">Setup the modem for inbound use [<I>optional</I>].</A>
<LI><A HREF="#HFaxd">Setup client access.</A>
<LI><A HREF="#Cron">Setup periodic maintenance work.</A>
</OL>
Note that many decisions in setting up a server machine
are dependent on the operating system present on the machine.
Some system-specific guidance is sprinkled throughout these
materials, with additional information provided in a section on
<A HREF="#Guidance">system-specific guidance</A>.
There is also a section on
``<A HREF="#Problems">Modem Configuration Issues</A>,'' while
advanced configuration and setup issues are discussed in a
subsequent chapter titled
``<A HREF="setup-advanced.htl">Advanced Server Configuration</A>.''
<H3><A NAME="Software"><P><HR WIDTH="65%" ALIGN=right>Installing HylaFAX</A></H3>
Most installations of HylaFAX will be done
from a source code distribution.
In this case installation on a server machine is done by running:
<UL><LISTING>
hyla# make install # NB: must be done by the super-user
</LISTING></UL>
from the top-level of the build area.
Note that <EM>this step must be done as the super-user or file ownerships
will be wrong</EM>.
<P>
When working from a binary distribution the technique required
to install the software programs varies based on the format used
to distribute the materials.
Each binary distributions of HylaFAX should include detailed
installation instructions that reflect the exact contents of the distribution
and any distribution-specific requirements.
<H3><A NAME="Modem"><P><HR WIDTH="65%" ALIGN=right>Selecting a Facsimile Modem</A></H3>
Selecting a modem usually means purchasing a modem that is capable
of sending and receiving facsimile.
Most any fax-capable modem can be used with HylaFAX but not all are equal.
HylaFAX has drivers for Class 1, Class 2, and Class 2.0 facsimile
modems, but there are <A HREF="class1.html">caveats on the use of
Class 1 modems</A>.
Class 2 modems are the most common, but due to the non-standard
nature of the specification that they are implemented against
compatibility can be a problem.
Note also that the quality of Class 2 modems varies significantly.
Class 2.0 modems follow the latest standard, a ratified version of
the specification used in implementing Class 2 modems.
There are significantly fewer Class 2.0 modems available, though
the quality of these modems also varies significantly.
There is a (constantly growing)
<A HREF="modems.html">list of modems</A>
that have been tried with HylaFAX and
this list includes several modems that have been found to be
reliable for use in sending and receiving facsimile.
<P>
<TABLE BORDER=0>
<TR>
<TD><IMG ALT="Note!" SRC="icons/warning_icon.gif" HSPACE=8></TD>
<TD><EM>If you are buying a modem to use
with this software you will do best if you use one of the
recommended Class 2 or Class 2.0 modems; rather than a Class 1 modem</EM>.</TD>
</TR>
</TABLE>
<H3><A NAME="Check"><P><HR WIDTH="65%" ALIGN=right>Checking Your Modem</A></H3>
Once you have a modem to use with HylaFAX
first make sure that the modem works for data use.
One can not say this enough. If you can not use a communication
program such as
<I>cu</I>,
<I>tip</I>,
or
<I>kermit</I>,
with your modem, do not
try to configure it for use with HylaFAX.
This means in particular that you should verify that you have a
working cable between
your host and modem and that this cable is suitable for use. That is,
that the cable has the relevant signals for doing hardware flow control
if that is necessary and that it passes the DCD and DTR signals
appropriately.
<P>
Verify that the modem you are using is a fax modem.
This can be done by communicating directly with the modem
using a communication
program such as cu; for example:
<UL><LISTING>
hyla% <B>cu -l ttyf2</B>
Connected
<B>at+fclass=?</B>
0,1,2
OK
<B>~</B>[hyla]<B>.</B>
Disconnected
</LISTING></UL>
The <TT>at+fclass=?</TT> command asks the modem to report which
<I>classes</I> it is capable of supporting.
Class 0 is for data use.
Class 1, Class 2, and Class 2.0 are for facsimile use.
Other classes may be reported, for example, for modems that
provide digitized voice support.
HylaFAX can be used with any modem that supports Class 1, Class 2,
or Class 2.0.
<H3><A NAME="FlowControl"><P><HR WIDTH="65%" ALIGN=right>Selecting a Flow Control Scheme</A></H3>
<I>Flow control</I> refers to the mechanism used to control the transfer
of data <EM>between the host and the modem</EM>
(there may also be a flow control scheme used in modem-to-modem
communication but the discussion here is specific to the scheme used
between the host and a modem).
The rules to use for selecting a host-modem flow control method for
facsimile use are:
<UL>
<LI>If you have a Class 1 modem, then you can use either hardware or
software flow control, but beware of using hardware flow control
as the Class 1 specification only requires vendors to support
software flow control (and many of the Class 1 modems tried so far
do not properly support hardware flow control).
<LI>If you have a Class 2 or Class 2.0 modem,
then you can use either hardware or
software flow control, but if you are going to communicate with the
modem faster than 9600 baud then you should probably use hardware
flow control.
</UL>
<P>
<TABLE BORDER=0>
<TR>
<TD><IMG ALT="Note!" SRC="icons/warning_icon.gif" HSPACE=8></TD>
<TD><EM>Beware that although a modem may properly implement hardware
flow control when doing data communication, it may not
support hardware flow control during facsimile communication. Consult
the <A HREF="Modems/">modem information</A> for specifics on
some modems.</EM></TD>
</TR>
</TABLE>
<P>
If a prototype configuration file for your modem is included in the
HylaFAX distribution then the appropriate default flow control scheme
should be defined for the modem.
<P>
<TABLE BORDER=0>
<TR>
<TD VALIGN=top><IMG ALT="Note!" SRC="icons/warning_icon.gif" HSPACE=4></TD>
<TD><EM>Note that some operating systems do not support RTS/CTS flow
control unless carrier is present.
In particular, some versions of SunOS and
Solaris requires patches to correct this mis-behaviour;
consult the sections below for
<A HREF="#Guidance">system-specific guidance</A>.</EM></TD>
</TR>
</TABLE>
<TABLE BORDER=0>
<TR>
<TD VALIGN=top><IMG ALT="Note!" SRC="icons/warning_icon.gif" HSPACE=4></TD>
<TD><EM>
Versions of IRIX prior to 6.2 have a bug in the
device driver for the on-board serial ports on IP20 and IP22 systems
that causes RTS/CTS flow control to be turned off by HylaFAX.
Patch 475 (``RTS/CTS flow control busted when <TT>CLOCAL</TT> is set'')
and its successors correct
this problem and must be installed to use HylaFAX with hardware flow control.
For complete details refer to the section below on
<A HREF="#IRIX">IRIX-specific guidance</A>.</EM></TD>
</TR>
</TABLE>
<P>
When in doubt or having trouble, configure the modem to use software
flow control for fax use.
<H3><A NAME="Device"><P><HR WIDTH="65%" ALIGN=right>Choosing a TTY Device</A></H3>
There are two things to beware of in selecting a tty device file to
use with your modem: flow control usage and port locking mechanisms.
<P>
On many systems different devices are used to select different
flow control schemes and/or whether or not the system will monitor
the DCD signal.
For example, IRIX systems use <B>ttym*</B> and <B>ttyf*</B>
device names to identify devices that monitor DCD but only
the latter support RTS/CTS flow control.
Similarly, the FAS driver for SCO uses a different names
as does the standard HP-UX terminal driver.
<P>
On some systems inbound and outbound port use is interlocked by
using a pair of devices, one for inbound use and another for
outbound use. Typically this scheme works by stopping programs that
use the inbound device until an inbound call is received (and DCD
is raised by the modem).
Outbound usage is also interlocked against applications waiting
for the inbound device.
HylaFAX provides no direct support for this because this scheme
requires that a modem
auto-answer incoming calls (something that is hard to make work with
multi-mode--i.e. fax and data--modems).
When faced with a system that uses this scheme
most people elect to avoid the inbound device and run both incoming and
outgoing traffic on the outbound device, using the built-in interlocking
mechanism provided by HylaFAX.
In this case the appropriate device to use is typically named
<B>/dev/cu*</B>, but check local conventions.
<P>
On some systems, especially SVR4-based systems,
device special files are located in subdirectories.
Thus a typical device name might be <B>/dev/term/10</B>.
HylaFAX server processes often reference a modem by
a <I>device identifier</I>
that is derived from the device filename by removing the
leading ``<B>/dev/</B>'' prefix and then converting any remaining
``/'' characters to ``_'' characters.
Thus <B>/dev/term/10</B> would have a device identifier of ``term_10''.
Usually this work is transparent and device filenames can be
interchanged freely with device identifiers.
However because of this interchangability it is not possible to
use device files that have names that include
``_'' in them, e.g. ``/dev/my_tty''.
<H3><A NAME="faxsetup"><P><HR WIDTH="65%" ALIGN=right>Using faxsetup to Configure a Server Machine</A></H3>
Before any HylaFAX software can be used on a server machine the
<A HREF="@CGIPATH@/manpage?faxsetup">faxsetup</A> script
must be run.
This interactive script verifies the installation of the HylaFAX
software and also carries out a variety of one-time tasks that
prepare the system for use.
Running faxsetup is especially important when working from
a binary distribution because it checks that parameters setup at
the time the distribution was built are correct for the target
machine where the software is to be run.
<P>
faxsetup carries out a variety of tasks and then writes
configuration information to two files in the HylaFAX
spooling area.
The file <B>etc/setup.cache</B> in the spooling area
contains the parameter settings used by HylaFAX command
scripts while the <B>etc/setup.modem</B> file
contains settings and shell functions
used by command scripts that communicate with modems.
<P>
<TABLE BORDER=0>
<TR>
<TD><IMG ALT="Note!" SRC="icons/warning_icon.gif" HSPACE=4></TD>
<TD><EM>The <B>setup.cache</B> and <B>setup.modem</B>
files must be present for HylaFAX to function properly.
If these files do not exist then HylaFAX server applications will
terminate with an error message.</EM></TD>
</TR>
</TABLE>
<P>
The work done by faxsetup includes the items
listed below.
Note that faxsetup always prompts for permission before
doing anything that might affect normal system
operation (e.g. adding a new user to the password file).
<UL>
<LI>faxsetup
verifies that the pathnames compiled into HylaFAX applications
are correct and that the expected directory hierarchy used by
client and server applications is present and setup correctly.
If any of these checks fails then it is assumed that HylaFAX
has not been installed or that there is a misconfiguration
problem such as might occur when a binary distribution is
loaded in an unexpected location.
<LI>faxsetup
verifies that the TIFF software distribution is properly installed
on the server machine. HylaFAX uses certain of the TIFF tools
in normal server operation and, if the TIFF library has been
built as a DSO, requires the TIFF library DSO for proper operation.
<LI>faxsetup
verifies that the server machine is properly configured to support
FIFO special files. Some operating systems are distributed
without support for this feature and must be reconfigured
before HylaFAX can be used.
<LI>faxsetup
verifies that the configured PostScript RIP is present and that
it has the necessary functionality to use it with HylaFAX.
Ghostscript users must be sure to configure the ``tiffg3''
device driver when building Ghostscript for use with HylaFAX.
IRIX users must be aware that the DPS-based RIP distributed
for use with HylaFAX is a COFF executable that cannot be
used under IRIX 6.2 or later.
<LI>faxsetup
verifies that a ``fax'' user is registered in the password file
or YP/NIS database. If one is not setup then one is created.
The fax user is used in various places in HylaFAX and should
be setup to have the same user ID as that of ``uucp''
so that UUCP lock files can be shared. (If you run IRIX the
``fax'' user will also
be added to the <B>passwd.sgi</B> file so that it does not show up in
the normal palette of users displayed during the login procedure.)
<LI>faxsetup
verifies that suitable entries for the ``hylafax'' and ``snpp''
services exists in the <B>/etc/services</B>
file or in the equivalent YP/NIS database.
If no entries are present then they may optionally be setup
(the software will still function properly without them).
<LI>faxsetup
verifies that the hfaxd client-server protocol process
is started up when the system is brought up multi-user or
that hfaxd is started by the
<A HREF="@CGIPATH@/manpage?inetd">inetd</A>
program.
hfaxd is the process that HylaFAX client applications
communicate with to submit jobs, query server status, etc.
It operates most efficiently when run in standalone but may
also be invoked through inetd.
Without hfaxd HylaFAX is basically useless.
<LI>faxsetup
verifies that a ``FaxMaster'' entry is present in the aliases
database. This alias is equivalent to the normal PostMaster alias
that is used to deliver mail-related problems; HylaFAX
directs notices about problems and received facsimile to this alias.
The FaxMaster alias should list those system administrators that will
handle HylaFAX-specific problems.
If an alias is not present, then one is created.
</UL>
Following the above work faxsetup then prompts to create
a configuration file for the HylaFAX scheduler process and
for any modems on the system that are to be used by HylaFAX.
Finally the HylaFAX server processes are started up, or restarted
if an existing installation is being updated or reconfigured,
and any modem configuration work is performed.
The following sections elaborate on this work and provide examples
of how this work is done.
<H3><A NAME="faxaddmodem"><P><HR WIDTH="65%" ALIGN=right>Using faxaddmodem to Configure Modems</A></H3>
Modems are configured for use with the
<A HREF="@CGIPATH@/manpage?faxaddmodem">faxaddmodem</A> script.
This is an interactive script that walks you through the
configuration and installation of a new or existing modem.
Even if you have a previous version of HylaFAX or FlexFAX
installed it is a good idea to run faxaddmodem
to update the configuration information for your modems after
installing a new distribution.
<P>
faxaddmodem may be run directly from the command line
or via the faxsetup script
that is used to prepare a server machine for use with HylaFAX.
<P>
The remainder of this
section shows a sample configuration session and describes
the work done. The session is shown on the left hand side
in a <TT>fixed width font</TT> with user-supplied input
in a <TT><B>bold font</B></TT>.
Comments are shown to the right in a normal or <I>italic</I> font,
separated by horizontal rules.
Blank space is present in the session output
where it is needed to fit comments on the page; in
normal operation the output from faxaddmodem does not include
this white space.
faxaddmodem displays the current/default setting for a configuration
parameter enclosed in ``<TT>[]</TT>''; the current value
is accepted by typing a carriage-return.
<P>
This session was collected on a Silicon Graphics Indy machine
running IRIX 5.3
and communicating with a USR Courier v.Everything modem.
<HR>
<TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0>
<TR>
<TD VALIGN=top><LISTING>
hyla# <B>faxaddmodem ttyf2</B>
Ok, time to setup a configuration file for the modem. The manual
page config(4F) may be useful during this process. Also be aware
that at any time you can safely interrupt this procedure.
</LISTING></TD>
<TD VALIGN=top><FONT SIZE=2>
If your modem is configured to
communicate with the host at a fixed speed, then use the
<TT>-s</TT> option to lock the host-modem baud rate.
Note also that faxaddmodem must be run as root.
</FONT></TD>
</TR>
<TR>
<TD COLSPAN=2><FONT SIZE=2>
<HR>
<I>Collect server-specific configuration parameters.</I>
Per-modem configuration files contain parameters that pertain to
the operation of the modem and parameters that control the function
of the HylaFAX server software that controls the modem.
The former parameters are termed modem-specific while the
latter are referred to as server-specific.
faxaddmodem collects server-specific parameters first and then
modem-related parameters are setup based on the type of modem.
<HR>
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
Reading scheduler config file /var/spool/hylafax/etc/config.
</LISTING></TD>
<TD><FONT SIZE=2>
The configuration file for the HylaFAX scheduler is automatically
read to get default settings for parameters such as the area code.
<HR>
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
No existing configuration, let's do this from scratch.
</LISTING></TD>
<TD><FONT SIZE=2>
If a configuration file already exists for a modem, the
server-specific parameters will be carried over to the new configuration,
but the modem-specific parameters will not.
<HR>
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
Country code [1]?
Area code [510]?
</LISTING></TD>
<TD><FONT SIZE=2>
<EM>The area code may be set to a null string or omitted
in locations where one does not exist.</EM>
<HR>
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
Phone number of fax modem [+1.999.555.1212]? <B>+1 510 526-8788</B>
</LISTING></TD>
<TD><FONT SIZE=2>
This is the phone number associated with the modem.
By default this number is passed as an <I>identity</I>
to peer fax machines (see below) and it may also appear
on tag lines created by the fax server.
</FONT></TD>
</TR>
<TR>
<TD COLSPAN=2><FONT SIZE=2>
<HR>
<IMG ALT="Info" SRC="icons/info_icon.gif" HSPACE=8 ALIGN=left>
Phone numbers should be supplied with a
complete international dialing specification:
``+<<I>country code</I>> <<I>local part</I>>''
(the <<I>local part</I>> includes an area code
where such a notion exists.)
<BR CLEAR=left>
<HR>
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
Local identification string (for TSI/CIG) ["NothingSetup"]? <B>""</B>
</LISTING></TD>
<TD VALIGN=top><FONT SIZE=2>
The local identification string is passed to
peer fax machines during
communication. If it is not specified, or set to a null string, then
the canonical phone number of the fax modem is used instead.
</FONT></TD>
</TR>
<TR>
<TD COLSPAN=2><FONT SIZE=2>
<HR>
<IMG ALT="Info" SRC="icons/info_icon.gif" HSPACE=8 ALIGN=left>
Beware
that the facsimile communication protocol restricts
the local identification string to numbers, blank, and the ``+'' symbol.
In practice however, most facsimile machines will accept any ASCII string.
<BR CLEAR=left>
<HR>
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
Long distance dialing prefix [1]?
International dialing prefix [011]?
Dial string rules file (relative to /var/spool/hylafax)
[etc/dialrules.sf-ba]?
</LISTING></TD>
<TD VALIGN=top><FONT SIZE=2>
The dial string rules file holds rules
used to convert user-supplied
dialing strings (i.e. phone numbers) to a canonical format and to
prepare strings for delivery to a modem. The default rules do very
little. Specific dialing rules may be useful for your site or locale
based on how your modems are connected to the PTT. Consult the
section in the <A HREF="setup-advanced.html#DialRules">Advanced Server
Configuration</A> chapter for more information.
<HR>
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
Tracing during normal server operation [1]?
Tracing during send and receive sessions [11]?
</LISTING></TD>
<TD VALIGN=top><FONT SIZE=2>
These parameters control the logging done by server processes.
</FONT></TD>
</TR>
<TR>
<TD COLSPAN=2><FONT SIZE=2>
<HR>
<IMG ALT="Note!" SRC="icons/warning_icon.gif" HSPACE=8 VSPACE=8 ALIGN=left>
<EM>It is important that tracing during send and receive sessions include
sufficient information to diagnose problems. For Class 1 modems this
parameter is usually set to <TT>0x4f</TT> so that HDLC frames are
included in the logs. For Class 2 and Class 2.0 modems the default
setting of 11 is typically ok.
Consult the descriptions of <TT>ServerTracing</TT> and <TT>SessionTracing</TT>
in the
<A HREF="@CGIPATH@/manpage?hylafax-config">config</A> manual page.</EM>
<BR CLEAR=left>
<HR>
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
Protection mode for received facsimile [0600]?
</LISTING></TD>
<TD VALIGN=top><FONT SIZE=2>
The default parameter selected here makes
all received facsimile accessible
only to the fax user. It may be desirable to set this parameter to
<TT>0644</TT> so that anyone can look at received facsimile.
<HR>
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
Protection mode for session logs [0600]?
Protection mode for ttym2 [0600]?
</LISTING></TD>
<TD VALIGN=top><FONT SIZE=2>
Note that if sensitive information such as credit card access codes
are supplied by users that they will appear in the session logs kept
on the server machine. For this reason the default protection mode
for session logs protects them from public access.
<HR>
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
Rings to wait before answering [1]?
</LISTING></TD>
<TD><FONT SIZE=2>
This parameter is used during inbound call handling. It
specifies the number of rings to wait before answering the phone.
See the section on inbound call handling for a discussion of
the different schemes that are supported for handling calls.
<HR>
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
Modem speaker volume [off]?
Command line arguments to getty program ["-h %l dx_%s"]?
</LISTING></TD>
<TD VALIGN=top><FONT SIZE=2>
This parameter is also related to inbound call handling. It controls
whether or not to enable support for inbound data calls and should
not be set without first understanding how to setup your system
for incoming data usage.
<HR>
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
Pathname of TSI access control list file
(relative to /var/spool/hylafax) [""]?
</LISTING></TD>
<TD VALIGN=top><FONT SIZE=2>
The TSI access control list file can be used to restrict inbound
facsimile access. The default parameter causes all inbound calls
to be accepted. This parameter is discussed more below.
<HR>
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
Tag line font file (relative to /var/spool/hylafax) [etc/lutRS18.pcf]?
Tag line format string ["From %%l|%c|Page %%p of %%t"]?
</LISTING></TD>
<TD VALIGN=top><FONT SIZE=2>
Tag lines are an optional feature that cause each
page of an outbound facsimile to be marked with a line of text.
A proper description of the tag line support is provided in the
<A HREF="setup-advanced.html#TagLine">Tagline Configuration</A> section
of the next chapter.
</FONT></TD>
</TR>
<TR>
<TD COLSPAN=2><FONT SIZE=2>
<HR>
<IMG ALT="Note!" SRC="icons/warning_icon.gif" HSPACE=8 ALIGN=left>
<EM>Note that in the United States some form of identification
of the sender of a facsimile is required by law; properly configured
tag lines are an acceptable form of identification.
Beware that the default tag line includes the phone number
defined above; make sure this number is correct!
</EM>
<BR CLEAR=left>
<HR>
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
Time before purging a stale UUCP lock file (secs) [30]?
</LISTING></TD>
<TD VALIGN=top><FONT SIZE=2>
This parameter controls the time that a HylaFAX server process
will wait before removing a UUCP lock file whose owner appears
to be gone. The default parameter forces these stale lock files
to be left around for just 30 seconds.
This is an appropriate value to use on systems where applications
that use UUCP lock files are known to be well behaved.
<HR>
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
Percent good lines to accept during copy quality checking [95]?
Max consecutive bad lines to accept during copy quality checking [5]?
Max number of pages to accept in a received facsimile [25]?
Syslog facility name for ServerTracing messages ["local5"]?
</LISTING></TD>
<TD VALIGN=top><FONT SIZE=2>
More parameters associated with inbound facsimile jobs; consult
the section below.
</FONT></TD>
</TR>
<TR>
<TD COLSPAN=2><FONT SIZE=2>
<HR>
<IMG ALT="Info" SRC="icons/info_icon.gif" HSPACE=8 ALIGN=left>
The syslog facility controls where HylaFAX directs server tracing-related
messages. By setting this parameter to a non-standard
value HylaFAX messages can easily be recorded in a file separate
from the normal system messages. Consult the
<A HREF="troubleshooting.html#ServerBasics">Troubleshooting chapter</A>,
for more information.
<BR CLEAR=left>
<HR>
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
Set UID to 0 to manipulate CLOCAL [""]? <B>yes</B>
</LISTING></TD>
<TD VALIGN=top><FONT SIZE=2>
This parameter should only need to be set on Silicon Graphics
systems. Consult the section on
<A HREF="#IRIX">IRIX-specific guidance</A> for
a description of why this parameter might be used.
<HR>
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
The non-default server configuration parameters are:
CountryCode: 1
AreaCode: 510
FAXNumber: +1 510 526-8788
LongDistancePrefix: 1
InternationalPrefix: 011
DialStringRules: etc/dialrules.sf-ba
SessionTracing: 11
RingsBeforeAnswer: 1
SpeakerVolume: off
GettyArgs: "-h %l dx_%s"
LogFacility: local5
TagLineFont: etc/lutRS18.pcf
TagLineFormat: "From %%l|%c|Page %%p of %%t"
MaxRecvPages: 25
ClocalAsRoot: yes
Are these ok [yes]?
</LISTING></TD>
<TD VALIGN=top><FONT SIZE=2>
This completes the collection of server-related parameters; the
remaining steps identify and configure the modem for use.
If the displayed parameters are unacceptable, typing something other
than <TT>yes</TT> or a carriage return will cause faxaddmodem
to prompt for new/changed parameter settings.
</FONT></TD>
</TR>
<TR>
<TD COLSPAN=2><FONT SIZE=2>
<HR>
<I>Setup modem-specific configuration parameters.</I>
faxaddmodem probes the modem to find out what type it is and
what capabilities it has.
The modem identity is then matched against a set of prototype
configuration files to come up with modem-specific parameters
that are appropriate to the modem and the style of flow control
that is to be used between the host and modem.
If the modem is not supported by an existing prototype configuration
then faxaddmodem will prompt to get values for parameters.
<HR>
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
Now we are going to probe the tty port to figure out the type
of modem that is attached. This takes a few seconds, so be patient.
Note that if you do not have the modem cabled to the port, or the
modem is turned off, this may hang (just go and cable up the modem
or turn it on, or whatever).
</LISTING></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
Probing for best speed to talk to modem: 38400 OK.
</LISTING></TD>
<TD><FONT SIZE=2>
Use the <TT>-s</TT> option to avoid probing.
<HR>
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
This modem looks to have support for both Class 1 and 2;
how should it be configured [2]?
</LISTING></TD>
<TD VALIGN=top><FONT SIZE=2>
Modems that support multiple classes can be configured to use
any supported class. By default Class 2.0 is considered better
than Class 2 which is preferred over Class 1.
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
Hmm, this looks like a Class 2.0 modem.
Modem manufacturer is "USRobotics Courier V.Everything".
Modem model is "Product type US/Canada External".
</LISTING></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
DTE-DCE flow control scheme [default]?
</LISTING></TD>
<TD VALIGN=top><FONT SIZE=2>
The flow control scheme requested is one of <TT>xonxoff</TT> for
software flow control, <TT>rtscts</TT> for hardware flow control,
or <TT>default</TT> for a setting that is appropriate for the
modem and the tty device.
</FONT></TD>
</TR>
<TR>
<TD COLSPAN=2><FONT SIZE=2>
<HR>
<IMG ALT="Note!" SRC="icons/warning_icon.gif" HSPACE=8 VSPACE=8 ALIGN=left>
<EM>Beware of using an improper flow control scheme for the selected
tty device. On systems where faxaddmodem understands how
tty device names reflect flow control characteristics, selecting
a flow control scheme not supported by the device will cause
faxaddmodem to prompt for confirmation and/or to change the device
name or the flow control scheme.</EM>
<BR CLEAR=left>
<HR>
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
Using prototype configuration file usr-2.0...
The modem configuration parameters are:
ModemFlowControl: rtscts
ModemHardFlowCmd: AT&H1&I0&R2
ModemNoFlowCmd: AT&H0&I0&R1
ModemRate: 38400
ModemResultCodesCmd: ATQ0X4
ModemSetVolumeCmd: "ATM0 ATM1 ATM1 ATM1 ATM1"
ModemSetupAACmd: AT+FAA=1
ModemSetupDCDCmd: AT&C1
ModemSetupDTRCmd: ATS13=1&D2
ModemSoftFlowCmd: AT&H2&I2&R1
Class2BUGCmd: AT+FBU=0
Class2CQQueryCmd: !(0),(0)
Are these ok [yes]?
</LISTING></TD>
<TD VALIGN=top><FONT SIZE=2>
The modem-specific configuration parameters are obtained
from prototype configuration files that reside in the <B>config</B>
subdirectory of the HylaFAX spooling area. These parameters have
been taken from working systems and should provide a functioning configuration
based on the modem type and the selected flow control scheme.
</FONT></TD>
</TR>
<TR>
<TD COLSPAN=2><FONT SIZE=2>
<HR>
<I>If no prototype configuration file exists for a modem then faxaddmodem
will prompt for settings.</I>
There are generic prototype configuration
files for Class 1, Class 2, and Class 2.0 modems.
Because there are many configuration parameters for modems it may
be preferrable to use a normal text editor instead of
faxaddmodem when constructing a configuration file for an
unsupported modem, To do this simply accept the default parameters
and then edit the generated configuration file before starting up
a server for the modem. Once a working configuration file is
created it is simple to create a prototype file from it; consult the
<A HREF="@CGIPATH@/manpage?faxaddmodem">faxaddmodem</A>
or
<A HREF="@CGIPATH@/manpage?hylafax-config">config</A>
manual pages for information on doing this.
<HR>
</FONT></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
Creating new configuration file /var/spool/hylafax/etc/config.ttyf2...
Done setting up the modem configuration.
</LISTING></TD>
</TR>
<TR>
<TD VALIGN=top><LISTING>
Checking /var/spool/hylafax/etc/config for consistency...
...everything looks ok; leaving existing file unchanged.
Don't forget to run faxmodem(1M) (if you have a send-only environment)
or configure init to run faxgetty on ttyf2.
</LISTING></TD>
<TD VALIGN=top><FONT SIZE=2>
At this point faxaddmodem compares the parameters setup
for the modem against the parameters setup for the HylaFAX scheduler
process. If any parameters are incompatible
it prompts to see if they should be used to create a new
file for the scheduler.
</FONT></TD>
</TR>
</TABLE>
<HR>
Once a modem has been setup with faxaddmodem the HylaFAX
scheduler process must be informed of its presence.
This can be accomplished in one of two ways.
If a system is to be used only for transmitting facsimile then the
scheduler is informed by running the faxmodem command.
Otherwise, if a modem is to be used for both inbound and outbound
use then a faxgetty process should be setup to manage
the modem--this process will automatically inform the scheduler
once it has initialized the modem for use.
There are also valid reasons to use faxgetty on modems that
are to be used strictly for data; this and other variations in
configuring the software are discussed later.
If a modem was previously in use nothing needs to be
done; the HylaFAX server processes will notice the new configuration
file and automatically use its contents.
If faxaddmodem was invoked by faxsetup then faxsetup should complete
the steps necessary to complete the setup of a HylaFAX server machine.
<H3><A NAME="Starting"><P><HR WIDTH="65%" ALIGN=right>Starting Outbound Service</A></H3>
Outbound service is carried out by the HylaFAX scheduler process, the
<A HREF="@CGIPATH@/manpage?faxq">faxq</A> program.
There is one faxq process for all modems on a system.
The faxq program learns about modems that can be used for outbound
jobs by messages it receives on a FIFO special file located
in the HylaFAX spooling area on the server machine.
These messages come from two sources: from the
faxmodem program that is used to manually enable a modem for use, or
from faxgetty processes that are
setup to run on each tty device where a fax modem resides.
<P>
Specifying modems with faxmodem is useful when HylaFAX
is to be used in a <I>send-only configuration</I>.
Doing this however limits the functionality of the scheduler
because it will not know the true state of each modem; e.g. when
a modem is in use by an outbound application such as uucp or tip.
Instead faxq will assume that each modem is ready for use except
when it is actively being used by HylaFAX to transmit a facsimile
or alpha-numeric page.
<P>
A modem specified with faxmodem
is identified by the tty device it is attached to.
Thus, to notify the scheduler that two modems are available for use, the
following might be used:
<UL><LISTING>
hyla# <B>faxmodem tty01</B>
hyla# <B>faxmodem /dev/tty02</B>
</LISTING></UL>
(note that devices may be specified with or without a leading
<B>/dev/</B> prefix.)
Modem specified as above are assumed to have a default set of
<I>capabilities</I>: whether or not they support polled retrieval
of facsimile documents, what speeds they support for transmitting
facsimile, whether or not they handle high resolution facsimile, etc.
It is a good idea to specify the correct set of capabilities
for a modem when using faxmodem, otherwise you may not get best use
of a modem.
Not identifying when a modem has limited capabilities can also
cause HylaFAX to do extra work or cause errors that might be
avoided.
<P>
Modem capabilities are specified through faxmodem with the syntax
used by Class 2 and Class 2.0 modems.
This makes it easy to setup a Class 2/2.0 modem: all you need to
do is make a simple query to the modem to get the capabilities
string to pass to faxmodem.
For example, for a Class 2.0 modem the following commands would
be used:
<UL><LISTING>
hyla% <B>cu -l ttyf2</B>
Connected
<B>at+fclass=2.0</B>
OK
<B>at+fcc=?</B>
(0,1),(0-5),(0-2),(0-2),0,0,0,(0-7)
OK
</LISTING></UL>
This sets the modem in Class 2.0 and then asks for the set of
communication capabilities.
The resulting string is then passed to faxmodem:
<UL><LISTING>
hyla# <B>faxmodem -c '(0,1),(0-5),(0-2),(0-2),0,0,0,(0-7)' ttyf2</B>
</LISTING></UL>
(note the quote marks around the string so that the shell does
not interpret the parentheses).
<P>
For a Class 2 modem the commands are slightly different:
<UL><LISTING>
hyla% <B>cu -l ttyf2</B>
Connected
<B>at+fclass=2</B>
OK
<B>at+fdcc=?</B>
(0,1),(0-5),(0-2),(0-2),0,0,0,(0-7)
OK
</LISTING></UL>
<P>
For a Class 1 modem an entirely different procedure is needed because
the modem only implements a small portion of the facsimile protocol.
This means that the capabilities are mostly dependent on the HylaFAX
software and not on the modem.
The only information needed from the modem is which signalling rates
are supported for transmitting fax data; this is obtained with:
<UL><LISTING>
hyla% <B>cu -l ttyf2</B>
Connected
<B>at+fclass=1</B>
OK
<B>at+ftm=?</B>
24,48,72,73,74,96,97,98
OK
</LISTING></UL>
and from there a capabilities string can be crafted by understanding
that the above list indicates the modem can transmit at speeds from
2400 bps (<TT>24</TT>), 4800 bps (<TT>48</TT>), 7200 bps
(<TT>72,73,74</TT>), and 9600 bps (<TT>96,97,98</TT>).
(Multiple values for a particular speed indicate support for
multiple <I>modulation schemes</I>; if any one value is reported then
the corresponding speed should be specified in the capabilities string.)
Thus the capabilities string is
``(0,1),(0-3),(0-2),(0-2),0,0,0,(0-7)''
(note the second segment is 0-3 instead of the 0-5 used above
which indicated that the modem supported 12200 and 14400 bps
signalling rates).
Consult the
<A HREF="@CGIPATH@/manpage?faxmodem">faxmodem</A>
manual page for more information.
<P>
When faxq is used in conjunction with faxgetty no modems need
to be specified using faxmodem.
If modems are specified however; faxq will
just treat the modems as ready for use until it receives more up to date
information from the faxgetty processes.
<H3><A NAME="Inbound"><P><HR WIDTH="65%" ALIGN=right>Setting up Inbound Service</A></H3>
To setup HylaFAX for inbound facsimile or data service a
modem configuration file must be setup and
a faxgetty program must be started to listen for input on the tty device.
The configuration file setup is usually done at the same time
that outbound service is configured; i.e. when faxaddmodem is run.
A faxgetty server for the modem should be setup to be run by the
<A HREF="@CGIPATH@/manpage?init">init</A>
process according to local system conventions.
For System V-based systems this is done by editing the
<B>/etc/inittab</B> file to spawn faxgetty on the appropriate port.
For example, if a modem is to be started on <B>/dev/ttyf2</B> the
following line might be appropriate:
<UL><TT>
<PRE>t2:23:respawn:/usr/local/sbin/faxgetty ttyf2</PRE>
</TT></UL>
For systems that use a BSD-style setup the following line might
be appropriate for the <B>/etc/ttyab</B> file.
<UL><TT>
<PRE>cua0 "/usr/local/sbin/faxgetty /dev/cua0" dialup on</PRE>
</TT></UL>
Note that faxgetty may be run on a modem port whether or not it is
to provide inbound service.
By setting the <TT>RingsBeforeAnswer</TT> configuration parameter to zero,
faxgetty will not answer an
incoming phone call unless it is explicitly commanded to by the
<A HREF="@CGIPATH@/manpage?faxanswer">faxanswer</A>
program.
This may be desirable if a phone line is used, for example,
as the primary line for voice calls.
<P>
In general it is desirable to run faxgetty because
faxgetty informs the HylaFAX scheduler process whenever
modems are in use and because it identifies modems' capabilities
(passing them on to the scheduler so that it can make informed
scheduling decisions).
faxgetty also includes support for
screening calls based on
caller-ID information (consult the section
``<A HREF="setup-advanced.html#CallerID">Caller-ID Support</A>'')
and for automatically routing calls based
on distinctive ring when these services are provided by the local PTT
(consult the section
``<A HREF="setup-advanced.html#DistinctiveRing">Distinctive Ring Support</A>'') .
For this additional functionality, and
because faxgetty does a reliable job of reseting and configuring
recalcitrant modems, it may even be desirable to run faxgetty on
non-fax modems.
<P>
The following sections discuss HylaFAX support for
servicing particular types of inbound calls.
<H4><A NAME="Fax"><P><HR WIDTH="25%" ALIGN=center>Facsimile Service</A></H4>
In normal operation HylaFAX's faxgetty process
will automatically answer inbound phone
calls and receive facsimile.
Received facsimile are written to files in the <B>recvq</B> directory
in the spooling area on the server machine.
Facsimile data is stored as a TIFF Class F (TIFF/F) file and
protected according to the <TT>RecvFileMode</TT> configuration parameter
specified in the modem configuration file.
The <TT>RecvDataFormat</TT> configuration parameter can be used to
control the encoding of data stored in these files; consult the
section on
``<A HREF="setup-advanced.html#Transcoding">Transcoding of Received Facsimile</A>''
for more information on this facility.
The maximum number of pages that will be received in a single
call can also be controlled with the <TT>MaxRecvPages</TT>
configuration parameter.
Finally, HylaFAX provides an access control list mechanism for
restricting recived facsimile according to the TSI
string passed as part of the facsimile protocol;
consult the section on
``<A HREF="setup-advanced.html#QualifyTSI">Rejecting Junk Facsimile</A>''
for more information.
<H4><A NAME="Data"><P><HR WIDTH="25%" ALIGN=center>Data Service</A></H4>
By default HylaFAX does not enable support for inbound data calls.
Data service is not enabled so that naive users do not accidentally
setup inbound access to their system before proper password controls
are in place.
To enable inbound data service the modem configuration file must
be setup to accept data calls and to invoke the normal system
getty program to process the incoming call.
Normally this involves enabling the use of
<I>adaptive-answer</I> functionality
and the setup of the <TT>GettyArgs</TT> parameter
in the configuration file.
<P>
Adaptive answer is the ability for a modem to determine
whether an incoming phone call is for data, fax, or voice use.
If a modem supports a good adaptive-answering facility
then it should be enabled with the <TT>ModemSetupAACmd</TT>
and the faxgetty process will automatically service fax, data, or voice
calls <EM>as identified by the modem</EM>.
Most Class 2 and Class 2.0 modems provide adaptive-answer support
that distinguishes data calls from fax calls
and the prototype configuration files that come with HylaFAX
automatically enable it if it is provided by the modem.
Most Class 1 modems do not provide adaptive-answer support, but
HylaFAX provides adaptive-answer support in the server.
Consult the section on
``<A HREF="setup-advanced.html#AdaptiveAnswer">Adaptive Answer Support</A>''
in the next chapter for help on configuring adaptive-answer support.
<P>
Setting up the <TT>GettyArgs</TT> parameter requires an
understanding of how to automatically startup the system getty program.
HylaFAX will invoke the getty program when a data call is
recognized and set up the standard input, output, and error
descriptors to point to the appropriate tty device.
The getty program should not reopen or reinitialize the modem
before doing its work.
Some getty programs are incapable of this and are unsuitable
for use with HylaFAX.
The parameters passed to the getty program must also identify the
speed to use to communicate with the local modem.
Some getty programs want to automatically detect this rate based
on the <TT>CONNECT</TT> message that a modem sends to the host
when a connection is established; these programs are unsuitable for use
with HylaFAX.
A getty program used with HylaFAX must be able to handle a fixed speed
for host-modem communication, with the speed specified on the command line.
<P>
For System V-style getty programs the appropriate parameters
are typically of the form:
<UL><TT>
GettyArgs: "-h %l dx_%s"
</TT></UL>
where the <TT>-h</TT> parameter instructs getty to not hangup the
device first, the <TT>%l</TT> parameter is translated to the
device name (``the tty line''), and the <TT>dx_%s</TT> parameter
identifies the <B>/etc/gettydefs</B> entry to use (<TT>%s</TT>
is translated by HylaFAX to the speed used to communicate with
the modem). Note that the exact parameters to supply depend
on the getty program used; consult local documentation to understand
what options should be used.
<P>
For BSD-style systems, <TT>GettyArgs</TT> is usually of the form:
<UL><TT>
GettyArgs: "std.%s -"
</TT></UL>
where <TT>std.%s</TT> refers to an entry in the <B>/etc/gettytab</B>
file for a fixed speed port; e.g.
<UL><TT>
g|std.19200|19200-baud:sp#19200:<BR>
h|std.38400|38400-baud:sp#38400:<BR>
</TT></UL>
(Note that as before, the ``<TT>%s</TT>'' is replaced by the speed
for host-modem communication.)
<H2><A NAME="HFaxd"><P><HR WIDTH="65%" ALIGN=right>Setting up Client Access</A></H2>
HylaFAX client applications such as sendfax do not communicate directly
with server processes such as faxq or faxgetty.
Instead they communicate with the
<A HREF="@CGIPATH@/manpage?hfaxd">hfaxd</A>
client-server protocol process.
This architecture insulates client applications from the internal
structure of a server machine, provides a more robust operating
environment, and scales better for many clients.
<P>
hfaxd is normally started up when the faxsetup program is run.
faxsetup also arranges for hfaxd to be
automatically started up each time a server machine is booted;
either <I>standalone</I>
by a script invoked by the init process or <I>indirectly</I>
by the inetd process.
The preferred way to run hfaxd is in a standalone mode as this
gives optimal performance.
<P>
When hfaxd is started the command line arguments specify which of
several client-server protocols it should offer.
hfaxd currently has support for three protocols:
<UL>
<LI>the Version 4.0 HylaFAX client-server protocol,
<LI>the old HylaFAX client-server protocol used in versions prior to 4.0, and
<LI>the Simple Network Pager Protocol (SNPP) that is used to submit
alpha-numeric text pager requests.
</UL>
When operating in a standalone fashion the command line
options specify the protocols to support
and the ports at which service should be provided.
For example, to startup hfaxd in a standalone mode supporting all three
protocols the following might be used:
<UL><LISTING>
# <B>/usr/local/sbin/hfaxd -i 4559 -o 4557 -s 444</B>
</LISTING></UL>
This specifies that the Version 4.0 protocol is to be offered at
port 4559, the old protocol at port 4557, and SNPP at port 444.
<P>
It is also possible to have the inetd program startup hfaxd.
In this case only a single protocol can be requested since inetd
advertises service and establishes the network connection.
For example, the following entry might be used in the <B>inetd.conf</B>
file to startup hfaxd to service SNPP requests:
<UL><LISTING>
snpp stream tcp nowait fax /usr/local/sbin/hfaxd hfaxd -S -d
</LISTING></UL>
The <TT>-S</TT> option specifies that hfaxd should service SNPP
requests using the standard input and output descriptors and the
<TT>-d</TT> option keeps hfaxd from detaching itself from the
controlling tty.
<P>
It is possible to run hfaxd in a standalone mode as well
as indirectly from inetd so long as this is done for
separate protocols.
Doing this however is of questionable value since it is much more
efficient for a single standalone hfaxd process to support multiple
protocols than to have multiple unrelated hfaxd processes.
<P>
<TABLE BORDER=0>
<TR>
<TD><IMG ALT="Note!" SRC="icons/warning_icon.gif" HSPACE=8></TD>
<TD><EM>Beware that hfaxd must either be started up by the super-user
or be installed setuid-root for proper operation.</EM></TD>
</TR>
</TABLE>
<P>
Besides arranging for hfaxd to get started up when a server machine
is booted, it is necessary
to specify which client machines and users can have access to a HylaFAX
server machine.
This is specified by the contents of the <B>etc/hosts.hfaxd</B> file in
the HylaFAX spooling area on the server machine.
The contents of this file is specified in the
<A HREF="@CGIPATH@/manpage?hosts.hfaxd">hosts.hfaxd</A>
manual page.
The default <B>etc/hosts.hfaxd</B> file that comes with HylaFAX permits anyone
to have access through the <I>localhost</I> network interface; i.e. the
hosts.hfaxd file contains:
<UL><TT>
<PRE>localhost
127.0.0.1</PRE>
</TT></UL>
It is a good idea to refine the controls specified in this file before
providing general access to the server.
Access can be restricted both on a per-client-machine basis and
by user.
Passwords can also be required though support for this is presently
somewhat awkward.
<P>
<TABLE BORDER=0>
<TR>
<TD><IMG ALT="Note!" SRC="icons/warning_icon.gif" HSPACE=8></TD>
<TD><EM>The <B>etc/hosts.hfaxd</B> file must be owned by the fax user and
be mode 0600 or hfaxd will not permit client access.</EM></TD>
</TR>
</TABLE>
<H3><A NAME="Cron"><P><HR WIDTH="65%" ALIGN=right>Setting up Periodic Maintenance Work</A></H3>
HylaFAX comes with two programs that need to be run periodically on the
server machine:
<A HREF="@CGIPATH@/manpage?faxqclean">faxqclean</A>
and
<A HREF="@CGIPATH@/manpage?faxcron">faxcron</A>.
<P>
The faxqclean
program is responsible for removing old
document and job description
files from the spooling area on a server.
These files are created when outbound jobs are created but are removed
in a delayed fashion to permit clients to resubmit jobs without
retransmitting all the information to the server and to allow imaged
documents to be reused in unrelated facsimile transmissions.
faxqclean is also responsible for <I>archiving</I> outbound jobs that
have completed.
<P>
<TABLE BORDER=0>
<TR>
<TD><IMG ALT="Note!" SRC="icons/warning_icon.gif" HSPACE=8></TD>
<TD><EM>The faxqclean program in version 4.0 does not support
job archiving; but consult the manual page to verify this
(in case someone has done some local improvements).</EM></TD>
</TR>
</TABLE>
<P>
faxqclean must be run by the super-user.
A sample entry for the cron program that runs faxqclean
once each hour might be:
<UL><LISTING>
0 * * * * /usr/local/sbin/faxqclean
</LISTING></UL>
The second program that should be routinely run on each server machine is
faxcron.
This is a script that does maintenance such as truncating log files
and purging old session logs and received facsimile.
faxcron needs to be run by the fax user once a day or so and it is
a good idea to capture its output since it includes information
about failed phone calls that might warrant investigation.
A sample cron entry to run faxcron might be:
<UL><LISTING>
25 23 * * * sh /usr/local/sbin/faxcron | mail FaxMaster
</LISTING></UL>
<H3><A NAME="Problems"><P><HR WIDTH="65%" ALIGN=right>Modem Configuration Issues</A></H3>
Beware that when faxgetty processes control a modem they
may leave the modem in a state suitable for sending and receiving facsimile.
That is, they may leave the modem running in Class 1, Class 2, or Class 2.0.
This may have implications for data communication programs such as
<I>tip</I>,
<I>cu</I>,
and <I>uucp</I>. For example, it may be
necessary to force the modem into Class 0 (for data communication) when
placing a call:
<UL><TT>
<PRE>AT+FCLASS=0DT<<I>phone number</I>></PRE>
</TT></UL>
Exactly how things work depends on the contents of the
modem configuration file. It is usually a good idea to
setup the configuration parameters so that the modem is
left idling in Class 0 (for data use) when HylaFAX is not
actively using a modem.
Note however that this may not always be possible as some modems
require that a modem idle in Class 2 or 2.0
when doing adaptive answer.
<P>
<TABLE BORDER=0>
<TR>
<TD><IMG ALT="Note!" SRC="icons/warning_icon.gif" HSPACE=4></TD>
<TD><EM>Note that when HylaFAX places an outbound facsimile call it
automatically forces the modem into Class 1, 2, or 2.0
<STRONG>before</STRONG> issuing <TT>ModemDialCmd</TT>.
Thus the old FlexFAX trick of changing the class in the
<TT>ModemDialCmd</TT> parameter should not be used.</EM></TD>
</TR>
</TABLE>
<H2><A NAME="Guidance"><P><HR WIDTH="65%" ALIGN=right>System-specific Guidance</A></H2>
This section contains some setup-related issues that are
dependent on the operating system installed on the target machine.
The information included here is by no means exhaustive; it reflects
feedback from users accumulated over multiple HylaFAX versions
and/or operating system releases.
<H3><A NAME="IRIX"><P><HR WIDTH="65%" ALIGN=right>IRIX Guidance</A></H3>
On Silicon Graphics Indigo and Indy machines
you can not use a Macintosh modem cable to connect your modem
to the DIN-8 connector on the back of your host.
A Macintosh cable uses a special wiring pattern to pass
the RTS and CTS signals between the host and modem.
This wiring is not compatible with the wiring used on SGI machines.
While it may appear that the the modem and cable work,
hardware flow control will not function properly and
data will eventually be lost. Consult the
<A HREF="@CGIPATH@/manpage?serial">serial</A>
manual page for an explanation of how to wire up modem cables.
<P>
The tty device that is used must reflect whether
hardware or software flow control is to be used.
Under IRIX, modem devices (i.e. those that monitor DCD) come
in two flavors: <TT>ttyf*</TT>
devices support RTS/CTS flow control while <TT>ttym*</TT>
devices support XON/XOFF flow control.
If you want to use hardware flow control to communicate with your
modem you should use a <TT>ttyf*</TT> device, otherwise use a
<TT>ttym*</TT> device.
If you fail to use the correct device you may still get the
correct flow control (because later versions of IRIX actually
permit flow control to be switched irrespective of the device
used), but you are likely to collide with other modem users such
as cu, uucp, ppp, and slip that still use the old-style device names
(so UUCP lock files may be created for a different name than the
one HylaFAX is using).
<P>
<TABLE BORDER=0>
<TR>
<TD><IMG ALT="Note!" SRC="icons/warning_icon.gif" HSPACE=4></TD>
<TD><EM>USR modems work under IRIX 5.x
only when patch 475 or a successor is installed
and <TT>ClocalAsRoot</TT> is set to <TT>Yes</TT>
in the modem configuration file</EM>.</TD>
</TR>
</TABLE>
<P>
Versions of IRIX prior to 6.2 have a bug in the
device driver for the on-board serial ports on several systems
that causes RTS/CTS flow control to be turned off as a
side effect of setting the <TT>CLOCAL</TT> flag on the associated
tty device.
Patch 475 (``RTS/CTS flow control busted when <TT>CLOCAL</TT> is set'')
and its successors correct
this problem and must be installed to use HylaFAX with RTS/CTS flow control
(install the appropriate successor to patch 475).
Also, when this patch is installed the
<TT>ClocalAsRoot</TT> modem configuration parameter must be set
to <TT>Yes</TT> for proper operation
(see
<A HREF="@CGIPATH@/manpage?hylafax-config">config</A> for a detailed
explanation of what this parameter does).
If you do not have the appropriate patch installed on your system
then you will either see flow control-related problems when transmitting
facsimile or possibly some other problems related to modems dropping
DCD when carrier is lost.
<P>
<TABLE BORDER=0>
<TR>
<TD><IMG ALT="Note!" SRC="icons/warning_icon.gif" HSPACE=4></TD>
<TD><EM>
The DPS-based PostScript imager program distributed with HylaFAX
is available only in COFF format.
Because IRIX 6.2 does not support COFF executables this program cannot
be used with HylaFAX.
A Ghostscript-based RIP should be used under IRIX 6.2</EM>.
</TD>
</TR>
</TABLE>
<P>
The font metric files required by client applications are contained
in the <B>dps_eoe.sw.dpsfonts</B> image that is part of
the standard IRIX distribution.
<H3><A NAME="SCO"><P><HR WIDTH="65%" ALIGN=right>SCO Guidance</A></H3>
The standard SCO serial I/O driver (SIO) does nothing with modem control
lines if <TT>CLOCAL</TT> is set on the tty device.
The usual workaround is to use the FAS driver instead.
<H3><A NAME="Solaris"><P><HR WIDTH="65%" ALIGN=right>Solaris Guidance</A></H3>
<P>
Versions of Solaris prior to 2.5 require a patch to
correct the handling of RTS/CTS flow control with serial ports
built around the Zilog ZS8530 chip.
<P>
Some versions of Solaris (2.3 is known to do this) silently
truncate or discard syslog messages longer than about 120 characters.
<P>
Use the <B>/dev/cua/*</B> devices and not the <B>/dev/term/*</B>
devices.
<P>
When using <I>ttymon</I> to service inbound data calls set the
<TT>GettyArgs</TT> parameter to something like the following:
<UL><TT>
<PRE>GettyArgs: "-g -h -d /dev/cua/a -l 38400 -m ldterm,ttcompat"</PRE>
</TT></UL>
<P>
<TABLE BORDER=0>
<TR>
<TD><IMG ALT="Note!" SRC="icons/warning_icon.gif" HSPACE=8></TD>
<TD><EM>Be certain you are not running a ttymon with sac when using HylaFAX.
Disable all ports that are to be used by HylaFAX
with admintool or <I>pmadm</I>(1m).</EM></TD>
</TR>
</TABLE>
<H3><A NAME="SunOS"><P><HR WIDTH="65%" ALIGN=right>SunOS Guidance</A></H3>
<P>
Versions of SunOS prior to 4.1.4 require a patch to
correct the handling of RTS/CTS flow control with serial ports
built around the Zilog ZS8530 chip.
These patches are available at:
<UL>
<LI><A HREF="ftp://sunsolve1.sun.com/pub/patches/100513-05.tar.Z">ftp://sunsolve1.sun.com/pub/patches/100513-05.tar.Z</A> for SunOS 4.1.[123], and
<LI><A HREF="ftp://sunsolve1.sun.com/pub/patches/100621-04.tar.Z">ftp://sunsolve1.sun.com/pub/patches/101621-04.tar.Z</A> for SunOS 4.1.3_U1.
</UL>
(choose the one appropriate to the system you are running).
<H3><A NAME="SVR4"><P><HR WIDTH="65%" ALIGN=right>SVR4 Guidance</A></H3>
<P>
The following <B>GettyArgs:</B> configuration parameter is
suitable for many SVR4-based systems:
<UL><TT>
<PRE>GettyArgs: "-g -h -t 60 -l ff_%s"</PRE>
</TT></UL>
Be sure entries for different baud rates are defined in the
<B>/etc/ttydefs</B> file.
<H3><A NAME="Ultrix"><P><HR WIDTH="65%" ALIGN=right>Ultrix Guidance</A></H3>
[<I>Ed: Thanks to Albert DeKnuydt for the following advice.</I>]<BR>
<UL>
<LI>As Ultrix has a brain-damaged shell, the command <TT>/bin/sh ./configure</TT> does
not work properly.
You should use instead <TT>/bin/sh5 < configure </TT>.
<LI>The archaic syslog facility should be upgraded from
<A HREF="ftp://gatekeeper.dec.com/pub/DEC/jtkohl-syslog-complete.tar.Z">ftp://gatekeeper.dec.com/pub/DEC/jtkohl-syslog-complete.tar.Z</A>.
<LI>Ultrix lacks some functions in the c library, and needs to linked to <B>libiberty.a</B> as well.
After configuration, change the line in the defs file from
<PRE>MACHDEPLIBS = -lm -lmalloc</PRE>
to
<PRE>MACHDEPLIBS = -lm -lmalloc -liberty</PRE>
Libiberty is available with the gcc compiler.
<LI>Ultrix header files violate ANSI rules so you have to tell gcc 2.95 (and later) to allow
this with the added line in the defs file :
<PRE>LC++OPTS = -fpermissive</PRE>
<LI>Interrupt handling is out of date, and cannot claim to be compatible with <TT>SV_INTERRUPT</TT>.
Add the following line to port.h after configuration :
<PRE>#undef SV_INTERRUPT</PRE>
<LI>Most (all?) DEC mips machines do not completely support serial port speeds above 19200.
</UL>
<!--FOOTER-->
<P>
<TABLE BORDER=0 WIDTH="100%">
<TR>
<TD><A HREF="setup-advanced.html"><IMG ALT="Next" SRC="icons/next.gif">
Advanced server configuration</A>.</TD>
<TD><A HREF="toc.html"><IMG ALT="Back" SRC="icons/back.gif">
HylaFAX table of contents</A>.</TD>
</TR>
</TABLE>
<HR>
<ADDRESS>
<A HREF="sam.html">Sam Leffler</A> / <A HREF="mailto:webmaster@hylafax.org">webmaster@hylafax.org</A>.
Last updated $Date: 2001/06/04 05:57:22 $.
</ADDRESS>
</BODY>
</HTML>
