Fax Solution Preview

[Ref: OpenBSD 6.1, Asterisk 13.16 | ReceiveFAX | Doxygen Docs | Extension Names and Patterns | Extensions.conf - the Dial Plan | Fax for Asterisk - No longer supported in Asterisk 13 ]

Warning: Asterisk-13.16.0 segfaults during startup. Resolution is to have an ari.conf configuration file, even if it is not being used

Faxes have gone the way of the dinosaur, some are wont to say. Do you really need to do this, in this day and age? Bolt onto this dilemma is
how unreliable Fax is over VoIP you should really consider well before climbing into this rabbit hole.

If you really have to do Fax over VoIP, you will provide yourself some sanity by reading more about infrastructure to provide decent service to your users/clients.

If you have a PSTN line terminating directly on your OpenBSD/Asterisk box, good for you.

Some of these instructions work in Asterisk 1.8 onwards, but the successful implementation for FAX Receipt has been on Asterisk 13.16, which has some significant differences from earlier version.

To verify whether you have already enabled the FAX Module, use the following command.

*CLI> module show like fax
Module             Description                              Use Count  Status      Support Level
res_fax.so         Generic FAX Applications                 1          Running              core
res_fax_spandsp.so Spandsp G.711 and T.38 FAX Technologies  0          Running          extended
2 modules loaded

The asterisk res_fax.so module implements two applications for fax transmissions.

*CLI> core show applications like fax
    -= Matching Asterisk Applications =-
            ReceiveFAX: Receive a FAX and save as a TIFF/F file.
               SendFAX: Sends a specified TIFF/F file as a FAX.
    -= 2 Applications Matching =-

Resource Configuration

The configuration options, standard fax settings, can be specified each time a fax using the function FAXOPT or the settings can be conveniently maintained in the resource configuration file res_fax.conf:

File extract: /etc/asterisk/res_fax.conf

[general]
maxrate      = 14400       ; Maximum transmission rate
minrate      = 2400        ; Minimum transmission rate
ecm          = yes         ; Enable/Disable T.30 ECM (Error Correction Mode)

The options shown above are the ones we see used in example dialplan. Read the file to see other options.

Review the running configuration using the *CLI command fax show settings

*CLI> fax show settings
FAX For Asterisk Settings:
    ECM: Enabled
    Status Events: On
    Minimum Bit Rate: 2400
    Maximum Bit Rate: 14400
    Modem Modulations Allowed: V17,V27,V29
    T.38 Negotiation Timeout: 5000

FAX Technology Modules:

Spandsp (Spandsp FAX Driver) Settings:

Receiving a Fax

[Ref: Application ReceiveFax]

ReceiveFAX answers a call and negotiates the fax transmission and when successful, writes the fax to the specified file.

The most basic DialPlan for receiving fax is as below:

[fax-receipt]
exten => _X.,1,ReceiveFAX(/var/spool/asterisk/fax/faxfile.raw)
 same => n,Hangup()

When a call goes to this dialplan context, ReceiveFAX will:

  • Answer the Call
  • Negotiate FAX Transmission
  • Receive the FAX Transmission into the file faxfile.raw
    • in the path: /var/spool/asterisk/fax

For a more detailed plan to receive faxes, follow through to our Receiving Faxes

Sending a Fax

[Ref: Application SendFax Asterisk Call Files]

Our preferred method for sending faxes in Asterisk requires two separate actions:

DialPlan Context

Remembering that when our DialPlan connects to two extensions together (whether both extensions are internal, or whether one is external) this connection is through a CHANNEL (e.g. SIP, PJSIP, IAX2)

  • Configure Channel
  • Context

Configure Channel

Configure your Channel, we're going to just stick with the standard SIP channel. FAX over VoIP, barely works over uncompressed codecs (alaw,ulaw) so make them the minimum codecs. Do not entertain using any compressed codecs (such as GSM.)

File extract: /etc/asterisk/sip.conf

[fax-trunk](!)
type         = peer
dtmfmode     = rfc2833
directmedia  = no
videosupport = no
canreinvite  = no
qualify      = yes
disallow     = all
allow        = alaw
allow        = ulaw
sendrpid     = pai
trustrpid    = yes
deny         = 0.0.0.0/0
port         = 5060
context      = from_trunk

[carrier](fax-trunk)
bindaddr = XXX ; relevant NIC IP Address
host     = YYY ; VoIP Carrier IP Address
permit   = YYY/32

DialPlan Context

The DialPlan [context] for sending a fax, is the Application SendFax which accepts the parameter of the filename to be transmitted.

Dialplan Example:

[fax-outbound]
exten => send,1,SendFAX(${FAXFILE})
 same => n,Hangup()

When the Application SendFax is encountered, it will attempt to connect with the technology/node specified by ${CHANNEL}

The details for ${CHANNEL} can be provided to SendFAX using Asterisk Call Files discussed below.

Ready to Transmit

[Ref: Asterisk Call Files]

Asterisk's Call Files can be used to directly call SendFAX, but we will be using DialPlan context for the flexibility it offers.

To create a callfile:

  • Open/Edit a text file on the same partition as the Asterisk outgoing spool directory (normally: /var/spool/asterisk/outgoing)
  • Move the created file into the Asterisk outgoing spool directory

A call file consists of <key>:<value> pairs (one per line)

You can get more details from the Call Files documentation, and the below is an example.

Channel:    SIP/carrier/0212345678
Archive:    Yes
WaitTime:   60
MaxRetries: 5
RetryTime:  360

Context:    fax-outbound
Extension:  send
Priority:   1
SetVar: FAXFILE=/var/tmp/faxtosend.tiff

When a Call File is read, Asterisk will attempt to connect to the Channel specified. This would be similar to a Dial(SIP/carrier/0212345678).

If the channel connection is successful, Asterisk will execute the specified Dialplan Context, Extension, Priority. This would be similar to a GoTo(context,extension,priority)

Summary

When Asterisk notices the new Call File in the outgoing spool directory:

Asterisk

  • attempts to connect to the channel
  • if the connection is successful
    • Sets Channel Variable FAXFILE
    • executes the context,extension,priority
    • Our [fax-outbound] context uses the SendFAX application to transmit the Image File ${FAXFILE}

A simple outbound fax solution.

Help

[Ref: Asterisk WIKI]

Asterisk documentation is available in many places on the Internet, but don't forgot the inbuilt documentation, diagnostics data.

*CLI> core show help fax
    fax set debug {on|off} Enable/Disable FAX debugging on new FAX sessions
    fax show capabilities Show the capabilities of the registered FAX technology modules
    fax show session Show the status of the named FAX sessions
    fax show sessions Show the current FAX sessions
    fax show settings Show the global settings and defaults of both the FAX core and technology modules
    fax show stats Summarize FAX session history
    fax show version Show versions of FAX For Asterisk components

Application Manpage

Without using the internet, you can find out more information (manual page) about applications such as ReceiveFAX and SendFAX within the Asterisk CLI.

*CLI> core show application ReceiveFAX
Receive a FAX and save as a TIFF/F file.

[Description]
This application is provided by res_fax, which is a FAX technology agnostic
module that utilizes FAX technology resource modules to complete a FAX
transmission.
Session arguments can be set by the FAXOPT function and to check results of the
ReceiveFax() application.

[Syntax]
ReceiveFAX(filename[,options])
...

Statistics

To see an updated record of facsimile behaviour

CLI> fax show stats
FAX Statistics:
---------------

Current Sessions     : 0
Reserved Sessions    : 0
Transmit Attempts    : 874
Receive Attempts     : 0
Completed FAXes      : 525
Failed FAXes         : 349

Spandsp G.711
Success              : 525
Switched to T.38     : 0
Call Dropped         : 41
No FAX               : 0
Negotiation Failed   : 63
Train Failure        : 15
Retries Exceeded     : 0
Protocol Error       : 1
TX Protocol Error    : 171
RX Protocol Error    : 6
File Error           : 0
Memory Error         : 0
Unknown Error        : 0

Spandsp T.38
Success              : 0
Call Dropped         : 0
No FAX               : 0
Negotiation Failed   : 0
Train Failure        : 0
Retries Exceeded     : 0
Protocol Error       : 0
TX Protocol Error    : 0
RX Protocol Error    : 0
File Error           : 0
Memory Error         : 0
Unknown Error        : 0