It’s been a rocky road getting an open source (free) faxing alternative to work reliably with Asterisk® 1.8. To further complicate things, CentOS 5.6 was finally released which brought us a few more Asterisk 1.8 headaches and updates finally leading up to an all-new and nearly perfect PBX in a Flash 22.214.171.124 thanks in large part to Tom King. The new release also forced some under-the-covers modifications in Incredible PBX. Now you’re caught up on last week’s news. But what have we done for you lately?
Well, one alternative was to shift gears to the commercial Fax for Asterisk from Digium® which is supported in FreePBX 2.8 and 2.9 and includes one free license. But we’re open source fans and, of course, nothing beats free. Thanks to the efforts of a number of folks on the PBX in a Flash forums including our old pal, Joe Roper, there is an alternative that folks have been wrestling with for over two years. The combination of Hylafax, Avantfax, and IAXmodem is a compelling open source solution if you don’t need T.38-compatible faxing.1 The drawback has been the learning curve to install all the components and get them working reliably together. Well, for those using Incredible PBX 1.8 with PIAF-Purple and Asterisk 1.8, today we have a newly minted installation script that is simple enough that even a monkey can use it. If you know your own email address and your local area code AND you can find the Enter key on your keyboard, you are fully qualified to perform today’s installation. It’ll take you under 5 minutes! We’ve also got a nice little surprise for you toward the end of this article.
Prerequisites. You’ll first need to install the latest version of PBX in a Flash with the PIAF-Purple (Asterisk 1.8) payload. Then sign up for a free Google Voice account and install Incredible PBX 1.8. You’ll find complete installation instructions for everything here. Can you just wing it and run this installation script on a garden-variety Asterisk 1.8 machine? No. And the reason is that all of these components have dependencies which are too complex to cover in a 5-minute article. You might want to have a look at the A-Fax Project which is where we started. Suffice it to say, the combination of PIAF-Purple and Incredible PBX 1.8 provides the ideal platform on which to install Incredible Fax. If you prefer to do-it-yourself, by all means have at it. We lost about 10 years worth of hair even starting with the work of a dozen very talented Linux gurus who have been wrestling with this for over two years! But, hey, YMMV! We never claimed to be the sharpest tool in the shed.
Installing Incredible Fax. Once you have your Incredible PBX 1.8 platform up and running, adding Incredible Fax is a stroll in the park. Just log into your server as root and issue the following commands. If you’ve downloaded Incredible PBX in the last few days, the script may already be on your system. In this case, just type /root/incrediblefax.sh to run it.
chmod +x incrediblefax.sh
After checking to make sure Incredible PBX 1.8 is installed, the script will prompt you to enter an email address where incoming faxes should be delivered. Then all of the necessary components will be installed after which the Avantfax install script will be run. With the exception of entering your local area code when prompted to do so, the correct response to every other question is to press the Enter key if you live in the U.S. or Canada. Don’t "improve" anything if you expect the end product to work reliably. For those outside North America, you’ll need to also make the usual adjustments to account for your country and city codes.
Avantfax has its own security model, but we’ve grown to appreciate the Apache authentication model which is built into PBX in a Flash so it’s been incorporated into Incredible Fax as well. When the install completes, just reboot your server to get everything working. On the PBX in a Flash web GUI, there will be a new Admin icon for Faxing. Or you can access Avantfax with a browser by going to http://serverIPaddress/avantfax. When prompted for your username and password, use maint and whatever your maint password happens to be. These can be reset with passwd-master. Literally everything has been preconfigured in Avantfax to get you going. Here’s a 3-minute video to show you how easy it is. Just don’t forget to reboot once the install completes.
If you want to be able to print to fax from Windows-based machines, then you’ll need to make one addition. Click on the small Toolbar icon in the upper right corner of the AvantFax home screen and choose New User from the pull-down Menu. For the user, enter Fax for the Name, fax for the Username, a secure password for Password, and an email address that is DIFFERENT from the one you used to set up Incredible Fax. Check the boxes for User Can Delete Faxes and User Can Fax From Any Modem. Finally, check the boxes for all four IAXmodems. Then click the Save button to add this new user.
A Word About Reliable Faxing. Suffice it to say that analog faxing over VoIP trunks is something less than ideal. If you want reliable analog faxing, then you’ll need a PSTN line from your favorite local telephone company. It doesn’t need any fancy add-ons like CallerID which doubles the price in many cities. Then you’ll need a properly configured analog telephone adapter (ATA) with at least one FXO port to support your Ma Bell phone line. Our favorite is the OBi110 which also can double as an additional Google Voice trunk for your PBX. But an SPA3102 will work equally well. It just costs more and gives you less.
Now that we’ve covered the obligatory warnings… will Incredible Fax work with a pure VoIP connection? Absolutely. We do it all the time. Is it flawless? No. Are there certain providers that are better than others? You bet. Do some providers not support faxing at all? Correct. Based on our 5+ years wrestling with this, here’s our recommendation. First, you’ll need a DID (i.e. phone number) from one of our recommended providers to handle inbound faxes. With the latest release of Asterisk 1.8, you no longer need a DID dedicated to faxing. In other words, you can use the same DID to receive incoming voice calls as well. The good news is that pay-as-you-go DIDs are dirt cheap. Some providers such as voip.ms offer DIDs for under $1 a month with 1¢ per minute calls. VoIP.ms also has unlimited inbound calling DIDs for under $4 a month. Other providers whose trunks we have found work reliably for VoIP faxing include Vitelity (see our special sign up deal below), Axvoice, Teliax, VoIPMyWay ($45 for first year with unlimited outbound and inbound calling with a local DID), and Future-Nine2. Google Voice trunks are hit and miss. We’re batting about .250 in our testing with Google Voice lines. Bottom Line: If VoIP faxing doesn’t work after you complete the install, it’s probably the fault of your VoIP trunk, not the setup. To make absolutely sure, connect a standard fax machine to an extension using an FXS telephone adapter and send a fax to that extension from the Avantfax web interface. You’ll find it works every time!
Configuring FreePBX for Incredible Fax. Here are the steps you’ll need to complete to get analog faxing working reliably with FreePBX. First, set up an account with one of the companies we’ve mentioned above. With voip.ms, create a subaccount on their site with credentials to use with the DID you purchased to link to that subaccount.
Unless you’re using today’s release of Incredible PBX, you’ll need to activate FreePBX’s Fax Configuration Module if you want to take advantage of Asterisk 1.8′s fax detection capabilities. It didn’t work reliably in previous Asterisk 1.8 releases. This module already is either available or already installed on your server. In the FreePBX GUI using a browser, choose Tools, Module Admin and then click on Fax Configuration. A drop-down list will provide several choices. Choose either Install or Enable depending upon the version of Incredible PBX you currently are running. Then click the Process button and finally Reload the settings when prompted.
Unless you installed Incredible PBX today, you’ll need to create a SIP trunk for your new provider in FreePBX using the credentials you set up on the provider’s web site. The VoIP.ms template now is included in Incredible PBX so you can just edit the existing one to add your credentials. And, at least with VoIP.ms, you can set the outbound CallerID to anything you like (as long as it’s legal). Unless you want a knock at your door, we wouldn’t recommend using the main number at the White House. Then put all of the settings below in the Outgoing Settings PEER Details where 1234567 is your main account number, subacctname is the name of the subaccount you created, and atlanta is your closest voip.ms server location:
For the registration string, it should look like the following. If you’re planning to only use the trunk for outbound faxing, then you can leave off the trailing DID number.
In addition to setting up the Trunk for your provider, you’ll also need to create an Outbound Route for sending faxes out through this trunk AND an Inbound Route to receive incoming faxes on the DID you purchased from your provider.
For the Outbound Route, we recommend setting the Dial Pattern with a prefix not otherwise used on your Incredible PBX so that you can make fax calls easily by dialing this prefix. For example, on our sample system, we used 7 so that fax calls could be made by dialing 7 plus a 10-digit number in the U.S. and Canada. Here’s how our Outbound Route for VoIP.ms looks in FreePBX, and the latest Incredible PBX release already has it in place as shown below:
For the Inbound Route, you want to specify the DID from your provider which must match the 10-digit number you affixed to the end of the trunk registration string above. If you don’t want to share this number for voice and fax calls, then simply direct these inbound fax calls to the Fax Custom Destination. Extension (329 spells F-A-X) also can be used to process incoming faxes and route them to your email address as well as the Avantfax web GUI.
Our experience suggests that using a single trunk for both voice and fax delivery is hit and miss so you may wish to consider adding an additional trunk just to support faxing. You’ll find the templates for adding a second Google Voice trunk in the /tmp directory, and complete instructions are available on the PIAF Forums. We’ve also provided preconfigured trunk settings for both Vitelity and VoIP.ms if you’d like to try those options as well. Just plug in your credentials and configure an inbound route to map incoming faxes to the Fax Custom Destination.
AvantFax in a Nutshell. Here’s a quick summary of the main features in the AvantFax web GUI. You can access the GUI by pointing a browser to the IP address of your server + /avantfax. After you enter your maint account name and maint password, the following screen will display with your Inbox. As noted, all of these incoming faxes also will be emailed to the account you set up when you ran the Incredible Fax install script.
The icons to the right of each thumbnail fax let you View, Rotate, Download PDF, Reply to Fax, Email PDF, Add a Note, Archive the Fax, and Permanently Delete the Fax.
At the top of the screen just to the right of Inbox is the option to Send a Fax. Here you’d specify the phone number to dial. Don’t forget the 7 and then a 10-digit number. Next you can attach a document from your local disk. Finally, fill in the blanks for the Fax Cover Sheet, and then click Send. Your fax will be on its way. You can monitor the progress of the fax transmission by clicking on Outbox. It’s also a good idea to fire up an SSH session to your server and run asterisk -rvvvvvvvvvv to monitor the first few calls to be sure all is well in Incredible FaxLand.
Implementing Fax on Demand. Finally, there’s a nifty little command line utility for sending faxes from within the Linux CLI. You can attach PDF files as well as any sort of plain text file. Here’s the command syntax: sendfax -n -d 78005551212 /etc/crontab. The most practical use for this command line utility would be to construct a Fax on Demand service to let callers dial in to download a PDF document to their fax machine. So we’ve done a simple one just to show you how easy it is to construct. When callers dial in to the Fax on Demand service, they are prompted to enter the number of their fax machine and then a document number (0-9) to retrieve. The Fax on Demand service then delivers the requested PDF document to their fax machine. You can embellish this in any way you like obviously.
If you’ve downloaded Incredible PBX 1.8 since yesterday (May 1), this service already is enabled once you install Incredible Fax and activate VoIP.ms service. Just dial 363 (F-O-D) from an extension on your system, enter your fax number (it can be an extension on your local system as well) and then 0-9 for the document number to retrieve. You can easily point a DID to the FaxOnDemand Misc Destination to enable the service for outside callers; however, versions downloaded before 9 p.m. EDT this evening lacked a password option so don’t do it without replacing the code with what’s provided in the next paragraph AND adding a secure password! See the next paragraph for the location of the dialplan code. The actual PDF documents are stored in /var/lib/asterisk/agi-bin with file names of fod-0.pdf through fod-9.pdf. Sample documents already are there for you to try out.
If you’d like to add this to your existing Incredible PBX system, log into your system as root and edit extensions_custom.conf in /etc/asterisk. Add the following block of code just below the [from-internal-custom] context marker at the top of the file. Make certain you change the password on line 3 to something VERY SECURE if you provide outside access to this service. You don’t want creeps sending faxes to very expensive phone numbers on your nickel. Then restart Asterisk. Now execute the following commands to load the sample PDF documents onto your server:
cp fod-0.pdf fod-1.pdf
cp fod-0.pdf fod-2.pdf
cp fod-0.pdf fod-3.pdf
cp fod-0.pdf fod-4.pdf
cp fod-0.pdf fod-5.pdf
cp fod-0.pdf fod-6.pdf
cp fod-0.pdf fod-7.pdf
cp fod-0.pdf fod-8.pdf
cp fod-0.pdf fod-9.pdf
To test it out, dial 363 from an extension on your system. Enter a fax number when prompted, and then choose a document number to deliver by keying in 0 through 9. Press 1 to confirm your entries. Doesn’t get any simpler than that!
Where to Go Next. HylaFax and AvantFax are very mature open source products with a huge international following. We apologize for focusing primarily on U.S. and Canadian users today, but anything is possible with this software. The first piece you probably will want to tackle is adding Print to Fax capability on your Windows machine. The software you’ll need can be downloaded here. You’ll find excellent documentation on the setup by visiting the PBX in a Flash Forum. One little footnote for those using Windows 7. Microsoft and Apple are back to their old tricks so there are no Apple postscript print drivers in Windows 7. We’ve had equally good results using Dell’s 3100cn PS driver. Incidentally, there’s a similar print-to-fax utility for Mac OS X, but it’ll set you back $36. Here’s the link. HylaFax also maintains a terrific resource list for those that want additional goodies for PCs, Macs and Linux systems.
Originally published: Monday, May 2, 2011
Changes in PBX in a Flash Distribution. In light of the events outlined in our recent Nerd Vittles article and the issues with Asterisk 1.8.4, the PIAF Dev Team has made some changes in our distribution methodology. As many of you know, PBX in a Flash is the only distribution that compiles Asterisk from source code during the install. This has provided us enormous flexibility to distribute new releases with the latest Asterisk code. Unfortunately, Asterisk 1.8 is still a work in progress to put it charitably. We also feel some responsibility to insulate our users from show-stopping Asterisk releases. Going forward, the plan is to reserve the PIAF-Purple default install for the most stable version of Asterisk 1.8. As of June 1, Asterisk 126.96.36.199 is the new PIAF-Purple default install. Other versions of Asterisk 1.8 (newer and older) will be available through a new configuration utility which now is incorporated into the PIAF 188.8.131.52.2 ISO.
Here’s how it works. Begin the install of a new PIAF system in the usual way by booting from your USB flash drive and pressing Enter to load the most current version of CentOS 5.6. When the CentOS install finishes, your system will reboot. Accept the license agreement, and choose the PIAF-Purple option to load the latest stable version of Asterisk 1.8. Or exit to the Linux CLI if you want a different version. Log into CentOS as root. Then issue a command like this: piafdl -p beta_1841 (loads Asterisk 184.108.40.206), piafdl -p 184 (loads Asterisk 1.8.4), piafdl -p 1833 (loads Asterisk 220.127.116.11), or piafdl -p 1832 (loads Asterisk 18.104.22.168). If there should ever be an outage on one of the PBX in a Flash mirrors, you can optionally choose a different mirror for the payload download by adding piafdl -c for the .com site, piafdl -d for the .org site, or piafdl -e for the .net site. Then add the payload switch, e.g. piafdl -c -p beta_1841.
Bottom Line: If you use the piafdl utility to choose a particular version of Asterisk 1.8, you are making a conscious decision to accept the consequences of your particular choice. We would have preferred implementation of a testing methodology at Digium before distribution of new Asterisk releases; however, that doesn’t appear to be in the cards. So, as new Asterisk 1.8 releases hit the street, they will be made available through the piafdl utility until such time as our PIAF Pioneers independently establish their reliability.
whos.amung.us If you’re wondering what your fellow man is reading on Nerd Vittles these days, wonder no more. Visit our new whos.amung.us statistical web site and check out what’s happening. It’s a terrific resource both for us and for you.
New Vitelity Special. Vitelity has generously offered a new discount for PBX in a Flash users. You now can get an almost half-price DID and 60 free minutes from our special Vitelity sign-up link. If you’re seeking the best flexibility in choosing an area code and phone number plus the lowest entry level pricing plus high quality calls, then Vitelity is the hands-down winner. Vitelity provides Tier A DID inbound service in over 3,000 rate centers throughout the US and Canada. And, when you use our special link to sign up, the Nerd Vittles and PBX in a Flash projects get a few shekels down the road while you get an incredible signup deal as well. The going rate for Vitelity’s DID service is $7.95 a month which includes up to 4,000 incoming minutes on two simultaneous channels with terminations priced at 1.45¢ per minute. Not any more! For PBX in a Flash users, here’s a deal you can’t (and shouldn’t) refuse! Sign up now, and you can purchase a Tier A DID with unlimited incoming calls for just $3.99 a month and you get a free hour of outbound calling to test out their call quality. To check availability of local numbers and tiers of service from Vitelity, click here. Do not use this link to order your DIDs, or you won’t get the special pricing! After the free hour of outbound calling, Vitelity’s rate is just 1.44¢ per minute for outbound calls in the U.S. There is a $35 prepay when you sign up. This covers future usage and any balance is fully refundable if you decide to discontinue service with Vitelity.
Some Recent Nerd Vittles Articles of Interest…
- Yes, we’re aware that HylaFax theoretically supports T.38 with the right hardware. Feel free to point us to someone who has it actually working with Asterisk 1.8. [↩]
- Vitelity, Teliax, VoIPMyWay, and Future-Nine trunks require the following additional entries in your Inbound trunk settings: t38pt_rtp=no, t38pt_tcp=no, t38pt_udptl=no [↩]