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 written 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 transmission. 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 communications protocol implemented by the hfaxd(1m) 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 supports 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.
The actual transmission is handled by a faxsend(1m) process that is initiated by the scheduler. This program may be substituted for by specifying 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(1m) 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 separate log file named by its canonical phone number.
The remote job submission facility includes host and user access control. 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(4f).
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(4f), 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 information, 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 tagline 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 tagline 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 potentially chopped, all pages are potentially chopped, or chopping is disabled. The minimum whitespace threshold is also configurable. Applications can override the default configuration parameters on a per-job basis.
HylaFAX supports a simple form of access control for receiving facsimile. 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 permitted 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 facsimile data. When this feature is enabled faxgetty decodes and analyzes the received facsimile data as it is received. If data is received with too many errors, according to the setting of the MaxConsecutiveBadLines 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 significantly reduce the space needed to store received facsimile.
faxgetty is also capable of using distinctive ring information to identify whether an inbound call is voice, data, or fax. Consult the RingData, RingFax, and RingVoice parameters in hylafax-config(4f) for a description of this facility.
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 transmission, 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(4f) for information about the format. See xferfaxstats(1m) and recvstats(1m) for example scripts that print summarized accounting information.
Finally, the hfaxd process supports a event monitoring facility that can be access via the faxwatch(1m) program. This facility permits clients to register interest in various events and receive ``realtime notification'' when such events occur on the server. Using this facility it is/should-be simple to construct applications that do things like monitor modem status and use.
When HylaFAX is used in a send-only configuration there are no faxgetty processes and communication must be done directly with the faxq process. The faxstate program can still be used to manipulate modem use for outbound jobs but the faxconfig program is not frequently needed.
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(1m) 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 faxmodem program, and the faxconfig program. If multiple modems share the same priority value, then faxq(1m) will allocate jobs to them in a round-robin fashon.
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(1m) program can be used to dynamically change configuration parameters). Values set in this way however are lost when the process exits or if the configuration file is re-read.
FIFO fifo for job submission
FIFO.<devid> fifo for communicating with a faxgetty process
${SBIN}/faxinfo command that prints information about received facsimile
${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
Extensive documentation is available in online at http://www.hylafax.org/. Many of these materials are also included in the software distribution.