Asterisk Fax Readme/Installation
From Asterisk Australia
Contents |
Digium's Fax For Asterisk README
Digium offers a commercially-licensed software Fax solution that is compatible with Asterisk and provides a high level of interoperability with Fax products used around the world. Please visit the following web address to read more about this product and to purchase license keys:
http://store.digium.com/productview.php?product_code=816-00003
Then, follow the instructions below to download and install Digium's Fax For Asterisk.
Installation Overview
Once you have your Fax For Asterisk license key there are several tasks to install Fax For Asterisk.
1) Download and execute the 'register' tool to generate a valid license. 2) Download and execute the 'benchfax' tool to select the optimum build. 3) Use the 'Fax Selector' web utility to determine your required components. 4) Download and install the 'res_fax' module for your system. 5) Download and install the 'res_fax_digium' module for your system.
The steps to complete these tasks are described in the next section, Installation Instructions.
The register utility, Fax For Asterisk binaries, and benchfax utility may be downloaded from the following locations:
http://downloads.digium.com/pub/register http://downloads.digium.com/pub/telephony/fax http://downloads.digium.com/pub/telephony/fax/benchfax
Notes:
- Supported software builds are provided for 32-bit x86 platforms, optimized for a variety of processors. Choose the directory that describes your Asterisk version and processor architecture. Inside those directories you will see TAR files containing the fax modules for each type of processor supported.
Installation Instructions
1) Download and execute the 'register' tool to generate a valid license.
1.1) Download the register utility to the root home directory of your Asterisk server.
- Command-line example for 32-bit Linux:
# Log in as root or use the "su" command to assume root privileges. cd /root wget http://downloads.digium.com/pub/register/x86-32/register
1.2) Change the permissions of the /root/register file to r-x------.
- Command-line example:
chmod 500 /root/register
1.3) Run the register tool and follow the interactive instructions.
Internet access is required from your Asterisk server in order to register your Fax For Asterisk key for licensed use. Outgoing network traffic to TCP port 443 (SSL) must be allowed in order for the register utility to successfully communicate with Digium's license server and complete the registration process. The registration utility will prompt you for your Fax For Asterisk license key.
- Command-line example:
/root/register
2) Download and execute the 'benchfax' tool to select the optimum build.
There are various optimized versions of the fax module available for different commonly available CPU types in x86-32 architectures. To determine which build of the module performs best on your system, the 'benchfax' utility will run a series of tests and report which fax module will maximize performance on your system.
2.1) Download the benchfax utility to the root home directory of your Asterisk server.
- Command-line example for 32-bit Linux:
# Log in as root or use the "su" command to assume root privileges. cd /root wget http://downloads.digium.com/pub/telephony/fax/benchfax/x86-32/benchfax-1.0.5-x86_32 -O benchfax
2.2) Change the permissions of the /root/benchfax file to r-x------.
- Command-line example:
chmod 500 /root/benchfax
2.3) Run the benchfax tool and record the 'flavor' that it recommends that you use on your system.
- Command-line example:
/root/benchfax
3) Use the 'Fax Selector' web utility to determine your required components.
Depending upon your version of Asterisk and processor architecture, different components are required for the use of Fax For Asterisk. Digium provides a 'Fax Selector' web utility in order to assist with choosing the correct components. The 'Fax Selector' web utility should be viewed with a standard web browser and may be accessed via the following URL:
http://www.digium.com/en/docs/FAX/faa-download.php
The files that the Fax Selector utility informs you are required for your platform should be the files that you use in place of the examples provided in steps 4 and 5 of this section.
4) Download and install the 'res_fax' build for your platform.
If the 'Fax Selector' web utility used in step 3 did not indicate that a 'res_fax' download is required for your system, please skip to step 5.
There are different versions of 'res_fax' for various Asterisk releases; there is a single version for Asterisk 1.4.22 and above, and there are versions for Asterisk 1.6.x point releases (1.6.0, 1.6.1, etc.). Note that these modules are *not* loadable in prior releases of Asterisk, only the specific version they are designed to be used with. Please be sure that you download the correct version of 'res_fax' for your Asterisk version, as recommended by the 'Fax Selector' in step 3. Note that the 'Fax Selector' utility may indicatethat for your version of Asterisk a 'res_fax' download is not required.
In addition, there are frequently updated builds of 'res_fax' posted, and each build has a 'version number'. This version number is part of the filename, and is also included in the copyright/license messsage that is displayed when the module is loaded into Asterisk. In this document, build number '1.0.3' has been used as an example, but when you read this document the current build number may be different (higher).
4.1) Download res_fax to the root home directory of your Asterisk server.
- Command-line example for 32-bit Linux:
wget http://downloads.digium.com/pub/telephony/fax/res_fax/asterisk-1.6.0/x86-32/res_fax-1.6.0_1.0.3-x86_32.tar.gz
4.2) Expand the res_fax archive and copy the res_fax.so file to the
/usr/lib/asterisk/modules directory
- Command-line example:
tar xzvf res_fax-1.6.0_1.0.3-x86_32.tar.gz cp /root/res_fax-1.6.0_1.0.3-x86_32/res_fax.so /usr/lib/asterisk/modules
5) Download and install the 'res_fax_digium' build for your platform.
There are different versions of the binary for various Asterisk releases; there is a single version for Asterisk 1.4.22 and above, and there are versions for Asterisk 1.6.x point releases (1.6.0, 1.6.1, etc.). Note that these modules are *not* loadable in prior releases of Asterisk, only the specific version they are designed to be used with. Please be sure that you download the correct version of 'res_fax_digium' for your Asterisk version, as recommended by the "Fax Selector" web utility in step 3.
In addition, there are frequently updated builds of 'res_fax_digium' posted and each build has a 'version number'. This version number is part of the filename, and is also included in the copyright/license message that is displayed when the module is loaded into Asterisk. In this document, build number '1.0.3' has been used as an example, but when you read this document the current build number may be different (higher).
5.1) Download res_fax_digium to the root home directory of your Asterisk server, replacing 'pentium4m' in the example with the flavor recommended by the benchfax utility.
- Command-line example:
wget http://downloads.digium.com/pub/telephony/fax/res_fax_digium/asterisk-1.6.0/x86-32/res_fax_digium-1.6.0_1.0.3-pentium4m_32.tar.gz
5.2) Expand the res_fax_digium archive and copy the res_fax_digium.so file
to the /usr/lib/asterisk/modules directory
- Commmand-line example:
tar xzvf res_fax_digium-1.6.0_1.0.3-pentium4m_32.tar.gz cp /root/res_fax_digium-1.6.0_1.0.3-pentium4m_32/res_fax_digium.so /usr/lib/asterisk/modules
5.3) Asterisk must be restarted in order to load your new Fax For Asterisk
licensed channels. (See General Notes to use multiple licenses on one server.)
- Command-line example:
asterisk -rx "restart now"
5.4) Verify that the number of Fax For Asterisk licensed channels available
to Asterisk matches the number of Fax For Asterisk licensed channels that you purchased. This can be verified by issuing "fax show stats" in the Asterisk CLI. Take into consideration any previous Fax For Asterisk licensed channels that you may have already had registered to your Asterisk server before verifying this number.
* Command Line Example * asterisk -rvvv *CLI> fax show stats Current Sessions :10 Transmit Attempts :13 Receive Attempts :13 Completed Faxes :16 Failed Faxes :0
Digium G711 : Licensed Channels :15 Max Concurrent :10 Success :16
5.5) Copy the generated license files to a safe place as described in the
following Backup Instructions.
Installation summary:
- Command-line installation example for the Pentium 4M and Asterisk 1.6.0
on a 32-bit Linux installation, using the benchfax tool: * Log in as root or use the "su" command to assume root privileges. cd /root wget http://downloads.digium.com/pub/register/x86-32/register chmod 500 /root/register /root/register wget http://downloads.digium.com/pub/telephony/fax/benchfax/x86-32/benchfax-1.0.5-x86_32 -O benchfax chmod 500 /root/benchfax # 'Fax Selector' tool may note that res_fax download is not required for your platform. # If so, move on to the next wget wget http://downloads.digium.com/pub/telephony/fax/res_fax/asterisk-1.6.0/x86-32/res_fax-1.6.0_1.0.3-x86_32.tar.gz tar xzvf res_fax-1.6.0-1.0.3-x86_32.tar.gz cp /root/res_fax-1.6.0-1.0.3-x86_32/res_fax.so /usr/lib/asterisk/modules # benchfax will suggest the best flavor for your system. # 'pentium4m' is used in this example wget http://downloads.digium.com/pub/telephony/fax/res_fax_digium/asterisk-1.6.0/x86-32/res_fax_digium-1.6.0_1.0.3-pentium4m_32.tar.gz tar xzvf res_fax_digium-1.6.0_1.0.3-pentium4m_32.tar.gz cp /root/res_rax_digium-1.6.0_1.0.3-pentium4m_32/res_fax_digium.so /usr/lib/asterisk/modules asterisk -rx "restart now"
Backup Instructions
- It is VERY IMPORTANT to backup the license(s) generated by your system.
The /var/lib/asterisk/licenses directory contains the Host-ID specific license files for your system. These license files are tied to the MAC address of all the ethernet devices installed in your system. Creating a backup of this directory will allow you to restore your Fax For Asterisk license file in case you need to reinstall your operating system. This will help prevent you from needing to contact Digium to request authorization to increment your Fax For Asterisk key and from needing to purchase a new Fax For Asterisk key if you exceed the maximum number of Fax For Asterisk key increments allowed.
General Notes
- Multiple Fax For Asterisk keys may be registered to the same Asterisk server. This will allow you to increase the total number of available Fax For Asterisk licensed channels on your Asterisk server. New Fax For Asterisk keys may be registered to your Asterisk server using the same instructions provided in the Installation Instructions section. There will be an additional Fax For Asterisk license file generated in the /var/lib/asterisk/licenses directory for each Fax For Asterisk key that is successfully registered to your Asterisk server. It is extremely important that you follow the instructions provided in Backup Procedure section whenever a new Fax For Asterisk key is successfully registered to your Asterisk server. - A Fax For Asterisk key must be re-registered if any of the Ethernet devices in your Asterisk server are changed, added, or removed. The unique Fax For Asterisk license file which is located in your /var/lib/asterisk/licenses directory is tied to the MAC address of all the Ethernet devices installed in your system. A Fax For Asterisk key can only be re-registered once without authorization from Digium. Digium must be contacted by phone in order to request authorization to have your Fax For Asterisk key incremented. Digium reserves the right to deny authorization for having a Fax For Asterisk key incremented. - It is not required or suggested to specify a load line in the /etc/asterisk/modules.conf for the res_fax.so or res_fax_digium.so files. Asterisk will automatically load them using the autoload option. The autoload option is set on by default.
Technical Support
For more help, please visit the Fax For Asterisk category of the Digium Knowledgebase:
http://kb.digium.com/?CategoryID=263
For interactive assistance, contact the Digium Technical Support Department by phone, either toll-free within the US at 1-877-DIGIUM-1 (1 877 344 4861) or directly at +1 256 428 6000, if you have any questions or concerns. You may also contact Digium Technical Support by email at support@digium.com.