[UPDATED] Asterisk & FreePBX Faxing Solution with IAXModem + Hylafax + AvantFax

Updated: 04-11-2013 This guide attempts to walk you through installing a faxing solution on top of Asterisk that has FreePBX as it’s frontend GUI/dialplan generator. So for it to work, you need to be
1) Using Debian (this is a Debian guide btw). Tested working on Debian 5,6
2) Have a working Asterisk (tested on 1.6,1.8,10,11) either locally or remote. If locally, the IAXModem as shown below, points to itself i.e., if its somewhere, just change the IP
3) Running FreePBX 2.7 or higher (don’t need that if you do manual dialplans tho) The process is as follow:
1) Create an IAX extension on FreePBX
2) Install IAXModem – Configure at least one virtual serial port
3) Install Hylafax – “Bind” the modem you just created above into Hylafax
4) Install Avantfax, create users and bind users to each virtual modem
5) Use Avantfax to login and retrieve/send faxes FreePBX IAX extensions (the FAX number)
1) Create an IAX extension in FreePBX, insert the DID and CID so that calls can come into that extension
2) Click on the newly created IAX extension and modify the port (do not use port 4569, use anything else that does not conflict with your system’s UDP listening ports), example below is 4800 and the next IAX extension for fax can then use 4801, so on… This corresponds to the ttyIAX0 file setup below. 
3) Apply configuration
4) Go back to that IAX extension again you just created, and set requirecalltoken to no or auto (FreePBX 2.11).

Update apt and fix any broken apt installs
1) # apt-get update
2) # apt-get -f install

Install and configure IAXModem
Install and configure first IAXModem which will then map to the newly created extension above. If you use device/user mode you need to fix the user to an extension and use the user as the username and password in the IAXModem setup below.
1) # apt-get install gcc libtiff-tools libtiff4-dev
2) # apt-get install iaxmodem
3) # cd /etc/iaxmodem/
4) # Create our first modem config as below
5) # nano ttyIAX0 (see something like this below). Note, if you are running Asterisk on this same box, then use as your server IP
device          /dev/ttyIAX0
owner           uucp:uucp
mode            660
port            4800
refresh         3600
peername        5500
secret          myCOMPLEX123pass
codec           ulaw 6) Edit your inittab to add two lines for each ttyIAX modem you just created, example below
7) # nano /etc/inittab (NOTE: The last zeros are running numbers on IA00, m0, ttyIAX0)

# Load iaxmodem
IA00:23:respawn:/usr/bin/iaxmodem ttyIAX0
# Load hylafax modem listener agent
m0:2345:respawn:/usr/sbin/faxgetty ttyIAX0

7b) #telinit q
The above will initialize /dev/ttyIAX0 or others if you’ve configured them

8) Load your modems
9) #/etc/init.d/iaxmodem stop, then start
10) #ps -ef |grep iaxmodem (you should see your first modem there)
11) On your asterisk server (run on the same server if it runs asterisk as well)
12) # asterisk –rx “iax2 show peers” (you should see that your extension above is now registered, in this case 5500) should show you OK, it may take a while before registration spawns into action.

IAXModem is now done and is registered to Asterisk (ready to receive calls, you can try and you will hear the ringing but no picks up yet, this is hylafax’s job done below..)

Install and configure Hylafax
1) # apt-get install openssh-server hylafax-server
2) Time to configure hylafax
3) #faxsetup
When the faxsetup calls the faxaddmodem script, when it asks “Serial port that modem….enter the modem name above which like ttyIAX0), it will then ask you to enter you country code, area code and phone number, enter anything you wish there. For the rest of the questions, enter default values [press enter all the way till the end unless you know this stuff, i don’t, but you may want to set the “Local Identification String” to say your company name on headers..].  Finally it will probe our modem and if that worked it will say OK and tell you what class modem you’re running. If it prompts you to create another modem just terminate by pressing <CTRL+C>
3b) If you are merely adding new users/faxmodems just run # faxaddmodem instead of # faxsetup (which is done only once)
4) #telinit q (run #ps –ef |grep fax and you should see faxgetty there now)
5) For each modem you created in #faxaddmodem a file will be created in /etc/hylafax
6)  #nano /etc/hylafax/config.ttyIAX0, at the end of this file add the following

## Add for AvantFAX use each time you add new modems
FaxRcvdCmd:     bin/faxrcvd.php
DynamicConfig:  bin/dynconf.php
UseJobTSI:      true

8) #/etc/init.d/hylafax restart
Hylafax setup done, the modem should pickup and you hear the modem sound

Install and configure AvantFax
1) # apt-get install -y apache2-mpm-prefork apache2-utils apache2.2-common libapache2-mod-php5 libapr1 libaprutil1 libpq5 libsqlite3-0 php5-cli php5-common mysql-server imagemagick libtiff4-dev netpbm libnetpbm10-dev libungif-bin libungif4-dev sudo php-mail php-mail-mime php-file php-db php5-mysql sudo php-mail php-mail-mime php-file php-db php5-mysql

(NOTE: if you get a disclaimer file from mysql5.1 and you see the word “END” after scrolling down, do a “:q!” to quit that screen and continue)

Note: During the Avantfax install script for debian below, it may disable or remove other SMTP engine. This script WILL ATTEMPT TO REMOVE OTHER SMTP and INSTALL POSTFIX, continue first, we will show you how to fix that below…
2) #cd /usr/src
3) #wget http://downloads.sourceforge.net/project/avantfax/avantfax-3.3.3.tgz
4) #tar -zxvf avantfax-3.3.3.tgz
5) #cd avantfax-3.3.3
6) #mv /usr/src/avantfax-3.3.3/avantfax /var/www/
7) #chmod -R 777 /var/www/avantfax/tmp /var/www/avantfax/faxes
8) #cd /var/spool/hylafax/bin
9) #mv faxrcvd faxrcvd.old
10) #mv notify notify.old
11) #ln -s /var/www/avantfax/includes/faxrcvd.php /var/spool/hylafax/bin/faxrcvd
12) #ln -s /var/www/avantfax/includes/notify.php /var/spool/hylafax/bin/notify
13) #mv /usr/bin/faxcover /usr/bin/faxcover.old
14) #ln -s /var/www/avantfax/includes/faxcover.php /usr/bin/faxcover
15) #cd /usr/src/avantfax-3.3.3
16) #nano create_tables.sql
17) When editing this file, right on top of this file insert “USE avantfax;” without quotes
18) # nano debian-prefs.txt (IMPORTANT!: Ensure the settings here are correct, e.g. ROOTMYSQLPWD is the root MySQL user, supply its password, pay attention to the httpuser and httpgroup (you can do a ps –ef |grep apache and see what user apache2 is running)
19) Fix some apache logging requirements for Avantfax
20) #mkdir /etc/apache2/logs
21) #touch /etc/apache2/logs/avantfax-error_log
22) #/etc/init.d/apache2 restart

Start install script. This will be the install script for debian then…below. IMPORTANT: if you do not want to use postfix because you already have an email server, like exim, edit the debian-install.sh script and remove the existence of the word postfix normally found at the line that says apt-get install, then, start. Install will start downloading packages, configuring postfix (if enabled), getting some pear perl stuff. (YOU SHOULD NOT SEE ANY ERRORS!) .

23) #./debian-install.sh
24) When install completes, it may point you to /admin URL, ignore that, we go into /avantfax/admin instead. Do note, that htaccess may interfere with Avantfax, if you face issues being unable to login, remote .htaccess where the avantfax directory also got affected. Once done, you can now login to the WebUI at http(s)://<IPADDRESS>/avantfax/admin. You will be asked to change the password, please do that! Creating new users/faxes/devices etc…
Firstly, create a category, e.g. Engineering Team, using the pulldown menu.
For each modem you create (iaxmodem), create it also in AvantFax. Modems can be mapped to users, which is what we will do now. Under the pull-down menu, select modems. Create the modem when you configured iaxmodem above.
Now, you need to create a new user:
Under the pull-down menu, select new user: create a user and make sure you map him/her to a modem like below;
IMPORTANT! – When you create a new user, there’s a “bug” in hylafax that you also need to manually do it over the cli. So in this case, I’ve created user sanjay and must delete this user and recreate via cli like below; YOU MUST FOLLOW THE ORDER IN WHICH IS SHOWN AFTER CREATING A USER IN AVANTFAX UI ABOVE.
# faxdeluser sanjay
# faxadduser sanjay
It should not have any other objects/characters after the @ for the newly created regular users! as seen corrected above by the faxadduser command.. Make sure the name you created in Avantfax is similar and unique and match that name with the faxadduser command. Be sure to restart hylafax after doing that. #/etc/init.d/hylafax restart

Now, you should be able to send the fax in to this user/extension and log on to the WebUI or you can receive an fax-to-email email. Regular users can login to: http(s)://<IPADDRESS>/avantfax/ and start receiving and sending faxes. Here’s a test fax i just received without any modification to the graphics and what not:


To create more users/devices/faxes:
1) Create a FreePBX extension like shown above (make sure you use unique port numbers, like 4801….4802….4803…etc)
2) Create an IAX modem (you can copy the ttyIAX0 config file to another file, say #cp ttyIAX0 ttyIAX1, modify that 1 file to match the FreePBX extension info you just created on FreePBX), follow the rest of the steps there to restart and create the inittab entry, like below (for ttyIAX1) : NOTICE the underlined values go up as we add new modems.

# Load modem
IA00:23:respawn:/usr/bin/iaxmodem ttyIAX0
IA01:23:respawn:/usr/bin/iaxmodem ttyIAX1
# Faxgetty
m0:2345:respawn:/usr/sbin/faxgetty ttyIAX0
m1:2345:respawn:/usr/sbin/faxgetty ttyIAX1

3) # /etc/init.d/iaxmodem restart && tellinit q
4) Add hylafax, faxmodem, #faxaddmodem, choose ttyIAX1 now and so on..
5) # /etc/init.d/hylafax restart
6) Create modem in AvantFax called ttyIAX1, create user, say john and map to ttyIAX1
7) # faxdeluser john
8) # faxadduser john
9) # /etc/init.d/hylafax restart
10) That user can log in to http(s)://<IPADDRESS>/avantfax/

If you wish to get help with all of these and more customization, contact us at info[@@@]astiostech.com – use one @ of course

As usual, your feedback is much appreciated.


  1. i followed your setp, and i am using asterisk freepbx,
    but unfortunately FAX is not working,

    can you guide me plz

  2. sorry! really i did not provide any stuff for help!
    Actually i want to connect PSTN to My hylafax+asterisk+iaxmodem. and i dont know how it will works.

    guide me in this reqards, i am new in Voip, plz

  3. Sanjay,
    Can you get the hylafax+asterisk+iaxmodem setup to work with Google Voice as a trunk? I have my google voice working as a SIP trunk. I just wondering if i can use it for faxing (most T38) which is more reliable than analog faxing which is succeptable to channel jitter and other noise.

    By the way, I am using plain asterisk 1.8. Can you provide dial plan (extension.conf) and iax.conf and other files configuration setup?

  4. Hiya,

    I dont see a problem routing fax through Google Voice. I don't have GV here in Malaysia so can't really test that for you.

    As for dialplans, have you done one before? And also IAX2.conf?

    If not, i suggest using FreePBX, its simple and its GUI to help you create your dialplans.

  5. Nido, if you've not done that before, i suggest reading up on FreePBX and probably using it. Its the simplest way to get it started (if you're not already done so) It even has a DAHDI (for PSTN) module to configure those Digium cards (if you're using Digium cards)

  6. Thank You for a comprehensive write up. I have not been able to get the modem to pickup reliably. At times external calls will continue to ring, but internal calls will allow the modem to pickup.

    Other times both external and internal calls will ring continuously. While sometimes but rarely both internal and external will pickup. I have tried setting the number of rings to pickup to 2, with no change in behavior.

    Here's a log of a call that does not pickup http://volkswagner.com/gate/iaxDebug.txt

  7. hi, i can't really tell looking at the log. Is the modem initialized and listening? When you added a fax device #faxsetup or #faxadduser did it successfully connect to the modem and said something like [spandsp], yada yada?

    It could be that hylafax isn't working.

    What OS are u using/asterisk/etc..

  8. Hello my friend, i have a problem, apparently everything is fine, but when I restart my system the modem tone not working and fax fail. Thank you.

  9. i kniow this is an old thread but i did everything described installed avant fax etc however it wont load in the browser, i used your swasterisk version.

    i installed iaxmodem etc all fine and avantfax seems installed too but when i try to load it on the browser by going to http(s):///avantfax/admin. it wont do nothing empty page

    i tried removing .htaccess files etc but there arent any there

    let me know cheers

Comments are closed.