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 (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 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:

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.

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.

• 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 bps 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 supports both. HylaFAX can make use of the avanced command, AT+FAR=1 ("adaptive reception" - which is different from "adaptive answer"), and HylaFAX also supports V.34-Fax in Class 1.0.
• 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 bps carrier while training and image data are communicated using V.27ter, V.29, or V.17 carriers (2400 bps through 14400 bps). 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 begun.
  
• 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 complete.
  
• Phase C comprises the communication of the page image data (typically "TIFF", 1D-MH or 2D-MR data described by ITU-T.4 or 2D-MMR data described by ITU-T.6 - but JPEG and JBIG are also options). 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-data code (such as an RTC, EOFB, RCP, etc.) signal within the data itself, or by detecting the loss of carrier.
  
• 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 MPS 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.

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.

---