FreePBX, iaxmodem, HylaFAX & DDIs (DIDs)

In a move to eventually reduce the number of incoming telephony lines at our office, I have been exploring the various fax options that can be easily integrated with an Asterisk PBX. Without dissecting all the detail, the route we have decided to implement as a test combines Asterisk (with the FreePBX interface) and HylaFAX with iaxmodem as the magic glue.

We have lots of DDIs (otherwise known as DIDs) broken into a number of ranges that come in to the business either by ISDN30 (E1) or ISDN2 (BRI). The DDI ranges associated with our IDSN2 circuits are exclusively used for fax and are connected to our current Zetafax server. This is great but we also have legacy DDIs that are used for fax within the ranges associated with our ISDN30 circuit which is connected to our Asterisk PBX. This was fine when we had a analogue Zetafax server, but since it went to ISDN2 so we could have proper fax to desktop we have been handling the faxes coming into our ISDN30 by bouncing them straight back out on a second ISDN30 channel to a specified DDI on the ISDN2 circuit. The small cost of the local call between the ISDN30 and ISDN2 circuits isn’t so much of a problem as having to effectively provide three ISDN channels to receive one fax!

Long term if this all works out we will more than likely ditch the Zetafax server and use HylaFAX for all our faxing requirements, both inbound and outbound. But lets get onto the the real topic, how to glue these bits together.

If you are still reading then you must already know that iaxmodem is a software virtual modem that connects to a VOIP PBX (typically Asterisk) using the IAX2 protocol, so that needs no further qualification. You must also know that HylaFAX is UNIX fax server software. What you maybe scratching your head about is how to get the two to work together using DDIs. The assumes you have got iaxmodem and HylaFAX installed, and you have an Asterisk server using the FreePBX management interface. There are lots of HOW-TOs and other information detailing the configuration, but what they all consistently ommited or got plainly wrong is how to implement DDI routing of inbound faxes.

There are five main steps:

1. Configure your IAX2 extensions & virtual modems in FreePBX and /etc/iaxmodem/.
2. Create a custom dialplan context in /etc/asterisk/extensions_custom.conf.
3. Create a ‘Custom Destination’ in FreePBX.
4. Create ‘Inbound Routes’ for the DDIs you want to use for fax.
5. Edit /var/spool/hylafax/etc/FaxDispatch.

Step 1 is fairly straightforward. Here you only need to configure as many extensions as concurrent fax calls you want to handle, not an extension per DDI. I’ve seen references on the internet where people must have configured an extension (and iaxmodem) per DDI as they had quantities in the multi-hundreds! We went for 4 for testing purposes.

Step 2 is where things tend to unravel. Below is the normal recommendation of how to configure a custom context in /etc/asterisk/extensions_custom.conf:

[custom-fax-iaxmodem]
exten => s,1,Dial(IAX2/610/${EXTEN})
exten => s,n,Dial(IAX2/611/${EXTEN})
exten => s,n,Dial(IAX2/612/${EXTEN})
exten => s,n,Dial(IAX2/613/${EXTEN})
exten => s,n,Busy
exten => s,n,Hangup

Well it doesn’t work as the dialled digits that get passed with every fax are simply ‘s’. If you check the main Asterisk wiki you’ll see that the ‘s’ extension is normally used when the is no known called number, exactly the reverse of our situation where we want to specifically route on the called number.

What you need is this:

[custom-fax-iaxmodem]
exten => _X.,1,Dial(IAX2/610/${EXTEN})
exten => _X.,n,Dial(IAX2/611/${EXTEN})
exten => _X.,n,Dial(IAX2/612/${EXTEN})
exten => _X.,n,Dial(IAX2/613/${EXTEN})
exten => _X.,n,Busy
exten => _X.,n,Hangup

Here we accept any called number (we choose these with our inbound routes) and pass it one of our four iaxmodems. This passes the dialled digits correctly as we are not resetting the ${EXTEN} variable by using the ‘s’ extension.

Step 3 creates the custom destination to use in conjunction with inbound routes. Goto:

Tools –> Custom Destinations

The ‘Custom Destination’ statement should be:

custom-fax-iaxmodem,${EXTEN},1

With a description of something like ‘HylaFAX-IAXModem Pool’.

Step 4 is easy. Just create a new inbound route for each inbound DDI you want to use for fax and set the destination to be the custom destination you configured in step 3.

Finally Step 5 is edit/create /var/spool/hylafax/etc/FaxDispatch to configure the routing for your faxes by dialled DDI.

# Defaults
FROMADDR=hylafax@example.com;
FILETYPE=tif;

# DDI routing:
case "$CALLID4" in
788498) SENDTO=fred.smith@example.com;;
788497) SENDTO=harry.bloggs@example.com;;

# everything else goes to default case:
*) SENDTO=general-fax@example.com;;
esac

Done!