- Recent Changes
- SELinux Limitations
FAX Gateway is a GNU Bash script designed to interconnect Asterisk FAX support 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's SendFAX application. It also receives faxes from Asterisk's ReceiveFAX application and routes them to e-mail recipients. I wanted to create a program that would do both of these functions, complete with a wide range of document conversion capabilities, end user e-mail notifications, MTA delivery status notifications and enhanced mail system status codes.
I hope this has helped explain some of my process. If you have questions or would like to contribute, please e-mail me at mailto:email@example.com.
- Ability to convert a wide range of documents including:
- Employs entirely free and open source software for the fax to e-mail and e-mail to fax conversion and dirty work
- End user e-mail notification
- Retries and end user runtime option modification
- UTF-8 character set support
- Delivery Status Notifications RFC 3461 & Enhanced Mail System Status Codes RFC 3463
- Optional outbound recipient & sender information LDAP, MySQL, or PostgreSQL lookup to provide more specific cover page and accounting information
FAX Gateway is currently stable, though under active development for new features and improvements. As the program changes, the documentation and configuration will change as well.
- View all open tickets by priority
- View all tickets by priority (including closed)
- Submit a new ticket
- Top 3 open tickets by priority:
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 FAX Gateway. Mind you, none of them are really that difficult.
Required Program Dependencies
You will need the following programs installed and available for use by the user under which your Asterisk server runs. In Red Hat Enterprise Linux, CentOS, and Fedora Linux, these programs are already available in pre-packaged binary RPMs.
- Asterisk: The script has been designed and tested with the res_fax_spandsp.so module in Asterisk versions 1.8, 10, and 11, the app_fax.so module in Asterisk version 1.6, and Digium's Fax For Asterisk licensed res_fax_digium.so binary module.
- Fine Free File Command: for determining file types
- GNU Bash: FAX Gateway requires the GNU Bourne-Again Shell >= 3.2.
- GNU Coreutils: for various system commands including cat, cp, csplit, date, echo, head, mv, rm and wc. Other required system commands include flock, grep, gzip, sed and tar.
- GraphicsMagick for conversion and creation of high-quality, fax-suitable TIFF (Group 4) files
- LibreOffice or OpenOffice.org using PyUNO: for Open Document Format for Office Applications (ODF) and Microsoft Office document conversion and cover page creation
- 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.
- The Poppler pdftoppm binary: for high-quality PDF rasterization
- VM (View Mail) for Emacs: for reliable decoding of base64 and quoted-printable e-mail attachments
Optional Program Dependencies
If you would like to extend the functionality of the FAX Gateway with recipient and sender information lookups, you will need any or all of:
Fedora & Enterprise Linux RPM Installation
The preferred installation method for applicable systems is via RPM package install. See the Messinet Secure Services RPM Repository for configuration information.
yum install fax-gw
Manual Installation / Git Clone
Manual installation is less preferred, but also a viable option using the commands below. With no --destdir option specified, the installation will need to be performed as root. Ensure that your specify the --user <username> as the username under which your Asterisk installation runs. The manual installation method does not install Required Program Dependencies or Optional Program Dependencies.
git clone git://messinet.com/fax-gw.git ./fax-gw/install.sh --help ./fax-gw/install.sh --user asterisk
Mail Transport & Processing Configuration
Asterisk Dialplan Configuration
- See the fax-gw-extensions.conf file for examples. After installation, this file is also in your /etc/fax-gw directory.
- The [receivefax] and [sendfax] contexts are currently required.
FAX Gateway Configuration
Edit the following variables in the fax-gw.conf file to suit your needs.
Turn on debugging by setting 'debug' to a non-empty value. This will enable Bash, Graphics Magick, Python, and other debugging and really fill up the log file. Debugging is commented out by default.
Define a title which will appear in e-mail headers and fax cover pages.
Define the e-mail address from which notifications should be sent, the e-mail address of your fax administrator. You may also define the e-mail address which is to be Blind Carbon Copied on all e-mail sent from FAX Gateway. An empty "" value here will disable blind carbon copying.
fax_gw_email="firstname.lastname@example.org" faxmaster="email@example.com" bcc=""
Define the status templates that will be used for each of the end user and the faxmaster. If a given template is not listed, no e-mail will be sent for that status.
Define the name of the default LibreOffice/OpenOffice.org cover page template file, relative to the /etc/fax-gw/tpl/cover/ directory. An empty "" value here will disable default cover page generation.
Define the delay (in minutes) applied to all outbound faxes. The delay can be no longer than two digits in length, for a maximum of 99 minutes, and will be applied after processing, but before Asterisk initiates an outbound call.
Define the Asterisk extensions context from which outbound (destination leg) of the calls originate.
Define from_fax (Caller*ID number), from_name (Caller*ID name), account Asterisk account information, including the SendFAX and ReceiveFAX LOCALHEADERINFO and LOCALSTATIONID information. These variables should always be set with default values that apply to your system. They can be overidden on a per call basis using Optional Sender Lookup Configuration.
from_fax="7735551234" from_name="$title" account="7735551234" LOCALHEADERINFO ="$title" LOCALSTATIONID ="+1 773 555 1234" max_attempts="3" retry_time="300" wait_time="45" sendfax_context="sendfax"
Define Asterisk's failed extension REASON. As not all Asterisk installations are created equally, you may customize the error text that is communicated to your end users when Asterisk is unable to originate an outbound call. The defaults are shown below. For additional information, see the following.
# failed[$REASON]="My custom text to send to the end user" failed="General call failure, not BUSY, not NO_ANSWER, probable no route to destination" failed="Destination hung up" failed="Destination ring timeout" failed="Destination busy" failed="Destination congestion"
Define the Asterisk failed extension REASON(s) which should be considered fatal and where no further attempts should be made. *Note: the options are separated by pipes.*
LibreOffice & OpenOffice.org Configuration
It is important that you obtain and install the appropriate LibreOffice or OpenOffice.org and related binaries on your system. For a Fedora Linux system, LibreOffice and OpenOffice.org packages are quite segmented, requiring a large number of packages to satisfy program dependencies.
yum install libreoffice-calc libreoffice-core libreoffice-draw \ libreoffice-graphicfilter libreoffice-headless libreoffice-impress \ libreoffice-opensymbol-fonts libreoffice-pdfimport libreoffice-presenter-screen \ libreoffice-pyuno libreoffice-ure libreoffice-writer
yum install 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
If FAX Gateway is unable to start LibreOffice or OpenOffice.org in headless mode, please consider populating the following array variable (commented out by default) so that the AGI may find your LibreOffice or OpenOffice.org binary path. The path(s) you add will be attempted first, before other common installation paths defined within FAX Gateway itself.
#soffice_bin_paths+=( "/opt/libreoffice3.4/program" )
End User Variable Options
End users have the ability to modify certain runtime options such as removing or specifying an alternate cover page, substituting their own cover page, setting the resolution, or setting a delay for the fax. The end user can set the following variables by specifying <option name>:<value> in the subject line of the email. The options are lower-cased and removed from the subject before processing the outbound fax (so they won't display to the recipient).
- If the body of the e-mail is completely empty, there is at least one attachment, and the user specifies cover:no, no cover page will be generated.
- If filename.odt exists in the /etc/fax-gw/tpl/cover/ directory, that file will be used to generate a cover page. In addition, if the cover option is not specified, FAX Gateway will always attempt to process an attached file named <username>_cover.* to generate a user specific cover page.
- The delay (in minutes) can be no longer than two digits in length, for a maximum of 99 minutes, and will be applied after processing, but before Asterisk initiates an outbound call.
- The resolution can be one of standard, fine (the default), or superfine.
To specify that a fax should be sent with no cover page, a delay of 30 minutes, using "superfine" resolution, the user would specify the following in the subject line of the e-mail, and ensure the body of the e-mail is empty.
cover:no delay:30 res:superfine E-mail subject continues...
Optional Recipient & Sender Lookup Configuration
If you wish to enable the ability to lookup additional information for recipients and senders in order to make your cover pages more useful, you can set the lookup_parties variable (commented out by default) to any one of ldap, mysql, or pgsql. You should then configure the related variables below. The search limit for both recipient and sender lookups is one, so that only one entry is returned. If the lookup produces more than one result, it will fail so as to not pick the potentially wrong entry.
The following variables are used only when lookup_parties is defined.
- Common LDAP lookup variables
ldap_uri="ldap://127.0.0.1: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=""
- Common SQL lookup variables for PostgreSQL or MySQL
sql_host="127.0.0.1" sql_port="" sql_db="fax_gw" sql_table="accounts" sql_user="asterisk" sql_pass="asterisk"
The variables below define the LDAP attributes or SQL column names used during the queries. Inbound and outbound recipients are matched by comparing the recipient's fax number to the LDAP attribute or SQL column in the to_fax_attr variable. Outbound senders are matched by comparing the sender's e-mail address to the LDAP attribute or SQL column in the from_email_attr variable. The remaining variables are used to return other values during the search. For LDAP recipient searches, the facsimileTelephoneNumber, homeFacsimileTelephoneNumber, and otherFacsimileTelephoneNumber attributes are always searched in addition to those attributes defined below.
- Outbound sender lookup by email variables
account_attr="homePhone" from_email_attr="mail" from_fax_attr="homeFacsimileTelephoneNumber" from_name_attr="cn" cover_default_attr="documentIdentifier"
- Inbound & outbound recipient lookup by number variables
to_email_attr="mail" to_fax_attr="homeFacsimileTelephoneNumber" to_name_attr="cn"
- Inbound recipient & outbound sender lookup variables
I currently run FAX Gateway on a system that is using SELinux in permissive mode. One of my long-term goals is to achieve SELinux compatibility. I would appreciate testing in this area. While FAX Gateway is still in heavy development, the system paths (and therefore the SELinux contexts) may change, so I haven't settled on anything yet.