Welcome to the Asterisk FAX Gateway Trac Instance

This project is changing rapidly and while I am making changes in the Git Master branch, this documentation will lag behind.

02/14/2010: Configuration file change. Reverse the use of Channel vs. Context/Extension in the generated call file allows us to use  Asterisk's REASON variable for better evaluation of problems. This requires the addition of the "failed" extension in the [sendfax] context.

11/28/2009: In addition to working with the built in app_fax application in Asterisk 1.6, Asterisk FAX Gateway has been modified to work with Asterisk versions 1.4 & 1.6 using  Digium's Fax For Asterisk licensed res_fax and res_fax_digium binary modules.

Asterisk FAX Gateway is a bash script designed to interconnect  Asterisk 1.6 with your Mail Transport Agent. Currently, the biggest issue with regard to Asterisk and faxing is how to get faxes into and out of Asterisk. This bash script relies on a host of freely available software to create fax documents originating as e-mails from your MTA and send them out through Asterisk using the SendFAX application. It also takes faxes from Asterisk and routes them to e-mail recipients. I wanted to create a single script that would do both of these functions, complete with end user e-mail notifications, delivery status notifications (DSN), etc.

I was inspired to write this script using various bits and pieces from the  HylaFax,  HylaFax+,  mail2fax and  fax2mail scripts and owe credit to the creators of those respective programs.

As the program changes, the documentation and configuration will change as well. I hope this has helped explain some of my process. If you have questions or would like to contribute, please e-mail me at (amessina AT messinet DOT com) mailto:amessina@….

Features

  • Employs free, open-source software for the fax to e-mail and e-mail to fax conversion and dirty work
  • End user notification
  • Delivery Status Notification
  • Optional outbound sender lookup (LDAP) to provide more specific cover page and accounting information. (PostgreSQL and MySQL lookup examples are not yet implemented)

Download / Git Clone

As of July 31, 2009, the Asterisk FAX Gateway Trac Instance no longer uses  Subversion and now sits atop a  Git repository.

Documentation/Installation

As the job of this script is intended to pull together the excellent work of many other programs into a useful function, there are many individual bits of configuration in order to create a working Asterisk FAX Gateway. Mind you, none of them are really that difficult.

Program Dependencies

You will need the following programs installed and available for use by the user under which your Asterisk server runs. In  Fedora Linux, these programs are already available in pre-packaged binary RPMs.

  •  Asterisk: The script has been designed and tested with Asterisk 1.6's app_fax application. Initial work to inter operate with  Digium's Fax For Asterisk licensed res_fax and res_fax_digium binary modules is here 57.
  • Mail Transport/Processing Agent, including the 'sendmail' command or sendmail.postfix' replacement command: I use  Postfix exclusively and could use some help documenting how to implement this solution with  Sendmail,  Procmail and other MTAs.
  •  GNU Coreutils: for various system commands including base64, basename, cat, cp, csplit, date, echo, mv, and rm. Other required system commands include  awk,  grep,  gzip,  sed and  tar.
  •  OpenOffice.org using  PyUNO: for fax document conversion and cover page creation
  •  Ghostscript: for the creation of fax-suitable TIFF files
  •  LibTIFF: (tiff2pdf, tiff2ps, tiffcp) for tiff manipulation

Optional Program Dependencies

If you would like to extend the functionality of the Asterisk FAX Gateway with sender information lookups, you will need:

Filesystem Configuration

The easiest way to get started is to clone the development repository using Git.

  • The following will create a "fax-gw" sub directory with the appropriate files: 
    cd /usr/share/asterisk/agi-bin
git clone git://messinet.com/fax-gw.git
  • Ensure that fax-gw.agi is executable by the user under which Asterisk runs.
  • Then create the an ARCHIVE directory owned by the user and group under which Asterisk runs (as appropriate for your system): 
    mkdir -p /var/spool/asterisk/fax-gw/archive

Mail Transport/Processing Configuration

OpenOffice.org Configuration

While there is no specific configuration required for OpenOffice.org itself, it is important that you obtain and install the related binaries on your system. For a  Fedora Linux system, OpenOffice.org packages are quite segmented, requiring a large number of packages to satisfy program dependencies. The more of the required packages you have installed, the more types of files you should be able to convert and fax! 

openoffice.org-brand
openoffice.org-calc
openoffice.org-calc-core
openoffice.org-core
openoffice.org-draw
openoffice.org-draw-core
openoffice.org-graphicfilter
openoffice.org-headless
openoffice.org-impress
openoffice.org-impress-core
openoffice.org-opensymbol-fonts
openoffice.org-pdfimport
openoffice.org-presenter-screen
openoffice.org-pyuno
openoffice.org-ure
openoffice.org-writer
openoffice.org-writer-core

Asterisk Dialplan Configuration

Asterisk's dialplan configuration is currently different depending on which FAX module you are using.

Asterisk FAX Gateway Configuration

Edit the fax-gw.conf file to suit your system, ensuring that the configuration options, file names and file system paths you have chosen are consistent across the manager.conf, fax-gw.conf, and extensions.conf files.

Define a spool directory to which both Asterisk and your MTA can read and write. 

spool="/var/spool/asterisk/fax-gw/spool.$pid"

Define the archive directory. This is also the directory where received faxes will be created (whether or not you want to archive them.) 

archive="/var/spool/asterisk/fax-gw/archive"

Define the log file. 

log="/var/log/asterisk/fax-gw.log"

Define the location of your OpenOffice.org binary. It seems to be important to NOT choose the /usr/bin/soffice general binary, as it only spawns the real binary below. As Asterisk FAX Gateway will attempt to shutdown the originated OpenOffice.org process after conversion, we don't want to have the parent process left open. 

oo_binary="/usr/lib64/openoffice.org3/program/soffice.bin"

Define the OpenOffice.org cover page template. 

oo_cover="$astagidir/fax-gw/templates/cover_default.ott"

Define the e-mail address of your preferred administrator for notifications. 

faxmaster="faxmaster"

Define the e-mail address which is to be Blind Carbon Copied on all faxes. An empty value here ("") will disable the use blind carbon copying. 

bcc=""

Define the preferred file format of received faxes and notifications of sent faxes. This can by any one or combination of "pdf, ps or tif", separated by spaces, such as "pdf tif". Leaving this parameter blank disables sending faxes as attachments, see "LINK" below. 

attach_type="pdf"

Define the URL from which archived (sent and received) faxes may be obtained. This feature enables you to add a link in the e-mail that will download the FAX from the archive. You will need to set up the proper configuration in the server of your choice (http, ftp, rsync, etc.) which maps the location of the URL to pull the file from your "ARCHIVE" directory, defined above. It is also suggested that you enable user authentication/authorization for this feature. A sample configuration block for Apache is listed. 

link="https://your-domain.com/fax"

# --- Begin Apache Asterisk FAX Gateway Archive Configuration ---  #
Alias /fax /var/spool/asterisk/fax-gw/archive
<Directory /var/spool/asterisk/fax-gw/archive>
  Options None
  AllowOverride None
  AuthType Basic
  AuthBasicProvider ldap
  AuthName "Asterisk FAX Gateway Archive"
  AuthLDAPURL ldap://ldap.your-domain.com:389/ou=People,dc=your-domain,dc=com?uid?one?(objectClass=posixAccount)
  AuthzLDAPAuthoritative On
  Require ldap-user faxuser1 faxuser2
  Order allow,deny
  Allow from all
</Directory>
# --- End Apache Asterisk FAX Gateway Archive Configuration ---  #

Define, in seconds, the maximum time this script is allowed to run before terminating itself (using an until loop). This should be less than the 'fax_time_limit' parameter defined in Postfix's main.cf. 

timeout="600"

Asterisk Variable Configuration

Define the context previously created in extensions.conf from which outbound (destination leg) of the calls originate. 

ast_context="outbound-fax"

Define Caller*ID, Call Detail Record and Asterisk account information, including the SendFAX and ReceiveFAX LOCALHEDERINFO and LOCALSTATIONID information. These variables should always be set with default values that apply to your system. They can be modified on a per call basis, however; see "Asterisk FAX Gateway Optional Sender Lookup Configuration" below. 

ast_clid_name="Asterisk FAX Gateway"
ast_clid_num="7735551234"
ast_account="7735551234"
ast_localheaderinfo="Asterisk FAX Gateway"
ast_localstationid="+1 773 555 1234"

Asterisk FAX Gateway Optional Sender Lookup Configuration

If you wish to enable the ability to lookup additional sender information in order to make your cover pages and account codes more useful, you can define the "lookup_type" variable with the type of external lookup you wish to perform (one of ldap, mysql or pgsql). You should then set the related variables within the fax-gw.conf file. It is important to note that the sender can only be reliably looked up by email address. If the "lookup_type" variable is NOT empty, the "lookupSender" function will be called from the "fax-gw" bash script as follows: 

 lookupSender $lookup_type "<lookup_mail>"

Define the "lookup_type" variable with the type of lookup you will perform, then configure the related variables within the lookupSender function itself. 

# --- Begin LDAP Lookup Variables --- #
ldap_uri="ldap://ldap.your-domain.com:389"
ldap_dn="uid=asterisk,ou=People,dc=your-domain,dc=com"
ldap_pass="asterisk"
ldap_base="ou=People,dc=your-domain,dc=com"
ldap_scope="sub"
ldap_use_tls="FALSE"
lookup_by_mail_attrs=( cn homeFacsimileTelephoneNumber homePhone mail )
lookup_by_num_attrs=( cn facsimileTelephoneNumber homeFacsimileTelephoneNumber otherFacsimileTelephoneNumber mail )
ast_account_attr="homePhone"
ast_clid_name_attr="cn"
ast_clid_num_attr="homeFacsimileTelephoneNumber"
lookup_by_num_mail_attr="mail"
lookup_by_num_name_attr="cn"
localheaderinfo_attr="cn"
localstationid_attr="homeFacsimileTelephoneNumber"
# --- End LDAP Lookup Variables --- #

SELinux Configuration/Notes

I currently run this script on a system that is using SELinux in "permissive" mode. A part of the goal of this script is to achieve SELinux compatibility, though that might be a long haul. I would appreciate testing in this area. While the script is still in heavy development, the system paths (and therefore the SELinux contexts) may change, so I haven't settled on anything yet.

If you use Postfix as your MTA, the spool directory, the "/var/spool/asterisk/fax-gw" directory and all files and sub directories need to be labeled with the proper SELinux context: system_u:object_r:mail_spool_t:s0. Issue the following commands to set the default file context for the directory and relabel the directory and its contents with the new SELinux file context: 

semanage fcontext -a -t postfix_spool_t "/var/spool/asterisk/fax-gw(/.*)?"
restorecon -FRv /var/spool/asterisk/fax-gw

If you are not using Postfix as your MTA, you should substitute "mail_spool_t" instead of "postfix_spool_t" in the command above. You also need to allow Postfix to write to the local mail spool: 

setsebool -P allow_postfix_local_write_mail_spool=1