The HylaFAX "How-To" Guide

Lee Howard,

v4.2.2, 19 Oct 2005

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

1. Introduction

Is HylaFAX the package you're looking for?

If the answer is yes to any of these questions, then HylaFAX is the solution. Its open source nature and dedicated following provide for a flexible, customizable, and tested package, while basic and simple faxing needs can be met easily and quickly.

1.1 General HylaFAX Use

Most HylaFAX users have configured HylaFAX on a standalone server to both send and receive faxes for an existing workgroup of computers. Often, incoming faxes will be delivered by e-mail to a receptionist of sorts who routes those faxes to the intended recipients. HylaFAX also supports automated routing methods, such as routing based on DID/DNIS, caller ID, port/line, or other fax information. HylaFAX is often configured to handle outgoing faxes from a number of different computers and users. This saves them time, and there's no more waiting at the fax machine while a fax completes, either. Outbound faxes can be received by the server in a large number of different ways: popularly, by direct communication with the server or also by e-mail.

Many HylaFAX administrators take good advantage of the system's logging and reporting mechanisms. HylaFAX can be configured to give descriptive reports of all faxes and/or summaries of fax logs for any period of time.

Common coverpage customization allows for every fax to quickly relay standard information regarding the fax service, and unique information regarding the sender and recipient.

1.2 HylaFAX Capabilities

All of the following features are possible with HylaFAX (although not all may be detailed in this document):

1.3 About This Document

The purpose of this HOW-TO is to provide the reader with a complete and brief tutorial on the implementation of most common HylaFAX features. It is not intended to be an exhaustive resource for in-depth HylaFAX structure and analysis. It does not intend to replace the man pages. Also, this document is not meant to be an authoritative manual for HylaFAX use. Its intent is simply to show most users how to quickly implement the most popular HylaFAX features.

1.4 Behind Fax-Modem Compatibility

Please understand that I'm extremely biased in what I'm about to say. I'll *try* to withhold my bias, and be fair in my comments here, but please understand that I do work for Mainpine and I have also had friendly relationships with both Multitech and Comtrol... AND I've also developed (or helped develop) my own soft-modem of sorts.

Ten years ago things were different in the fax modem world. And, ten years before that things were even more different.

When HylaFAX first was released in roughly 1991 modems were quite expensive and faxing with modems was rather a novelty. I haven't done detailed research on this, so feel free to correct any wrongs in what I say, but (having worked closely in the PC industry for nearly all of that time) in the very early days you had many modems that didn't support fax at all, and then when you did find one it typically had Class 2 support. There was a reason for this.

Fax is timing sensitive. Most of the parts of the communication are governed by strict timing constraints, and if you get a delay of even 1 second in places it can cause failure. Because PCs in 1991 were rather slow it only made sense that fax modems use Class 2 (because the CPU couldn't be relied on for timing-sensitive operations). However, the downside to Class 2 (or Class 2.0, as USR's version of the specification became known - as opposed to Rockwell's "Class 2") is that a lot of fax logic and programming has to get stuffed into the chips on the card. ECM requires more than 64KB to operate (which was an expensive proposition then - although the ECM specification may not have even existed at that time). So back then the selection was rather limited to modems using Rockwell (later to become Conexant) chipsets or modems using USR technology (now 3Com, but the fax technology actually came from Texas Instruments). Judging from the variety of HylaFAX prototype configuration files I must conclude that there had to have been several other smaller manufacturers of fax modem chipsets, but as far as my experience goes, these two were the big players.

I have used many of these modems, and undoubtedly the fax operation was considered "good" for those days, but by today's standards they're actually quite poor. Furthermore, Class 2 is eventually a dead-end on every board because eventually the manufacturer has to move on to newer products. This progression essentially leaves intact any bugs that appear afterwards especially due to interactions with newer equipment. However, on older equipment (like i386SX CPUs) using Class 2 was really the only way to go. However, by the time CPUs were in the i586 days the CPU should generally be considered fast enough to handle fax protocol timings reliably. Thus, as CPU speed increased so did the applicability of Class 1 protocol for fax applications.

By in large using Class 1 (in your software application) was a smarter choice because it left the software developers with much more control. Typically in those days the CPU had access to much larger and much less-expensive sources of RAM and computing speed. So applications could (in theory) start implementing things like ECM support (which is really the backbone to any degree of reliability in faxing). However, very few (if any) fax applications took advantage of the power that Class 1 presented --- probably because it would have required a fair amount of work on their part. So there passed many years where modem manufacturers were pointing fingers at application developers and vice-versa. Consequently, you have a whole era of Class 2 modems that worked just about as well as did the fax applications in Class 1 - neither one usually supporting things like ECM. Funny thing, though, many of those older fax machines didn't work that reliably, either. "Line noise" got blamed a lot of times, but I think that the truth was more likely not so much to blame on such "noise", but rather due to misunderstandings and disagreements over the fax protocol itself or incompatibilities in the DSPs.

Back in those days modems were almost exclusively on 8-bit or 16-bit ISA boards. You saw a lot of Rockwell-chipsetted modem cards out there. Although there were some "clone" USR modems around, if you wanted a TI-chipsetted modem you largely needed to buy USR. I've also seen some old ISA Lucent and Motorola cards, so obviously there were other players, but my experience was largely to see only those two chipsets (Rockwell and USR).

In those days both USR's Class 2.0 and Rockwell's Class 2 were usable. By today's standards they were both rather unreliable, but back then users tended to prefer Rockwell's Class 2 over USR's Class 2.0... although each one had their advantages and disadvantages. Eventually both had Class 1 on their cards, and truthfully I feel that Rockwell did a better job of it (Class 1). Although Class 1 should be easier for the modem manufacturer to implement, USR's Class 1 always left something to be desired. So by the time HylaFAX had ECM support built into it you'll see people preferring Class 1 over Class 2/2.0 on all modems, but preferring Rockwell's version of it.

Modem manufacturers were slow to move on to PCI cards. So companies like Lucent (later Agere and then LSI) and little-known PCTel took advantage of that gap and quickly you'll see modems appearing with lots of Lucent and PCTel chipsets. CPUs were fast enough that the manufacturers even started offloading the DSP and DCE (parts of the modem controller - and sometimes even the serial controller) onto the CPU - in so-called "winmodems" where the "driver" did a lot more work than it did previously. This was a wise move in some respects. It meant that they could avoid dealing with hardware restrictions and could leverage the fast and cheap CPU and RAM available in the rest of the system. The downside, however, was that anyone not using a supported operating system (namely Windows) was not supported. And most of us HylaFAX users were relegated to sticking to old ISA modems.

During this time Conexant (previously Rockwell) purchased PCTel and so PCI modems with "Conexant" chipsets were invariably "winmodems". The PCTel drivers worked well on Linux - as did the drivers for Lucent "linmodems", but they had a hard time keeping up with the pace of Linux kernel development, and it didn't take long before you really couldn't use a PCTel modem on any current version of Linux. However, about three PCI chipsets that were actual hardware modems existed: Lucent/Agere "Venus", USR/3Com "5610" a.k.a "kermit", and a little-known "Topic" chipset (which seemed available only in Europe - and thus I've never used one myself).

In later versions the Venus chipset supported V.34-fax which had previously been unavailable on consumer fax modems. It was available both in the Lucent/Agere "Class 2.1" and "Class 1.0" (which is different from Rockwell/Conexant's "Class 1.0" which supports some advanced Class 1 commands but not V.34-fax). These fax modems also supported ECM in that Class 2.1... which therefore easily set them apart from typical Class 2 reliability.

Modem manufacturers which had traditionally used only Rockwell chipsets started offering models that were not (possibly because the stockpile of Rockwell chipsets was drying up or possibly because the cost in adding a hardware DSP/DCE/serial controller to the Conexant chipset was excessive). For example, Multitech started offering it's popular "5634" line which used Lucent/Agere chipsets. Zoom (on "2920") and Mainpine (on "RockForce") did as well.

Again, I'm ignoring several other minor fax modem chipset and chipset firmware players. For example, Analog Devices, SmartLink, Intel, etc. all are out there, but they seem to be exclusive to certain types of modems.

These days modem manufacturers seem slow (again) to be adopting new bus technology (namely PCIe). Mainpine has been very forward-looking with it's PCIe IQ Express cards, however.

Several years ago I found myself in a bit of a fix using Asterisk PBXes (with actual TDM lines) and unable to inexpensively and reliably connect to a fax modem or fax system of some kind. Consequently I used the developing spandsp library to help its author put the finishing touches on a viable Class 1 soft-modem. I called it "IAXmodem" because it operated on the Asterisk IAX2 audio channel. As I have since used this modem extremely heavily I have made sure that it is quite robust in operation.

Several manufacturers do add a fair amount of customization to the chipset technology that they adopt, so I don't mean to ignore that in what I'm saying, but these days your choices of modems really only hinge on the chipset (well, DSP and DCE) being used. So the point of my long-winded explanation here regarding a hardware compatibility list is that there will be very little difference in actual run-time operation between different cards using the same chipset. Your choices (as far as I can immediately recall) are...

LSI (previously Agere/Lucent) CFAX34 --- these are found on Mainpine IQ Express (PCIe card)

Agere/Lucent Venus - these are found on Mainpine Rockforce (PCI), Multitech 5634 (PCI, external, USB), and some rare Zoom 2920s (PCI, USB). This chipset has been discontinued, but you may still be able to purchase them. Be aware that Zoom has recycled the "2920" model name, so you're unlikely to find any these days that actually use Venus chipsets... if you're looking for a PCI card look for the Rockforce (multiport) or 5634s (multiport "ISI" versions require a proprietary driver).

Conexant - these are found on plenty of "winmodems", however you can also find them (or at least the ported "K56" or PCTel technology) on hardware modems from Multitech "5656", Comtrol RocketModem (multiport), and Zoom.

3Com/USR - these are found exclusively on USR modems. However, some of the USR "winmodems" actually use Conexant chipsets.

IAXmodem - this isn't actually a chipset at all, but you can use any number of "Zaptel"/"DAHDI"-compatible cards to run these with Asterisk like a driver - gives you a rather powerful voice application as well.

I've composed the list above in my order-of-preference, too - except for IAXmodem. When customers approach me about what to use for their HylaFAX installations I generally recommend to them to follow that order. So, if they have PCIe and if they can get a 2.6.28 kernel (or a kernel patched with the relevant mods to the serial driver), then I generally advise to go with the IQ Express (Rev3). If they are limited to PCI or absolutely cannot get into a different kernel, then I have them look at Rockforce for multi-port scenarios or the MT5634 for single-ports. (I have used the ISI modems, but their proprietary driver is cumbersome.) If they're trying to go cheap then they can sometimes find an old Comtrol Rocketmodem II (which uses Conexant chips) on eBay or something. The downside to them, however, is the proprietary driver which right now doesn't work on anything newer than 2.6.26... AND they don't support V.34-fax (which ends up being a nice-to-have with the Venus and CFAX34 chips). I never (ever) recommend USR modems. More often than not when I try helping people through using them we ultimately end up switching them out.

IAXmodem tends to be a bit of an alternative solution. For those who already have an Asterisk PBX (or FreeSWITCH or CallWeaver) it is the right solution for their TDM fax application. For those who are using a T1/E1/J1 (digital) line, it is the right solution (and essentially the *only* solution that won't make you faint over the pricetag like a new Patton 2977 or Brooktrout/Eicon/Dialogic solution will). But sometimes when the customer is unwilling to pay for a proper hardware solution (the IQ Express) and when V.34-fax really doesn't matter to them (IAXmodem doesn't support V.34-fax because the relevant patents are not yet expired), and when I don't want the hassle of finding something on eBay or monkeying with finding a non-current distro that still has support for on-line updates while also being compatible with the proprietary driver... in these cases I'll actually recommend going through the whole effort to deploy an Asterisk PBX just to drive the cheap TDM card that almost always ends up being exclusively used for fax. I tend to hold off on this recommendation because of the amount of work involved in setup and the potential for problems in so many different pieces of software. However, in my opinion one of the nicest things about the solution is that I can make a recording of the fax call and I can tell immediately what's going on - even if they are just dialing the wrong number: I can hear the recorded message saying so. :-)

So, anyway, that's why I haven't really put a whole lot of effort into a compatibility list... namely because, in my mind, the decision-making isn't so much about what is or isn't compatible (that list is rather small) or what works well (that list is even smaller), but what is the appropriate solution for the installation.