Hylafax How TO

Here's the start of it... I just haven't had time to make a step by step, but I will do that later on. But this will definitely help you!

Setup Build Dirs

cd /usr/src/
wget http://ksp.ca/asterisktools/hylafax-4.3.3-1rhel4.i386.rpm

yum -y install ghostscript
yum -y install sharutils
yum -y install mgetty-voice
ln -s /usr/share/fonts/default/ghostscript/ /usr/share/ghostscript/fonts
yum -y install iaxmodem

HylaFax Install

rpm -ivh hylafax-4.3.3-1rhel4.i386.rpm

Configure Hylafax
I answered yes or the default to everything except AreaCode and: Do you want to run faxaddmodem to configure a modem [yes]? no

/usr/sbin/faxsetup

Configure Asterisk (FreePBX)

Edit iax.conf (through FreePBX)
Log into the FreePBX control panel with your browser and Click:

Setup -> Extensions -> IAX2
And enter the following:

Extension Number: 1100
Display Name: IAXModem
Record Incoming: Never
Record Outgoing: Never
Secret: password
Perform this step once for each channel on which you wish to receive faxes. Changing the extension number each time. The example above uses a single channel and a single extension: 1100
Don't Forget Click Submit and then the red bar at the top!

Edit extensions.conf (through FreePBX)
Now configure asterisk to use this extension for faxes:

Setup -> General Settings -> Fax Machine -> Extension of fax machine
Select 'system' to have the system receive and email faxes.
Selecting 'disabled' will result in incoming calls being answered more
quickly. for receiving faxes: IAXModem <1100>
Don't Forget Click Submit Changes and then the red bar at the top!

Edit extensions.conf (through SSH)
I also had to append this line to the from-zaptel context. Apparently it doesn't ship with a fax extension. The from-pstn context does ship with a fax extension, but my config uses from-zaptel by default. Go figure.

exten => fax,1,Goto(ext-fax,in_fax,1)

Configure IAXModem

Edit Config Files
Change the 'peername' value from 'iaxmodem' to '1100' (this is the extension we created in the last step):
cd /etc/iaxmodem
cp iaxmodem-cfg.ttyIAX iaxmodem-cfg.ttyIAX0
cp iaxmodem-cfg.ttyIAX iaxmodem-cfg.ttyIAX1
cp iaxmodem-cfg.ttyIAX iaxmodem-cfg.ttyIAX2
cp iaxmodem-cfg.ttyIAX iaxmodem-cfg.ttyIAX3

nano /etc/iaxmodem/iaxmodem-cfg.ttyIAX0
nano /etc/iaxmodem/iaxmodem-cfg.ttyIAX1
nano /etc/iaxmodem/iaxmodem-cfg.ttyIAX2
nano /etc/iaxmodem/iaxmodem-cfg.ttyIAX2
You need a config file for each Zaptel channel on which you wish to receive faxes. The iaxmodem RPM sets up only one config file by default.

Setup Logs
make sure it can log properly:

mkdir /var/log/iaxmodem
touch /var/log/iaxmodem/iaxmodem-cfg.ttyIAX0
touch /var/log/iaxmodem/iaxmodem-cfg.ttyIAX1
touch /var/log/iaxmodem/iaxmodem-cfg.ttyIAX2
touch /var/log/iaxmodem/iaxmodem-cfg.ttyIAX3

Add faxgetty to /etc/inittab
These correspond to the device lines in the /etc/iaxmodem/* config files. (see previous step, above) I only have an X100p single line card, so I'm just adding one line:
nano /etc/inittab

You need one of these for each channel, so a T1/PRI would require 23 lines. The last argument to faxgetty ('ttyIAX' in this case) is the device name (i.e. /dev/ttyIAX) on which to connect to iaxmodem.

Configure HylaFax
There are a number of important files used by Hylafax. Most of them live in the /var/spool/hylafax/etc directory.

cd /var/spool/hylafax/etc
Create the necessary files and permissions for incoming fax reporting:

touch xferfaxlog
chown uucp:uucp xferfaxlog

FaxDispatch
One of the most important files is the FaxDispatch script.

Simple single E-Mail FaxDispatch example
Here is a simple example that routes faxes to my email address:

vim FaxDispatch

# ---------------- Start FaxDispatch Example 1 --------------------
FILETYPE=pdf;
SENDTO=jesse@guardiani.us;
# ---------------- Stop FaxDispatch Example 1 ---------------------

Inbound DID routing FaxDispatch example
More complex examples, such as inbound DID routing to separate email addresses, you can use something like the following:

# ---------------- Start FaxDispatch Example 2 --------------------
#!/bin/sh
##
## FaxDispatch
## (see `man faxrcvd` for more info)
FILETYPE=pdf;
SENDTO=fax@guardiani.us; # default

# The numbers before the paren correspond to asterisk extensions in
# extensions.conf
case "$CALLID4" in
# customer DID routing:
99995953033) SENDTO=someoneelse@guardiani.us; FILETYPE=pdf;;
99995953133) SENDTO=jesse@guardiani.us; FILETYPE=pdf;;

# everything else goes to default case:
*) SENDTO=fax@guardiani.us; FILETYPE=pdf;;
esac
# ---------------- Stop FaxDispatch Example 2 ---------------------
In order for the above complex DID routing example to work, the inbound DID has to be passed to IAXModem and show up in the CALLID4 variable. To facilitate this, try replacing the following line in extensions.conf:

exten => analog_fax,3,Dial(${DIAL},20,d)
with this:

exten => analog_fax,3,Dial(${DIAL}/${CALLERID(number)},20,d)
In the above example, an inbound DID of 99995953133 should result in an email to jesse@guardiani.us, whereas an inbound DID of 99995953033 should result in an email to someoneelse@guardiani.us, and everything else results in an email to fax@guardiani.us.
NOTE: The inbound DID example is largely untested on trixbox. I have it working on a T1 PRI with normal asterisk + iaxmodem (no trixbox - different OS), but this example has been regurgitated purely from memory and is untested. Feel free to contact me (mailto://jesse@guardiani.us) if you have any problems and I'll try to help you solve them.
cd /var/spool/hylafax/etc
nano config.ttyIAX

cp config.ttyIAX config.ttyIAX0
cp config.ttyIAX config.ttyIAX1
cp config.ttyIAX config.ttyIAX2
cp config.ttyIAX config.ttyIAX3

Another important file is the config.ttyIAX file. This file tells the faxgetty daemon(s) how to communicate with the iaxmodem /dev/ttyIAX* files.

chown uucp:uucp config.ttyIAX0
chown uucp:uucp config.ttyIAX1
chown uucp:uucp config.ttyIAX2
chown uucp:uucp config.ttyIAX3

You'll need one config.ttyIAX* file for each faxgetty instance.

Finish Up

Start Up IAXModem

/etc/init.d/iaxmodem start
See if it's running:

ps auxwww | grep iax
if not, check the log:

tail -f /var/log/iaxmodem/iaxmodem
tail -f /var/log/iaxmodem/iaxmodem-cfg.ttyIAX3

Start Up Faxgetty
Tell init to reload it's config (this starts faxgetty):

telinit q
Make sure faxgetty is running:

ps auxwww | grep faxget
Make sure it's communicating with iaxmodem properly (i.e. no errors):

tail -f /var/log/messages

Verify E-Mail Traffic
You can also check the sendmail log to verify that emails are being sent as expected:

tail -f /var/log/maillog
Here is an example of a successful fax email log:

Oct 18 17:15:34 asterisk1 sendmail[17145]: k9ILFYxx017145: from=, size=67575, class=0, nrcpts=1, msgid=<200610182115.k9ILFXIg017123@asterisk1.local>, proto=ESMTP, daemon=MTA, relay=localhost [127.0.0.1]
Oct 18 17:15:34 asterisk1 sendmail[17123]: k9ILFXIg017123: to=jesse@guardiani.us, delay=00:00:01, xdelay=00:00:00, mailer=relay, pri=97313, relay=[127.0.0.1] [127.0.0.1], dsn=2.0.0, stat=Sent (k9ILFYxx017145 Message accepted for delivery)
Oct 18 17:15:34 asterisk1 sendmail[17147]: STARTTLS=client, relay=mail.guardiani.us., version=TLSv1/SSLv3, verify=FAIL, cipher=DHE-RSA-AES256-SHA, bits=256/256
Oct 18 17:15:35 asterisk1 sendmail[17147]: k9ILFYxx017145: to=, delay=00:00:01, xdelay=00:00:01, mailer=esmtp, pri=187575, relay=mail.guardiani.us. [192.168.88.97], dsn=2.0.0, stat=Sent (ok 1161206135 qp 10280)

Reporting
Now test some fax calls and you're done! You can use the following command to view a report of the faxes you receive:

recvstats