UPDATE: Changes to mutex usage in Asterisk 1.4.23 cause NVFax to cease to compile properly, see below for updated files that compile with 18.104.22.168
We have bridged our HylaFax server with our Asterisk server in order to be able to send and receive faxes over VOIP phone lines and to eliminate dedicated PSTN phone lines hooked up directly to modems on our HylaFax server. A lot of documentation floating around on the internet states that VOIP phone lines are not really suited to send/receive faxes. We have found out that it mostly depend on the providers you are using and on your network connectivity quality.
Note: To be able to send/receive faxes over IP, your provider has to support the ulaw codec (alaw in Europe and other areas). gsm, g729 and other compression codecs won't work.
We obtain virtually 100% successful completion for fax transmissions (20 pages per transmission in our tests) with one specific provider while it doesn't work at all with other providers.
Note although that the setup described is this article is also convenient if your faxes come in through PSTN lines (conventional copper wire lines) hooked up to your asterisk server. We used to have dedicated PSTN lines hooked up directly to physical hardware modems on our HylaFax server. We moved those lines to Asterisk and it forwards the call to virtual modems (iaxmodems) running on the HylaFax server residing on the same LAN. Note that there is zero degradation in fax transmission over an iax2 channel on the LAN (Local Area Network).
Iaxmodem documentation states that it should only be used to connect to an Asterisk server over a LAN connection, there is no degradation in fax transmission over an iax2 channel on a LAN. So if you receive fax phone calls over VOIP from the internet, Asterisk will be in charge of dealing with your VOIP provider to insure that the fax is transmitted correctly. If your asterisk server receives fax phone calls over traditional PSTN copper wire lines, you will experience zero fax transmission problems with the setup defined in this article.
Iaxmodem is viewed as an IAX2 extension from Asterisk. It allows you to use any other software at your convenience beside HylaFax to handle the faxes. From linux or hylafax, the virtual iaxmodem is just viewed as a standard hardware fax-modem that could be connected to your system.
What is needed:
At minimum, if you have a dedicated number for your fax machine and you don't need to detect incoming fax tones from a human person you will need:
If you need to detect incoming fax tones in order to be able to share your fax lines with human voice, you will need to recompile asterisk with NVFaxdetect support, simply compile Asterisk after adding the following files into the apps folder in the asterisk sources. The Makefile is just the genuine Makefile with the NVfax apps added into it like this:
UPDATE: For Asterisk 22.214.171.124 and probably for future Asterisk releases, use the following NVFax files instead:
Note: If you downloaded and installed Asterisk from a pre-compiled distribution repository (yum install, trixbox, etc.), you may already have NVFax support built-in to your Asterisk server. Just type the following command to find out, if the modules are there, you already have support for NVFax and you can skip this step.
$ ls /usr/lib/asterisk/modules/app_nv_*
Note2: If your fax calls come in exclusively through PSTN lines, you do not need NVFax, just use Zaptel for fax detection. Zaptel fax detection is bundled with every asterisk distribution as far as we can tell. We do not really know because our PSTN lines are hooked to a GXW4104 IP Analog Gateway that forwards PSTN fax calls to our Asterisk server through VOIP. We do not use Zaptel, except ztdummy with high resolution timer kernel support for timing.
You will also need a software to handle faxes coming into or going out from your iaxmodem, we use HylaFax:
Download, compile and install iaxmodem. We built iaxmodem statically ( issuing the command "./build static" to build) and we have just copied the generated executable (iaxmodem) to /usr/local/bin
Install the configuration file for your modem in /etc/iaxmodem (mkdir /etc/iaxmodem), we configured 2 faxes to be mapped to 2 extensions defined in asterisk configuration; extension 125 and extension 126:
extension 125 file in /etc/iaxmodem/tty125 :
cidname Technologies OC9-ACTS
extension 126 file in /etc/iaxmodem/tty126 :
cidname Technologies OC9-ACTS
We arranged so that iaxmodem starts automatically by adding the following to our rc.local file :
Note: Do not put any other file in /etc/iaxmodem if you use the above command. We left a text file that didn't look at all like an iaxmodem config file but still, iaxmodem read that file and locked up the default iax2 port (4569) on the machine! ;-)
With no option given, iaxmodem just automatically reads all files in /etc/iaxmodem and configures all virtual modems accordingly. We defined extension 125 and 126 with the same passwords in asterisk.On startup iaxmodem registers extension 125 and 126 with the asterisk server. We can see this by running the following command:
asterisk -r -x "iax2 show peers"
126 192.168.11.138 (D) 255.255.255.255 4571 OK (2 ms)
125 192.168.11.138 (D) 255.255.255.255 4570 OK (2 ms)
At this point asterisk is ready to forward calls to the 2 iaxmodems. We have a dedicated fax number, we just mapped that number to extension 125 in FreePBX incoming routes and asterisk forwards all calls to that number to the iaxmodem virtual fax.
Setting up fax tone detection
This step is only required if you want to share your fax lines with human voice. Basically, NVFaxdetect will listen for fax tones when a call comes into asterisk. If it hears fax tones, it will forward the call to extension 126 otherwise, the call is just normally forwarded to our IVR (automated digital receptionist).
To enable Asterisk to use NVFax to detect incoming faxes, we simply need to recompile it after adding the files listed above in the "What is needed" section.
We can now enable fax detection in FreePBX incoming route, specifying to forward the call to extension 126 if fax tones are detected. 5 seconds is the recommanded time to listen for fax tones before passing the call to the IVR or to a human. A human caller will simply hears an additional ring tone during that 5 seconds.
Note that you can use any software to pickup and send faxes from/to the iaxmodems, we just use Hylafax. Here is our HylaFax config file so that it can talk with the iaxmodem on extension 125:
file in /var/spool/hylafax/etc/config.tty125 :
GettyArgs: "-h %l dx_%s"
LocalIdentifier: "OC9 Technologies"
TagLineFormat: "From %%l|%c|Page %%P of %%T"
# Modem-related stuff: should reflect modem command interface
# and hardware connection/cabling (e.g. flow control).
ModemType: Class1 # use this to supply a hint
# Enabling this will use the hfaxd-protocol to set Caller*ID
# If "glare" during initialization becomes a problem then take
# the modem off-hook during initialization, and then place it
# back on-hook when done.
#ModemResetCmds: "ATH1\nAT+VCID=1" # enables CallID display
Class1TMConnectDelay: 400 # counteract quick CONNECT response
# If you have trouble with V.17 receiving or sending,
# you may want to enable one of these, respectively.
Class1RMQueryCmd: "!24,48,72,96" # enable this to disable V.17 receiving
Class1TMQueryCmd: "!24,48,72,96" # enable this to disable V.17 sending
# You'll likely want Caller*ID display (also displays DID) enabled.
ModemResetCmds: AT+VCID=1 # enables CallID display
# The pty does not support changing parity.
# If you are "missing" Caller*ID data on some calls (but not all)
# and if you do not have adequate glare protection you may want to
# not answer based on RINGs, but rather enable the CallIDAnswerLength
# for NDID, disable AT+VCID=1 and do this:
# Uncomment DATE and TIME if you really want them, but you probably don't.
#CallIDPattern: "USER=" # username provided by call
#CallIDPattern: "PASS=" # password provided by call
#CallIDPattern: "CDID=" # DID context in call
We now need to fork the usual Hylafax faxgetty to listen for incoming fax :
in rc.local :
/usr/local/sbin/faxgetty tty125 &
/usr/local/sbin/faxgetty tty126 &
as well as the usal daemons, see HylaFax documentation if you are interested in using it.
in rc.local :
View this free package: AvantFax. It allows you to let your users access fax functionality from a web browser. Some have used this package along with what is described in this article to set up pools of over 2000 iaxmodems and they have got so to speak in the fax sending/receiving outsourcing business.