HylaFAX is a free fax server program (consisting of several daemons) that runs on a Debian Linux system. Even though the HylaFAX software is running on a Linux system, client software for it is available for Windows and Macintosh systems. In some cases the fax client is simply a logical printer. When the user “prints” their document to this printer it gets redirected to the fax server. A fax server can be a real paper saver for organizations that send a lot of outbound faxes.
Because there is no way to address a fax to a given individual in an organization (i.e. the only recipient “address” for a fax is the fax phone number), HylaFAX handles received faxes using e-mail. First, the received fax is converted to a .TIF, .PDF, or PostScript file. It then sends an e-mail to a user listed in the configuration with an FTP link to the file. You could also have HylaFAX attach the file to the e-mail. (Note that these e-mail options would require you to have Sendmail installed and configured on the fax server.)
An alternative to the e-mail method would be to set up HylaFAX to automatically print all received faxes to an lpr printer (see the LAN Servers page on how to set up an lpr printer on your fax server – it’s not hard). The printer would have to have PostScript capability, and this method doesn’t offer any reduction in paper usage for received faxes, but it does negate the need for a separate fax machine (and its associated toner/ink supplies).
Setting Up The Server
Once you have a fax-modem connected to your system (see more about connecting a modem to your Debian system on the Modems page) you install the HylaFAX package with the command:
During the installation you’ll be asked to insert numerous CDs. After the installation is complete you’ll need to run a couple configuration utilities. Have your modem hooked up before proceeding. At the shell prompt type in the command:
and press Enter and you’ll see a lot of text fly by. Answer Yes to adding a FaxMaster alias.
For a user to received fax-related mail enter the user account you created for yourself during the Debian installation.
Four configuration parameters will be listed and you’ll be prompted as to their correctness. Press Enter to accept these values. You’ll then be asked if you want to run
to set up the software to use the modem. Press Enter to accept the default Yes response.
Enter the correct ttyS designation for the serial port your fax-modem is connected to (ttyS0 is for COM1). You’ll be prompted for quite a few values. For most you can accept the default values by pressing Enter. The values you’ll want to enter are:
- Country code (1 for US)
- Area code
- Phone number of fax modem
- Local identification string (this should be something like ‘My Fax Server’ as it is printed on the tag line of outgoing faxes)
- Long distance dialing prefix (1 in US)
- International dialing prefix (011 in US)
- Dial string rules file (accept the default)
- Tracing during normal server operation (accept the default)
- Tracing during send and receive operations (accept the default)
- Protection mode for received fax – enter 0644
- Protection mode for session logs – enter 0644
- Protection mode for ttySx – enter 0666
- Rings to wait before answer
Note: The default is 1 but setting it to 0 establishes your server as a “Send Only” fax system
- Modem speaker volume (valid values are OFF QUIET LOW MEDIUM HIGH (you may want to set it to HIGH for testing purposes as you can change it to OFF later)
- Command line arguments for getty (accept the default)
- Pathname of TSI ACL file (accept the default)
- Pathname of Caller-ID ACL file (accept the default)
- Tag line font file (accept the default)
- Tag line format string (accept the default)
- Time before purging UUCP lock (accept the default)
- Hold UUCP lockfile during data calls (accept the default)
- Hold UUCP lockfile during voice calls (accept the default)
- Percent good lines to accept (accept the default)
- Max consecutive bad lines to accept (you may want to reduce the default 5 to 3)
- Max number of pages to accept in a received fax (you may want to increase the default value of 25)
- Syslog facility name for ServerTracing messages (the default is ‘daemon’ but you could change it to ‘local7’ if you’re logging to a remote syslog server)
- Set UID to 0 (accept default)
- Use priority job scheduling (accept default)
You’ll then be asked to confirm the values that you entered and then the utility will query to modem to determine the fax classes that it supports.
Even if your modem supports both Class 1 and Class 2 you should set it to Class 1 for compatibility with all fax machines.
You will then be asked for values specific to the modem. Just press Enter to accept the default values as they are a result of the modem query and the class you selected. You’ll then be prompted to confirm these values by pressing Enter.
The non-default scheduler values will then be displayed with a confirmation prompt. The Area Code may not be correct. If so, answer No and correct any erroneous values. You may also want to increase the time value for “Timeout when converting PostScript documents” if you fax long documents but you can just press Enter to accept the default values for the rest of the values.
Answer No when asked if you want to configure another modem.
Accept the default Yes answer to run faxmodem on your newly configured modem to verify settings. You’ll then be returned to the shell prompt.
If you want to manually edit the file that contains these settings do so with the command:
Add this line to config.ttyS0 for modem not to wait DIALTONE before dialing
ModemDialCmd: ATX3dt%s # For not waiting dialtone
If an old modem send for every fax black pages you have to put ‘Use2D: no’
You have to run the faxaddmodem utility to create this file first though.
Next we’ll set up HylaFAX to run automatically when you boot the system. Check the configuration file:
to make sure there’s no # character at the beginning of the line containing RUN_HYLAFAX=1. Exit the editor.
One last that item is to let HylaFAX know who is allowed to send faxes. You can use a modified subnet address to let everyone on your network submit faxes to the server. Edit the hosts.hfaxd file with the command:
As an example, if your using a subnet address for your network of 192.168.10.0 enter the following line into the hosts.hfaxd file:
Likewise, if your using a subnet address of 172.16.0.0 your hosts.hfaxd file entry would be:
You can enter as “wide” of a network address or multiple narrower address entries as you’d like. If you’d like to restrict access to specific users you can enter their individual IP addresses. When done, save the file and exit the editor.
NOTE: You will see the paths /var/spool/hylafax and /var/spool/hylafax/etc specified in HylaFAX documentation and utilities. Do NOT edit the files in these directories. The files are duplicated in the /etc/hylafax directory. If you ever want to manually edit the configuration files, only edit the files in the /etc/hylafax directory. Reboot the system by pressing Ctrl-Alt-Del and you’ll have yourself a fax server! Once you’re back at a shell prompt, type in the command:
and you should see output similar to the following:
HylaFAX scheduler on localhost: Running
Modem ttyS0 (+1.111.555.1212): Running and idle
The first line indicates that the HylaFAX daemon is running. The second line indicates that the fax-modem is initialized and ready.
Fax Server Clients
YajHFC – Yet another Java HylaFAX Client is a client for the HylaFAX fax server written completely in Java.(my suggestion)
Installation using APT
The recommended way to install YajHFC on Debian/Ubuntu is to use the YajHFC apt repository.
To use it, add the following line to your /etc/apt/sources.list and run apt-get update :
deb http://download.yajhfc.de/repository/apt/ stable/
The packages found there should work for both Debian and Ubuntu, so you can use the same apt line for both distributuions.
Usually you will receive a warning that my packages are not authenticated when you try to add my packages for the first time (since I am not a Debian or Ubuntu maintainer).
You can either ignore this warning *or* import my public key, so that apt considers my packages “trustworthy”.
To import the public key, execute the following command in a terminal (and re-run “apt-get update” afterwards):
wget -q http://download.yajhfc.de/JonasWolz.pub -O – | sudo apt-key add –
After successfully adding the repository, you will have the following additional packages available:
sudo apt-get install yajhfc
- Installs the main jar file, a launcher and adds a menu shortcut.
- sudo apt-get install yajhfc-console
- Installs a command line only version of YajHFC (cyajhfc).
- sudo apt-get install yajhfc-faxprinter
- Installs a fax printer in CUPS.
- sudo apt-get install yajhfc-fopplugin
- Installs the YajHFC FOPPlugin.
If you can not or do not want to use the apt repository, you can download the packages directly from the following directory:
The sources for the .deb packages are available in the following locations:
deb-src http://download.yajhfc.de/repository/apt/ stable/
There are numerous free and commercial HylaFAX clients available for Linux, Windows, and Macintosh systems. The commercially available clients tend to be more sophisticated including the ability to view incoming faxes, but at a price. However, you may need only one or two of these more sophisticated clients to manage received faxes and set up the majority of network users with a less-sophisticated free client.
- Faxing documents in PostScript, PDF, JPEG, PNG, TIFF, GIF and HTML format
- Polling faxes
- Support for generating cover pages from templates (in PostScript, HTML and (with a Plugin) XSL:FO or ODT format)
- Viewing sent and received faxes
- Phone book (entries can optionally be read from SQL databases or LDAP directories)
- Visible table columns may be selected in a dialog
- Runs under Windows, Linux and Mac OS X (and probably other platforms if a suitable JRE is available)
- Supports ten languages: Chinese, English, French, German, Greek, Italian, Polish, Russian, Spanish and Turkish
- A installed Java 5.0 (or higher) JRE (Java 6 or higher recommended)
- A running HylaFAX server in your network (should be obvious 😉 )
- A program to view faxes (optional, also see the FAQ)
- A PostScript viewer (optional, e.g. Ghostview)
- GhostScript (optional)
tiff2pdffrom the libtiff utilities package (optional)
For Windows I found WinPrint HylaFAX at winprinthylafax.sourceforge.net to be the easiest to set up and use (and ease of use is a consideration if you’re planning on implementing network faxing to a wide variety of users). It’s a send-only client that sets up a printer. You then simply modify to printer port properties to point to the IP address of your fax server.
The above Web page not only provides a download link for the software but has excellent instructions with screen shots on how to set up the WinPrint HylaFAX client.
Automatic Fax Printing
To automatically print incoming faxes to lpr, insert a line of code similar to
/usr/bin/tiff2ps -a $FILE | lpr
into your faxrcvd script, assuming that your printer is PostScript compatible.
sudo gedit /var/spool/hylafax/bin/faxrcvd
Dieter Kluenter has added at line 112 of faxrcvd these lines for his printing:
if [ -n "$SENDTO" ]; then echo "" echo "The facsimile was automatically dispatched to: $SENDTO." else $TIFFBIN/fax2ps $1 | lpr -Plp fi Michael firstname.lastname@example.org states:
Our printing environment is specific, a shared HP LJ1100 (A4 only). To be able to print out various types of paper sizes, we use the following code for printing (0.95 * A4 size): /usr/bin/tiff2ps -a -h 11.1082 -w 7.8543 $FILE | /usr/bin/lpr If we use fax2ps, it would be complicated to handle the printouts of different paper sizes.
Winprint HylaFAX is a Windows print monitor designed to send its output directly to a HylaFAX Server. Once installed, you can print to a HylaFAX Server from any application, and it will pop up a simple dialog box, allowing you to enter the destination FAX number. It’s not intended to be fancy or all encompassing, just a quick and easy way to send FAXes from any Windows application
It is packaged in the form of a Windows Installer, which installs the required sets of .DLL files and registers the monitor with the system. This adds support for a new type of port to your system, called a “WinPrint HylaFAX Port.” Once you’ve successfully installed the files, setup is straightforward, but it has a number of steps. First, you’ll want to create an appropriate PostScript printer using the “Add Printer” button. You want to select a “Local printer,” but since it’s not a physical printer, uncheck the “Automatically detect and install my Plug and Play printer” box.
Next, you’ll be asked what port to use. Select the radio button “create a new port type.” If the installation went well, you should see “Winprint Hylafax” as one of the options. The drop list might scroll, so it may not be obvious that it’s at the bottom of the list. (If it doesn’t appear on the list at all, something went wrong with your installation.)
Next, a box will pop up for you to name the port. The name doesn’t actually matter, but naming it HFAX1: will help to identify it.
Next, select the printer type. Experience has shown that the Apple LaserWriter 12/640 PS is a good choice, and I recommend it. Most any other PostScript printer will probably work.
Of course, name it whatever you want, preferably something that says, “hey, this is going to a FAX machine.”
Do not share the printer. This is rather silly anyway, since you can locally install Winprint HylaFAX on any system that needs it, and it communicates directly with the HylaFAX server. Since it pops up the dialog box asking where to send the FAX job locally, this would be ugly, at best. Also, don’t print a test page, since you’re not done configuring the printer yet.
Right-click on the printer to call up its properties, and select the “Ports” tab. Locate the port you just created.
Press the “Configure Port” button to configure the connection to your HylaFAX server.
You have to manually create the address book folder C:\program files\winprinthylafax and the files names.txt and numbers.txt inside.
Most people who have problems are going to have problems because their HylaFAX server won’t let them connect. Break out your HylaFAX server documentation, and make sure that you have set up the correct permissions, which can be as simple as putting the IP address of your client into /var/spool/fax/etc/hosts.hfaxd. You may not need the username -or- password, in which case, you can leave password blank, but the username is always required, even if it isn’t authenticated.
Okay, now you’re ready to print a test job. When you send anything to this printer, a dialog box will appear:
The FAX number is completely unedited and unverified. It relies on HylaFAX’s dialing rules to make sense of it. As you would expect, the HylaFAX server will send an e-mail confirming delivery (or failure to do so) to the specified e-mail address.
Sending received faxes as e-mail
The following steps illustrate how we can configure Hylafax to transmit incoming faxes to a pre-defined e-mail address.The recipient will receive the fax as an e-mail attachment.
To do this, the configuration file
/var/spool/hylafax/etc/FaxDispatch must contain the following parameters:
- The destination e-mail address for incoming faxes.
- The format of the attachment. In addition to
tiff(Tagged Image File Format) and
ps(Postscript™) are also acceptable options.
After the file has been saved, you must restart the fax server with /etc/init.d/hylafax restart.
We can test e-mail transmission by sending ourselves a fax with sendfax -n -d <faxnumber> <file.txt>
ubuntuserver:~# sendfax -n -d 6045557977
After a short time your target e-mail address should receive an e-mail in the following format:
recvq/fax000000016.tif (ftp://ubuntuserver:4559/recvq/fax000000016.tif): Sender: IAXmodem Pages: 4 Quality: Normal Size: North American Letter Received: 2007:06:02 02:49:45 Time To Receive: 1:58 Signal Rate: 9600 bit/s Data Format: 2-D MMR Error Correct: Yes CallID1: 2007 CallID2: IAXmodem 1 Received On: ttyIAX0 CommID: 000000033 (ftp://ubuntuserver:4559/log/c000000033) [...] The attachment will be a PDF file. In this example, the PDF is named
Now you can not only send and receive faxes, but received faxes are also received as e-mail attachments.
The HylaFAX Web site has extensive documentation on setting up a server, advanced configuration options, customization, available clients, and a FAQ. They also have several mailing lists that you can subscribe to as well as archives of mailing list messages. Their Web site is at:
Handbook:Advanced Server Configuration:Job Protection
Job protection has been enhanced in HylaFAX 6.0.0 and jobs can now be completely hidden from other users if wanted.
HylaFAX permission model
In the HylaFAX permission model, the file gid is used to represent the HylaFAX uid. The groub bits thus control the uid permissions while the other bits control the other permissions. Admins always have read+write access to any file.
Send Queue protection
By default, HylaFAX has always made the listings of the sendq/doneq include all jobs to any client connected to hfaxd. By setting PublicSendQ to false, hfaxd will also enforce it’s normal access restrictions on the listing of jobs in the sendq/doneq.
The file mode setting for new job qfiles in the HylaFAX queues (sendq and doneq) is controlled by the JobProtection config option. The default setting of 0644 allows all users to view all job parameters in the send/done queues. If PublicJobQ is set to false, then this file mode determines the permissions of the clients to see the jobs, following the HylaFAX permission model of the group bits controlling uid permissions and the other bits controlling other permissions. The job owner (a user connected with the same username as the owner value of a job) and admins always have read+write access to the job.
Receive Queue protection
By default, HylaFAX has always made the listings of the recvq include all faxes to any client connected to hfaxd. By setting PublicRecvQ to false, hfaxd will also enforce it’s normal access restrictions on the listing of faxes in the recvq.
The default file mode set on incoming fax by faxgetty is 0600. It can be changed with the RecvFileMode parameter in the modem config file. Complex access restrictions can be implemented using FaxDispatch.
Sample complex access restriction
In some setup, the recipient of a fax is known according to the incoming modem, DID or some other parameter available to FaxDispatch. In such cases, it is possible to have HylaFAX restrict the received faxes to the right users at reception.
HylaFAX users must have their uid set in hosts.hfaxd.
hfaxd.conf must contain the following line:
config.$DEVID must contain the following line:
FaxDispatch can now be used to give the received faxes to the right users. FaxDispatch settings are configured in
/etc/hylafax/FaxDispatch, if this file does not exist, create it and make it contain the following:
case $DEVICE in ttyS0) chgrp $UID_OF_DEPT1 $FILE ## Give it the right "fax uid" chmod g+r $FILE ## Give that uid read rights ttyS1) chgrp $UID_OF_DEPT3 $FILE ## Give it the right "fax uid" chmod g+r $FILE ## Give that uid read rights esac
For more FaxDispatch options, see http://www.hylafax.org/content/Advanced_Permissions_with_6.0
Many platforms will require the HylaFAX user (usually uucp) to be a member of the groups used as “fax uid” before the chgrp command will work. Remember to restart every faxgetty when you add uucp to a new group.
It is also possible to configure sudo to allow the uucp user to change a file to any group by adding the following lines to the sudoers file:
Defaults:uucp!requiretty uucp ALL=(root) NOPASSWD: /bin/chgrp
Note that this allows the uucp user to change the group of any file, even files owned by other users.
Documents Queue protection
Documents in the docq directory use the normal access restrictions of HylaFAX to define who can access which file.
This means that two users sharing the same uid may not see each other’s job (if the job file rights are set to 0600. but will be able to see the actual fax content of those jobs.
HylaFAX, an advanced open source fax server.