Chapter 19. Fax

Have no fear of perfection. You’ll never reach it.

Salvador Dali

The concept of facsimile transmission has been around for over 100 years, but it was not until the 1980s that the use of fax machines became essential in business. This lasted for perhaps two decades. Then the Internet came along, and very shortly after that, the fax quickly became almost irrelevant.

Incoming Fax Handling

Received faxes are commonly encoded in Tagged Image File Format (TIFF). This graphics file format, while not as well known as JPEG or GIF, is not as obscure as one might think. In fact, we suspect your computer (whether you’re running Windows, Linux, or MacOS) will already have the ability to interpret TIFF files built in. While it has become popular to offer PDF as a delivery format for received faxes, we’re not sure this is strictly required, since TIFF is so ubiquitous.

Received faxes will be stored by Asterisk as files. Where those files are stored will depend on several factors, including:

  • What software you are using to simulate a fax modem (e.g., IAXmodem, Digium ReceiveFAX, etc.)

  • The location in your filesystem that you have configured for storage of received faxes

  • Any post-receipt processing you have decided to perform on the files

In the dialplan, you will need to build in enough intelligence to name faxes in such a way that they will be distinct from each other. There are many channel variables and functions that can be used for this purpose, such as the STRFTIME() function. Asterisk can easily handle capturing the fax to a file, but you will need to make sense out of what happens to that file once it is stored on the system.

Fax to TIFF

The Tagged Image File Format is not very well known, but it is actually more common than you might realize, and since it is natively supported on Windows, MacOS, and Linux, TIFF files can be viewed on pretty much any computer with the most basic graphics viewer. A subset of the TIFF file format has for a long time been the de facto file format used for faxes.

Since Asterisk will receive and store faxes in TIFF format, there is no post-processing required. Once the incoming fax call has been completed, the resulting TIFF file can be opened directly from the folder where it was stored (or perhaps emailed to the intended user).

Fax to Email

Once Asterisk has received a fax, the resulting TIFF file needs a way to get to its final destination: a person.

The key consideration is that unless the information that Asterisk knows about the fax is sufficiently detailed, it may not be possible to deduce the intended recipient without having someone actually read the fax (it is common for a fax to have a cover page with the recipient’s information written on it, which even the most capable text recognition software would have a difficult time making sense of). In other words, unless you dedicate a DID to each user who might receive a fax, Asterisk isn’t going to be able to do much more than send all faxes to a single email address. You could code something in the dialplan to handle this, though, or have an external cron job or other daemon handle distributing the received faxes.

A simple dialplan to handle fax to email might look something like this (you will need the mail program mutt installed on your system):

exten => fax,1,Verbose(3,Incoming fax)
; folder where your incoming faxes will initially be stored
  same => n,Set(FAXDEST=/tmp) 

; put a timestamp on this call so the resulting file is unique
  same => n,Set(tempfax=${STRFTIME(,,%C%y%m%d%H%M)}) 
  same => n,ReceiveFax(${FAXDEST}/${tempfax}.tif)
  same => n,Verbose(3,- Fax receipt completed with status: ${FAXSTATUS})

; *** This line should not have any line breaks
  same => n,System(echo | mutt -a ${FAXDEST}/${tempfax} 
-s "received fax"

Obviously, this sample would not be suitable for production (for example, it does not handle fax failure); however, it would be enough to start prototyping a more fully featured incoming fax handler.

Fax Detection

You may have a dedicated phone number for receiving faxes. However, with Asterisk, that is not a requirement. Asterisk has the ability to detect that an incoming call is a fax and can handle it differently in the dialplan. Fax detection is available for both DAHDI and SIP channels. To enable it for DAHDI, set the faxdetect option in /etc/asterisk/chan_dahdi.conf. In most cases, you should set this option to incomingTable 19.1, “Possible values for the faxdetect option in chan_dahdi.conf” lists the possible values for the faxdetect option in chan_dahdi.conf.

Table 19.1. Possible values for the faxdetect option in chan_dahdi.conf

To enable fax detection for SIP calls, you must set the faxdetect option in /etc/asterisk/sip.conf. This option may be set in the [general] section, or for a specific peer. Table 19.2, “Possible values for the faxdetect option in sip.conf” covers the possible values for the faxdetect option in sip.conf.

Table 19.2. Possible values for the faxdetect option in sip.conf

incomingEnables fax detection on inbound calls. When a fax is detected, applies the faxbuffers option if it has been set and redirects the call to the fax extension in the dialplan. For more information on the faxbuffers option, see the section called “Using Fax Buffers in chan_dahdi.conf”.
outgoingEnables fax detection on outbound calls. The dialplan is not executing on an outbound channel. If a fax is detected, the faxbuffers option will be applied and the channel will be redirected and start executing the dialplan at the fax extension.
bothEnables fax detection for both incoming and outgoing calls.
noDisables fax detection. This is the default.
cngEnables fax detection by watching the audio for a CNG tone. If a CNG tone is detected, redirects the call to the fax extension in the dialplan.
t38Redirects the call to the fax extension in the dialplan if a T.38 reinvite is received.
yesEnables both cng and t38 fax detection.
noDisables fax detection. This is the default.