Multiple incoming faxes with HylaFAX and IAXModem

I have been using the this combo for about a year to receive and send all of our company faxes over a SIP provider. Keep in mind SIP is unreliable so you have to have a Tier 1 provider otherwise you will have very unreliable results. I'm posting this because most of the tutorials I have seen deal with very specific setups. For example detecting a fax on each of 23 PRI channels.

This is totally generic. It creates an iaxmodem hunt group and allows you to send faxes to it from any source, ZAP, SIP, extension transfer, etc. I would highly recommend HylaFax, because of its error correction, over the built in system fax. I just setup a new server using this method and it was far easier to install then the one I setup 1 year ago.

Sorry that the formatting is not great - feel free to put this into a nicer format or wiki.

Trixbox / IAXModems / Hylafax

Reference Websites
http://www.evaristesys.com/workshop/index.php/Inward_fax-to-email...

http://www.guardiani.us/index.php/TrixBox_IAXModem_HylaFax

Install Hylafax & iaxmodem (both in trixbox repository)
# yum install hylafax
# ln -s /usr/share/fonts/default/ghostscript/ /usr/share/ghostscript/fonts
# yum install iaxmodem
# faxsetup #(this configures hylafax. Except for area codes and fax numbers, just go with the defaults. The dialing rules are all handled by Trixbox.

NOTE: I use mcedit, which is part of Midnight Commander (mc). Use the editor of you choice (vi, nano, etc.)

Stop all services while configuring
# amportal stop
# service hylafax stop
# service iaxmodem stop

Configure iaxmodem
# cd /etc/iaxmodem
# mv iaxmodem-cfg.ttyIAX iaxmodem-cfg.ttyIAX0 (don't leave non-used config files - use 2 digit numbering if more than 10 modems will be setup)
# faxaddmodem (this setups a config file for hylafax to handle this modem. It will create a file /var/spool/hylafax/etc/config.ttyIAX0 to match the iaxmodem ttyIAX0)
# mcedit iaxmodem-cfg.ttyIAX0

Edit contents of iaxmodem config file (iaxmodem-cfg.ttyIAX0)
device

/dev/ttyIAX0
owner

uucp:uucp
mode

660
port

4570
refresh

300
server

127.0.0.1
peername

FaxDSP0
secret

2255
cidname

Fax Server
cidnumber
9497481112
codec

ulaw

Device must be unique. To keep it simple make thedevice end the same as the config file name.
Port must be unique for each iaxmodem. I started at 4570 and matched the last digit to the device name (i.e. 4570 for ttyIAX0)
Peername is the IAX peer that will be defined later in iax_custom.conf. Less confusing if you keep the numbers matching FaxDSP0 --> ttyIAX0
Codec - only allow ulaw

Duplicate the iaxmodem-cfg.ttyIAX0 for as many modems as you will need (i.e. simultaneous fax calls). Always make a few extra because the modems take a few seconds to reset after a call is ended.

# cp iaxmodem-cfg.ttyIAX0 iaxmodem-cfg.ttyIAX1 (repeat for 2, 3, 4, 5, etc.)
# mcedit iaxmodem-cfg.ttyIAX1 (change the device name = /dev/ttyIAX1, port=4571 and peername=FaxDSP1. Repeat this for each config modem config file.)

Configure Hylafax config files
# cd /var/spool/hylafax/etc
# touch xferfaxlog (setup log file)
# chown uucp:uucp xferfaxlog
# mcedit config.ttyIAX0

Most of this can be left as is. A few things to make sure
RingsBeforeAnswer: 1

If you are using a quality SIP provider you will get better results by slowing down the transmission
Class1RMQueryCmd: "!24,48,72,96" # enable this to disable V.17 for receiving
Class1TMQueryCmd: "!24,48,72,96" # enable this to disable V.17 sending

Duplicate Hylafax config file for each iaxmodem
# cp config.ttyIAX0 config.ttyIAX1 (repeat for 2, 3, 4, 5, etc.)

Setup faxgetty to answer the iaxmodems
# mcedit /etc/inittab

Add to the bottom of inittab
# Run faxgetty for hylafax / iaxmodems
f0:23:respawn:/usr/sbin/faxgetty /dev/ttyIAX0
f1:23:respawn:/usr/sbin/faxgetty /dev/ttyIAX1
f2:23:respawn:/usr/sbin/faxgetty /dev/ttyIAX2
f3:23:respawn:/usr/sbin/faxgetty /dev/ttyIAX3
f4:23:respawn:/usr/sbin/faxgetty /dev/ttyIAX4
f5:23:respawn:/usr/sbin/faxgetty /dev/ttyIAX5
f6:23:respawn:/usr/sbin/faxgetty /dev/ttyIAX6

Create 1 entry for each iaxmodem created. Beginning of line (i.e. f0, f1, etc.) must be unique.

Setup the IAX peer for Trixbox
I did this as a custom iax, but it can also be done through the FreePBX GUI as an IAX extension. The username in /etc/iaxmodem/iaxmodem-cfg.ttyIAX? must match the extension/iax peer setup.

# cd /etc/asterisk
# mcedit iax_custom.conf

[FaxDSP0]
username=FaxDSP0
dial=IAX2/FaxDSP0
secret=2255
disallow=all
type=friend
setvar=REALCALLERIDNUM=Fax
qualify=yes
port=4569
transfer=no
host=dynamic
context=from-internal
callerid=device
allow=ulaw

The name of the iax peer (i.e. [FaxDSP0]) must be unique and is the peername used in /etc/iaxmodem/iaxmodem-cfg.ttyIAX??. Repeat this for every iaxmodem configured.

Edit extensions_custom.conf to create iaxmodem hunt group and change handling of SYSTEM fax
# cd /etc/asterisk
# mcedit extensions_custom.conf

; ******* iaxmodem hunt group for use with inbound calls - passes DID to hylafax ******
; cw - create a custom destination so inbound calls can be routed to this hunt group (i.e. IAXModems External points to [iaxmodems-ext])
[iaxmodems-ext]
exten => s,1(bank),Dial(IAX2/FaxDSP0/${CALLERID(dnid)},1,r)
exten => s,2,Dial(IAX2/FaxDSP1/${CALLERID(dnid)},1,r)
exten => s,3,Dial(IAX2/FaxDSP2/${CALLERID(dnid)},1,r)
exten => s,4,Dial(IAX2/FaxDSP3/${CALLERID(dnid)},1,r)
exten => s,5,Dial(IAX2/FaxDSP4/${CALLERID(dnid)},1,r)
exten => s,6,Dial(IAX2/FaxDSP5/${CALLERID(dnid)},1,r)
exten => s,7,Dial(IAX2/FaxDSP6/${CALLERID(dnid)},1,r)
exten => s,8,Noop(WARNING: INCOMING FAX OVERFLOW - FAX BANK FULL - DIALSTATUS: ${DIALSTATUS})
exten => s,9,Busy(20)

; ******* iaxmodem hunt group for use with extension transfers - passes calling extension to hylafax ******
; cw - create a custom destination so inbound calls can be routed to this hunt group (i.e. IAXModems Internal points to [iaxmodems-int])
; cw - create a mis application so users can dial an extension number that uses this custom destination (i.e. 999 --> IAXModems Internal)
[iaxmodems-int]
exten => s,1(bank),Dial(IAX2/FaxDSP0/${CALLERID(number)},1,r)
exten => s,2,Dial(IAX2/FaxDSP1/${CALLERID(number)},1,r)
exten => s,3,Dial(IAX2/FaxDSP2/${CALLERID(number)},1,r)
exten => s,4,Dial(IAX2/FaxDSP3/${CALLERID(number)},1,r
exten => s,5,Dial(IAX2/FaxDSP4/${CALLERID(number)},1,r)
exten => s,6,Dial(IAX2/FaxDSP5/${CALLERID(number)},1,r)
exten => s,7,Dial(IAX2/FaxDSP6/${CALLERID(number)},1,r)
exten => s,8,Noop(WARNING: INCOMING FAX OVERFLOW - FAX BANK FULL - DIALSTATUS: ${DIALSTATUS})
exten => s,9,Busy(20)

; ******* will override [ext-fax] located in extensions.conf *******
; cw - just copy [ext-fax] from the end of extensions.conf and modify how SYSTEM is handled
[ext-fax]
exten => s,1,Answer
exten => s,2,Goto(in_fax,1)
exten => in_fax,1,StopPlayTones
exten => in_fax,2,GotoIf($["${FAX_RX}" = "system"]?3:analog_fax,1)
; ***** cw start change ****
;exten => in_fax,3,Macro(faxreceive) **** place ; to comment out this line -replace this line with the one below - direct system fax to iaxmodem pool
exten => in_fax,3,Goto(iaxmodems-ext,s,1) ; this send system fax to [iaxmodems-ext] rather than the trixbox system fax
; **** cw - end change ****
exten => in_fax,4,Hangup
exten => analog_fax,1,GotoIf($["${FAX_RX}" = "disabled"]?4:2) ;if fax is disabled, just hang up
exten => analog_fax,2,Set(DIAL=${DB(DEVICE/${FAX_RX}/dial)});
exten => analog_fax,3,Dial(${DIAL},20,d)
exten => analog_fax,4,Hangup
;exten => out_fax,1,wait(7)
exten => out_fax,1,txfax(${TXFAX_NAME},caller)
exten => out_fax,2,Hangup
exten => h,1,system(/var/lib/asterisk/bin/fax-process.pl --to ${EMAILADDR} --from ${FAX_RX_FROM} --dest "${FROM_DID}" --subject "Fax fro
exten => h,2,Hangup()

How this works: [iaxmodems-ext] is called and dials the 1st modem. If it is busy it tries the next and so on. As soon soon as an iaxmodem answers it passess the DID number called. [iaxmodems-int] is identical, but passes the extension of the person who transferred the fax. This is useful because fax detect is not 100% and sometimes a user will answer the phone and hear a fax signal. They can then transfer to extension 999 and the fax will be routed back to them.

[ext-fax] overrides what is in extension.conf and sends the detected fax to [iaxmodems-ext] instead of the built in system fax. Hylafax is far superior with error correction. I have been successfully using Hylafax for over 1 year using only SIP providers (bandwidth.com).

Start all services again and set to run at startup
# amportal start
# service iaxmodem start
# service hylafax start
# init q
# chkconfig --add hylafax
# chkconfig --add iaxmodem

Now use the Trixbox GUI to allow access to setup custom destinations to the dial plan just defined
PBX Setting --> Tools --> Custom Destinations
Custom Destination = iaxmodems-ext,s,1 (this is saying goto the dial plan created above)
Description = IAXModems External
Notes = Use for inbound DID calls

Custom Destination = iaxmodems-int,s,1
Description = IAXModems Internal
Notes = Use for extension transfers to fax

This custom destination can now be used in the Set Destination area of Inbound Routes, or any other setting that allows it.

Create a Misc Application for users to dial if they need to transfer a fax
PBX Settings --> Misc Applications
Description: Hylafax Extension
Feature Code: 999
Custom Destination: IAXModems Internal

How to setup inbound routes
If your inbound route is a dedicated fax
PBX Settings --> Inbound Routes
Set Destination: Custom Destination --> Hylafax Modem Pool

If you inbound route will have fax detect
PBX Settings --> Inbound Routes
Fax Extension: system or FREE PBX Default (if set to system on general settings page)
Fax Email: not used - will route through hylafax
Fax Detection Type: Select the fax detect that is right for your config (I use NVFax for SIP trunks)
Pause After Answer: 4 (adjust this as needed to make sure faxes are detected)

This is the standard Trixbox / FreePBX setup. The difference is now system is redirected to the iaxmodem hunt group and Hylafax.

Setup how Hylafax will deliver received faxes
# cd /var/spool/hylafax/etc
# mcedit FaxDispatch

## the numbers before the ) correspond to DID number whether fax detect or directly routed to [hylafax-pool]
case "$CALLID4" in
# toll free numbers
*8005551212)
SENDTO=your@email.com; FILETYPE=tif;; # Comment here
*8885551212)
SENDTO=my@email.com; FILETYPE=tif;; # Comment here
100)
SENDTO=from-extension@email.com; FILETYPE=pdf;; # this routes back to the user that transferred fax to ext 999
*)
SENDTO=catch-all@email.com; filetype=tif;; # catch all email

esac

You can really get fancy here, but it is beyond my scope.

After hours of troubleshooting and debugging (not because of the implementation, but because of the SIP provider) I was able to get this working. Works like a charm on a POTS line. For anyone else who stumbles upon this, a Teliax SIP or IAX account with a 10mbps/2mbps cable modem will not work. Lots of 'no carrier' messages which leads me to belive the resends accumulate and the default fax values (95% good, 5% bad) kick in and make the transmission fail.

My test lab looks like this:

Trixbox 2.6 -> Postfix -> Exchange (for inbound mail relay)
WinprintHylaFax (for outbound faxing) simple print driver

Im sure this could be used without Exchange, but the mail server currently hosts our domain email. Adding a user account on the mail server for smtp auth, and the lines into the postfix config make this a snap (if a mail server exists within the company already).

Curious to see who else has followed the above and whether or not they are using SIP for dialtone ? If so, which provider? Sorry, not trying to hijack the thread, seems to be a valid question.

I've spoken to bandwidth.com in the past, but haven't purchased service from them yet. The next test for me will be a 3mb pipe with a SIP->PRI Cisco IAD. Current faxing works on it, so it should be a snap.

that's funny that teliax posts on here, i had no idea. :)

welcome to my test bed.
im using the nyc proxy, codec is set to 711. i havent tried the other proxies, assuming the results would not improve with added latency.. will try later though, now that you mention it. i've also tried slinear with the same results.

to send faxes, i'm using a standard fax machine on a POTS line, and my fax client at work which uses 711/SIP.

i understand how faxing works especially relating to the internet, so no i havent called support. while testing, i've been isolating all internet traffic and only allowing the voice. we're testing the capabilities before offering services, so this isn't exactly a pressing issue to make this work on our teliax account. i'm going to setup another SIP account and compare the results.

Bandwidth unfortunately is a real commitment, they want a 1 year contract so it is hard to test. I've recently started testing with Flowroute.com, which so far seems good. The only thing I noticed is that NVFax detect doesn't seem to work on flowroute.com, while it works about 90% of the time on Bandwidth.com.

I think the problem with Trixbox pro is that it has an older linux kernel and so the repository it will pull from is different than if you are running Trixbox CE 2.6 or higher. You you have to manually download and install the RPM files.

I'm not sure if it has anything to do with the IAXModems not answering the call, but I noticed the following line in your output;

[Apr 16 12:28:40] NOTICE[6780] channel.c: Dropping incompatible voice frame on SIP/uuXXXXXXXX-XXXXXXXX of format slin since our native format has changed to 0x4 (ulaw)

Might want to double check under iax_custom.conf to insure you have
disallow=all
allow=ulaw

Also check what format the call is coming in via SIP