Managing Faxes with HylaFAX

Today's users expect their computing environment to provide a lot of services that used to be considered luxuries. Sending faxes from the desktop is one of them. These days, since most PCs come equipped with a modem, it's not uncommon for the standalone fax machine to be eliminated.

Today’s users expect their computing environment to provide a lot of services that used to be considered luxuries. Sending faxes from the desktop is one of them. These days, since most PCs come equipped with a modem, it’s not uncommon for the standalone fax machine to be eliminated.

There are several open source faxing packages available for Linux systems. Perhaps the best known of them is HylaFAX (http://www.hylafax.org). In addition to sending and receiving faxes, HylaFAX can also act as a central fax server that accepts fax jobs from other hosts on the network. It maintains a queue of outgoing faxes, transmits them when it can, and delivers incoming faxes as email messages.

Let’s take a look at how to configure and manage HylaFAX.

Setting Up HylaFAX

Many Linux distributions, including Red Hat and SuSE, ship with the HylaFAX package already installed (if not, there are RPMs and source files available). After it’s installed, run the faxsetup script, which automates the initial configuration. It will ask you a series of questions about your system and how you want to use the package, then generate the appropriate HylaFAX configuration files based upon your answers.

There are quite a few configuration files that HylaFAX uses. Although faxsetup will generate them for you, it’s helpful to know what they are and what information they hold. The following are the most important configuration files:

  • /var/lib/fax/hfaxd.conf: Configuration file for hfaxd, the HylaFAX server daemon. It defines where additional configuration files and other parameters are located. The installed version of this file rarely needs to be modified.

  • /var/lib/fax/sendfax.conf: System-wide settings for the sendfax command, which initiates an outgoing fax. Users can also create their sendfax configuration file as $HOME/.hylarc.

  • /var/spool/fax/etc/config: General HylaFAX settings for the local system/site. Here you specify how to dial outgoing telephone numbers (including how to distinguish long distance and international calls from local ones), the amount of logging, the maximum number of concurrent jobs to handle (which should be no more than the number of modems connected to the system), the maximum page lengths for faxes (sending and receiving, including cover page), and the maximum number of phone calls and transmission attempts that will be made to send each fax.

  • /var/spool/fax/etc/config/config.line: Specifies the serial device file connected to each modem (e.g., ttyS0) and contains a variety of modem-specific communications-related settings.

Once the faxsetup script has finished, there are still a few things to do before HylaFAX is completely configured:

  • Make sure there is a link to /etc/init.d/hylafax from an S-file and a K-file in /etc/rc.d/rc3.d (and in /etc/rc.d/rc5.d if the system uses a graphical login). This will ensure that the HylaFAX daemons are started each time the system boots.

  • If you plan to receive faxes, you must add an entry to /etc/inittab to run the faxgetty program for every modem. Each call to faxgetty should be given the device file for a modem as an argument. Here’s an example:

fax:2345:respawn:/usr/lib/fax/faxgetty /dev/ttyS0

  • Add a cron job to call the faxclean utility, which will automatically purge log files related to completed jobs and older failed jobs. The frequency will depend on the amount of fax traffic you have as well as the available disk space on the system. If faxing is occasional, then running it once a week is probably fine. On the other hand, if a system is providing full-time fax services for a local network, then it may need to be run as often as once an hour.

Note that there is no utility to maintain or clean up the per-job log files (stored in /var/spool/fax/log). Although these are generally quite small, you will have to manage them yourself. For example, you could write a cron job to delete all but the most recent entries. You’ll also want to keep an eye on the main log file, /var/spool/fax/etc/xferfaxlog, and possibly implement a similar scheme for it as well.

If you add an additional modem for faxing after you’ve configured HylaFAX, use the faxaddmodem script to configure it and place it under the server’s control. You can also use faxaddmodem to modify the settings for an existing modem.

HylaFAX Components

Now that we’ve performed the initial configuration of HylaFAX, let’s see how to send and receive faxes. The actual fax services are provided by two HylaFAX daemons:

  • faxq, the queuing agent, is responsible for sending and receiving fax transmissions.

  • hfaxd, the server daemon, handles faxing from remote hosts, access control, and other management functions.

The package also includes a variety of utilities (some have already been mentioned, and we’ll look at a few others in a bit). The actual executables are generally stored in /usr/lib/fax and /var/spool/fax/bin.

The main HylaFAX queuing area is /var/spool/fax. This directory has a number of important subdirectories. Table One lists their names and purposes.

Table One: Main HylaFAX queue directories




Stores outgoing fax image files


Stores incoming fax image files


Holds outgoing fax job control files (which specify the fax’s destination and other transmission-related information)


Contains log files for each fax job


Stores modem type definitions


Contains most of the HylaFAX configuration files

Sending Faxes

Sending faxes is done with the sendfax utility. Figure One shows a sample invocation that uses many command-line options. The only required option is -d, which specifies the recipient’s name and phone number, separated by an @ character. Also required is the name of the file (or files) that should be faxed. HylaFAX can fax ASCII text, Postscript, and TIFF image files.

Figure One: Calling sendfax

$ sendfax -s na_let -d “Amy Ng”@1.293.555.1212 \
-f “Erika Plantagenet” -r “Reg. Data” \
-h dalton.ahania.com letter.txt graph.tif

The other arguments shown in Figure One are optional, but are worth discussing (there are even more arguments, but this article will not cover them). The -s option specifies the paper size to use. This example specifies US Letter (those working in European or Asian countries can use a4 for A4 size). The -f option specifies the sender’s name, and the -r option specifies the subject (it stands for “Re:”).

Finally, the host name of the fax server to use is specified with -h. If it’s not specified, the fax is sent to the server specified by the FAXSERVER environment variable (if defined) or to the local host (if FAXSERVER is not defined).

Most of the sendfax options are used to specify information for the fax cover sheet. The default template file is /usr/lib/fax/ faxcover.ps. You can create new PostScript templates with TEX if you want. The cover sheet can be suppressed with the -n option.

Monitoring and Managing Outgoing Faxes

HylaFAX includes several utilities for monitoring and manipulating fax jobs. The faxstat command displays information about fax jobs that have been sent by using the -s option. Outgoing fax jobs have a job ID assigned (similar to print jobs).

Several other HylaFAX utilities manipulate individual fax jobs, which are always referred to by job ID (listed in the first column in the faxstat -s output).

The faxabort command can be used to stop (or interrupt) a job from being sent, but does not remove it from the sending queue. The faxrm command aborts the job and removes the fax from the sending queue. Again, the job ID is provided as an argument to both these commands. Jobs on a remote HylaFAX server can terminated by using the -h option followed by the hostname of the remote server.

Both faxabort and faxrm require either superuser privileges or the HylaFAX administrative password. We’ll see how to set this up in a bit.

The faxalter command, (which can only be run by the superuser) is used to modify the characteristics of a pending fax job. For example, the following command sets job 24 to be released for transmission at 9:00 p.m. and sets its priority to bulk (low):

# faxalter -p bulk -a 21:00 24

Finally the xferfaxstats command produces a summary report of all fax activity, broken down by sending user.

Handling Incoming Faxes

Incoming faxes are saved in the recvq directory in TIFF format and can be viewed with any TIFF viewer (e.g., gimp) or converted to Postscript with the fax2ps command.

Unfortunately, HylaFAX does not have an automated method of routing faxes to recipients. The closest thing you can do is route the fax to a destination based on the incoming phone number. The /var/spool/fax/bin/faxrcvd script (called by the faxgetty daemon) calls the FaxDispatch script (located in the same directory) and looks up the fax’s originating phone number in the file /var/spool/fax/etc/users. This file, which must be built by hand, contains a list of phone numbers and an email address. When a fax comes in from a certain phone number, it is sent to the corresponding email address. A sample file might look like this:

If FaxDispatch finds a match for the source phone number in this file, faxrcvd creates an email message and sends it to the corresponding user. The fax itself (converted to Postscript) is included in the message as a MIME attachment. If there is no match, the fax is left in the recvq directory.

Unfortunately, this isn’t usually a practical scheme for two reasons: most faxes don’t come from a predictable phone number, and ones that do come from a frequent sender probably go to several different people within your organization.

An alternative is to modify the faxrcvd script to perform a different action on an incoming fax. For example, to print each incoming fax, place this command in the faxrcvd script:

/usr/bin/fax2ps -S $1 | lpr -P $FAX_PRINTER

Faxes are then delivered the old-fashioned way (albeit from a printer and not a fax machine).

Controlling Access to HylaFAX

You can limit access to the Hylafax facility by user and host. These restrictions are defined in the /var/spool/fax/etc/hosts. hfaxd file. An example file might look like this:


Each line has four fields, separated by colons.

  • The first field is the sender and is specified by a regular expression. If the name of the fax sender (the name format is user@host) matches the regular expression, then the permissions specified in the remaining fields apply. The leading exclamation point in the second line means that the user king is denied access to the fax service.

  • The second field, map-to-uid, is optional and indicates the local UID that matching senders will use for file permissions and accounting purposes. In the last line of the example, all users from the zoas.org domain are mapped to uid 123.

  • The third field, send-password, is an optional password (stored in an encrypted form). If specified, it must be entered before a fax will be sent (no password is needed for receiving). Looking at the last line of the example, all users in the zoas.org domain must specify a password to send a fax. If the field is blank, then no password is needed to send a fax. Thus, all users in the domain ahania.com (see the third line in the example) may send a fax without specifying a password.

  • If the final field, admin-password, is set (it’s also stored in an encrypted form), then that password must be specified to perform HylaFAX administrative functions (e.g., modifying or removing other users’ faxes). In the first line of the example, the user chavez can run an administrative command from anywhere in the ahania.com domain.

The first entry that matches the sender criteria in the file is used, so the order of entries within the file is important (if no entry matches, then access is denied). For this reason, entries should be ordered from most to least specific.

Both the sending and administrative passwords are stored in an encoded form. When modifying the password fields, you must use the faxadduser and faxdeluser commands, which perform the password encryption. However, if you’re only adding or modifying entries and not specifying or changing the password fields, you can edit the file directly.

For example, here’s a call to the faxadduser command that creates an entry allowing the user mercury in the local domain (ahania.com) to administer the fax system, whose administrative password is “olympus”:

# faxadduser -a olympus ‘mercury@.*ahania\.com

Unfortunately, there is no modification utility. If you wish to change an existing entry, you must run faxdeluser followed by faxadduser.

Paperless Faxing

Despite the ubiquity of email, there are still times when faxing is required. HylaFAX provides a way to fax files directly from your computer without having to print them first.

With proper configuration, incoming faxes can be delivered directly to their recipients to be viewed, stored, or deleted electronically, without ever being printed. This saves paper, and more importantly, it frees you from hanging around the fax machine, waiting for your fax to come in.

Æleen Frisch is the author of Essential System Administration. She can be reached at aefrisch@lorentzian.com.

Comments are closed.