Foreword from Joe Roper
This script was created by Joe Roper for a recent project - which he then modified for use with PBXIAF.
===================================
Installation and Configuration of HylaFAX and AvantFax for Basic Fax Services on PBXIAF.
I suppose faxes are one of the things I consider to be a “necessary evil”. In this day and age, there’s a lot of better ways to move documents around than pushing paper through a fax machine. But a lot of individuals and even more businesses can’t seem to break the fax habit. So much in fact that faxing must be in the top three requested functions of a pbx.
But reliable faxing via PBX – especially with any degree of ease of use, has proven somewhat elusive. Right here in the forums, you can find information covering at least two different sets of software and methodologies for faxing with your PBX.
And yet – there are still more alternatives for us to explore! Aren’t choices grand?
HylaFAX and AvantFax
Among the fax software available for free use, one of the most recognized and supported programs is Hylafax. HylaFAX is considered to be a robust system capable of handling multiple modems and a heavy traffic load – while not being so complex and cumbersome as to make it undesirable for the smaller installation.
AvantFax web based software allows for immediate and easy access to the fax server via web interface – without ever having to install a fax client on the user’s machine.
The combination includes everything needed for a complete solution – able to send and receive faxes – that’s simple enough for the home user, and robust enough for the enterprise.
But Great Zeus – getting the HylaFax and AvantFax software to install and operate – well lets say it’s not a job for the rushed, or timid.
The good news is forum friend and guru Joe Roper has just blown the doors off by releasing a completely open source installation script that gets these two programs working with great results on our PBXIAF boxes!
Prerequisites / Notices
We believe that this solution will co exist with Ward's Fax program, as they use very different methodologies to send and receive faxes; although this has not been thoroughly tested. However, it may not be compatible with other fax experiments you may have performed – so any such previous systems should be removed before attempting to install this solution.
This installation script has been adapted specifically for PBXIAF by Joe Roper – and has not been tested on any other distribution. In the spirit of Open Software being “open”, the scripts are not compiled, nor are contents obfuscated in any way. You are free to open it, read it, change it, and make it work in your own environment. It’s also a great learning tool to see how things work “under the hood”.
That’s not even the best part! The best part is the script completes the installation, and creates most of the configuration items inside FreePBX, usually in less than 5 minutes.
Installing HylaFax/Avantfax
Log into your PBX as root (in putty or your favorite program), and execute the following lines:
(Thanks to forum user jack for pointing out we needed to run update-fixes!)
During the installation, you will be prompted for information several times. Press ENTER and accept the defaults in each case.
Note1: This link pulls the most current version from SVN, which may be buggy. Previous/released versions can be found here.
Note2: This fax installation does not require actual modems in any way; Instead, virtual IAX2 modems are configured on the platform. These virtual modems don’t care wheather they are communicating over VoIP, zaptel, or dahdi trunks. They simply use whatever trunks we assign to them.
Installing HylaFax WebMin Module
To make final configuration of the fax software painless - we want to install an additional management tool. This will expose more of the configuration settings on the fax server, and allow us to configure in a graphic environment.
In this case, that tool is a plugin, or module, for the Webmin program.
If you don’t have WebMin – you can’t use this management tool. WebMin is generally available by Icon from the Admin Menu. If for some reason you don’t see the Icon, you can try going to : http://yourpbx:9001
Step 1: Download WebMin Module from this location, and save it to your workstation someplace you can find it again - such as your desktop.
Step 2: Log Into WebMin as root. Form under WebMin, Webmin Configuration, Select WebMin Modules.
Step 3: Select From uploaded file radio button, and then click the BROWSE button. From the browse dialog box, select the module file you downloaded to your workstation in step 1, above. Finally, click INSTALL MODULE button at the bottom of the page.
WebMin will inform you of its success after the installation is completed.
Using HylaFax WebMin Management Module
The HylaFax webmin module is used primarily to set defaults and other configuration items which or not readily available in a user interface elsewhere.
Step 1: Log Into WebMin as root. Form under Servers, Select HylafaxServer.
You will be presented with a list of 4 (virtual) iax modems. Don’t be concerned if they do not show running and idle immediately, you may need to recheck status.
Step 2: Configuration Options should be reviewed for correctness for your particular PBX installation, starting with General Options.
General
Vertical Resolution: If left unselected, will default to regular resolution – which is pretty nasty looking, but faster to send. We decided to make our faxes look their best, so we select HIGH for high resolution faxes. (And wait till you see the amazing quality you are able to send. Never again hear that the fax recipient couldn’t read your fax!) During testing – the quality of sent and received faxes form this system was nothing short of tremendous.
Like any newly installed program, care should be taken not to over stimulate the new arrival by excessive unnecessary configuration changes. My advice is change only what you must, until you get the system working fully – THEN you can go back and configure it until it doesn’t work any more.
Make other changes here which you believe are necessary – and click Update.
IAX Modems
The software as deployed comes with 4 IAX2 modems preinstalled.
IAX2 Modems are virtual modems, that work in place of actual physical modems in the system.
The relationship between the various parts of this solutions are like this:
Advantfax => hylafax => Modem => asterisk
The IAX2 modems registered as 4 peers in asterisk. This can be demonstrated by typing IAX2 show peers in the asterisk CLI.
An important security feature is that the IAX modems do not register with a user name and password, they authenticate based on the IP address that they come from, using the permit and deny statements. This completely prevents anyone surreptitiously connecting to them for purposes of wrong-doing.
As a result, should you remove an iax2 modem context from the iax_custom.conf file, you must also remove the corresponding IAX modem from /etc/iaxmodem. Failure to do so will cause many thousands of registration attempts per second, forcing your processor utilization through the roof, and your PBX to its knees.
NOTE: There is no need to remove any of the 4 IAX2 modems from the system – this information is provided as an advisory only.
The following changes are suggested for each of the 4 IAX virtual modems:
Area Code = Set to your local area code
Country code, long distance calls prefix, and international calls prefix: Edit to suit your specific circumstances.
Fax number = the number you receive faxes on
The remaining settings should generally be left unchanged.
See HylaFAX / AvantFax for your PBXIAF! - Part2
This script was created by Joe Roper for a recent project - which he then modified for use with PBXIAF.
===================================
Installation and Configuration of HylaFAX and AvantFax for Basic Fax Services on PBXIAF.
I suppose faxes are one of the things I consider to be a “necessary evil”. In this day and age, there’s a lot of better ways to move documents around than pushing paper through a fax machine. But a lot of individuals and even more businesses can’t seem to break the fax habit. So much in fact that faxing must be in the top three requested functions of a pbx.
But reliable faxing via PBX – especially with any degree of ease of use, has proven somewhat elusive. Right here in the forums, you can find information covering at least two different sets of software and methodologies for faxing with your PBX.
And yet – there are still more alternatives for us to explore! Aren’t choices grand?
HylaFAX and AvantFax
Among the fax software available for free use, one of the most recognized and supported programs is Hylafax. HylaFAX is considered to be a robust system capable of handling multiple modems and a heavy traffic load – while not being so complex and cumbersome as to make it undesirable for the smaller installation.
AvantFax web based software allows for immediate and easy access to the fax server via web interface – without ever having to install a fax client on the user’s machine.
The combination includes everything needed for a complete solution – able to send and receive faxes – that’s simple enough for the home user, and robust enough for the enterprise.
But Great Zeus – getting the HylaFax and AvantFax software to install and operate – well lets say it’s not a job for the rushed, or timid.
The good news is forum friend and guru Joe Roper has just blown the doors off by releasing a completely open source installation script that gets these two programs working with great results on our PBXIAF boxes!
Prerequisites / Notices
We believe that this solution will co exist with Ward's Fax program, as they use very different methodologies to send and receive faxes; although this has not been thoroughly tested. However, it may not be compatible with other fax experiments you may have performed – so any such previous systems should be removed before attempting to install this solution.
This installation script has been adapted specifically for PBXIAF by Joe Roper – and has not been tested on any other distribution. In the spirit of Open Software being “open”, the scripts are not compiled, nor are contents obfuscated in any way. You are free to open it, read it, change it, and make it work in your own environment. It’s also a great learning tool to see how things work “under the hood”.
That’s not even the best part! The best part is the script completes the installation, and creates most of the configuration items inside FreePBX, usually in less than 5 minutes.
Installing HylaFax/Avantfax
Log into your PBX as root (in putty or your favorite program), and execute the following lines:
Code:
[FONT=Arial]cd /root[/FONT]
[FONT=Arial]wget [URL]http://projects.colsolgrp.net/projects/afax/repository/raw/a-fax.sh[/URL] (Link updated 9/22/10) *See Note 1[/FONT]
[FONT=Arial]chmod +x [COLOR=#2f6084]a-fax.sh[/COLOR] [/FONT]
[FONT=Arial]./[COLOR=#2f6084]a-fax.sh[/COLOR] [/FONT]
[FONT=Arial]update-fixes[/FONT]
During the installation, you will be prompted for information several times. Press ENTER and accept the defaults in each case.
Note1: This link pulls the most current version from SVN, which may be buggy. Previous/released versions can be found here.
Note2: This fax installation does not require actual modems in any way; Instead, virtual IAX2 modems are configured on the platform. These virtual modems don’t care wheather they are communicating over VoIP, zaptel, or dahdi trunks. They simply use whatever trunks we assign to them.
Installing HylaFax WebMin Module
To make final configuration of the fax software painless - we want to install an additional management tool. This will expose more of the configuration settings on the fax server, and allow us to configure in a graphic environment.
In this case, that tool is a plugin, or module, for the Webmin program.
If you don’t have WebMin – you can’t use this management tool. WebMin is generally available by Icon from the Admin Menu. If for some reason you don’t see the Icon, you can try going to : http://yourpbx:9001
Step 1: Download WebMin Module from this location, and save it to your workstation someplace you can find it again - such as your desktop.
Step 2: Log Into WebMin as root. Form under WebMin, Webmin Configuration, Select WebMin Modules.
Step 3: Select From uploaded file radio button, and then click the BROWSE button. From the browse dialog box, select the module file you downloaded to your workstation in step 1, above. Finally, click INSTALL MODULE button at the bottom of the page.
WebMin will inform you of its success after the installation is completed.
Using HylaFax WebMin Management Module
The HylaFax webmin module is used primarily to set defaults and other configuration items which or not readily available in a user interface elsewhere.
Step 1: Log Into WebMin as root. Form under Servers, Select HylafaxServer.
You will be presented with a list of 4 (virtual) iax modems. Don’t be concerned if they do not show running and idle immediately, you may need to recheck status.
Step 2: Configuration Options should be reviewed for correctness for your particular PBX installation, starting with General Options.
General
Vertical Resolution: If left unselected, will default to regular resolution – which is pretty nasty looking, but faster to send. We decided to make our faxes look their best, so we select HIGH for high resolution faxes. (And wait till you see the amazing quality you are able to send. Never again hear that the fax recipient couldn’t read your fax!) During testing – the quality of sent and received faxes form this system was nothing short of tremendous.
Like any newly installed program, care should be taken not to over stimulate the new arrival by excessive unnecessary configuration changes. My advice is change only what you must, until you get the system working fully – THEN you can go back and configure it until it doesn’t work any more.
Make other changes here which you believe are necessary – and click Update.
IAX Modems
The software as deployed comes with 4 IAX2 modems preinstalled.
IAX2 Modems are virtual modems, that work in place of actual physical modems in the system.
The relationship between the various parts of this solutions are like this:
Advantfax => hylafax => Modem => asterisk
The IAX2 modems registered as 4 peers in asterisk. This can be demonstrated by typing IAX2 show peers in the asterisk CLI.
An important security feature is that the IAX modems do not register with a user name and password, they authenticate based on the IP address that they come from, using the permit and deny statements. This completely prevents anyone surreptitiously connecting to them for purposes of wrong-doing.
As a result, should you remove an iax2 modem context from the iax_custom.conf file, you must also remove the corresponding IAX modem from /etc/iaxmodem. Failure to do so will cause many thousands of registration attempts per second, forcing your processor utilization through the roof, and your PBX to its knees.
NOTE: There is no need to remove any of the 4 IAX2 modems from the system – this information is provided as an advisory only.
The following changes are suggested for each of the 4 IAX virtual modems:
Area Code = Set to your local area code
Country code, long distance calls prefix, and international calls prefix: Edit to suit your specific circumstances.
Fax number = the number you receive faxes on
The remaining settings should generally be left unchanged.
See HylaFAX / AvantFax for your PBXIAF! - Part2