Asterisk IAXmodem


Main purpose: Connect Hylafax to IAXmodem.

IAXmodem is a software modem written in C that uses an IAX channel (commonly provided by an Asterisk PBX system) instead of a traditional phone line and uses a DSP library instead of DSP hardware chipsets.
IAXmodem interfaces an IAX library known as libiax2 with a DSP library known as spandsp, and then IAXmodem interfaces the DSP library with a tty device node for interfacing with modem applications.

The incoming call flow (for faxes) would be as follows:

PSTN => TDM Card => Asterisk => iaxmodem => Hylafax => Email user (or printer)

similarly, sending outgoing faxes can be as follows:

User => Analog Fax => SIP ATA => Asterisk => TDM Card => PSTN


User => Hylafax (through email2fax or virtual fax printer) => iaxmodem => asterisk => TDM Card => PSTN

Read the Hylafax docs to find out about sending faxes from hylafax. Example calling extension 123 using modem "ttyIAX":

sendfax -n -d 123 -h ttyIAX@localhost /tmp/fax.tif

Iaxmodem uses the spandsp library. So currently its modulation protocol support covers V.27ter, V.29 and V.17. V.34 (Super G3) support is not available, and won't become available in the near future for patent reasons. So, fax speeds from 2400 bps to 14400 bps are supported. Most new fax machines that you would purchase off-the shelf would support either 2400 bps to 14400 bps if the do not support Super G3/V.34, or 2400 bps to 33600 bps if they do. Quite a lot of thermal paper machines still only support 9600 bps. ECM (error correction) will be handled by HylaFax (even though newer versions of SpanDSP now also include ECM support).


Right now Asterisk does not have very good fax support. So for the most part you will not want to pass fax through an Asterisk PBX. (Like, have a separate phone line dedicated for fax.) That said, you can get reliable performance by simply using the Asterisk PBX as a T1 PRI "bridge"... meaning you bring your T1 into your multi-port T1 card on your Asterisk server, and then you send all fax calls back out through a different port which terminates on a T1 faxmodem in your HylaFAX server or on a T1 channel bank that is connected to analog faxmodems.

However, I can certainly understand that if you don't use fax very often, don't want to use an on-line fax service, don't want to pay for a dedicated fax line, and aren't using T1 lines that the options above aren't really options at all. So for that purpose (and *still* not wanting to use txfax/rxfax) I've created IAXmodem. Realize that the first release on this was just a week ago, and so I wouldn't say that IAXmodem is ready for heavy production use. However, if you're interested in testing, playing around, or maybe just deal with a random fax once in a while... well, then maybe IAXmodem will be good to you for now.

Required network quality

The audio path between the DSP and the PSTN really cannot be over any sort of a medium that will experience a frequent variance in the latency. So IAX is okay as long as the network will not "jitter". This is possible, and is especially possible when talking about a short, short IAX connection over the loopback device. If you involve any traditional "VoIP" medium (like an average LAN, WAN, or the internet), then the likelihood of the medium's variance in the latency will cause data corruption to occur... and depending on the frequency and timings of that data corruption will influence the likelihood of that data corruption causing a fax failure.

You can try running the IAXmodem IAX channel over your switched network, but my recommendation would be to always run IAXmodem on the Asterisk system (to prevent even minute audio corruption). In my experience passing modulated fax audio over a small LAN has not been that big of a problem. Everyone that plugs fax machines into SIP ATAs (and even IAXys, I've heard) are a testimony to that. However, in those situations I think that either they have a very well-tuned network, a very low-traffic network, or the ECM capabilities and protocol error recovery features of their fax machines are managing to work around any audio corruption that may occur. I wouldn't recommend passing modulated fax audio over a UDP/IP network for businesses where those faxes are critical.

Example usage

  • IAXmodem as HylaFax modem, both HylaFax and Asterisk on the same machine
  • IAXmodem in conjunction with termnetd+ttyd from the termpkg package (HylaFax and IAXmodem on distant machines)

You can enabled V.17 in spandsp which causes FaxGetty "MODEM Supports" messages you quote here. You can disable any particular speeds with the Class1RMQueryCmd and Class1TMQueryCmd options:

Class1RMQueryCmd: "!24,48,72,96"
Class1TMQueryCmd: "!24,48,72,96"

So the above will disable V.17 in sending and receiving.
My iaxmodem config file for HylaFAX suggests using this Class1RMQueryCmd option but not the Class1TMQueryCmd (so V.17 works in sending but not receiving).


Q0: How do I configure Hylafax for IAXmodem?
A0: Follow the IAXmodem README instructions; after (!) that a) start IAXmodem, and - only if you are on Gentoo Linux - b) run 'faxaddmodem' for the serial port 'ttyIAX' which will create FIFO.ttyIAX (alternatively do 'mkfifo /var/spool/fax/FIFO.ttyIAX); finally c) start 'faxgetty /dev/ttyIAX' and you should be ready to go.
Hint: Place iaxmodem and faxgetty into /etc/inittab and issue 'init q' to start them up.

  • there is a fork of HylaFax called HylaFax+ that is maintained by the author of IAXmodem (Lee Howard)
  • you will need libtiff-dev (in case of Debian) in order to be able to compile spandsp
  • depending on your distribution (Debian, Gentoo, ...) you will either find /var/spool/fax or /var/spool/hylafx on your system
  • after placing the iaxmodem config file into the hylafax .../etc directory you might still have to run "faxaddmodem"
  • in case of multiple iaxmodems create ttyIAX1, ttyIAX2 etc. named files for 1. FIFO, 2. Hylafax config file, 3. iaxmodem config file and 4. iax.conf users; try HylaFax+ in case 'faxaddmodem ttyIAX' of HylaFax (.org) effectively kills your running iaxmodem
  • for Debian the Hylafax init script also starts faxgetty; so here better include faxgetty in /etc/inittab; in this case make sure that hylafax starts after iaxmodem (otherwise the faxgetty for your iaxmodem(s) will not be brought up by the hylafax start script)
  • check the access rights (user:group) for the FIFO, usually this needs to be set to uucp:uucp
  • you will get weird distorted results should more than instance of the same iaxmodem be up und running, so better check with "ps axf". A recorded .raw file will look fine, however the actual audio will be much different; check with "iax2 show peers" for a iaxmodem that has registered on a random port, that'll be your culprit.

Output of 'ps axf' with two iaxmodem configured, hylafax and asterisk:

10634 ? S 0:00 /bin/sh /usr/sbin/safe_asterisk
31776 ? S 0:01 \_ asterisk -vvvg -c
3809 ? Ss 0:00 /usr/bin/iaxmodem
3810 ? S 0:00 \_ /usr/bin/iaxmodem
3811 ? S 0:00 \_ /usr/bin/iaxmodem
3870 ? Ss 0:00 /usr/sbin/faxq
3872 ? Ss 0:00 /usr/sbin/hfaxd -i 4559
3880 pts/4 S 0:00 /usr/sbin/faxgetty ttyIAX1
3881 pts/4 S 0:00 /usr/sbin/faxgetty ttyIAX2

Q5: What if I really want to use IAXmodem but my Asterisk server is connected to my HylaFAX server only by a latent (e.g. internet) connection?
A5: The connection between IAXmodem and Asterisk must be clean and clear. However, the connection between HylaFAX and IAXmodem need not be. For example, you could run IAXmodem on the Asterisk server communicating on the loopback adapter, and HylaFAX would communicate with IAXmodem remotely using a "remote tty" service such as termpkg's termnetd and ttyd programs. (A patch is included with IAXmodem source that will permit ttyd to be used for fax communications. You'll want to use a termnetd.conf entry like: "64570:on:/dev/ttyIAX0:B19200 CLOCAL CREAD IGNBRK;")

Q6: How do I set up my Asterisk dialplan for IAXmodem?
A6: This will vary depending upon what you want, but in many instances it will be something like this:

exten => fax,1,Dial(IAX2/ttyIAX/${EXTEN}) ; replace ${EXTEN} with a meaningful string or variable

If you do not put ${EXTEN} there then IAXmodem will not receive DID information. However, in this example "fax" is your fax extension number. If you use the Asterisk "fax" extension given by zaptel fax detection then ${EXTEN} will lose its meaning, and you'll need to use a workaround to get the correct called-number passed on to IAXmodem.

If you want to operate multiple IAXmodem instances (to handle more than one fax at a time) do something like this (where in case ttyIAX0, ttyIAX1 etc have been chosen as username in iax.conf, unlike as shown in the iaxmodem README where it'd be "iaxmodme" or "iaxmodem2"):

exten => fax,1,Dial(IAX2/ttyIAX0/${EXTEN})
exten => fax,2,Dial(IAX2/ttyIAX1/${EXTEN})
exten => fax,3,Dial(IAX2/ttyIAX2/${EXTEN})
exten => fax,4,Busy
exten => fax,5,Hangup

Each IAXmodem instance can only handle one call at a time. Thus it will report as busy if it is already handling a call, and Asterisk will then proceed to the next entry in the dialplan.


Hylafax with 200 IAXmodems

I run HylaFAX on a separate box from my dual PRI Asterisk box, and Asterisk relays the call to HylaFAX when it detects the fax. It relays the call on a private subnet with a crossover Ethernet cable with the slin codec. I have over 200 IAXmodems running on the HylaFAX box, which is an underclocked Athlon 64 running CentOS with a terabyte RAID5 array. HylaFAX automatically converts the fax to PDF and emails it to the enduser. Mail to fax works fine as well, except my Exchange server mungs the mimetype so it chokes on attachment conversion from Exchange, still trying to figure that one out. Fax volume is 100-500 faxes a day from a couple thousand potential senders, with a reject rate well under 1%. Load average on the HylaFAX box is usually like 0.01 or 2, with only 256 meg RAM consumed on the server for HylaFAX, sendmail, the usual suspects running. Overall, an outstanding solution that was done for a couple grand. Heap praises on Lee Howard and Steve Underwood for IAXModem and the SpanDSP libraries which made this possible.
One unusual thing I had to do was to get my reject rate below 1% I had to alter the Ethernet txqueuelen parameter to 2000 from the stock 1000.

From the field

About PLC (packet loss concelment) and alaw, ulaw or slin
You could be surprised. I know that I have been suprised by how easy it
is for a UDP packet to get dropped or lost. I've had a few customers
approach me that had both an Asterisk server and a HylaFAX server
running on separate networked systems and wanted to use iaxmodem
(running on the HylaFAX box, channels from the Asterisk box)... and in
tests after configuration it has never worked well enough for me to
sign-off on it, audio packets were getting dropped, and we've always
gone the route of using termnetd+ttyd to use the modems "remotely"... so
iaxmodem would run on the Asterisk server and HylaFAX would use a
ttyd-created remote modem device. (I haven't completely enjoyed this,
either, but it's more acceptable to me than the arrangement of dropping
UDP audio packets.)

In fact, the only environment where I have seen a suitable arrangement
where iaxmodem communicates with an Asterisk server that is not running
on the same host is at my own home-office... and the traffic on my home
network is certainly more than in some of my customers'... so I'm not so
sure that it always has to do with traffic volume... and I'm more
inclined to think that it either has to do with the hardware involved
(the ethernet switches, for example) or it has to do with other
specifics of the network configuration.

Losing an audio packet here or there wouldn't normally be so bad for
fax. Normally I would expect the fax protocol, especially ECM protocol,
to be able to recover from it. However, Asterisk seems to not work in
an ideal fashion for this purpose. Whenever Asterisk encounters a lost
audio packet something called "packet loss concealment" is performed by
placing a "PLC" frame there as a placeholder. When the audio is
retransmitted the PLC frame is supposed to be converted into synthesized
audio. Between what I have been told and from what I have observed,
this conversion of PLC frames into synthesized audio does not happen
with uLaw, alaw, or slinear codecs (the only codecs suitable for fax).
Consequently the PLC frame is converted into zero-data... or 20 ms of
silence... which is probably the worst-possible thing that could happen.

A 20 ms period of silence will make the modem detect "carrier loss". In
fax protocol carrier loss is used to synchronize the communications...
when carrier loss is detected the fax device knows that it's time to
move on to the next step in the protocol. So, depending at the timing
of the packet loss things can go awry enough to cause the fax session to
fail outright.

So... because a mere 20 ms gap in audio can cause so much trouble for
faxing, it's very important to make sure that the lossless communication
medium between Asterisk and the fax device is truly lossless.


See also

Go back to Asterisk fax

Created by: JustRumours, Last modification: Mon 29 of Mar, 2010 (17:49 UTC) by cbbs70a
Please update this page with new information, just login and click on the "Edit" or "Discussion" tab. Get a free login here: Register Thanks! - Find us on Google+