A FreeBSD Fax Server

   This how-to will step through installing and configuring HylaFax on FreeBSD.

What is HylaFax?

From the HylaFax web site...
"    HylaFAX is an enterprise-class system for sending and receiving facsimiles as well as for sending alpha-numeric pages.
    The software is designed around a client-server architecture. Fax modems may reside on a single machine on a network and clients can submit an outbound job from any other machine on the network. Client software is designed to be lightweight and easy to port.
    HylaFAX is designed to be very robust and reliable. The fax server is designed to guard against unexpected failures in the software, in the configuration, in the hardware and in general use. HylaFAX can support multiple modems and a heavy traffic load.
    If you expect to send more than a few facsimiles a day, then HylaFAX is the fax package for you! "

The Hardware

  This help file was done using FreeBSD 6.2 and HylaFax 4.3.4 from the ports collection. The server is a 2.4 Gig P4 with 1 Gig of ram and 320Gigs of disk space. The server is also running a web server, MySQL database, and is a Samba file server. The addition of HylaFax added very little load to the system and could be run on a lot smaller box.
    An external USR Sportster 28.8 fax modem was used to send and receive faxes.  This external modem is connected to com2 on the PC.  The use of an external modem is recomended.  If the modem need repair or replacement, then the whole box does not need to be taken down to fix it.

Installation

    Install HylaFax from the ports collection. Durring the install, the system will ask about where to install the various binaries. Go ahead and just select the defaults.

# cd /usr/ports/comms/hylafax
# make install
# make clean

    Once it is installed then run the faxsetup program. Most of the defaults are OK here and the only thing that will need changing is the area code.  When it gets to the end it will ask you if you would like to run the faxaddmodem program.  Select "No". We will run this after but we need to add the port on the command line.

# /usr/local/sbin/faxsetup

    Next configure up the fax modems.  The faxaddmodem script will setup each modem that is connected to the system.  Make sure that your modem is plugged in and turned on before you run this script as it will probe the modem at the end of the script ot determine best speed and capabilities. For the USR Sportster that I was using it determined that the modem was capable of both Class 1 and Class 2.0 fax.  I selected Class 1 as this allows Hylafax more control over the call. Since we only have one fax modem and it is connected to /dev/cuad1 (COM2 in the PC world) we use the following command.

# /usr/local/sbin/faxaddmodem cuad1
Enter the defaults for all the questions except for the following lines:
Area Code [415]? 780
Phone number of fax modem [+1.999.555.1212]? +1.780.555.1212
Local identification string (for TSI/CIG) ["NothingSetup"]? "ITS EPSB"
Command line arguments for getty program ["-h %l dx_%s"]? "std.%s -"

 


 

 

Setting up to Receive Calls

    HylaFax needs it's own getty program installed in order to answer  the telephone line and process a fax.  The HylaFax getty program is called faxgetty.  The following lines will have to be added into /etc/ttys (note: change cuad1 to cuad0 if you are using COM1):

# Setup for Hylafax
cuad1   "/usr/local/sbin/faxgetty"      dialup  on  secure

After installing the above line you can now 'kill -HUP 1' to get init to use the new changes. After HUPing init then you should be able to call into the phone number of the fax modem and it will pick up the line.  

Forwarding Faxes via Email

    By default HylaFax will send an email to the FaxMaster email account showing the a fax was received and it will also include a link that allows the user to FTP the fax off the server.  This is not very convienient or secure. A better way to set this up is to designate a fax manager that will receive all the faxes and then forward them to the correct person.  This person will then receive an email with the an attachment of the incoming fax (in TIFF, PS, or PDF format). For this example we will attach the faxes in PDF format as this seems to be the most common way for users to view them.

    First we will use the template capability in HylaFax to send our HTML format messages.  These are a lot easier to read for the average user and can easily be customized.

# cd /var/spool/hylafax/etc/templates
cp -Rp html-sample1 html

    Then we will tell HylaFax to use the new html templates and include the fax in the message as a PDF.  To do this we need to create a new file called /var/spool/hylafax/etc/FaxDispatch

# cd /var/spool/hylafax/etc
# vi FaxDispatch
FILETYPE=pdf;
SENDTO=faxmanager@bohica.net;
TEMPLATE=html

   HylaFax will not read this file when a fax comes in and send a copy of the fax (in PDF format) to $SENDTO

Printing Incoming Faxes

    HylaFax can also print faxes as they come in to any local or network printer.  This how-to will not go over setting up a printer on your FreeBSD system and assumes that printing is already setup and working. I have my system setup so that it will print out the fax on a network printer as well as email the fax to the fax manager. Here is how I did it.
    HylaFax processes all incoming faxes with a shell script called faxrcvd. This shell script is the one that processes and emails the incoming fax.  By adding the following line into the script (after line 206) it can also print out the faxes. NOTE: This does assume that the printer can print postscript files.

/usr/local/bin/fax2ps $FILE | /usr/bin/lpr -Pprinter