TrixBox IAXModem HylaFax

This howto is for Trixbox 1.1.1 (which is based on CentOS 4.4) It should work through at least Trixbox 2.6.1.13. Please let me know if it doesn't. Also, please note that this Howto assumes that your connection to the PSTN network is clean, free of static, free of echo, and sounds good when using a phone. If it's not, don't be surprised if faxing doesn't work. For analog lines and Zaptel hardware, there are things you can change that might help (i.e. RX/TX gain), but tuning an analog card is completely outside the scope of this howto.

Contents
[hide]

1 Getting Started o 1.1 Got Root? o 1.2 Setup Build Dirs o 1.3 Download Software o 1.4 Download Third Party RPM (if you dare) o 1.5 Satisfy HylaFax Deps o 1.6 Satisfy Unspoken HylaFax Deps o 1.7 HylaFax Install o 1.8 Configure Hylafax o 1.9 IAXModem Install 2 Configure Asterisk (FreePBX) o 2.1 Edit iax.conf (through FreePBX) o 2.2 Edit extensions.conf (through FreePBX) o 2.3 Edit extensions.conf (through SSH) 3 Configure IAXModem o 3.1 Edit Config Files o 3.2 Setup Logs o 3.3 Add faxgetty to /etc/inittab 4 Configure HylaFax o 4.1 FaxDispatch 4.1.1 Simple single E-Mail FaxDispatch example 4.1.2 Inbound DID routing FaxDispatch example o 4.2 config.ttyIAX 5 Finish Up o 5.1 Start Up IAXModem o 5.2 Start Up Hylafax o 5.3 Add Automatic Log Rotation for IAXModem logs

o o o

5.4 Start Up Faxgetty 5.5 Verify E-Mail Traffic 5.6 Reporting

Getting Started
Got Root?
su -

Setup Build Dirs

cd /usr/local/src/ mkdir iaxmodem cd iaxmodem

Download Software
For latest HylaFax builds see here: ftp://ftp.hylafax.org/binary/linux/redhat/RPMS/i386/
wget 'ftp://ftp.hylafax.org/binary/linux/redhat/RPMS/i386/hylafax-4.3.02rhel4.i386.rpm'

Download Third Party RPM (if you dare)

For latest iaxmodem build see here: http://www.taylortelephone.com/asterisk/
wget http://yum.trixbox.org/centos/4/RPMS/iaxmodem-0.1.14-1.i386.rpm

Satisfy HylaFax Deps

yum install ghostscript sharutils mgetty-voice

Satisfy Unspoken HylaFax Deps

faxsetup will complain if you don't do this
ln -s /usr/share/fonts/default/ghostscript/ /usr/share/ghostscript/fonts

HylaFax Install
rpm -Uvh hylafax-4.3.0-2rhel4.i386.rpm

or the version you downloaded.

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

Add Hylafax to system startup sequence:

chkconfig --add hylafax

IAXModem Install
rpm -Uvh iaxmodem-0.1.14-1.i386.rpm

or the version you downloaded. Add iaxmodem to system startup sequence:

chkconfig --add iaxmodem

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)

Note: This is not required for TrixBox 2.x. I also had to append this line to the from-zaptel context in /etc/asterisk/extensions.conf. 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), also change the secret to reflect FreePBX extension secret:
vi /etc/iaxmodem/iaxmodem-cfg.ttyIAX

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.ttyIAX

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:
t2:23:respawn:/usr/sbin/faxgetty ttyIAX

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 if you have any problems and I'll try to help you solve them.

config.ttyIAX
Another important file is the config.ttyIAX file. This file tells the faxgetty daemon(s) how to communicate with the iaxmodem /dev/ttyIAX* files. Here is an example:
# ---------------- Start config.ttyIAX Example -------------------CountryCode: 1 AreaCode: 423 FAXNumber: 1.111.111.1111 # replace this with a real phone number LongDistancePrefix: 1 InternationalPrefix: 011 DialStringRules: etc/dialrules ServerTracing: 0xFFF SessionTracing: 0xFFF RecvFileMode: 0600 LogFileMode: 0600 DeviceMode: 0600 RingsBeforeAnswer: 1 SpeakerVolume: off GettyArgs: "-h %l dx_%s" LocalIdentifier: "IAXmodem" TagLineFont: etc/lutRS18.pcf TagLineFormat: "From %%l|%c|Page %%P of %%T" MaxRecvPages: 600 # # # Modem-related stuff: should reflect modem command interface

# and hardware connection/cabling (e.g. flow control). # ModemType: Class1 # use this to supply a hint # # The modem is taken off-hook during initialization, and then # placed back on-hook when done to prevent glare. # ModemResetCmds: "ATH1\nAT+VCID=1" # enables CallID display ModemReadyCmds: ATH0 Class1AdaptRecvCmd: Class1TMConnectDelay: Class1RMQueryCmd: well AT+FAR=1 400 # counteract quick CONNECT response "!24,48,72,96" # V.17 fast-train recv doesn't work

CallIDPattern: "NMBR=" CallIDPattern: "NAME=" CallIDPattern: "ANID=" CallIDPattern: "NDID=" # Uncomment these if you really want them, but you probably don't. #CallIDPattern: "DATE=" #CallIDPattern: "TIME=" #20060302 JDG - Fix for broken libtiff JBIG support in tiff2pdf Class1JBIGSupport: no # ---------------- Stop config.ttyIAX Example ---------------------

Make sure the permissions are correct:

chown uucp:uucp config.ttyIAX

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

Finish Up
Start Up IAXModem
service iaxmodem start

See if it's running:

service iaxmodem status

Start Up Hylafax
service hylafax start

See if modems are up and recognized (give a few secs for init)
faxstat -s

Add Automatic Log Rotation for IAXModem logs

Note: We had issues of modem initialization if log files are larger than 2Gb, this step is strongly recommended. The following will rotate the iaxmodem log files if they are larger than 500Mb, keeping the last 2 versions. add to /etc/logrotate.d/asterisk:
/var/log/iaxmodem/*log { missingok rotate 2 size 500M postrotate /sbin/service iaxmodem restart > /dev/null 2>&1 || true endscript }

Check the logs to verify proper operation and registration of iaxmodem to asterisk (verify that there are no registration errors in the log):
tail -f /var/log/iaxmodem/iaxmodem-cfg.ttyIAX tail -f /var/log/iaxmodem/iaxmodem

Also verify from asterisk (Status column should indicate "OK"):

asterisk -vvvvvvvvvvr iax2 show peers

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=<fax@asterisk1.local>, 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=DHERSA-AES256-SHA, bits=256/256 Oct 18 17:15:35 asterisk1 sendmail[17147]: k9ILFYxx017145: to=<jesse@guardiani.us>, 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