Sunday, 13 November 2011

Fax Solution - Hylafax / IAXModems / Asterisk

Overview
This section depicts integration of Fax solution with Hylafax, IAXModem and Asterisk server. Hylafax is structured around client-server architecture. Hylafax client (JAVA API or Command) can be used by application to submit fax jobs to Hylafax Server. IAX Modems (as software) are used by Hylafax server to communicate with Asterisk Server. Hylafax provides support to send and receive faxes. We used Hylafax solution for sending fax.

Send flow of fax documents from application to fax machine (hard copy):


Application - > Hylafax Client -> Hylafax Server - > IAX Modems - > Asterisk Server - > Fax Machine


System Environment

Software
Version
Linux OS
Linux version 2.6.18-128.el5 (Red Hat 4.1.2-44)
Hylafax          
6.0.3  (http://www.HylaFax.org)
IAXModem
TED
2.21   (http://www.nllgg.nl/Ted/)

Asterisk
Asterisk is free, open source software that turns an ordinary computer into a feature-rich voice communications server. Asterisk makes it simple to create and deploy a wide range of telephony applications and services. Asterisk supports a wide range of telephony protocols. It includes rich support for the handling and transmission of voice over traditional telephony interfaces including analog lines, ISDN-BRI lines and digital T1/E1 trunks.

Hylafax:
Hylafax is an open source fax solution which is structured around client-server architecture. Fax modems may reside on a single machine on a network and clients can submit outbound jobs from any machine that can communicate with the machine on which the modems reside. An access control mechanism controls which users on which machines may access a server.

IAXModem
The IAXmodem application emulates a faxmodem, which would be operated by a HylaFax server to communicate with Asterisk server.

Integration Diagram 



 Issues Faced During Integration

     1.     IAXModems and FaxGetty services are not being started at system startup.
      
     Solution:
There is one Linux file '/etc/inittab' describes which processes are started at boot up.  Below entries have been added in same file to start IAXModem and FaxGetty services.
       
Syntax:
        id:runlevels:action:process
       
Entries:
        m0:5:respawn:/usr/bin/iaxmodem ttyIAX0
        f0:5:respawn:/usr/local/sbin/faxgetty ttyIAX0

Here ‘5’ is a default run level.
       
In case of services are not being started at system reboot, following two things must be ensured:

·         Id for all processes available in file must be unique. Like m0 or f0 should not be configured for other processes.
·         Ensure whether configured run level is a system default run level. On the shell, use below Linux command to check default run level
      $ runlevel

2.      IAXModems are not being registered with Asterisk server
     
      Solution:
·          Ensure the proper communication between box (Asterisk server) and box (Hylafax, IAXModem).
·          Ensure that firewall is not restricting communication between both boxes.
·          Ports for proper communication must be opened on both boxes.

 For example:

Asterisk Server listen IAX connections on port 4569. And IAXModem is configured with port 4570 (in file /etc/iaxmodem/ttyIAX0).  Port 4569 must be opened on IAXModem box and port 4570 must be opened on Asterisk server box.

·          Ensure following configuration files are in  proper unix format
        /etc/iaxmodem/ttyIAX0
       /var/spool/hylafax/etc/config.ttyIAX0
       /var/spool/hylafax/etc/config

      If not, use below command to convert in proper format.

      $ dos2unix       /etc/iaxmodem/ttyIAX0

3.      Outbound fax notification (as email) is not being sent by Hylafax server.
    
     Solution:
Ensure that whether 'sendmail' utility is working properly on Linux system. Use below command to check:
$ sendmail <email-id>

Type any text, press ENTER, type. (Dot), press ENTER. Mail should be delivered to mentioned email id. If not, check sendmail utility configurations. 

Questions & Answers

1.      How to flow dynamic information from Hylafax client to fax email notification?
     Ans:   Use below option with sendfax command to show dynamic information in email notification.
        sendfax -i <tag-value> -d <fax-number> <fax-document>
       <tag-value> can be retrieved in email notification templates using $jobtag variable.

     2.      How to create and use customized email notification template?
     Ans:   Script file ‘/var/spool/hylafax/bin/notify’ is responsible to call Hylafax email notification
     templates. Create new email notification template and modify 'notify' script to use the customized
     template.

Location of existing templates: /var/spool/hylafax/etc/templates

Below line is configured in /var/spool/hylafax/bin/notify file to use existing templates.

template="etc/templates/$TEMPLATE/notify-$WHY.txt"

Newly created file path can be assigned to template variable to use customized templates.

3.      How to convert RTF document to PS format?
     Ans: Use TED tool to convert RTF document into PS format. For more detail about TED
     referhttp://www.nllgg.nl/Ted/
  
References

Ø  Hylafax Source
http://www.HylaFax.org
Ø  Hylafax "sendfax" Command:
http://linux.die.net/man/1/sendfax
Ø  Online PS Viewer:
http://view.samurajdata.se/psview.php?id=2ad4f1f8&page=1&ori=1s
Ø  Hylafax Sendq Tags Description:
http://hylafax.sourceforge.net/man/sendq.php
Ø   Link for Fax Cleanup:
Ø   Summary of transmission errors
http://www.hylafax.org/HylaFAQ/Q344.html
Ø   Hylafax FAQ Archive:
http://www.hylafax.org/archive/2006-03/threads.php
Ø   Hylafax/IAXModem Setup (installation):
http://www.the-asterisk-book.com/unstable/faxserver-mit-iaxmodem-und-hylafax.html#faxe-empfangen
Ø   Configuring Multiple IAXModems:
http://www.trixbox.org/forums/trixbox-ce-development-forum/fax-development/multiple-incoming-faxes-hylafax-and-iaxmodem