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 . ==============================================================================