The HylaFAX "How-To" Guide

Lee Howard,

v4.2.2, 19 Oct 2005

This is a detailed guide to HylaFAX installation, configuration, and troubleshooting.

3. Using HylaFAX Server

For a thorough understanding of the HylaFAX server there is no alternative to reading the man pages. Especially useful are hylafax-server(5F), faxgetty(8C), hfaxd(8C), faxq(8C), faxrcvd(8C), hylafax-log(5F), hosts.hfaxd(5F), and although technically a client application, faxstat(1) is useful in determining the status of the HylaFAX server.

3.1 The HylaFAX Service, hfaxd

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.

3.2 HylaFAX faxgetty

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.

3.3 Setting hosts.hfaxd Permissions

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 ( 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 faxadduser(8C) and faxdeluser(8C), commands.

Beginning with HylaFAX version 4.2.0, PAM support may also be used to authenticate users.

3.4 Understanding faxstat

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, 'faxstat' returns:

When idle, 'faxstat' should return:

When faxgetty is respawning, 'faxstat' will return:

If hfaxd is not running, 'faxstat' will return:

The rest of the 'faxstat' results should be self-explanatory.

3.5 Using The HylaFAX Server Logs

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 accurate analysis.

At this stage of development, hfaxd continually outputs information to the "debug" facility - the "LogFacility" parameter is not recognized. This means that any communication from a client will generate log entries. In particular, clients that regularly poll the faxserver for status can generate a significant amount of log information. Some distributions, including Ubuntu, may have configured the system log daemon to record all debug events - which when combined with a polling fax client can result in sizable log files.

A workaround is to turn off logging of debug. Depending on the log daemon used, the debug messages can be ignored or re-directed to null.

For syslogd, include the line: daemon.debug /dev/null before any other "debug" line in the syslog.conf file. This will "eat" debug information from Hylafax, while allowing information from other applications to flow through.

For syslog-ng, change filters in syslog-ng.conf (or the syslog-ngthat reference daemon. Examples include: filter f_daemon { facility(daemon); }; becomes filter f_daemon { facility(daemon) and not level(debug); }; and then to keep debug clear: filter f_debug { level(debug) and not facility(auth, authpriv, news, mail); }; becomes filter f_debug { level(debug) and not facility(auth, authpriv, news, mail, daemon); };

For rsyslog, change the selectors in rsyslog.conf (or the file(s) in the rsyslog.d directory): daemon.* becomes daemon.!debug

This does mean that any other application using the daemon facility and debug priority will no longer create logs - but this would typically only be needed on a development system which Hylafax is unlikely to be run on. At such time as hfaxd is updated to support the LogFacility parameter, these workarounds should no longer be required.

3.6 Understanding Fax Technology

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.

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.

3.6.3 ECM
The general 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 used.

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 page.

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. A receiver may also decode the image data prior to transmitting MCF to make sure that there is valid image data within the ECM blocks. 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 properly.

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. The use of ECM protocol is also required for JPEG and JBIG image data, as well as for V.34-Fax.

Despite the ability to use the tighter-compressed MMR data format, the use of ECM may potentially use 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 bps) 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 bps. The fax protocol messages during phases B and D are usually communicated at 1200 bps.

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.

In the case that the HylaFAX-controlled modem is working behind a fax-compatible PBX system and that PBX system receives DID information from the telco, then if that PBX can pass the DID information to the modem as a series of DTMF digits after the modem answers a call - and if the modem supports reception of DTMF digits in this fashion (usually requires that the modem have "voice" support) - then the modem hardware does not need to have specific DID-capabilities to receive DID information from the PBX, as HylaFAX supports DID reception via DTMF in this manner.