Difference between revisions of "Handbook:Server Operation:Understanding Your 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.

The HylaFAX Daemon (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.

For security reasons, inetd has been replaced by other programs such as xinetd, but the concept is the same.

Note, that for performance purposes, some configurations do not use inetd at all. Its preferred to simply use hfaxd in standalone mode. This avoids the overhead of inetd (or the equivalent program) to hand off to hfaxd.

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.

Client Authentication

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.

Client-Server Protocol

HylaFAX's client-server protocol is very similar to FTP. It has never been exhaustively documented in any form, unless you consider the source code to be sufficient documentation!

By far the best starting point for understanding the client-server protocol is to study the hfaxd(1m) UNIX Manual Page. The next step is to submit a fax using sendfax (the fully-featured command line client included with the HylaFAX distribution) and watch the client/protocol exchange by adding a '-vv' to the sendfax command. For example:

[darren@myhost darren]$ sendfax -vv -n -k 'now + 2hours' -m -d 912155551212 /etc/hosts
Trying localhost (127.0.0.1) at port 4559...
Connected to localhost.localdomain.
220 myhost.mycompany.com server (HylaFAX (tm) 4.2.3) ready.
-> USER darren
230 User darren logged in.
match against (..., 240)
rule: offset 0 string = "%!" -- failed (comparison)
rule: offset 0 short = 0x4d4d -- failed (comparison)
rule: offset 0 short = 0x4949 -- failed (comparison)
rule: offset 0 short = 0x1da -- failed (comparison)
rule: offset 0 short = 0x1f1e -- failed (comparison)
rule: offset 0 short = 0x1f9d -- failed (comparison)
rule: offset 0 short = 0x506 -- failed (comparison)
rule: offset 0 short = 0x5343 -- failed (comparison)
rule: offset 0 short = 0xf702 -- failed (comparison)
rule: offset 0 string = "GIF" -- failed (comparison)
rule: offset 0 long = 0x59a66a95 -- failed (comparison)
rule: offset 0 string = "%PDF" -- failed (comparison)
rule: offset 0 string = "x T psc" -- failed (comparison)
rule: offset 0 string = "begin" -- failed (comparison)
rule: offset 0 string = "xbtoa" -- failed (comparison)
rule: offset 0 string = "P1" -- failed (comparison)
rule: offset 0 string = "P2" -- failed (comparison)
rule: offset 0 string = "P3" -- failed (comparison)
rule: offset 0 string = "P4" -- failed (comparison)
rule: offset 0 string = "P5" -- failed (comparison)
rule: offset 0 string = "P6" -- failed (comparison)
rule: offset 0 string = "WNGZWZSS" -- failed (comparison)
rule: offset 0 string = "#Inventor V" -- failed (comparison)
rule: offset 0 ascii = -- success (result postscript, rule "%F/textfmt
-B -f Courier-Bold       -Ml=0.4in -p 11 -s %s >%o <%i")
CONVERT "/usr/local/sbin/textfmt -B -f Courier-Bold     
-Ml=0.4in -p 11 -s default >/tmp//sndfaxvZW07y </etc/hosts"
Apply DisplayNumber rules to "912155551212"
--> return result "912155551212"
-> TYPE I
200 Type set to Image.
SEND compressed data, 6051 bytes
-> PORT 127,0,0,1,226,33
200 PORT command successful.
-> MODE Z
200 Mode set to ZIP.
-> STOT
150 FILE: /tmp/doc1103.ps (Opening new data connection).
SEND 2277 bytes transmitted (2.7x compression)
226 Transfer complete (FILE: /tmp/doc1103.ps).
-> JNEW
200 New job created: jobid: 2070 groupid: 2070.
-> JPARM FROMUSER "darren"
213 FROMUSER set to "darren".
-> JPARM LASTTIME 000159
213 LASTTIME set to 000159.
-> JPARM MAXDIALS 12
213 MAXDIALS set to 12.
-> JPARM MAXTRIES 3
213 MAXTRIES set to 3.
-> JPARM SCHEDPRI 127
213 SCHEDPRI set to 127.
-> JPARM DIALSTRING "912155551212"
213 DIALSTRING set to "912155551212".
-> JPARM NOTIFYADDR "darren@myhost.mycompany.com"
213 NOTIFYADDR set to "darren@myhost.mycompany.com".
-> JPARM VRES 196
213 VRES set to 196.
-> JPARM PAGEWIDTH 215
213 PAGEWIDTH set to 215.
-> JPARM PAGELENGTH 279
213 PAGELENGTH set to 279.
-> JPARM NOTIFY "none"
213 NOTIFY set to "none".
-> JPARM PAGECHOP "default"
213 PAGECHOP set to "default".
-> JPARM CHOPTHRESHOLD 3
213 CHOPTHRESHOLD set to 3.
-> JPARM DOCUMENT /tmp/doc1103.ps
200 Added document /tmp/doc1103.ps as docq/doc1103.ps.2070.
-> JSUBM
200 Job 2070 submitted.
request id is 2070 (group id 2070) for host localhost (1 file)
[darren@myhost darren]$

By spending some time with the sendfax manual page experimentng with the various commandline options and seeing how they affect this client-server protocol exchange, a person should be able to quickly reverse engineer most common transactions with minimal effort.

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.

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

Fax Technology Primer

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.

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.

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 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 ("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 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 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.

Error Correction Mode (ECM)

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

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.

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.

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.