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
Follow the instructions below to download and install Digium's Fax For
Asterisk or Digium's Free Fax For Asterisk. Technical support is only
provided for Digium's Fax For Asterisk customers. Users of Free Fax
For Asterisk are not entitled to any Digium technical support.
==[ Installation Overview ]===================================================
It is required that the proper version of Asterisk be installed prior to
installing Fax For Asterisk. Fax For Asterisk is currently supported on:
Open Source Asterisk branch 1.4 >= 1.4.22
Open Source Asterisk branch 1.6.2 >= 1.6.2.0
Open Source Asterisk branch 1.8 >= 1.8.0
Once you have a Fax For Asterisk license key, there are several tasks to
perform in order to install Fax For Asterisk.
1) Download and execute the 'register' utility to generate a valid
license.
2) Download and execute the 'benchfax' utility to determine the optimum
build.
3) Use the 'Fax Selector' web utility to determine the recommended
Fax For Asterisk download packages.
4) Download and install the 'res_fax' module for your platform.
5) Download and install the 'res_fax_digium' module for your platform.
The steps to complete these tasks are described in the Installation
Procedures section.
The register utility may be downloaded from:
http://downloads.digium.com/pub/register
The benchfax utility may be downloaded from:
http://downloads.digium.com/pub/telephony/fax/benchfax
The Fax Selector may be viewed from:
http://www.digium.com/en/docs/FAX/faa-download.php
The Fax For Asterisk binaries may be downloaded from:
http://downloads.digium.com/pub/telephony/fax
Notes:
- Supported software builds are provided for 32-bit and 64-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 Procedure ]==================================================
1) Download and execute the 'register' utility to generate a valid license.
1.1) Download the register utility to the root home directory of your
Asterisk server. First, log in as the user "root".
Command-line Example for 32-bit Linux:
# 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 utility 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' utility to select the optimum build.
There are various optimized versions of the fax module available for
different CPU types in both x86-32 and x86-64 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:
# cd /root
# wget http://downloads.digium.com/pub/telephony/fax/benchfax/x86-32/\
benchfax-1.1.0-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 utility and record the build that it recommends should
be used for your platform.
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 is a
version for Asterisk 1.6.2 releases. 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 indicate that
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.1.6' 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.2.0/x86-32/res_fax-1.6.2.0_1.1.6-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.2.0_1.1.6-x86_32.tar.gz
# cp /root/res_fax-1.6.2.0_1.1.6-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, there is a version
for Asterisk 1.6.2 releases, and a version for Asterisk 1.8 releases. 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.1.6' 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.2.0/x86-32/\
res_fax_digium-1.6.2.0_1.1.6-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.2.0_1.1.6-pentium4m_32.tar.gz
# cp /root/res_fax_digium-1.6.2.0_1.1.6-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 when convenient"
Notes:
- Asterisk will automatically restart once there are no active calls.
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
FAX Statistics:
---------------
Current Sessions : 0
Transmit Attempts : 0
Receive Attempts : 0
Completed FAXes : 0
Failed FAXes : 0
Digium G.711
Licensed Channels : 200
Max Concurrent : 0
Success : 0
Switched to T.38 : 0
Canceled : 0
No FAX : 0
Partial : 0
Negotiation Failed : 0
Train Failure : 0
Protocol Error : 0
IO Partial : 0
IO Fail : 0
Digium T.38
Licensed Channels : 200
Max Concurrent : 0
Success : 0
Canceled : 0
No FAX : 0
Partial : 0
Negotiation Failed : 0
Train Failure : 0
Protocol Error : 0
IO Partial : 0
IO Fail : 0
5.5) Copy the generated license files to a safe place as described in the
following Backup Procedure section.
==[ Backup Procedure ]=====================================================
It is extremely important that you backup all of the files located in the
/var/lib/asterisk/licenses directory. This 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 the need 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. Please note that Digium will not provide assistance with
Free Fax For Asterisk keys; support is only provided for paid Fax For
Asterisk customers.
==[ 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 Procedure 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.
==[ Asterisk CLI Commands ]===================================================
Fax For Asterisk provides the following Asterisk CLI commands:
"fax show capabilities" - Display the capabilities of the registered
Fax For Asterisk modules
"fax show hostid" - Display the Fax For Asterisk Host-ID
"fax show licenses" - Display the Fax For Asterisk licensing
information
"fax show session" - Display the status of the named fax sessions
"fax show sessions" - Display the current fax sessions
"fax show stats" - Display a summary of the fax session history
"fax show version" - Display the versions of the Fax For Asterisk
components
==[ AMI Actions ]=============================================================
Fax For Asterisk provides the following AMI actions:
"FaxLicenseList"
"FaxLicenseStatus"
These are explained in greater detail below.
- Issuing the "FaxLicenseList" AMI action will display all Fax For Asterisk
licenses and their loading status.
AMI Example:
Action: FaxLicenseList
Response: Success
Message: License list will follow
Event: FaxLicense
File: FAX-EXAMPLE1.lic
Key: FAX-EXAMPLE1
Product: RESFAX
Host-ID: ex:am:pl:e0:ex:am:pl:e0:ex:am:pl:e0:ex:am:pl:e0:ex:am:pl:e0
Ports: 200
Status: OK
Event: FaxLicenseList complete
- Issuing the "FaxLicenseStatus" AMI action will display Fax For Asterisk
license utilization.
AMI Example:
Action: FaxLicenseStatus
Response: Success
PortsLicensed: 200
==[ Technical Support ]=======================================================
For more help, customers of Fax For Asterisk and users of Free Fax For
Asterisk may visit the Fax For Asterisk category of the Digium
Knowledgebase:
http://kb.digium.com/?CategoryID=263
For customers of Fax For Asterisk only, if you have questions or concerns,
contact Digium Technical Support by phone, either toll-free within the US at
1.877.DIGIUM.1(1.877.344.4861) or directly at +1.256.428.6000. You may also
contact Digium Technical Support by visiting http://www.digium.com/support .
==============================================================================
