Messinet Secure Services
wiki:FAXGateway
Last modified 12 days ago Last modified on 05/06/13 16:49:16

  1. Features
  2. Recent Changes
  3. Tickets
  4. Installation
    1. Required Program Dependencies
    2. Optional Program Dependencies
    3. Fedora & Enterprise Linux RPM Installation
    4. Manual Installation / Git Clone
  5. Configuration
    1. Mail Transport & Processing Configuration
    2. Asterisk Dialplan Configuration
    3. FAX Gateway Configuration
    4. LibreOffice & OpenOffice.org Configuration
    5. End User Variable Options
    6. Optional Recipient & Sender Lookup Configuration
  6. SELinux Limitations

FAX Gateway

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 was inspired to write this script using various bits and pieces from the ​HylaFax and ​HylaFax+ programs and owe credit to the creators of those respective programs.

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:amessina@messinet.com.

Features

Recent Changes

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.

Tickets

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

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

Configuration

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. 

#debug="true"

Define a title which will appear in e-mail headers and fax cover pages. 

title="FAX Gateway"

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="noreply@your-domain.com"
faxmaster="faxmaster@your-domain.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. 

return_status_user="queue_failed,queue_success,receivefax_failed,receivefax_success,sendfax_failed,sendfax_retry,sendfax_success"
return_status_faxmaster="queue_failed,receivefax_failed,sendfax_failed"

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. 

cover_default="default.ott"

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. 

delay_default="0"

Define the Asterisk extensions context from which outbound (destination leg) of the calls originate. 

context="outbound-fax"

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[0]="General call failure, not BUSY, not NO_ANSWER, probable no route to destination"
failed[1]="Destination hung up"
failed[3]="Destination ring timeout"
failed[5]="Destination busy"
failed[8]="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.* 

failed_fatal="0|8"

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.

  • LibreOffice: 
    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
  • OpenOffice.org: 
    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. 
    cover:no
  • 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. 
    cover:filename.odt
  • 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. 
    delay:XX
  • The resolution can be one of standard, fine (the default), or superfine. 
    res: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. 

#lookup_parties="ldap"

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 
    localheaderinfo_attr="cn"
localstationid_attr="homeFacsimileTelephoneNumber"

SELinux Limitations

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.