[ HOME ] [ BACK ] [ NEXT ]
For a thorough understanding of the HylaFAX server there is no alternative to reading the
man pages. Especially useful are
and although technically a client application,
faxstat(1) is useful in determining the status of the HylaFAX server.
In order for any HylaFAX client program to communicate with the HylaFAX server, hfaxd, the
HylaFAX service daemon, must be running. In most cases, hfaxd is started at boot time by a SysV init style script in the
same manner as named, sendmail, and httpd, and can be controlled similarly.
hfaxd is typically used in one of two ways; either as a standalone process that is started at
system boot time to listen for client connections on one or more ports, or as a subservient
process to the inetd(8C) program. The two forms of use may however be combined so long as
the same service is not provided both by the standalone hfaxd and through inetd.
faxgetty is the HylaFAX server program that listens for incoming phone calls and either
handles each call directly or hands it off to an appropriate program. In addition faxgetty
monitors modem usage and notifies the HylaFAX scheduler process when a modem's status changes;
e.g. when a modem is busy with an outbound call.
One faxgetty should be run for each facsimile modem on a machine. faxgetty is typically
started by init(8C). faxgetty can also be used with data-only modems; this may be desirable if
some of the non-facsimile features are important, such as the support for screening calls
according to Caller-ID information.
The ASCII file etc/hosts.hfaxd in the HylaFAX spooling area specifies the hosts and users
that are permitted to access services through the hfaxd(8C) process. This file must exist for
client access; if it is not present then hfaxd will deny all requests for service.
The default setting for hosts.hfaxd is to allow access to localhost (127.0.0.1). If you will
be using a client program which communicates with hfaxd from somewhere other than localhost
(email-to-fax gateways often communicate with hfaxd on localhost), then
you should become familiar with the hosts.hfaxd man page and configure that file appropriately.
Normal HylaFAX user maintenance is conveniently provided by the
Beginning with HylaFAX version 4.2.0, PAM support may also be used to authenticate users.
When invoked without options faxstat reports only the status of the server. Server status
information indicates the state of the server (idle, sending, receiving, etc.) and the phone
number that is associated with the fax modem.
Before faxgetty has successfully initialized the modem, '
HylaFAX scheduler on faxserver.mydomain.com: Running
Modem ttySx (000-123-4567): Waiting for modem to come ready
When idle, '
faxstat' should return:
HylaFAX scheduler on faxserver.mydomain.com: Running
Modem ttySx (000-123-4567): Running and idle
When faxgetty is respawning, '
faxstat' will return:
HylaFAX scheduler on faxserver.mydomain.com: Running
Modem ttySx (000-123-4567): Initializing server
If hfaxd is not running, '
faxstat' will return:
Can not reach server at host "localhost", port 4559.
The rest of the '
faxstat' results should be self-explanatory.
Files in the log directory in the HylaFAX spooling area contain logging/tracing information
about transmit and receive sessions. One file exists for each inbound or outbound call, with the
filename of the form ``cXXXXXXXX'' where XXXXXXXX is a decimal sequence number termed a
communication identifier. The amount and kind of tracing information that is recorded for a call
is defined by the SessionTracing parameter specified in the modem configuration file; see hylafax-config(5F).
Note that logging/tracing information generated by the server outside of a session is directed
to the syslog(3) service and is controlled by the LogFacility and ServerTracing parameters
specified in the modem configuration file.
It is a good idea to review the log file for any failed fax in order to determine the nature
of the failure. If the error is not made plainly known by the log file, and if you do not know
how to correct the problem, it is a good idea to post the error-containing sections of the log file
to the hylafax-users mailing list for review. In many instances
it is important to know the modem type, the modem config file, and the remote fax machine type for
As with any other technology, fax has its own set of terms, jargons, assumptions, and acronyms.
It is important to understand fax technology in order to best utilize a fax server, and to do that
the language used should be understood.
3.6.1 Fax Classes
The firmware and hardware of a faxmodem, also known as the DCE, will support one or more
communication methods, called "Classes", with the host software (HylaFAX), also known as the DTE.
This communication only occurs between the DTE and the DCE and is not the communication that
occurs between the local DCE and the remote DCE (the other fax machine).
Class 1 and Class 1.0 are generally known as "Class 1", while Class 2, Class 2.0, and Class 2.1 are generally known
as "Class 2". Class 1 provides a low-level interface between the DTE and DCE. This gives a significant amount of
control to the DTE with regards to fax protocol features and handling at the expense of requiring the DTE to be
cautious of the timing sensitivities required for faxing. Most computer equipment sold prior to 1990, when the first
Class 1 standard was published, was generally considered to be incapable of handling those timing sensitivities properly.
Thus, Class 2 provides a higher-level interface between the DTE and DCE, which requires the DCE to perform most of the
fax protocol itself as requested by the DTE. History has shown, however, that many Class 2 implementations are
flawed and err in the fax protocol, or without errors, most Class 2 implementations are fairly limited in their
support of fax features. As the burden of fax protocol rests on the DTE when using Class 1, HylaFAX currently supports
more features in Class 1 than most modems feature in Class 2. Furthermore, experience has shown that nearly any
computer system in use today (i486 or better) will easily handle the timing sensitivities required for faxing.
For these reasons it is generally recommended that HylaFAX use Class 1 when it is available.
- Class 1 is a standard defined by EIA/TIA-578 (1990). Its implementation is fairly standard across
manufacturers. Common Class 1 commands are "AT+FTH=3" (raise the V.21 transmission carrier), "AT+FRM=146" (raise the
V.17 14400 baud reception carrier), and AT+FTS=7 (transmit silence for 70 ms).
- Class 1.0 is a standard defined by ITU-T.31. This standard is nearly identical to its predecessor,
EIA/TIA-578 with the addition of a few advanced commands and, in its Amendment 1, defines a slightly different
communication method to be used with V.34-Fax (SuperG3). Some manufacturers (e.g. Rockwell/Conexant) have a Class 1.0
implementation that supports the advanced commands but not V.34-Fax. Other manufacturers (e.g. Lucent/Agere) have an
implementation that supports V.34-Fax but not the advanced commands. HylaFAX cannot currently make use of the advanced
commands. However, it is believed that their usage would be of little benefit.
- Class 2 is a standard defined by the unfinished 1990 draft of what would later become EIA/TIA-592.
Common Class 2 commands are "AT+FDR" (receive data), "AT+FDCC=?" (describe DCE capabilities), and "AT+FDIS=?" (describe
DCE settings). Some manufacturers, most notably Rockwell, standardized on this draft of the Class 2 standard years
before it was published. Because the standard changed significantly between 1990 and 1993 and because there were so
many Class 2 modems in use that supported the 1990 draft, a distinction was therefore made between Class 2, the 1990
draft, and Class 2.0, the 1993 publication.
- Class 2.0 is a standard defined by EIA/TIA-592 (1993). Common commands are "AT+FDR" (receive data),
"AT+FCC=?" (describe DCE capabilities), and "AT+FIS=?" (describe DCE settings).
- Class 2.1 is a standard defined by ITU-T.32. It is an extension to Class 2.0. In addition to the
features supported in Class 2.0, a Class 2.1 modem may support "extended" resolutions beyond normal and fine, and it
may also support V.34-Fax.
3.6.2 An Overview of T.30
ITU-T.30 and its annexes describe the DCE-to-DCE communication that occurs during a facsimile session. A fax session
is divided into five segments or "phases": A, B, C, D, and E.
- During phase A the call is established. A calling DCE
will send the CNG signal which is a series of monotonous beeps. When the receiving DCE answers it
traditionally transmits the CED signal which sounds like a long, loud squelch. Once the
DCEs detect each other then a carrier is established. In traditional sessions the initial handshaking and
all protocol messages with the exception of TCF use a V.21 300 baud carrier while training and image data are
communicated using V.27ter, V.29, or V.17 carriers (2400 baud through 14400 baud). The DTE notices the end of Phase A
by a "CONNECT" message in Class 1, an "+FCON" message in Class 2, and a "+FCO" message in Class 2.0. Phase B is then
- During Phase B the connected stations negotiate the parameters of the image communication. Typically
the receiver will begin by transmitting NSF (identifies the manufacturer and other proprietary features), CSI (called
station identification string), and DIS (describes the receiver's capabilities). Then the receiver waits for responses
from the sender. The sender analyzes the receiver's signals and makes a decision on which parameters should be used to
attempt to communicate the image. It then typically transmits the TSI signal (sender identification string), DCS (the
selected capabilities to use for the fax session), and TCF (a 1.5-second sequence of zeros transmitted at the selected
modulation and speed). The receiver analyzes these signals and then typically responds with either FTT (training
failed, or DCS rejected) or CFR (training succeeded, ready to receive). Once the CFR signal is communicated phase B is
- Phase C comprises the communication of the page image data ("TIFF", typically 1D-MH or 2D-MR data described
by ITU-T.4 or 2D-MMR data described by ITU-T.6). The receiver listens for the raising of the
high-speed data carrier, and after the sender raises that carrier it then transmits the image data. When the image
data is transmitted in its entirety, the sender drops the carrier. The receiver detects the end of the page image data
either by detecting an end-of-page code such as an RTC or EOFB signal within the data itself, or by detecting the loss
- At the outset of phase D the sender transmits a post-page message signal which describes if the page was the
last page to be sent (EOP), if there are more pages to follow (MPS), or if it is the last page of a document but more
documents follow (EOM). The receiver responds to the post-page message with either RTN (received page was
unacceptable, must retrain to continue) or MCF (confirmation that the received page was acceptable). If the post-page
message signal was EOM and the page was acceptable, then then the flow returns to the beginning of phase B. In the
case of MCF the flow returns to the beginning of phase C. In the case of EOP, the sender then transmits the DCN
(disconnect) signal and proceeds to phase E.
- The call connection is terminated during phase E usually with the "ATH0" modem command.
The procedure described in 3.6.2 above is for transmission of image data pages that are received with acceptable
quality. Such images may be received with some data corrupted, but not enough to be rejected by the receiver. In
order to communicate pages of image data of perfect quality an error-correcting procedure (ECM) must be
The usual ECM protocol is described by T.30 Annex A. The image data transmitted during phase C is divided into
"blocks" of no more than 64KB. Each block is divided into no more than 256 "frames". Each frame is HDLC-encoded
which allows the integrity of the frame to be checked and verified with accuracy. Thus instead of a post-page message
the sender will transmit a partial-page message signal which indicates the same kind of information as the post-page
message with the addition of a PPS-NULL signal, indicating that there are more blocks to be transmitted for that
The RTN signal is not used by the receiver. Instead, the receiver responds to the partial-page signal with a PPR
(partial-page response) message that describes which frames of the block were detected as corrupt. If no frames were
detected as corrupt then the receiver responds with MCF. The sender is expected to return to the beginning of phase C
and retransmit any frames specified by the receiver's PPR signal.
Provision is made within the ECM protocol to adjust the modulation and speed settings selected in the DCS signal
(CTC) or to give up retransmissions (EOR) in the case that the sender seems unable to communicate the data
The use of ECM protocol enables the sender to transmit 2D-MMR-compressed image data because any image data
corruption would also corrupt the interpretation of any data that followed it. Therefore perfect image quality is
required for communicating MMR image data.
Despite the ability to use the tighter-compressed MMR data format, the use of ECM generally uses more connection
time than when not using ECM at the same communication speeds. That is the price to get perfect image quality
instead of acceptable image quality.
3.6.4 V.34-Fax (SuperG3)
ITU-T.30 Annex F describes the use of the V.34 carrier (speeds from 2400 to 33600 baud) for faxing. With V.34-Fax the
V.21, V.27ter, V.29, and V.17 modulation systems are not used. Also, the carrier is not raised and dropped repeatedly
throughout the communication; it remains raised from phase A through phase D.
Instead of CED the V.34-Fax-capable receiver transmits an ANSam signal. The sender detects this, and begins V.8
(so-called "fast") handshaking to establish the V.34 carrier. The V.34 protocol itself establishes and adjusts the
communication speed throughout the fax session, so the TCF signal is unnecessary and is therefore omitted. The CTC
signal is also unused as it would be meaningless.
ECM is required when using V.34. Phase C image data communication speeds using V.34 usually do not exceed 24000
baud. The fax protocol messages during phases B and D are usually communicated at 1200 baud.
V.34-Fax makes for a very stable communication channel because the carrier remains connected during the entire fax
session. V.34-Fax operates at speeds significantly faster than otherwise. However, if there is a problem with the
V.34 modulators, then the fax session must be terminated because the carrier cannot be changed.
3.6.5 DID, Direct Inward Dialing
Although not a fax-specific technology, DID is commonly used by fax receivers instead of multiple separate lines and
modems to route incoming facsimile to the intended recipient. This works by the telco signalling the
dialed number to the modem over the DID-enabled line. The modem then takes that DID signal and reports it to
the DTE similar to how it reports a Caller ID signal. HylaFAX can use that information to allow the administrator to
set up routing for each DID fax received.
DID requires special hardware capable of receiving the DID signal. DID also requires special lines and/or
signalling provided by the telco.
[ HOME ] [ BACK ] [ NEXT ]
Last updated $Date: 2004/08/14 20:21:17 $.