Difference between revisions of "Fax Server"

Revision as of 18:08, 17 June 2014

Menu: (Apps-Fax Server)

Once you have setup a fax server extension and you try sending a fax to it: - if the fax is successfully received it will be emailed to the address (or comma separated addresses) you supplied when you set up the fax server extension. The email will also indicate the fax senders' identification information (if they have configured it on their fax machine), and the number of pages in the fax. - if the fax is not successfully received an email will be sent to the address (or comma separated addresses) you supplied when you set up the fax server extension. The email will indicate the error message from the fax receipt process, the fax senders' identification information (if they have configured it on their fax machine) and the number of pages that were expected in the fax.

If someone deletes the fax from the server before it has been successfully emailed to the configured email address(es), then an email will still be sent, but there will be a message in the email indicating that the attachment is missing. When we have a failed fax the attachment will also be missing and therefore the message will be similar.

Dependencies:

tiff2pdf command line

CentOS

 yum install ghostscript
 yum install libtiff

Ubuntu

 apt-get install ghostscript
 apt-get install libtiff-tools

Testing:

When you set up a fax server extension it creates a dialplan entry for that fax extension. If you look at that dialplan extension you will find an action line like this: /usr/bin/php /var/www/fusionpbx/secure/fax_to_email.php email=youremailaddress@yourdomain extension=yourfaxextension name=${last_fax} messages='result: ${fax_result_text} sender:${fax_remote_station_id} pages:${fax_document_total_pages}'

If you are having trouble receiving faxes as emails you can test the fax email process manually by running this line interactively, but you can simplify it a bit as the variables mean nothing if you run it from the shell prompt eg. /usr/bin/php /var/www/fusionpbx/secure/fax_to_email.php email=youremailaddress@yourdomain extension=yourfaxextension name=the_name_of_the_fax_tif_file_without_a_file_extension messages='you don't need to put anything here')

Note that if you have multi-tenants, the above test may not work, as the ../fax_to_email.php script only look for fax file in /usr/local/freeswitch/storage/fax/<ext-no>/inbox and not in /usr/local/freeswitch/storage/fax/<your-domain>/<ext-no>/inbox.

Logging:

When a fax is received and emailed it is logged to freeswitch/storage/fax/emailed_faxes.log (on Centos this is found under /usr/local/freeswitch/storage/fax/emailed_faxes.log). Because FusionPBX doesn't use an MTA (message transfer agent eg. sendmail) to send the emails there is no message queue to check to see if a message has been sent, therefore checking this log will confirm if it has been sent or not

If a fax is received but FusionPBX is unable to email it (either because the email server is misconfigured in the FusionPBX Settings, or it is uncontactable at the time the fax is received) then the email will be queued and FusionPBX will continue to retry sending queued messages once every 3 minutes. The messages will queue on the server until sending is successful. These messages are queued in /usr/local/freeswitch/storage/fax/failed_fax_emails.log - the lines in that file are actually executed by the re-sending process, so the structure of the lines is important.

Warnings:

- Don't change an existing fax number, create a new one. If you change the number rather than creating a new one it will appear to work, but it will fail to create the "inbox" and "sent" folders for the fax server and as a result when FreeSwitch tries to write a fax into those folders it will fail.

Limitations:

It is not possible to send a fax to the fax server from an extension on the same phone system. ie. if you have a fax machine connected to an ATA on an extension of the phone system the system will fail to send the fax as an email because when the fax machine hangs up, the call terminates and the fax_to_email script is never executed. The only way you can make this work is to modify the dialplan created by the fax server function so that prior to starting rxfax it sets the variable api_hangup_hook=system /usr/bin/php /var/www/fusionpbx/secure/fax_to_email.php email=youremailaddress@yourdomain extension=yourfaxextension name=${last_fax} (where the bit following the keyword of system is the exact same data that is automatically put into the dialplan of the fax configuration on the action system line that follows the line containing rxfax). This limitation does not apply to externally sent faxes and therefore this line is not necessary (and in fact would cause you to receive externally sent faxes twice). Accordingly unless you have a really good reason to change it so you can receive internal faxes you should stick with the standard fax server configuration.

If you need to receive both external and internal faxes (for instance I use a fax machine as a scanner) you might want to set up a second fax number just for internal use and configure that with the above instruction so that it works for you. This approach works well. You could even consider putting it in your dialplan with the same number as the external number so that internal calls go there instead of the externally accessible destination.

Getting more detailed fax logging

(not for normal use, you'd typically only do this during testing if you wanted more details from FreeSwitch about the fax processing it does on an incoming fax)

Select ADVANCED, XML Editor and a new window will open. Choose autoload_configs from the list, then choose fax.conf.xml. In fax.conf.xml there is an option that by default sets a variable called verbose = false. If you change this to true you get more logging details as the fax is actually received, such as the quality of the connection etc. You can see these details when you run the freeswitch command line ie. /usr/local/freeswitch/bin/fs_cli

Fax Retry

• This is true for the development version as of 1/8/2013

If you send a fax via the GUI (Apps->Fax) FusionPBX will automatically try and resend a fax up to 5 times. It does this up to 5 times using various combinations of T38 (enabled or disabled), ECM (error correction mode on/off), and slow/fast speeds. An email will be sent to the email address of the user who was logged in and sent the fax (if filled out in contacts), and to the email address configured for the fax extension. The email will indicate success or failure, and include the document attached as a tiff.

Fax Statistics

you can grep your log files for FAX_RETRY_STATS to start keeping track of success/failure.

Examples

Here's how you can get some totals.

• Total:

cat freeswitch.log |grep FAX_RETRY_STATS |wc -l

• Success:

cat freeswitch.log |grep FAX_RETRY_STATS |grep SUCCESS |wc -l

• Failures:

cat freeswitch.log |grep FAX_RETRY_STATS |grep FAIL |wc -l

Fax Relay

• This is true for the development version as of 1/8/2013

Since it's extraordinarly difficult to guarantee faxing in VoIP, especially with real fax machines, it's often easier to relay the fax. Configured this way, FusionPBX can intercept a fax from a fax machine on the system, and then relay it out using the Fax Retry method described above.

Best Way

Step 1

When you configure a fax extension (Apps->Fax), add a Destination Number. This should ideally be something like:

329(\d{10})

Step 2

Find the dialplan entry for api_hangup_hook, and edit the last_fax variable. You need to add $1# at the front, like:

 last_fax=$1#\\\${caller_id_number}-${strftime(%Y-%m-%d-%H-%M-%S)}

• What this does: It will automatically create a dialplan entry for you (see Old Way below). It will require a prefix of 329 (spells fax) followed by a 10 digit number. If you configure your ATA to automatically add the 329 prefix, then it's transparent to the user, and just tell them to use 10 digits to send a fax. If the fax extension is deleted, so is the associated dialplan. Using fax relay this way will automatically utilize fax_retry.lua, and will send confirmation emails to the email address you provided when you configured the fax extension.

Old Way

• First, configure a fax machine/ATA and note the extension.
• Dialplan -> Dialplan Manager
• Add some new dialplan.

There are several things we can filter on. The method below looks specifically for a fax extension, but it could have just as easily been a number code in front (eg all fax machines must dial 8 and then a 10 digit number). You will want to set this in the 0 group so that it gets run before anything else. I set my fax ATA's up from extension 1030-1039. The fax extension noted in the dialplan below is the FusionPBX Fax Extension you configured for end users. All you should have to adjust are the email_to fax_extension and domain varaibles.

<extension name="Fax_relay" >
   <condition field="${user_name}" expression="^103[0-9]" />
   <condition field="destination_number" expression="^(\d{10})$" >
       <action application="set" data="email_to='fax@example.com'" />
       <action application="set" data="fax_extension=8001" />
       <action application="set" data="domain=voip.example.com" />
       <action application="set" data="api_hangup_hook=system /usr/bin/php /var/www/fusionpbx/secure/fax_to_email.php email=\\\${email_to} extension=\\\${fax_extension} name=\\\${last_fax} messages='result: \\\${fax_result_text} sender:\\\${fax_remote_station_id} pages:\\\${fax_document_total_pages}' domain=\\\${domain} caller_id_name='\\\${caller_id_name}' caller_id_number=\\\${caller_id_number} fax_relay=yes" />
       <action application="answer" />
       <action application="set" data="fax_enable_t38=true" />
       <action application="set" data="fax_enable_t38_request=false" />
       <action application="set" data="fax_use_ecm=false" />
       <action application="set" data="last_fax=$1#${caller_id_number}-${strftime(%Y-%m-%d-%H-%M-%S)}" />
       <action application="playback" data="silence_stream://2000" />
       <action application="rxfax" data="/usr/local/freeswitch/storage/fax/voip.example.com/8001/inbox/${last_fax}.tif" />
       <action application="hangup" />
   </condition>
</extension>