Digium Free Fax for Asterisk
It seems as much as we try to do without it, there are times when we just need to fax something. Maybe it's something that's legal or that needs a signature. Whatever, we need to fax. But, we sure don't want to invest in a fax machine! Digium and Asterisk to the rescue! Today we'll go through the steps to install Digium's Free Fax for Asterisk and get it all configured within FreePBX. Our base system is Certified Asterisk 11 with FreePBX 2.11.
Get a License
The first step is to visit Digium's web site and get a license for Free Fax for Asterisk. This license will allow for one concurrent fax, either sending or receiving. If you need more than one, you'll need to purchase the additional licenses. Complete the registration process and your license key will be emailed to you. The manual for the software is available here.
Running Some Utilities
Before we actually download and install the software, we have a little administrative work to do. First is to download the register utility and generate a license file from our license key. This utility needs Internet access and must be run on the machine where Free Fax for Asterisk will be installed. Visit http://downloads.digium.com/pub/register/ and download the register utility that is appropriate for your system. Once downloaded, use chmod to make it executable, and then run it and follow the directions.
[root@pbx digium]# wget http://downloads.digium.com/pub/register/x86-32/register
--2013-09-26 10:11:38-- http://downloads.digium.com/pub/register/x86-32/register
Resolving downloads.digium.com... 76.164.171.238, 2001:470:e0d4::ee
Connecting to downloads.digium.com|76.164.171.238|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 1178780 (1.1M)
Saving to: “register.1”
100%[======================================>] 1,178,780 1.07M/s in 1.1s
2013-09-26 10:11:40 (1.07 MB/s) - “register” saved [1178780/1178780]
[root@pbx digium]# chmod +x register
[root@pbx digium]# ./register
Digium Product Registration - Version 3.0.5
Copyright (C) 2004-2007, Digium, Inc.
Use the '-l' option to see license information for software
included in this program.
Please select a category
1 - Digium Products
2 - Cepstral Products
0 - Quit
Your Choice:
Now we need to get the benchfax utility and run it. It will test your systems performance to determine which processor-specific algorithm works best on your system, so you'll know which optimization of Free Fax for Asterisk to get. Visit http://downloads.digium.com/pub/telephony/fax/benchfax/ and download the utility. This utility will take a while to run, but at the end it will tell you which optimization ran best. Make note of this.
[root@pbx digium]# wget http://downloads.digium.com/pub/telephony/fax/benchfax/x86-32/benchfax-1.1.0-x86_32 -O benchfax
--2013-09-26 10:14:41-- http://downloads.digium.com/pub/telephony/fax/benchfax/x86-32/benchfax-1.1.0-x86_32
Resolving downloads.digium.com... 76.164.171.238, 2001:470:e0d4::ee
Connecting to downloads.digium.com|76.164.171.238|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 7974456 (7.6M)
Saving to: “benchfax”
100%[======================================>] 7,974,456 1.13M/s in 6.8s
2013-09-26 10:14:48 (1.12 MB/s) - “benchfax” saved [7974456/7974456]
[root@pbx digium]# chmod +x benchfax
[root@pbx digium]# ./benchfax
benchfax version 1.1.0
Use the '-l' option to see license information for software
included in this program.
Running test using CCITT FAX test page, US letter size, 204x196 resolution, MMR encoding, ECM enabled and V.17 (14.4kbps) modem
NOTE: Each individual test could take 20 seconds or longer; be patient.
Test run 1 for flavor 'generic' used 496 milliseconds of CPU time.
Beginning test run 2 of 5 for flavor 'generic'...
...
Recommended flavor for this system is 'core2' with an average of 466 milliseconds of CPU time.
Download Fax for Asterisk
Now we have enough information to download Fax for Asterisk! Visit http://my.digium.com/en/docs/FAX/faa-download/ and make the proper selections, and then download the file. Once downloaded, untar it and install it.
[root@pbx digium]# wget http://downloads.digium.com/pub/telephony/fax/res_fax_digium/asterisk-11.0/x86-32/res_fax_digium-11.0_1.3.1-core2_32.tar.gz
--2013-09-25 19:26:40-- http://downloads.digium.com/pub/telephony/fax/res_fax_digium/asterisk-11.0/x86-32/res_fax_digium-11.0_1.3.1-core2_32.tar.gz
Resolving downloads.digium.com... 76.164.171.238, 2001:470:e0d4::ee
Connecting to downloads.digium.com|76.164.171.238|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 570796 (557K) [application/x-gzip]
Saving to: “res_fax_digium-11.0_1.3.1-core2_32.tar.gz”
100%[======================================>] 570,796 1.00M/s in 0.5s
2013-09-25 19:26:40 (1.00 MB/s) - “res_fax_digium-11.0_1.3.1-core2_32.tar.gz” saved [570796/570796]
[root@pbx digium]# tar xzvf res_fax_digium-11.0_1.3.1-core2_32.tar.gz
res_fax_digium-11.0_1.3.1-core2_32/
res_fax_digium-11.0_1.3.1-core2_32/res_fax_digium.so
res_fax_digium-11.0_1.3.1-core2_32/res_fax_digium.conf
res_fax_digium-11.0_1.3.1-core2_32/README
res_fax_digium-11.0_1.3.1-core2_32/LICENSE
[root@pbx digium]# cd res_fax_digium-11.0_1.3.1-core2_32
[root@pbx res_fax_digium-11.0_1.3.1-core2_32]# ls
LICENSE README res_fax_digium.conf res_fax_digium.so
[root@pbx res_fax_digium-11.0_1.3.1-core2_32]# cp res_fax_digium.so /usr/lib/asterisk/modules/
[root@pbx res_fax_digium-11.0_1.3.1-core2_32]# asterisk -r
Asterisk 11.2-cert1, Copyright (C) 1999 - 2012 Digium, Inc. and others.
Created by Mark Spencer
Asterisk comes with ABSOLUTELY NO WARRANTY; type 'core show warranty' for details.
This is free software, with components licensed under the GNU General Public
License version 2 and other licenses; you are welcome to redistribute it under
certain conditions. Type 'core show license' for details.
=========================================================================
Connected to Asterisk 11.2-cert1 currently running on phone (pid = 1384)
pbx*CLI> core restart when convenient
Waiting for inactivity to perform restart
pbx*CLI>
Disconnected from Asterisk server
Asterisk cleanly ending (0).
Executing last minute cleanups
[root@phone res_fax_digium-11.0_1.3.1-core2_32]#
Incoming FAX
Setting up the incoming fax is fairly straight forward, but there are a few steps. Just follow them in order and you'll be fine. In this scenario, we are using SIP trunks for our fax lines (technically, faxing is not supported in this scenario due to the likelihood of packet loss), so you may need to alter the procedures slightly.
- In Admin/Module Admin, install the "Fax Configuration" module and "Apply Config"
- In FreePBX, go to Settings/Asterisk SIP Settings. At the bottom, in "Other SIP Settings," add
faxdetect=yes - In Connectivity/Inbound Routes, select the inbound route upon which you want to receive faxes. Set "Detect Faxes" to Yes, "Fax Detection type" to Sip, "Fax Detection Time" to 4, and "Fax Destination" to
Fax Recipientand then select the proper recipient - Go to Applications/Users and select the user who is the "Fax Recipient" in the above step. In the "Fax" section, make sure than "Enabled" is checked and set the "Fax Email" to be the email address of where to send the fax
- Apply Config for these changes, and incoming faxing should now be functional!
Outbound faxing
We will set up outbound faxing so that a user can upload a file in the User Portal, provide a phone number, and the system will fax it. The file uploaded must either be a TIFF (with .tif extension) or PDF (with .pdf extension), and the PDF may yield better results. We will get the fax User Portal module from http://faxgui-ari-module.googlecode.com/ and install it, install ghostscript (to convert PDF files to fax-ready TIFFs), and create an outbound fax context.
[root@pbx software]# wget http://faxgui-ari-module.googlecode.com/files/faxgui-ari-module.tar.gz
--2013-09-25 19:41:31-- http://faxgui-ari-module.googlecode.com/files/faxgui-ari-module.tar.gz
Resolving faxgui-ari-module.googlecode.com... 74.125.142.82, 2607:f8b0:4002:c03::52
Connecting to faxgui-ari-module.googlecode.com|74.125.142.82|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 4780 (4.7K) [application/x-gzip]
Saving to: “faxgui-ari-module.tar.gz”
100%[======================================>] 4,780 21.8K/s in 0.2s
2013-09-25 19:41:31 (21.8 KB/s) - “faxgui-ari-module.tar.gz” saved [4780/4780]
[root@pbx software]# tar xzvf faxgui-ari-module.tar.gz
faxgui-ari-module/
faxgui-ari-module/sendfax.module
faxgui-ari-module/sendfaxnotify.php
[root@pbx software]# cd faxgui-ari-module
[root@pbx faxgui-ari-module]# cp sendfax.module /var/www/html/recordings/modules
[root@pbx faxgui-ari-module]# chown asterisk.asterisk /var/www/html/recordings/modules/sendfax.module
[root@pbx faxgui-ari-module]# chmod 664 /var/www/html/recordings/modules/sendfax.module
[root@pbx faxgui-ari-module]# yum install ghostscript
Loaded plugins: fastestmirror, security
Determining fastest mirrors
epel/metalink | 12 kB 00:00
* base: mirror.hmc.edu
* epel: mirror.cogentco.com
* extras: centos.mirror.constant.com
* updates: mirrors.serveraxis.net
base | 3.7 kB 00:00
epel | 4.2 kB 00:00
epel/primary_db | 4.6 MB 00:04
extras | 3.5 kB 00:00
updates | 3.4 kB 00:00
updates/primary_db | 4.1 MB 00:03
Setting up Install Process
Resolving Dependencies
--> Running transaction check
---> Package ghostscript.i686 0:8.70-15.el6_4.1 will be installed
--> Processing Dependency: urw-fonts >= 1.1 for package: ghostscript-8.70-15.el6_4.1.i686
--> Processing Dependency: libXt.so.6 for package: ghostscript-8.70-15.el6_4.1.i686
--> Processing Dependency: libSM.so.6 for package: ghostscript-8.70-15.el6_4.1.i686
--> Processing Dependency: libICE.so.6 for package: ghostscript-8.70-15.el6_4.1.i686
--> Processing Dependency: ghostscript-fonts for package: ghostscript-8.70-15.el6_4.1.i686
--> Running transaction check
---> Package ghostscript-fonts.noarch 0:5.50-23.1.el6 will be installed
--> Processing Dependency: xorg-x11-font-utils for package: ghostscript-fonts-5.50-23.1.el6.noarch
---> Package libICE.i686 0:1.0.6-1.el6 will be installed
---> Package libSM.i686 0:1.2.1-2.el6 will be installed
---> Package libXt.i686 0:1.1.3-1.el6 will be installed
---> Package urw-fonts.noarch 0:2.4-10.el6 will be installed
--> Running transaction check
---> Package xorg-x11-font-utils.i686 1:7.2-11.el6 will be installed
--> Processing Dependency: libfontenc.so.1 for package: 1:xorg-x11-font-utils-7.2-11.el6.i686
--> Processing Dependency: libXfont.so.1 for package: 1:xorg-x11-font-utils-7.2-11.el6.i686
--> Running transaction check
---> Package libXfont.i686 0:1.4.5-2.el6 will be installed
---> Package libfontenc.i686 0:1.0.5-2.el6 will be installed
--> Finished Dependency Resolution
Dependencies Resolved
================================================================================
Package Arch Version Repository Size
================================================================================
Installing:
ghostscript i686 8.70-15.el6_4.1 updates 4.5 M
Installing for dependencies:
ghostscript-fonts noarch 5.50-23.1.el6 base 751 k
libICE i686 1.0.6-1.el6 base 52 k
libSM i686 1.2.1-2.el6 base 36 k
libXfont i686 1.4.5-2.el6 base 144 k
libXt i686 1.1.3-1.el6 base 179 k
libfontenc i686 1.0.5-2.el6 base 24 k
urw-fonts noarch 2.4-10.el6 base 3.1 M
xorg-x11-font-utils i686 1:7.2-11.el6 base 73 k
Transaction Summary
================================================================================
Install 9 Package(s)
Total download size: 8.7 M
Installed size: 26 M
Is this ok [y/N]: y
Downloading Packages:
(1/9): ghostscript-8.70-15.el6_4.1.i686.rpm | 4.5 MB 00:05
(2/9): ghostscript-fonts-5.50-23.1.el6.noarch.rpm | 751 kB 00:01
(3/9): libICE-1.0.6-1.el6.i686.rpm | 52 kB 00:00
(4/9): libSM-1.2.1-2.el6.i686.rpm | 36 kB 00:00
(5/9): libXfont-1.4.5-2.el6.i686.rpm | 144 kB 00:00
(6/9): libXt-1.1.3-1.el6.i686.rpm | 179 kB 00:00
(7/9): libfontenc-1.0.5-2.el6.i686.rpm | 24 kB 00:00
(8/9): urw-fonts-2.4-10.el6.noarch.rpm | 3.1 MB 00:02
(9/9): xorg-x11-font-utils-7.2-11.el6.i686.rpm | 73 kB 00:00
--------------------------------------------------------------------------------
Total 822 kB/s | 8.7 MB 00:10
Running rpm_check_debug
Running Transaction Test
Transaction Test Succeeded
Running Transaction
Installing : libICE-1.0.6-1.el6.i686 1/9
Installing : urw-fonts-2.4-10.el6.noarch 2/9
Installing : libSM-1.2.1-2.el6.i686 3/9
Installing : libfontenc-1.0.5-2.el6.i686 4/9
Installing : libXfont-1.4.5-2.el6.i686 5/9
Installing : 1:xorg-x11-font-utils-7.2-11.el6.i686 6/9
Installing : ghostscript-fonts-5.50-23.1.el6.noarch 7/9
Installing : libXt-1.1.3-1.el6.i686 8/9
Installing : ghostscript-8.70-15.el6_4.1.i686 9/9
Verifying : libICE-1.0.6-1.el6.i686 1/9
Verifying : libXfont-1.4.5-2.el6.i686 2/9
Verifying : 1:xorg-x11-font-utils-7.2-11.el6.i686 3/9
Verifying : urw-fonts-2.4-10.el6.noarch 4/9
Verifying : libXt-1.1.3-1.el6.i686 5/9
Verifying : ghostscript-fonts-5.50-23.1.el6.noarch 6/9
Verifying : libSM-1.2.1-2.el6.i686 7/9
Verifying : ghostscript-8.70-15.el6_4.1.i686 8/9
Verifying : libfontenc-1.0.5-2.el6.i686 9/9
Installed:
ghostscript.i686 0:8.70-15.el6_4.1
Dependency Installed:
ghostscript-fonts.noarch 0:5.50-23.1.el6
libICE.i686 0:1.0.6-1.el6
libSM.i686 0:1.2.1-2.el6
libXfont.i686 0:1.4.5-2.el6
libXt.i686 0:1.1.3-1.el6
libfontenc.i686 0:1.0.5-2.el6
urw-fonts.noarch 0:2.4-10.el6
xorg-x11-font-utils.i686 1:7.2-11.el6
Complete!
[root@pbx faxgui-ari-module]#
When installing the software, we found issues with the sendfaxnotify.php file having DOS characters in it. To remove those, we opened the file with vi, entered :set filetype=unix and pressed enter, and then entered :wq and pressed enter. Poof, the file was fixed!
[root@pbx faxgui-ari-module]# cp sendfaxnotify.php /var/lib/asterisk/bin
[root@pbx faxgui-ari-module]# chown asterisk.asterisk /var/lib/asterisk/bin/sendfaxnotify.php
The final step is making an outbound fax context. This is as simple as copying the following into your /etc/asterisk/extensions_custom.conf file. Of course, you'll want to update the headerinfo and localstationid to be appropriate for you!
[outboundfax]
exten => s,1,Set(FAXOPT(ecm)=yes)
exten => s,n,Set(FAXOPT(headerinfo)="TRIDATA LLC")
exten => s,n,Set(FAXOPT(localstationid)="8592635926")
exten => s,n,Set(FAXOPT(maxrate)=14400)
exten => s,n,Set(FAXOPT(minrate)=2400)
exten => s,n,SendFAX(${FAXFILE},d)
exten => s,n,System(${ASTVARLIBDIR}/bin/sendfaxnotify.php INIT "${EMAIL}" "${DESTINATION}" "${TIMESTAMP}" "NO_STATUS" "NO_PAGES")
exten => h,1,NoOp(FAXOPT(ecm) : ${FAXOPT(ecm)})
exten => h,n,NoOp(FAXOPT(error) : ${FAXOPT(error)})
exten => h,n,NoOp(FaxStatus : ${FAXSTATUS})
exten => h,n,NoOp(FaxStatusString : ${FAXSTATUSSTRING})
exten => h,n,NoOp(FaxError : ${FAXERROR})
exten => h,n,NoOp(RemoteStationID : ${REMOTESTATIONID})
exten => h,n,NoOp(FaxPages : ${FAXPAGES})
exten => h,n,NoOp(FaxBitRate : ${FAXBITRATE})
exten => h,n,NoOp(FaxResolution : ${FAXRESOLUTION})
exten => h,n,System(${ASTVARLIBDIR}/bin/sendfaxnotify.php NOTIFY "${EMAIL}" "${DESTINATION}" "${TIMESTAMP}" "${FAXSTATUSSTRING}" "${FAXPAGES}")
; end of outboundfax context
Now that all the pieces are in place, do an amportal restart to make sure that all of our changes get properly applied, and it's time to test! The User Portal should now have "Send Fax" in the navigation, and inbound faxes will be handled automatically!
Debugging
Inevitably, there will be issues related to faxing that need to be resolved. The Fax for Asterisk manual provides some good tips for debugging. The Digium Knowledge Base is also a good place to look for information.