Receiving and sending faxes with asterisk 1.4, NVFaxDetect, iaxmodem and hylafax

Recherche dans le site/ Search this Blog:

Login

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 1.4.23.1

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:

Iaxmodem (Click to download)

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:

APPS+=app_nv_faxdetect.so
APPS+=app_nv_backgrounddetect.so

UPDATE: For Asterisk 1.4.23.1 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_*

/usr/lib/asterisk/modules/app_nv_backgrounddetect-1.0.6_1.so

/usr/lib/asterisk/modules/app_nv_faxdetect-1.0.6_1.so

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:

HylaFax (Click to download)

Iaxmodem setup

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 :

device /dev/tty125
owner uucp:uucp
mode 660
port 4570
refresh 1800
server 10.10.1.20
peername 125
secret XXXXX
cidname Technologies OC9-ACTS
cidnumber 5555551212
codec ulaw

extension 126 file in /etc/iaxmodem/tty126 :

device /dev/tty126
owner uucp:uucp
mode 660
port 4571
refresh 1800
server 10.10.1.20
peername 126
secret XXXXX
cidname Technologies OC9-ACTS
cidnumber 5555551212
codec ulaw

We arranged so that iaxmodem starts automatically by adding the following to our rc.local file :

/usr/local/bin/iaxmodem

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.

HylaFax configuration

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 :

CountryCode:            1
AreaCode:               418
FAXNumber:              +1.555.555.1212
LongDistancePrefix:     1
InternationalPrefix:    011
DialStringRules:        etc/dialrules
ServerTracing:          1
SessionTracing:         11
RecvFileMode:           0660
LogFileMode:            0600
DeviceMode:             0600
RingsBeforeAnswer:      1
SpeakerVolume:          off
GettyArgs:              "-h %l dx_%s"
LocalIdentifier:        "OC9 Technologies"
TagLineFont:            etc/lutRS18.pcf
TagLineFormat:          "From %%l|%c|Page %%P of %%T"
MaxRecvPages:           175

#
#
# 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
#
#ModemSetOriginCmd:     AT+VSID="%s","%d"

#
# 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
#ModemReadyCmds:        ATH0

Class1AdaptRecvCmd:     AT+FAR=1
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.
#
PagerTTYParity:         none

#
# 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:
#
#RingsBeforeAnswer: 0
#ModemRingResponse: AT+VRID=1

# Uncomment DATE and TIME if you really want them, but you probably don't.
#CallIDPattern:          "DATE="
#CallIDPattern:          "TIME="
CallIDPattern:          "NMBR="
CallIDPattern:          "NAME="
CallIDPattern:          "ANID="
#CallIDPattern:          "USER="        # username provided by call
#CallIDPattern:          "PASS="        # password provided by call
#CallIDPattern:          "CDID="        # DID context in call
CallIDPattern:          "NDID="
#CallIDAnswerLength:    4

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 :

/usr/local/sbin/hfaxd
/usr/local/sbin/faxq

Add-on

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.

Commentaires / Comments (23)

How can I perform fax detection and forward to extension 125 in asterisk 1,4 ? (No FreePBX)

Hi,

Note that 125 is just a random extension number we picked up for our examples, it can be any extension number.

You can do the same in Asterisk 1.4 without FreePBX by manually editing your extension.conf file. Just follow the instructions in the article and edit your extension.conf manually instead of editing the extension settings in FreePBX.

Here are the lines required to detect a FAX or send to an IVR in the incoming section of extention.conf :
...
...
exten => s,n,Set(FAX_RX=125)
exten => s,n,Answer
exten => s,n,Playtones(ring)
exten => s,n,NVFaxDetect(5)
exten => s,n,Goto(ivr-2,s,1)
...

Just replace the lines in your configuration file that sends to the IVR with the above lines in order to first detect fax tones and reload Asterisk so it re-read its config files.

I have managed to install hylafax.When a fax comes my asterisk forward the call to iaxmodem.Iaxmodem to hylafax . But when I try to see the fax,which is in tiff format,through webmin then I receive an error , That the file format is not supported or Image something is not installed on my machine . What may be the problem ?

Hi,

If you got so far, it means you have successfully configured asterisk, iaxmodem and hylafax. Congratulations! ;-)

As you may already understand, the tiff issue is not related to the fax setup.

To be able to view faxes from webmin you should.

1) Make sure the tiff mime type is defined in your apache configuration, in your apache folder, in conf/mime.types, you should have a line with :

image/tiff tiff tif

2) You will need a program that supports displaying multi-page tiff images.

Do a search for "linux fax viewer" to find a program that displays multi-page tiff files correctly.

On my linux desktop, I use :

kfax (KDE fax viewer)

To have mozilla open the tiff file automatically when you click on it, you will need to define you fax viewer program (i.e. kfax) to handle tiff files in mozilla or in your system settings.

Alternatively, you can download the file to your local drive and use the tiff2ps or tiff2pdf utilities (to transform it either to a .ps or .pdf file.

Same principle applies on windows, on windows, my XP install came with a utility named "Windows image and faxes preview" and that's what I use to read/print faxes (e.g. tiff files).

Hi
i read your post on Asterisk list. last 3 months i am trying to set Asterisk Fax to email
on SIP, but i have no success when i try with Spandsp..
so do you have any idea how we can make this if we are using SIP-VOIP with
Asterisk.Otherwise help me to do this with any other software taht u check it.only need is that that work
with SIP-VOIP Asterisk.(SIP Channel).
plz provide me link or config deatils if you have so i can try this with my Asterisk
Asterisk version 1.4.9
on dell server with RHEL OS
using SIP Channel type.

i am waiting for ur reply

Regards
Amit

1) We try that too but we couldn't get it to work well. That's why we recommend using iaxmodem. Iaxmodem comes with its own spandsp libraries.

2) So asterisk knows nothing about spandsp, asterisk just forwards the call to iaxmodem which takes care of decoding the fax. We leave asterisk alone and handle the faxes with iaxmodem. Don't use spandsp within asterisk.

3) Since you tell asterisk to forward the call to iaxmodem in inbound routes, (or in extensions if you wish) it does not matter if the call comes in through a SIP trunk or an IAX trunk. We have calls coming in through SIP and IAX trunks and faxes are forwarded to the iaxmodem.

4) Hylafax is a very stable and powerful fax handling software, it does fax to email since at least 15 years ;-)

SIP trunk --> asterisk --> iaxmodem --> hylafax --> email So the instructions in the article will work with a SIP trunk too ;-)

Cheers,

Thanks for your tutorial. But i don't know how to create dial plan for my fax machine.So my asterisk know to send fax to the fax machine

Here my configuration

Hylafax+iaxmodem+trixbox2.4.xCisco router ios 13(FXO)Switching Center(PSTN Central)My fax machine(fax number 6211)
Could you give me example help to create dialplan in extension.conf for fax number in this case 6211 base on the configuration above.Thanks sorry for my English...

Here are the lines required to detect a FAX or send to an IVR in the incoming section of extention.conf :
...
...
exten => s,n,Set(FAX_RX=125)
exten => s,n,Answer
exten => s,n,Playtones(ring)
exten => s,n,NVFaxDetect(5)
exten => s,n,Goto(ivr-2,s,1)
...

Just replace the lines in your configuration file that sends to the IVR with the above lines in order to first detect fax tones and reload Asterisk so it re-read its config files.

If you share voice and fax, you need to use NVFaxDetect which catch the fax call at the IVR level and automagically forwards it to the fax extension. If you have a dedicated number for your fax, just forward all calls to the fax extension like you would normally do for a phone extension with a dedicated number.

If you use FreePBX just configure the fax handling in your Inbound Routes :
Fax Extension: 6211
Fax Email: (leave blank)
Fax Detection Type: NVFax
Pause After Answer: 5

Great read on your article, but there is a lot of misinformation on the subject.

1. Faxing over VoIP is not dependant on the carrier. Network jitter is what causes a fax to fail when sending/receiving faxes over SIP. The only reason you may get better results with one provider is because your connection to them, at this moment, may be good. However, this will eventually change at some point and your faxing will decrease to 50%-70% success rate.

2. IAX modem is slow (14.4k), but really only achieves 9.6k. This is something that will never change. Traditional lines are 33.6k. Hence, your 20 page document will take 5 times as long to send/receive.

3. Why are you trying to have Asterisk send the email? HylaFAX should be in charge of all fax functions including sending the pdf to email.

Guys, you will never be able to "beat" the system for faxing. If you want reliable faxing, stick with the PSTN.

Great read on your article, but there is a lot of misinformation on the subject.

---> Thanks !

1. Faxing over VoIP is not dependant on the carrier. Network jitter is what causes a fax to fail when sending/receiving faxes over SIP. The only reason you may get better results with one provider is because your connection to them, at this moment, may be good. However, this will eventually change at some point and your faxing will decrease to 50%-70% success rate.

----> I agree, but this is the same as your "good" carrier becoming a bad "carrier" or your "good" internet connectivity becoming "bad". It is therefore dependent on your carrier and your internet connectivity, which is pretty much what we have said in the article ;-)

2. IAX modem is slow (14.4k), but really only achieves 9.6k. This is something that will never change. Traditional lines are 33.6k. Hence, your 20 page document will take 5 times as long to send/receive.

----> Very good point ! This should definitely have been noted in the article !

3. Why are you trying to have Asterisk send the email? HylaFAX should be in charge of all fax functions including sending the pdf to email.

-----> I don't know where this is from, we recommend delegating everything to Hylafax just as you do.

Guys, you will never be able to "beat" the system for faxing. If you want reliable faxing, stick with the PSTN.

------> Agreed, if you run a mission critical fax operation that needs maximum reliability. But this is changing slowly as networks get better. Who would have thought that VOIP could be possible in the early ages of Internet (say in 1980, when I got my first access to it)?. Also, do not forget that Internet2 (Also called The Grid) is coming ;-)

-------> Also, note that the article states that the suggested setup is also valid if you use PSTN lines ONLY with Asterisk as your PBX, it lets you share your fax lines with voice, all handled by Asterisk, with only PSTN lines and VOIP used internally only.

hi there i have a tdm24xxp(fxo) port is it possible to route faxes to hylafax from asterisk + do you need to route your incoming calls to the iaxmodem, or can you route the calls strait from fxo to hylafax using asterisk?

any help welcome

Yes shou;ld be able to do that as long as you use ulaw between your asterisk and the tdm24xxp(fxo) and that it supports fax passtrough. You will also need to use a hardware modem on the hylafax server. This type of config is very similar to having hylafax hooked to a hardware modem that is turn hooked to a PSTN line. So asterisk routing prior to the fax call hitting the hardware modem on the hylafax server will be transparent.

Also, you wouldn't be limited by the relatively slow speed of iaxmodem, as a another user has rightly noted 2 messages ago.

Hi, nice tutorial, but I didn't see an example to send an fax using hylafax and asterisk, we have some PSTN lines connected to asterisk and we want to sent faxes using this lines.

Hi there,

great article, I wana setup this for only outgoing faxes, i-e, I only need to send faxes. Is it possible. Do I still need any extra hardware for this?

thanks for your help in advance!!!

cheers!
Nemo.

Just follow standard hylafax procedure to send a fax. Remember that hylafax sees your IAXmodem as any other modem. The fact that you use iax modem/asterisk is completely transparent to hylafax. Hylafax doesn't know anything about asterisk and iaxmodem, hylafax doesn't even know they exist!

That's the reason why we like this approach despite the limitations of iaxmodem, everything is nicely layered in indepandant layers.

To send a fax, we just use the following command triggered from our custom web interface, just have a look at AvantFax (link in the article) if you want to install a turn key solution :

command to send fax with hylafax:

/usr/local/bin/sendfax -x "Destination company" -r "Subject of the fax" -c "Comment for recipient" -D -h localhost:9008 -d "Recipient Name"@1555555121 2 file.pdf

The setup described in this article works equally well to send faxes, please have a look at above reply (Re: Sending fax) which pretty much answer your question.

Additionally, remember that this setup works with totally independent layers so any solution that works with hylafax to send faxes will work with this setup.

Hylafax exists since more than 15 years so many very mature solutions to send faxes with hylafax are available. Again, that's why we choose that solution, to completely abstract asterisk and VOIP out of the picture.

We also have tested two dozen providers. So far gafachi stands out. What is your best choice?

Hi:
How can I see the communication between hylafax and iaxmodem and the console of them?I only can see the console of asterisk.It shows: 'IAX2/iaxmodem-2 is ringing' when I dial the fax number.
and nothing else.I can't receive fax.
I installed asterisk 1.4.18 and iaxmodem-1.2.0 and
hylafax-5.2.9-1.fc9.i386.rpm and these are my main configurations:
extensions.conf:
[from-pstn]
exten => 9711315,1,Answer
exten => 9711315,2,Dial(IAX2/iaxmodem)
iax.conf:
[iaxmodem]
type=friend
secret=password
port=4570
host=dynamic
context=from-pstn
disallow=all
allow=alaw

/etc/iaxmodem/ttyIAX0
device /dev/ttyIAX0
owner uucp:uucp
mode 660
port 4570
refresh 50
server 127.0.0.1
peername iaxmodem
secret password
codec alaw
and this is my modem type in /var/spool/hylafax/etc/config.tty
ModemType: Class1
/etc/inittab:
id:5:initdefault:
IA00:23:respawn:/usr/bin/iaxmodem
ttyIAX0
IA00:23:respawn:/usr/bin/iaxmodem
ttyIAX0
mo00:23:respawn:/usr/sbin/faxgetty ttyIAX0

I started hylafax and run iaxmodem.
I see below lines when I run faxstat:
HylaFAX scheduler on localhost.localdomain: Running
Modem ttyIAX0 (9711315): Waiting for modem to come ready

I'd appreciate any help,idea.
~

Hello,

Well there is no big secret, we use a local provider a few hops away from us that is directly hooked to the Telco via T1 links. The provider is 15ms away from us.

International providers where the call is routed to (or received from) out of the country networks have less chances to succeed in a steady way. There is more spots on the network where weakness may cause the call to fail and you often do not know how the call is routed once it gets to the provider.

To get maximum reliability, we use a local provider and we know how our call is routed once it gets to that provider. Straight to the Telco with T1 links ;-)

We do not use any of our other 4 providers for faxes for the reasons stated above. We use g729 on those trunks anyway which is not best suited for faxes.

Hi,

It looks like you do have faxgetty running, to test that hylafax communicates with the modem, use the following command:

$ ps axw | grep faxgetty
14871 pts/9 S 0:00 /sbin/faxgetty -q /var/spool/hylafax-2 tty882991110992
14872 pts/9 S 0:00 /sbin/faxgetty ttyIAX
14873 pts/9 S 0:00 /sbin/faxgetty acts1

faxgetty does the communication between hylafax and iaxmodem

Hi:
thank you for reply.
after running : ps axw | grep faxgetty
I saw :
7687 pts/9 S+ 0:00 grep faxgetty
Is it problem?

Yes it is a problem, ps returned you the pid of the grep command you were currently running (pid=7687) ( pid= process ID ) this is the pid of the grep process created by the command you just typed.

But ps show that you DO NOT have faxgetty running hence hylafax can't receive faxes. To see that you have a faxgetty process running, you must have a faxgetty process showing up when you issue the command ps axw | grep faxgetty.

The process name will start with the name faxgetty as the examples show in previous posts. The name of the process will be faxgetty, not grep:

$ ps axw | grep faxgetty
14872 pts/9 S 0:00 /sbin/faxgetty ttyIAX

You may also use pidof faxgetty which will only return pids of faxgetty processes :

/sbin/pidof faxgetty
14872

See how we start faxgetty in our article, we just put the following command in /etc/rc.d/rc.local, you may also test it from the command line and it should just work :

/usr/local/sbin/faxgetty tty125 &

You can also use the following command to list all processes on your computer:

$top -b -n 1

Hopefully, this will help you to get a clearer picture ;-)

Ajouter votre commentaire / Add your comment

Votre nom / Your name:
Sujet / Subject:
Comment:

Retaper les lettres affichées / Word verification:

Mis à jour / Last updated ( vendredi, 06 mars 2009 00:31 )

Menu

Recherche dans le site/ Search this Blog:

Login

Ajouter votre commentaire / Add your comment

Consultez TOUS nos fils d'actualité ici. / View ALL our newsfeed here.