Provided by:
hylafax-server_4.4.0-2_i386 
NAME
HylaFAX - introduction to HylaFAX server operation and file formats
DESCRIPTION
HylaFAX is a system for sending and receiving facsimile. It supports
queued transmission and asynchronous reception of facsimile. Ancillary
programs are invoked by the system for flexibility and configurability.
HylaFAX includes client and server programs to support remote submis‐
sion of jobs for transmission, remote removal of queued jobs, and to
remotely query the status of jobs queued for transmission. This docu‐
ment describes the organization of the file system spooling area in
which HylaFAX server and server-related processes operate, and intro‐
duces the various files that reside in the spooling area.
OVERVIEW
The spooling area is typically located under the directory
/var/spool/hylafax. Ancillary command scripts used by the server pro‐
grams faxq(8), faxsend(8), pagesend(8), and faxgetty(8) are located in
the bin subdirectory. Configuration, access control, and accounting
information are maintained in the etc and config subdirectories. Out‐
going jobs are described by files in the sendq subdirectory, while
received facsimile are deposited in the recvq subdirectory. The docq
and temp subdirectories are also used in the preparation of outbound
jobs; the latter holds files that may be freely purged while the former
holds client files that may reside on the server independent of an
associated job. The doneq subdirectory holds jobs that have completed
but have not yet been purged or archived. On systems with job archival
support, completed jobs that have been archived are placed in the
archive subdirectory. The pollq subdirectory holds documents that are
available for polled retrieval from the server. The info subdirectory
contains files that describe the capabilities of facsimile machines
that HylaFAX has called-this information is used in preparing documents
for transmission. The status subdirectory contains files that server
processes write their current status to. The log subdirectory contains
logging information about send and receive sessions. The client subdi‐
rectory contains FIFO special files used for communication with faxq.
HylaFAX supports multiple modems on a host. A single process acts as
central queueing agent for all outbound jobs. Typically each modem
also has a server process that monitors the modem status and handles
inbound phone calls. Per-modem server processes communicate with the
central queueing agent using FIFO special files; see mknod(2) or
mkfifo(2). Any other synchronization between server processes is done
using file-level locking. The faxq process listens for commands writ‐
ten to the file named FIFO, while each faxgetty process listens for
commands written to a per-device file named FIFO.devid (where devid is
an identifier derived from the name of the device special file to which
the modem is connected; e.g. ttym2 for /dev/ttym2, term_10 for
/dev/term/10.) To send a command to the queueing agent, one writes to
FIFO. This is useful, for example, for submitting a job for transmis‐
sion. To send a command to a specific faxgetty process, the FIFO.devid
file is used.
Client applications interact with a HylaFAX server machine using a com‐
munications protocol implemented by the hfaxd(8) program. The hfaxd
program is typically started at system startup; it listens for client
requests for service and creates a process for each client. hfaxd sup‐
ports the submission of outbound jobs, querying the status of the send
and receive queues, and altering parameters of previously submitted
jobs. The hfaxd processes communicate with the faxq process through
FIFO special files. Commands sent to faxq are sent to FIFO and
responses are received on FIFO files that each hfaxd creates in the
client subdirectory.
SETUP
Each HylaFAX server machine must run the faxsetup(8) command prior to
starting up HylaFAX server processes. faxsetup verifies that the
HylaFAX software has been installed correctly and that any parameters
that were specified at the time the software was built are appropriate
for the system.
SENDING
Each outgoing facsimile job has a job description file that is located
in the sendq subdirectory. This file contains all the information nec‐
essary to manage the transmission; c.f. sendq(5). The actual docu‐
ments that are to be sent are usually located in the docq subdirectory
(though it is also possible to reference documents from the recvq
directory). HylaFAX accepts POSTSCRIPT, PDF, PCL, and TIFF documents
for transmission (though support for PCL documents is not currently
implemented). Documents are automatically converted to TIFF/F docu‐
ments prior to transmission according to the capabilities of the remote
facsimile machine: maximum page width and length, ability to handle 2D-
encoded data, and ability to handle high resolution (7 line/mm) data.
This remote machine capability information is stored in files in the
info subdirectory. If a machine has not been called before, HylaFAX
assumes the remote machine has the requested capabilities. If a capa‐
bilities mismatch is detected while sending a facsimile HylaFAX will
disconnect and re-convert the submitted documents according to the
newly discovered capabilities. Users may also restrict the session
parameters used to format documents on a per-job basis.
The actual transmission is handled by a faxsend(8) process that is ini‐
tiated by the scheduler. This program may be substituted for by speci‐
fying the FaxSendCmd configuration parameter in the faxq configuration
file.
While a job is being processed by a server process, its job description
file is locked for exclusive use with flock(2). The hfaxd(8) program
uses this information to tell if a job is actively being processed.
If the SessionTracing parameter in a server’s configuration file is
non-zero, then tracing information for an outgoing job will be logged
in a file in the log subdirectory. Each destination machine has a sep‐
arate log file named by its canonical phone number.
The remote job submission facility includes host and user access con‐
trol. The file etc/hosts.hfaxd must be present and list those hosts
and users that are permitted to queue jobs for transmission or do other
operations that alter the status of a job. Note that it is necessary
to include the ‘‘local host’’ definition (usually 127.0.0.1) if local
submission is to be permitted. For more information consult
hosts.hfaxd(5).
There are a number of controls on outbound calls that can be specified
using the etc/destcontrols file (or whatever file is specified in a
DestControls configuration parameter in the faxq configuration file).
This file, described in destctrls(5), allows an administrator to
restrict calls by phone number and to control the time of day that
calls may be placed. In addition, operational parameters such as the
maximum number of pages in a facsimile transmission can be constrained
on a per-destination basis.
If an error is encountered during transmission and a subsequent
retransmission would not include the original cover page, then HylaFAX
can be configured to generate a continuation cover page that is
prepended to the retransmitted pages. Such cover pages are usually
generated by the bin/mkcover command; though the exact command to use
can be specified in the configuration file read by faxq.
HylaFAX can be configured to generate a line of status information
across the top of each page of an outbound facsimile. This informa‐
tion, termed a ‘‘tagline’’, typically includes the sender’s identity
(i.e. phone number), the time and date of the transmission, and the
page number. The exact format of the tag line is configurable and
applications can override the default configuration parameters on a
per-job basis. Note that in the United States the law requires that a
tag line that identifies the sender’s phone number must appear on each
transmitted page of facsimile.
Facsimile transmitted to receivers that accept variable-length pages
may have short pages ‘‘chopped’’. That is, if a page has a significant
amount of trailing whitespace and the receiver accepts variable-length
pages then only the top part of the page will be transmitted. faxq can
be configured so that only the last page of each document is poten‐
tially chopped, all pages are potentially chopped, or chopping is dis‐
abled. The minimum whitespace threshold is also configurable. Appli‐
cations can override the default configuration parameters on a per-job
basis.
RECEIVING
faxgetty server processes can be configured to answer incoming phone
calls and automatically receive facsimile. Received documents are
placed in the recvq subdirectory as TIFF Class F files. The faxgetty
processes can be configured to make these files publicly accessible, or
they can be made private in which case an administrator must manage
their delivery and/or the assignment of ownership to particular users.
When a facsimile is received, the faxgetty process usually invokes the
bin/faxrcvd command; though the exact command to invoke can be speci‐
fied in the per-modem configuration file. The default notify command
is a shell script that sends a mail message to a well known user, the
FaxMaster, but one might also, for example, automatically spool the
document for printing.
HylaFAX supports a simple form of access control for receiving facsim‐
ile. Each faxgetty process may be configured to check the Transmission
Subscriber Identifiers (TSI) of the remote fax machine against an
access control list, typically etc/tsi. Only if the TSI is matched by
a regular expression pattern in the file, is the remote machine permit‐
ted to transmit a document. This mechanism can be used, for example,
to guard against junk fax.
HylaFAX can be configured to do copy quality checking on received fac‐
simile data. When this feature is enabled faxgetty decodes and ana‐
lyzes the received facsimile data as it is received. If data is
received with too many errors, according to the setting of the MaxCon
secutiveBadLines and PercentGoodLines configuration parameters, then
the sender will be told to retransmit the page. When copy quality
checking is enabled it is also possible to force received facsimile
data to be saved with a different compression scheme than was used for
transmission. This function is known as transcoding and can signifi‐
cantly reduce the space needed to store received facsimile.
POLLING
HylaFAX supports the polled retrieval of facsimile documents. Docu‐
ments that are received because of a poll request are stored in the
recvq subdirectory and also delivered directly to the requester using
the bin/pollrcvd command; though the exact command to invoke can be
specified with the PollRcvdCmd configuration parameter. The pollrcvd
script typically encodes the binary facsimile data and returns it to
the user via electronic mail.
In environments where Caller-ID information is available, HylaFAX also
supports a call screening facility similar to the TSI access control
facility. faxgetty can be configured to check the phone number of each
caller against an access control list, typically etc/cid. Only if the
number is matched by a regular expression pattern in the file is the
call answered. All Caller ID information is logged, irregardless of
whether or not it is used to screen incoming calls.
faxgetty is also capable of using distinctive ring information to iden‐
tify whether an inbound call is voice, data, or fax. Consult the Ring
Data, RingFax, and RingVoice parameters in hylafax-config(5) for a
description of this facility.
Most fax modems also support non-facsimile communication. HylaFAX uses
the locking mechanism employed by uucp(1C), cu(1C), slip(8), and
ppp(8). Any faxgetty processes will transparently ‘‘get out of the
way’’ when an application wants to use a modem for an outgoing call.
In addition, HylaFAX can be configured to deduce whether an incoming
call is for facsimile or data use. If a call from a data modem is rec‐
ognized and the GettyArgs parameter is specified in the configuration
file, faxgetty will invoke the getty(8) program so that caller may
login to the system. Similar functionality is also available for
invoking a ‘‘voice getty’’ process, though auto-detection of inbound
voice calls is less extensive.
STATUS
HylaFAX maintains status information in several forms. General status
information for each server process is maintained in the status subdi‐
rectory and returned to users by the faxstat(1) program. The syslog(3)
facility is used by all server processed for logging status and error
diagnostics. The server processes may also be configured to log vari‐
ous kinds of debugging and tracing information; c.f. the ServerTracing
parameter description in hylafax-config(5).
Any problems encountered when transmitting a facsimile are described in
messages returned to the user by electronic mail. A user may also
request notification by mail when a job is requeued; for example,
because a call failed. Notification by electronic mail is implemented
by the bin/notify command script; though the name of the script may be
overridden with the NotifyCmd configuration parameter.
The faxstat utility provides (remote) status of jobs queued for trans‐
mission, jobs received, and the general status of server processes.
The file etc/xferfaxlog contains status information about all facsimile
sent and received on a machine. This file is in a simple ASCII format
that is easy to manipulate with programs such as awk(1), to generate
accounting information. See xferfaxlog(5) for information about the
format. See xferfaxstats(8) and recvstats(8) for example scripts that
print summarized accounting information.
Finally, the hfaxd process supports a event monitoring facility that
can be access via the faxwatch(8) program. This facility permits
clients to register interest in various events and receive ‘‘real time
notification’’ when such events occur on the server. Using this facil‐
ity it is/should-be simple to construct applications that do things
like monitor modem status and use.
In normal operation each modem is managed by a HylaFAX server process
such as faxgetty. These processes communicate with the central sched‐
uler process to notify it when a modem is ready for use, busy for out‐
bound use, or possibly in an unusable state (either purposely marked
unavailable or potentially found to be wedged). Modem usage can be
explicitly controlled with the faxstate(8) program. The faxconfig(8)
program can also be used to dynamically make changes to configuration
parameters that may cause a modem to be treated differently (e.g.
setting RingsBeforeAnswer to zero will cause faxgetty to not answer
incoming calls).
When HylaFAX is used in a send-only configuration there are no faxgetty
processes and communication must be done directly with the faxq pro‐
cess. The faxstate program can still be used to manipulate modem use
for outbound jobs but the faxconfig program is not frequently needed.
Outbound jobs are scheduled by a single process. Jobs have a
‘‘scheduling priority’’ that is assigned at the time the job is submit‐
ted. This priority can be changed at any time the job is not actively
being processed using the faxalter(8) program. A job’s scheduling pri‐
ority may also be altered by faxq in response to certain scheduling
events (e.g. after a failed attempt to send).
Modems are assigned to outbound jobs if they are deemed ready for use.
Modem readiness is usually communicated to faxq by per-modem faxgetty
processes. In a send-only environment however this is not possible;
instead modems configured for use with faxmodem are considered always
ready for use unless they are presently assigned to an outbound job or
their state is explicitly changed through the faxstate(8) program
(faxstate can also be used in a send-recv environment).
Each modem has a ‘‘modem priority’’ in the range [0..255]. Modems with
a lower priority number are assigned to outbound jobs first. Modem
priority is statically configured through configuration files, the fax‐
modem program, and the faxconfig program. If multiple modems share the
same priority value, then faxq(8) will allocate jobs to them in a
round-robin fashion.
Outbound jobs are considered to be in one of several states that
reflect their treatment by the central scheduling process. Jobs are
initially created in a suspended state, and may be returned to this
state at any time that they are not actively being processed (e.g. a
faxsend program is running to process the job). Jobs that are sus‐
pended are not processed by the scheduler; and their internal state may
be safely altered by the owner or a system administrator. Suspending
and then releasing a job has the effect of requeueing the job, meaning
that it will end up at the bottom of queue for that job’s priority.
Jobs that are ready for processing by the scheduler are ‘‘submitted’’
and their state is changed to be either pending (delayed waiting for a
future time to send), sleeping (delayed waiting for a scheduled time‐
out), blocked (delayed by concurrent activity to the same destination),
or ready (ready for transmission, waiting only for available
resources). When a job is actively processed by the faxsend program
its state is marked active. Jobs that have completed, either success‐
fully or unsuccessfully are placed in a done state and their job
description files are moved to the doneq subdirectory. Clients may
still access the state of jobs that are done; until a ‘‘cleaner pro‐
cess’’ either purges them from the system or archives their state.
This delayed removal of a completed job’s state permits clients to
resubmit failed jobs using previously transmitted documents and other
job state information. The exact mechanics of how and when done jobs
are processed is system-dependent; for example, how long a job is left
in the done queue before being purged, and whether job archival support
is present.
CONFIGURATION
HylaFAX server programs read configuration information from a configu‐
ration file. Multiple files are used, one for the faxq program and one
for each modem. Long-running server programs all automatically re-read
their configuration file if it is modified. Typically this re-reading
is done frequently enough that administrators do not need to be aware
of exactly when it takes place. However in some esoteric cases the
file may not be read when expected (the one important case is that the
faxgetty process reads its configuration file only when answering a
call or when resetting a modem; this means that it will not recognize
changes when the modem is idle).
In addition to the static configuration files, HylaFAX server programs
accept commands on their FIFO special files to alter configuration
parameters in the running executable (the faxconfig(8) program can be
used to dynamically change configuration parameters). Values set in
this way however are lost when the process exits or if the configura‐
tion file is re-read.
NOTES
Automatic routing of incoming facsimile is desirable.
FILES
FIFO fifo for job submission
FIFO.<devid> fifo for communicating with a faxgetty process
/usr/sbin/faxinfo command that prints information about received facsimile
/usr/sbin/faxquit command to force server to quit
bin/faxrcvd faxd command for handling newly received facsimile
bin/mkcover faxd command for generating continuation cover pages
bin/notify faxd command for doing user notification
bin/pollrcvd faxd command for delivering facsimile received by poll
bin/ps2fax faxd command for converting POSTSCRIPT to TIFF
docq/doc* documents available for transmission
etc/setup.cache server setup file created by faxsetup
etc/cid caller id access control list
etc/config.<devid> configuration data for <devid>
etc/hosts.hfaxd hosts that may submit jobs for transmission
etc/tsi fax machine receive access control list
etc/xferfaxlog log of facsimile sent and received
info/* data base of remote fax machine capabilities
client/* FIFO special files created by client processes
config/* prototype configuration files used by faxaddmodem
log/* session logging records
recvq/fax* received facsimile
sendq/q* descriptions of jobs queued for transmission
doneq/q* descriptions of jobs that are done
status/* server status information
tmp/* temporary files created when submitting a job
archive/* database of archived jobs
faxsetup(8), faxq(8), faxgetty(8), hfaxd(8), faxsend(8), faxrcvd(8),
faxconfig(8), faxmodem(8), faxstate(8), notify(8), pollrcvd(8), recvs‐
tats(8), xferfaxstats(8), archive(5), hylafax-config(5), dialrules(5),
doneq(5), hosts.hfaxd(5), hylafax-info(5), hylafax-log(5), tsi(5),
recvq(5), sendq(5), status(5), xferfaxlog(5),
Extensive documentation is available in online at
http://www.hylafax.org/. Many of these materials are also included in
the software distribution.
January 18, 1996 HYLAFAX-SERVER(5)