AsterFax the Email to Fax Gateway for Asterisk.

--------------- We have moved -----------------

AsterFax and Asterisk IT have both been renamed.

Asterfax is now known as Noojee Fax

Asterisk IT is now known as Noojee Telephony Solutions.

Noojee Fax documentation and support can now be obtained via:
http://www.noojee.com.au/Page/NoojeeFax
https://wiki.noojee.com.au/Noojee_Fax
http://forums.noojee.com.au

--------------- We have moved -----------------

Asterisk IT is the primary developer and sponsor of AsterFax the Open Source Email to Fax Gateway for Asterisk.
Asterisk I.T. offer a range of support options for AsterFax as well as general Asterisk consulting services. Contact sales@asteriskit.com.au for more information.
You can also receive support from the Asterfax and Asterisk communities by by posting at the relevant forum.

AsterFax™ - Asterisk Fax

Configuring AsterFax

AsterFax uses just two configuration files which you will find in the 'config' sub-directory of your AsterFax install directory (usually /usr/lib/asterfax/config):

AsterFax.xml
log4j.xml

AsterFax.xml contains all of the critical settings and you will need to modify a number of these settings to get AsterFax operational.
The log4j.xml file contains configuration information pertaining to how and where AsterFax logs a variety of information. The default configuration will log messages to /var/log/asterfax/asterfax.log and to the console. It will also write an audit file to audit.log. Unless you are having problems or want to tweak the way logging is performed you can generally ignore the log4j.xml file.

The outline below gives an organised overview of the AsterFax configuration. This tree closely resembles the structure of AsterFax.xml. Use the links in the tree to drill down to more detailed information of the selected configuration setting.

General settings
- Company Name
- Return Fax Number
- Fax header and footer format
- Templates
- Page size
- Working folders
- Submitter
- Receiver
- Inbound mail configuration
  - Type of mail reception
  - Archiving
  - Delivery receipts
- Outbound mail configuration
  - From address
  - SMTP server details
- Debug settings
  - Enabled
  - PreserveTempFiles
  - TxFax
  - TxFaxSimulate
  - Converter
- Self diagnosis flag
Asterisk settings
- Host, username and password
- Outbound fax settings
- Inbound fax settings
  - Inbound fax handlers
- Channels
  - Name
  - Count
  - Priority
  - Context
Converters
- Mime type
- Extension
- Application
- Arguments

Manager API Authentication [back to tree]

AsterFax uses the Asterisk Manager API which means that AsterFax connects to the Asterisk server via a TCP connection. To do so it needs to know the Host address of the Asterisk server. This can either by an IP address or the actual host name. As AsterFax is on the same machine as Asterisk the default value of '127.0.0.1' is usually appropriate.
Note: AsterFax MUST be installed on the same machine as the Asterisk server as it needs to create files which AsterFax and Asterisk both have access to. (Although I suppose this could be achieved via a network share).

In almost every circumstance you will need to modify the AsterFax.xml file and in particular the Asterisk sub-elements.

Find the following sections in the AsterFax.xml file and make the necessary modifications as described below:

<Asterisk>
    <Host>127.0.0.1</Host>
    <Username>admin</Username>
    <Password>amp111</Password>
    <Channels>
        <Channel>
            <Name>Zap/1</Name>
          <Context>from-internal</Context>
            <Priority>1</Priority>
            <Count>1</Count>
        </Channel>
    </Channels>
</Asterisk>

Change the the Username and Password to login to the Asterisk Manager API.
The username and password can be found in the /etc/asterisk/ manager.conf file.
A typical example of the manager.conf is:
[admin]
secret = amp111
deny=0.0.0.0/0.0.0.0
permit=127.0.0.1/255.255.255.0
permit=10.0.5.55/255.255.0.0
read = system,call,log,verbose,command,agent,user
write = system,call,log,verbose,command,agent,user

In this case the username is 'admin' (without the quotes) and the password is 'amp111'' (again without the quotes).

Note: if you are using asterisk@home and have not changed the manager password then the default value is 'amp111' and the default value in the installed AsterFax.xml should work fine.

Channels [back to tree]

AsterFax allows the configuration of one or more channels (you must have at least one).
The channel is the line on which you want to send faxes.
Name - The name should be the channel name such as Zap/1; channel names are case insensitive.
Context - The context used in sending the fax. This should normally be 'from-internal'.
Priority - where more than one Channel is specified you can control the order in which AsterFax uses the channels by setting a priority. The lower the value the higher priority. (High priority channels are used before low priority channels). If you leave the Priority blank a default value of 1 will be used.
Count - the number of lines associated with the Channel. Some channels represent more than one line. This value lets you control how many simultaneous faxes should be sent using this channel. If you leave the Count blank a default value of 1 will be used.

If you want to add additional Channels simply copy the existing Channel element (from <Channel> to </Channel>) and paste directly under the existing Channel element. Then change the settings as necessary.

TO-DO: add notes on setting up Asterisk in detail as it pertains to AsterFax

manager.conf If you install AsterFax on a separate system to Asterisk (in which case you will need to be using a network share to share file access) then you may need to modify the /etc/asterisk/manager.conf.
Find the user details in manager.conf which you entered into AsterFax.xml. You should see a line similar to the following:
permit=127.0.0.1/255.255.255.0

Add an identical line directly under the existing line then change the IP address and subnet mask to match the details of the system that AsterFax is installed on.

Settings [back to tree]

Next find the <Settings> element in the AsterFax.xml file.

<OutBox>
The location where AsterFax stores tiff files ready for Asterisk to send.
The default location of the OutBox is the asterisk fax directory:
/var/spool/asterisk/fax

If the directory doesn't exist then you may need to create it.
If it already exits (which it should) then you may need to modify the permissions on the directory as both Asterisk and Asterfax need read/write access to the directory.
Note: we recommend that you use a fully qualified path
Note: these paths may not contain a space character.

<SpoolFolder>
The SpoolFolder is used to store incoming email messages. Once processed these messages are deleted.
The default location of the SpoolFolder is:
/var/spool/asterfax/spool
Note: we recommend that you use a fully qualified path
Note: these paths may not contain a space character.

<TempFolder>
Asterfax uses the TempFolder to store temporary files it creates as it processes mail. You can leave this value blank in which case AsterFax will use the default temp directory for the Operating System.

Note: we recommend that you use a fully qualified path
Note: these paths may not contain a space character.

<Submitter>
Starting with Version 1 rc 4 AsterFax supports multiple submission mechanisms. By changing the values for the submitter AsterFax can be made to send faxes using different mechanisms.

Currently there are two submitters that ship with AsterFax:

DefaultSubmitter - submits faxes using spandsp TxFax application
EfaxSubmitter - submits faxes using efax

Set the <Name> to the submitter that you want to use. The <Arguments> depend on the selected submitter. The DefaultSubmitter takes no arguments and will ignore any value set for arguments. The EfaxSubmitter requires two arguments, the serial device name prefix and the starting serial device ID.

<Receiver>
Starting with Version 1 rc 4 AsterFax supports multiple reception mechanisms. By changing the values for teh receiver AsterFax can be made to receive faxes using different mechanioisms.

Currently there are two receivers that ship with AsterFax:

DefaultFaxReceiver - receive faxes using spandsp and the RxFax application
EfaxReceiver - receive faxes using efax

Set the <Name> to the name of the receiver you intend to use. The <Arguments> depend on the receiver being used. The DefaultFaxReceiver takes no arguments and ignores any values set. The EfaxReceiver takes up to 3 arguments. The first is the serial device name prefix, the second is the serial device starting ID and the third is an option integer specifying the port AsterFax must listen on for notices of incoming faxes.

When the EfaxReceiver is started it starts a listener on the nominated port (or 5253 if one is not specified) for notices of incoming faxes. It then starts a number of efax instances waiting for faxes that will send a notice to the nominated port when a fax arrives.

<CompanyName>
The Company Name is displayed on the fax header where the %C parameter is used and should be modified to reflect your company name (beta 7 onward).

<ReturnFaxNumber>
The return fax number which can be included in headers and footers using the %R parameter.

<Templates>
Templates have been introduced to allow the variation of company names and header/footer formats based on destination fax number. In some organisations various companies are represented and the company name and header and footer must vary based on who the fax is being sent to.

Templates allow for this variation. In the configuration file create a <Template> element for each variation of the company name and header/footer format.The template elements must be created under the <Templates> element. The template element must have a fax attribute specifying the fax numbers that the template applies to. Multiple fax numbers are separated by commas, e.g. <Template fax="5551234,5559876">.

Add a <CompanyName>, <ReturnFaxNumber>, <Header> and <Footer> element under the template element as required.

<PageSize>
The Page is used to control how the tiff files are rendered. The default value is 'letter'. The value can be set to any of the known pages sizes supported by ghostscript.

Note: Page size names are case sensitive and must be specified precisely as appears on the ghostscript site!

http://www.cs.wisc.edu/~ghost/doc/AFPL/6.01/Use.htm#Known_paper_sizes

<FaxHeader>
The FaxHeader is used to control what information is displayed on the header of each fax page. The header is rendered in the top 5 mm (1/4inch) of each page transmitted. If you leave the FaxHeader blank then the header of each fax page will be left blank.

The fax header is defined using a special set of patterns combined with text. Each of the special patterns are represented by a % sign followed by a single letter. The current set of supported patterns are:

%C	Company name from the <CompanyName> element.
%S	Subject from email
%D	Date of fax
%T	Time of fax
%P	Page number and total page count (e.g. 1/5)
%R	The return fax number from the <ReturnFaxNumber> element.
%%	Displays a single % character.

Note: patterns are case sensitive.

You can mix the patterns with the text to construct a custom message.
e.g.Page number and total page count (e.g. 1/5)

"Fax from %C, subject %S, %D Page %P"

If the current values where:
CompanyName= Asterisk I.T.
Subject =Order for new tyres
Date=2010/1/1
Time=12:01
Total Page Count=5
Current Page =1

The resulting header would be:

Fax from Asterisk I.T., subject Order for new tyres, 1/Feb/2010 Page 1/5

The date would be displayed in a format appropriate for the locale.

The font for the header is specified in a <Font> element. To specify the font to use enter the following details:

<Name> - the font name, e.g. Arial
<Bold> - whether to use a bold font, either True or False.
<Italic> - whether to use an italic font, either True or False.
<Size> - the point size of the font, e.g. 16.

The text to be used in the header is divided into three parts:

<Left> - text that appears left aligned in the header
<Centre> - text that appears centre aligned in the header
<Right> - text that appears right aligned in the header

<FaxFooter>
The FaxFooter is used to control what information is displayed on the footer of each fax page. The footer is rendered in the bottom 5 mm (1/4inch) of each page transmitted. If you leave the FaxFooter blank then the footer of each fax page will be left blank.

The FaxFooter supports the same set of options as the FaxHeader.

Self Diagnosis [back to tree]

AsterFax automatically runs a set of self diagnosis each time it starts. You can disable the Self Diagnosis by setting the AsterFax.Settings.SelfDiagnosis.Enabled element to False.
<AsterFax>
    <Settings>
        <SelfDiagnosis>
            <Enabled>False</Enabled>
        </SelfDiagnosis>

Archival [back to tree]

AsterFax can automatically send a copy of every fax to an designated mailbox for archival purposes.
The archive includes a copy of the tiff file transmitted as a fax as well as the basic transmission details.
To configure the archival facility modify the default settings by changing the Enabled value to True and supplying an appropriate email address in the Mailbox.
You can specify multiple email addresses in the MailBox element by entering a semicolon separated list of email addresses. Make certain that you don't have any spaces.
<AsterFax>
    <Settings>
        <InboundMail>            <Archive>
                <Enabled>True</Enabled>
                <MailBox>archive@yourdomain.com.au</MailBox>
            </Archive>

Delivery Receipt [back to tree]

AsterFax is able to send a delivery receipt to the originator for each fax successfully sent.
Delivery Receipts can be configured globally as either manualy or automatic and the can be completely disabled.
When set to manual delivery receipts a user can request a delivery reciept by selecting the 'Return Receipt' option in their mail client. Note: Return Receipt is sometimes called 'Read Receipt' or 'Delivery Receipt' depending on the particular email client you are using.

By default AsterFax installs with automatic delivery receipts enabled.
You can disabled Delivery Reciepts by changing the Enabled element to False. You can make delivery receipts so that they are only sent when requested by change the Auto element value to False.
You can opt to have fax images included in PDF format rather than TIFF format by setting AttachAsPdf to True.
To have the fax images embedded in the body of the message rather than sent as attachments set Embed to True. Note that the images are embedded in JPEG format not in TIFF format.
You cannot opt for embedding and PDF format. PDF format will take prcedence of embedding.

<AsterFax>
    <Settings>
        <InboundMail>
            <DeliveryReceipt>
                <Enabled>True</Enabled>
                <Auto>True</Auto>
                <AttachAsPdf>False</AttachAsPdf>
                <Embed>False</Embed>
            </DeliveryReceipt>

Outbound SMTP Server [back to tree]

When sending delivery receipts, archiving faxes or sending error reports AsterFax requires access to an SMTP Server such as sendmail.
AsterFax has two methods of determining the SMTP server to use when sending emails. The default method is to do a DNS lookup using the senders email address' domain to obtain the MX record and the address of the SMTP server. Alternatively the outbound SMTP servers host and port may be explicitly set via the config/AsterFax.xml. The port may be left blank in which case the default value of port 25 is used.
If your SMTP server requires it you can also configure a username and password, otherwise just leave these settings blank.
You may also want to configure the email address used in the 'From' field when AsterFax is sending messages such as Archives, Receipts and Errors. You can configure the 'from' address used by entering a value between the <From></From> elements. This should be an email address within your domain e.g. asterfax@yourdomain.com.au.

<AsterFax>
    <Settings>
        <OutBoundMail>
            <From></From>
            <SMTP>
                <Host>mymailserver.mydomain.com</Host>
                <Port>25</Port>
                <Username></Username>
                <Password></Password>
            </SMTP>
        </OutBoundMail>

Fax Handlers [back to tree]

AsterFax provides has an extensible and pluggable fax handling facility. The idea is that you may need to handle faxes in differnt ways depending on the destination fax number or other fax characteristics. The fax handling facility allows you to plug as many fax handlers in as you require. Each handler might handle a fax differently. For instance, one handler might e-mail the fax to a certain e-mail addresses, another might update various details in a CRM system and another might archive the faxes in some way.
AsterFax ships with two fax handlers but others can be created as required. The two that ship with AsterFax are:

DefaultFaxHandler - e-mail the fax as attachment to a given list of recipients
XmlRoutingHandler - e-mail and store a fax to the file system based on CID or remote workstation ID.

Handlers are "plugged-in" by entering their name in a <Handlers> element in AsterFax.xml under the <TxFax> and <RxFax> elements. For example, to add the DefaultFaxHandler to the list of handlers to be called when a fax is sent add the following entry to AsterFax.xml:

<TxFax>
  .
  .
  .
  <Handlers>
    .
    .
    .
    <Handler>
      <Name>au.com.noojee.asterfax.handler.DefaultFaxHandler</name>
      <Arguments>someone@somewhere.com,someoneelse@somewhere.com</arguments>
    </Handler>
  </Handlers>
</TxFax>

The highlighted lines show the added entry. Sunstitute RxFax for TxFax when configuring handlers for inbound faxes.
Every handler is configured with a name and arguments. The name is significant it must be entered exactly as shown. Valid handler names are detailed below. The arguments will vary from handler to handler. Details of valid arguments for each handler are given below.

DefaultFaxHandler

The DefaultFaxHandler takes a list of e-mail addresses and e-mails a fax to each address. The list of recipients must be comma-separated. In AsterFax.xml the name must be entered as au.com.noojee.asterfax.handler.DefaultFaxHandler.

XmlRoutingHandler

The XmlRoutingHandler e-mails faxes and copies them to a location in the file system. It can also be configured to use different e-mail addresses and different file system locations based on CID or remote workstation ID. The formal name of the handler is au.com.noojee.asterfax.handlers.XmlRoutingHandler. The argument provided must be the name of a configuration file that XmlRoutingHandler reads to map CID's and remote workstation ID's to e-mail addresses and file locations. The file name must be an absolute path or a path relative to the AsterFax working directory. The default path is config/FaxRoutes.xml so if you use FaxRoutes.xml you can leave the Arguments blank.
Below is an example configuration file for XmlRoutingHandler. This file ships with AsterFax.

<FaxRoutes>
  <RootArchiveDir>archive</RootArchiveDir>
  <OutboundDir>outbound</OutboundDir>
  <InboundDir>inbound</InboundDir>
  <Manager>
    <Email>manager@someplace.com.au</Email>
    <ArchiveDir>manager</ArchiveDir>
  </Manager>
  <Routes>
    <Route>
      <CallerId>0312345678</CallerId>
      <DID>0312345678</DID>
      <Email>sales1@someplace.com.au</Email>
      <ArchiveDir>salesman1</ArchiveDir>
    </Route>
  </Routes>
</FaxRoutes>

This file is read as follows:

RootArchiveDir - the root directory XmlRoutingHandler will use for archiving faxes. Inbound and outbound faxes are stored in sub-directories of this directory.
OutboundDir - the sub-directory of the archive root directory to store outbound faxes in
InboundDir - the sub-directory of the archive root directory to store inbound faxes in
Manager/Email - the default address to send faxes to as an e-mail attachment. This address is used if no specific address is provided for a given CID/DID.
Manager/ArchiveDir - the default sub-directory (of the inbound and outbound directories) to store faxes in when no specific archive directory is configured for a given CID.
Routes/Route - specific CID's are configured in this section of the file
- CallerId OR DID - the CID or DID for incoming faxes (remote workstation ID for outgoing faxes). When the handler receives a fax to handle it compares the CID to the CallerId values in this file OR the DID to the DID in this file. If a match is found then the corresponding Email and ArchiveDir values are used otherwise the fax is routed to the manager (as configured above).
- Email - the e-mail address to send faxes to when this CallerID is found.
- ArchiveDir - the directory to save faxes to for this CallerID.

Converters [back to tree]

AsterFax supports a number of document formats. Each document format must be converted into a FAX TIF image before it is submitted as a fax. AsterFax uses this section of the configuration file to determine how to convert each document format.

When AsterFax receives an e-mail it extracts the attachment. Then using the mime-type and extension of the attachment it looks up an appropriate converter in the configuration. See the example below of the PDF converter that ships with AsterFax. In this example any attachment with a mime type of image/pdf and an extension of pdf will cause AsterFax to invoke the ghostscript application passing in the configured commadn line arguments.

<Converter>
  <Mime-Type>image/pdf</Mime-Type>
  <Extensions>pdf</Extensions>
  <Application>
    &ghostscript;
  </Application>
  <Arguments>
    -sDEVICE=tiffg3 -sPAPERSIZE=%pagesize% -r204x196 -dNOPAUSE -sOutputFile=%dest%
    -c save pop -c << /Policies << /PageSize 5 >>
    /PageSize [595 842] /InputAttributes << 0 <<
    /PageSize [595 842] &>> >> >> setpagedevice -f %src% -c quit
  </Arguments>
</Converter>

Notice that the ghostscript reference in the above example is an XML entity. The entity is defined at the top of the configuration file as <!ENTITY ghostscript "/usr/bin/gs">. So any reference to the ghostscript entity tells AsterFax to run the command /usr/bin/gs. It is not required that XML entities be used but where the command will appear in more than one converter it's good practice to use entities since any changes that might be required will only have to be made to the entity.

Notice also the use of XML entities to escape the < (<) and > (>) symbols in the command line arguments. Any arguments that require these symbols must use these entities. If the entities are not used the configuration file will not be a valid XML document and AsterFax will not start.

Should you wish to add your own converters then add a converter section similar to the above example to the end of the file, after the last </Converter> tag but before the closing <Converters> tag. Change that mime type, extension, application and arguments as required.

Debug Settings [back to tree]

There are several debugging flags that can be useful in isolating and eliminating issues with AsterFax.

Enabled

This setting toggles debug logging. When set to True AsterFax does more verbose logging which should help to isolate and identify issues.

PreserveTempFiles

This setting, when set to True causes all temp files creates by AsterFax during conversion to be preserved. Should any conversion issues be detected having this flag on will allow analysis of the temp files which might help to find the cause of the issue.

TxFax

The TxFax application can be run in debug mode causing it to write verbose logging to the Asterisk log. Set this to True to run TxFax in debug mode.

TxFaxSimulate

AsterFax has enhanced the TxFax application with a simulate mode. As the name suggests when run in simulate mode TxFax does not actually transmit the fax. TxFax will open the channel and then send the FaxTransmitted event (another AsterFax innovation). In this way testing can be done without transmitting faxes.

Converter

Toggles the converter debug flag. For certian document types AsterFax uses an OpenOffice.org script to do part of the conversion. Turning this flag on causes the script to write to a debug log. The log file name is ooconvert.log and it is written to the AsterFax logs directory.

TxFax Retries and Timeouts [back to tree]

In the TxFax section of the configuration document you can configure the number of times to retry a fax call when it fails. In the example below AsterFax will up to 3 tiems before abandoning an attempt to complete a fax call.
Set RetryTime to the number of seconds to pause between retries. In the example below AsterFax will wait 40 seconds before attempting to resend a failed fax.
Timeout is the number of seconds to wait before timeing out the originate call action.
<MaxRetries>3</MaxRetries>
<Priority>1</Priority>
<RetryTime>40</RetryTime>
<WaitTime>60</WaitTime>
<Timeout>60</Timeout>

Home
Downloads
Support
Licensing
News
FAQ
RoadMap
AsterFax UserGuide
Configuring Email Clients
Supported File Formats
Installing AsterFax
Configuring AsterFax
Testing AsterFax
Trouble Shooting AsterFax
Running AsterFax
Configuring SendMail
Configuring GhostScript
Configuring OpenOffice
SpanDSP
Add your own File format
Web2Fax

AsterFax is Sponsored by Asterisk I.T.
©2006 Asterisk I.T. all rights reserved. Some parts of this site may be the copyright of other authors. If you want to copy parts of this page you may do so provided you have gained permission from Asterisk I.T. first. Email asterfax@asteriskit.com.au
AsterFax™ is a trade mark of Asterisk I.T..
I'm not a great believer in Trade Marking Open Source software but unfortunately someone has been running a scam to redirect traffic to a bogus AsterFax web site. As such I've trade marked AsterFax's name to provide protection from such people.