Difference between revisions of "IAXModem with Sail and HylaFax"

From SME Server
Jump to navigationJump to search
(Created page with '{{Incomplete}} ----')
 
(Updated for latest Sail ACL security)
 
(65 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Incomplete}}
+
==IAXModem for SME Server==
 +
{{Level|Advanced}}
  
 +
===Introduction===
 +
This Howto is for the installation of IAXModem in conjunction with Asterisk, SAIL and HylaFax in order to provide a fax over VOIP solution. It is based on information from various forum posts [http://forums.contribs.org/index.php/topic,39258.msg179460.html] [http://forums.contribs.org/index.php/topic,41256.msg219493.html]
 +
 +
For further info see also
 +
 +
*[http://sarkpbx.com/twiki/bin/view Selintra SarkPBX]
 +
 +
*[http://iaxmodem.sourceforge.net/ IaxModem]
 +
 +
*[http://www.hylafax.org/content/Main_Page Hylafax]
 +
 +
*[[Asterisk]] and [[HylaFax]] Contribs Wiki entries
 +
 +
This Howto has only been tested with
 +
 +
*Asterisk - 1.4
 +
 +
*Sail - 2.4.1
 +
 +
*Hylafax Contrib from Dungog - smeserver-hylafax-0.9.6 with hylafax-4.4.4-1
 +
 +
No other asterisk contribs or implementations have been used or tested.
 +
 +
It is assumed that you have a working Sail/asterisk installation before you start.
 +
 +
YMMV
 +
 +
===Sail and Asterisk Setup===
 +
====Global Settings====
 +
In ''Global Settings''
 +
*Make sure that ''Late Termination'' is set to 'No'.
 +
*Make sure that the ''Autosense FAX Extension'' is set to a number you want to use for the Fax. You will need this number later.
 +
*The ''Fax Delay'' setting defaults to 2 seconds. You may need to adjust this later to make sure faxes get detected before asterisk attempts to terminate somewhere other than the FAX.
 +
 +
====Trunklines====
 +
For each Trunk under ''Trunklines'' that you want to be able to detect incoming Faxes on
 +
*Make sure that the ''Fax'' detection tick box is ticked
 +
*Include a ''Transformation String'' of '95:' at the beginning
 +
{{Tip box|We will configure HylaFax later to prefix dialled numbers with 95 so we can identify them as an outgoing fax and route them as desired.
 +
You can use any prefix you want, not just 95 as long as you use it consistently.
 +
See Fax Route and HylaFax sections later}}
 +
 +
====Fax Route====
 +
Create a new Route for faxes with dialplan(s) starting with 95.
 +
example: 95X.
 +
and with ''Paths'' pointing to the Trunks on which you wish to receive faxes - those with ''Fax'' detection ticked as above
 +
 +
====Fax Extension====
 +
Create a new Extension with the same number as set in the ''Autosense FAX Extension'' as above. The ''Device'' should be 'IAXModem'.
 +
{{Note box|We will assume an ''Extension Number'' of '2000' (the iaxmodem rpm installed later defaults to this), a ''Password'' (secret) of 'asterisk' and a ''Display Name'' of 'FaxModem'}}
 +
Once created check the stanza generally conforms to the following and change as necessary:
 +
[2000]
 +
type=friend
 +
username=FaxModem
 +
secret=xYz3aB45
 +
host=dynamic
 +
qualify=3000
 +
context=internal
 +
callerid="Faxmodem" <2000>
 +
mailbox=2000
 +
pickupgroup=1
 +
callgroup=1
 +
call-limit=99
 +
subscribecontext=extensions
 +
deny=0.0.0.0/0.0.0.0
 +
permit=127.0.0.1/255.255.255.0
 +
disallow=all
 +
allow=slin
 +
requirecalltoken=no
 +
 +
{{Note box| The 'secret' is a strong extension password generated automatically by Sail. It should not be changed, other than to another strong password. The value shown above is a dummy example.}}
 +
{{Note box| The latest revisions of Sail generate ACL deny/permit security in the stanza. The <nowiki>permit=</nowiki> ACL will default to allow access on the local IP. You will need to change this to 127.0.0.1 as above}}
 +
{{Note box| After updating to Asterisk14-1.4.28-88, the fax extension fails to register, and gives the following error in the asterisk cli,
 +
<nowiki>chan_iax2.c:4322 handle_call_token: Call rejected, CallToken Support required. If unexpected, resolve by placing address 127.0.0.1 in the calltokenoptional list or setting user 2000 requirecalltoken=no </nowiki>
 +
Add <nowiki>requirecalltoken=no</nowiki> to stanza for fax extension and it will register OK again}}
 +
 +
===IAXModem===
 +
====Installation====
 +
{{Note box|Sail installs /etc/rc.d/rc7.d/S93iaxmodem but does not install /etc/rc.d/init.d/iaxmodem
 +
 +
Current version of iaxmodem is 1.2 but there doesn't appear to be a Centos 4 package for it anywhere}}
 +
Download the iaxmodem rpm from Selintra and install
 +
wget http://sarkpbx.com/sail/iaxmodem/iaxmodem-1.0.0-1.noarch.rpm
 +
yum localinstall iaxmodem-1.0.0-1.noarch.rpm
 +
{{Warning box|The rpm from Selintra does not install an /etc/rc.d/init.d/iaxmodem script. This version of iaxmodem apparently relied upon an inittab entry for starting but we are going to start it as a service so will need to create the required script. A copy of the current version 1.2 code is reproduced at the end of this Howto. You may need to set the permissions and ownership.}}
 +
 +
====Configuration====
 +
Use a template fragment to generate the required Iaxmodem configuration file ''ttyIAX0'' in /etc/iaxmodem so that changes survive a reconfiguration and reboot etc.
 +
*Create the template directory
 +
mkdir -p /etc/e-smith/templates-custom/etc/iaxmodem/ttyIAX0
 +
cd /etc/e-smith/templates-custom/etc/iaxmodem/ttyIAX0
 +
*Now create and edit a new file called ''modem'' with the following content
 +
{
 +
    use esmith::DB::db;
 +
   
 +
    $OUT  = "";
 +
    my $db = esmith::DB::db->open_ro('/home/e-smith/db/selintra');
 +
   
 +
    unless ($db)
 +
    {
 +
        warn "Couldn't open Selintra DB in Iaxmodem ttyIAX0 template fragment. Using Defaults\n";
 +
    }
 +
   
 +
    my $extension = $db->get_prop('global','FAX')        || "2000";
 +
    my $pass      = $db->get_prop($extension,'passwd')  || "asterisk";
 +
    my $cidname  = $db->get_prop($extension,'desc')    || "Noname";
 +
    my $cidnumber = $db->get_prop($extension,'callerid') || "0123456789";
 +
   
 +
    $OUT .= "device          /dev/ttyIAX\n";
 +
    $OUT .= "owner          uucp:uucp\n";
 +
    $OUT .= "mode            660\n";
 +
    $OUT .= "port            4570\n";
 +
    $OUT .= "refresh        60\n";
 +
    $OUT .= "server          127.0.0.1\n";
 +
    $OUT .= "peername        $extension\n";
 +
    $OUT .= "secret          $pass\n";
 +
    $OUT .= "cidname        $cidname\n";
 +
    $OUT .= "cidnumber      $cidnumber\n";
 +
    $OUT .= "codec          slinear\n";
 +
}
 +
*Save and close the file.
 +
*Now expand the template
 +
/sbin/e-smith/expand-template /etc/iaxmodem/ttyIAX0
 +
*This will create the necessary ttyIAX0 file, using the settings from Sail/Asterisk. It assumes you have set the Fax extension in ''globals'' and have created a valid ''extension'' of type ''IAXModem''.
 +
{{Note box|If the required settings are not available in Sail/asterisk then it defaults to an extension of ''2000'', a secret/password of ''asterisk'', a CID Name of ''NoName'' and Caller ID of ''0123456789''. The default password of 'asterisk' is not secure and both this and the 'secret' value of the extension in Sail should be changed to a strong password. If the extension has been created in Sail then a strong password will have been generated automatically}}
 +
 +
====Check and Run====
 +
Check the modem registers with Sail and Asterisk
 +
/usr/local/sbin/iaxmodem ttyIAX0
 +
should give an output similar to
 +
Modem started
 +
Setting device = '/dev/ttyIAX'
 +
Setting owner = 'uucp:uucp'
 +
Setting mode = '660'
 +
Setting port = 4570
 +
Setting refresh = 60
 +
Setting server = '127.0.0.1'
 +
Setting peername = '2000'
 +
Setting secret = 'asterisk'
 +
Setting cidname = 'YourCompany'
 +
Setting cidnumber = '0123456789'
 +
Setting codec = slinear
 +
Opened pty, slave device: /dev/pts/0
 +
Created /dev/ttyIAX symbolic link
 +
Registration completed successfully.
 +
and in an asterisk CLI
 +
--Registered IAX2 '2000' (AUTHENTICATED) at 127.0.0.1:4570
 +
Now
 +
db configuration set iaxmodem service status enabled
 +
/etc/rc.d/rc7.d/S93iaxmodem start
 +
 +
====Modifications====
 +
If you make any changes within Sail/asterisk such as the fax number, or fax extension details, don't forget to update Iaxmodem
 +
/sbin/e-smith/expand-templates /etc/iaxmodem/ttyIAX0
 +
/etc/rc.d/rc7.d/S93iaxmodem restart
 +
 +
===HylaFax===
 +
Install the [[HylaFax]] contrib.
 +
When you run faxsetup, at the end it will ask to continue and run faxaddmodem to setup a modem.
 +
Enter 'ttyIAX' as the modem port and continue and set other values as required. The IAXModem should be discovered if it was working OK, is started and running as above.
 +
Do not reboot or start HylaFax yet.
 +
Edit /etc/hylafax/etc/config.ttyIAX and add
 +
ModemDialCmd:        ATDT95%s
 +
{{Note box|This will prefix all numbers dialled by HylaFax with 95 so they can be identified and routed by SAIL}}
 +
Also check
 +
# make attachments readable
 +
RecvFileMode:          0666
 +
LogFileMode:            0666
 +
DeviceMode:            0666
 +
# for shared lines set to 10
 +
RingsBeforeAnswer:      1
 +
# change to suit
 +
SpeakerVolume:          quiet
 +
LocalIdentifier:        "YourCompany"
 +
Now if you want you can configure who receives faxes by editing
 +
/etc/hylafax/etc/FaxDispatch
 +
Finally set the modem port in the database
 +
db configuration setprop hylafax port ttyIAX
 +
/sbin/e-smith/expand-template /etc/inittab
 +
/sbin/init q
 +
Now continue with the contrib setup for Hylafax
 +
 +
===Operation===
 +
Incoming faxes on a Trunkline with detection enabled should be detected by asterisk. You may need to increase the ''Fax Detect Delay'' in ''Global Settings'' of SAIL to ensure the fax is detected and routed to the fax extension before the call is routed anywhere else.
 +
Once detected the incoming fax should be routed to the ''Autosense FAX Extension'', where IAXModem will answer and pass the fax to Hylafax.
 +
 +
Outgoing faxes emailed to 'user@0123987654.fax' will be sent by Hylafax to IAXModem with a dial string prefixed by 95, for example 950123987654. This will initiate a call in asterisk. The 95 prefix will be recognised as the fax route and the call passed to the relevant outgoing Trunk, where the 95 is stripped off and the real number dialled.
 +
 +
===iaxmodem Startup Script===
 +
The following is the code for the /etc/rc.d/init.d/iaxmodem script from the current iaxmodem-1.2.0.tar.gz source. You will need to create this file and add the code below in order for iaxmodem to be automatically started as a service and controlled by the SME Server configuration database settings. Alternatively download the iaxmodem-1.2.0.tar.gz source file and extract it yourself (iaxmodem.fedora)
 +
#!/bin/sh
 +
# Startup script for iaxmodem
 +
#
 +
# chkconfig: 2345 95 05
 +
# description: IAXModem for asterisk <-> Hylafax gateway
 +
 +
# Source function library.
 +
. /etc/rc.d/init.d/functions
 +
 +
[ -f /usr/local/sbin/iaxmodem ] || exit 0
 +
 +
prog="IAXmodem"
 +
 +
start() {
 +
    echo -n $"Starting $prog: "
 +
    daemon /usr/local/sbin/iaxmodem
 +
    RETVAL=$?
 +
    echo
 +
    return $RETVAL
 +
}
 +
 +
stop() {
 +
    if test "x`pidof iaxmodem`" != x; then
 +
        echo -n $"Stopping $prog: "
 +
        killproc iaxmodem
 +
        echo
 +
    fi
 +
    RETVAL=$?
 +
    return $RETVAL
 +
}
 +
 +
reload() {
 +
    if test "x`pidof iaxmodem`" != x; then
 +
      echo $"Reloading $prog"
 +
      kill -HUP `head -1 /var/run/iaxmodem.pid`
 +
    fi
 +
}
 +
 +
case "$1" in
 +
        start)
 +
            start
 +
            ;;
 +
        stop)
 +
            stop
 +
            ;;
 +
        status)
 +
            status iaxmodem
 +
            ;;
 +
        reload)
 +
            reload
 +
            ;;
 +
        restart)
 +
            stop
 +
            start
 +
            ;;
 +
        condrestart)
 +
            if test "x`pidof iaxmodem`" != x; then
 +
                stop
 +
                start
 +
            fi
 +
            ;;
 +
 +
        *)
 +
            echo $"Usage: $0 {start|stop|reload|restart|condrestart|status}"
 +
            exit 1
 +
 +
esac
 +
 +
exit $RETVAL
 +
Don't forget to change the ownership and permissions if necessary
 +
chown root:root /etc/rc.d/init.d/iaxmodem
 +
chmod 766 /etc/rc.d/init.d/iaxmodem
  
 
----
 
----
 +
[[Category:Howto]]
 +
[[Category:Asterisk]]

Latest revision as of 12:24, 21 May 2010

IAXModem for SME Server

PythonIcon.png Skill level: Advanced
The instructions on this page may require deviations from standard procedures. A good understanding of linux and Koozali SME Server is recommended.


Introduction

This Howto is for the installation of IAXModem in conjunction with Asterisk, SAIL and HylaFax in order to provide a fax over VOIP solution. It is based on information from various forum posts [1] [2]

For further info see also

This Howto has only been tested with

  • Asterisk - 1.4
  • Sail - 2.4.1
  • Hylafax Contrib from Dungog - smeserver-hylafax-0.9.6 with hylafax-4.4.4-1

No other asterisk contribs or implementations have been used or tested.

It is assumed that you have a working Sail/asterisk installation before you start.

YMMV

Sail and Asterisk Setup

Global Settings

In Global Settings

  • Make sure that Late Termination is set to 'No'.
  • Make sure that the Autosense FAX Extension is set to a number you want to use for the Fax. You will need this number later.
  • The Fax Delay setting defaults to 2 seconds. You may need to adjust this later to make sure faxes get detected before asterisk attempts to terminate somewhere other than the FAX.

Trunklines

For each Trunk under Trunklines that you want to be able to detect incoming Faxes on

  • Make sure that the Fax detection tick box is ticked
  • Include a Transformation String of '95:' at the beginning
Information.png Tip:
We will configure HylaFax later to prefix dialled numbers with 95 so we can identify them as an outgoing fax and route them as desired.

You can use any prefix you want, not just 95 as long as you use it consistently. See Fax Route and HylaFax sections later


Fax Route

Create a new Route for faxes with dialplan(s) starting with 95.

example: 95X.

and with Paths pointing to the Trunks on which you wish to receive faxes - those with Fax detection ticked as above

Fax Extension

Create a new Extension with the same number as set in the Autosense FAX Extension as above. The Device should be 'IAXModem'.

Important.png Note:
We will assume an Extension Number of '2000' (the iaxmodem rpm installed later defaults to this), a Password (secret) of 'asterisk' and a Display Name of 'FaxModem'


Once created check the stanza generally conforms to the following and change as necessary:

[2000]
type=friend
username=FaxModem
secret=xYz3aB45
host=dynamic
qualify=3000
context=internal
callerid="Faxmodem" <2000>
mailbox=2000
pickupgroup=1
callgroup=1
call-limit=99
subscribecontext=extensions
deny=0.0.0.0/0.0.0.0
permit=127.0.0.1/255.255.255.0
disallow=all
allow=slin
requirecalltoken=no


Important.png Note:
The 'secret' is a strong extension password generated automatically by Sail. It should not be changed, other than to another strong password. The value shown above is a dummy example.


Important.png Note:
The latest revisions of Sail generate ACL deny/permit security in the stanza. The permit= ACL will default to allow access on the local IP. You will need to change this to 127.0.0.1 as above


Important.png Note:
After updating to Asterisk14-1.4.28-88, the fax extension fails to register, and gives the following error in the asterisk cli,
chan_iax2.c:4322 handle_call_token: Call rejected, CallToken Support required. If unexpected, resolve by placing address 127.0.0.1 in the calltokenoptional list or setting user 2000 requirecalltoken=no 

Add requirecalltoken=no to stanza for fax extension and it will register OK again


IAXModem

Installation

Important.png Note:
Sail installs /etc/rc.d/rc7.d/S93iaxmodem but does not install /etc/rc.d/init.d/iaxmodem

Current version of iaxmodem is 1.2 but there doesn't appear to be a Centos 4 package for it anywhere


Download the iaxmodem rpm from Selintra and install

wget http://sarkpbx.com/sail/iaxmodem/iaxmodem-1.0.0-1.noarch.rpm
yum localinstall iaxmodem-1.0.0-1.noarch.rpm
Warning.png Warning:
The rpm from Selintra does not install an /etc/rc.d/init.d/iaxmodem script. This version of iaxmodem apparently relied upon an inittab entry for starting but we are going to start it as a service so will need to create the required script. A copy of the current version 1.2 code is reproduced at the end of this Howto. You may need to set the permissions and ownership.


Configuration

Use a template fragment to generate the required Iaxmodem configuration file ttyIAX0 in /etc/iaxmodem so that changes survive a reconfiguration and reboot etc.

  • Create the template directory
mkdir -p /etc/e-smith/templates-custom/etc/iaxmodem/ttyIAX0
cd /etc/e-smith/templates-custom/etc/iaxmodem/ttyIAX0
  • Now create and edit a new file called modem with the following content
{
    use esmith::DB::db;
    
    $OUT  = "";
    my $db = esmith::DB::db->open_ro('/home/e-smith/db/selintra');
    
    unless ($db)
    {
        warn "Couldn't open Selintra DB in Iaxmodem ttyIAX0 template fragment. Using Defaults\n";
    }
    
    my $extension = $db->get_prop('global','FAX')        || "2000";
    my $pass      = $db->get_prop($extension,'passwd')   || "asterisk";
    my $cidname   = $db->get_prop($extension,'desc')     || "Noname";
    my $cidnumber = $db->get_prop($extension,'callerid') || "0123456789";
    
    $OUT .= "device          /dev/ttyIAX\n";
    $OUT .= "owner           uucp:uucp\n";
    $OUT .= "mode            660\n";
    $OUT .= "port            4570\n";
    $OUT .= "refresh         60\n";
    $OUT .= "server          127.0.0.1\n";
    $OUT .= "peername        $extension\n";
    $OUT .= "secret          $pass\n";
    $OUT .= "cidname         $cidname\n";
    $OUT .= "cidnumber       $cidnumber\n";
    $OUT .= "codec           slinear\n";
}
  • Save and close the file.
  • Now expand the template
/sbin/e-smith/expand-template /etc/iaxmodem/ttyIAX0
  • This will create the necessary ttyIAX0 file, using the settings from Sail/Asterisk. It assumes you have set the Fax extension in globals and have created a valid extension of type IAXModem.
Important.png Note:
If the required settings are not available in Sail/asterisk then it defaults to an extension of 2000, a secret/password of asterisk, a CID Name of NoName and Caller ID of 0123456789. The default password of 'asterisk' is not secure and both this and the 'secret' value of the extension in Sail should be changed to a strong password. If the extension has been created in Sail then a strong password will have been generated automatically


Check and Run

Check the modem registers with Sail and Asterisk

/usr/local/sbin/iaxmodem ttyIAX0

should give an output similar to

Modem started
Setting device = '/dev/ttyIAX'
Setting owner = 'uucp:uucp'
Setting mode = '660'
Setting port = 4570
Setting refresh = 60
Setting server = '127.0.0.1'
Setting peername = '2000'
Setting secret = 'asterisk'
Setting cidname = 'YourCompany'
Setting cidnumber = '0123456789'
Setting codec = slinear
Opened pty, slave device: /dev/pts/0
Created /dev/ttyIAX symbolic link
Registration completed successfully.

and in an asterisk CLI

--Registered IAX2 '2000' (AUTHENTICATED) at 127.0.0.1:4570

Now

db configuration set iaxmodem service status enabled
/etc/rc.d/rc7.d/S93iaxmodem start

Modifications

If you make any changes within Sail/asterisk such as the fax number, or fax extension details, don't forget to update Iaxmodem

/sbin/e-smith/expand-templates /etc/iaxmodem/ttyIAX0
/etc/rc.d/rc7.d/S93iaxmodem restart

HylaFax

Install the HylaFax contrib. When you run faxsetup, at the end it will ask to continue and run faxaddmodem to setup a modem. Enter 'ttyIAX' as the modem port and continue and set other values as required. The IAXModem should be discovered if it was working OK, is started and running as above. Do not reboot or start HylaFax yet. Edit /etc/hylafax/etc/config.ttyIAX and add

ModemDialCmd:        ATDT95%s
Important.png Note:
This will prefix all numbers dialled by HylaFax with 95 so they can be identified and routed by SAIL


Also check

# make attachments readable
RecvFileMode:           0666
LogFileMode:            0666
DeviceMode:             0666
# for shared lines set to 10
RingsBeforeAnswer:      1
# change to suit
SpeakerVolume:          quiet
LocalIdentifier:        "YourCompany"

Now if you want you can configure who receives faxes by editing

/etc/hylafax/etc/FaxDispatch

Finally set the modem port in the database

db configuration setprop hylafax port ttyIAX
/sbin/e-smith/expand-template /etc/inittab
/sbin/init q

Now continue with the contrib setup for Hylafax

Operation

Incoming faxes on a Trunkline with detection enabled should be detected by asterisk. You may need to increase the Fax Detect Delay in Global Settings of SAIL to ensure the fax is detected and routed to the fax extension before the call is routed anywhere else. Once detected the incoming fax should be routed to the Autosense FAX Extension, where IAXModem will answer and pass the fax to Hylafax.

Outgoing faxes emailed to 'user@0123987654.fax' will be sent by Hylafax to IAXModem with a dial string prefixed by 95, for example 950123987654. This will initiate a call in asterisk. The 95 prefix will be recognised as the fax route and the call passed to the relevant outgoing Trunk, where the 95 is stripped off and the real number dialled.

iaxmodem Startup Script

The following is the code for the /etc/rc.d/init.d/iaxmodem script from the current iaxmodem-1.2.0.tar.gz source. You will need to create this file and add the code below in order for iaxmodem to be automatically started as a service and controlled by the SME Server configuration database settings. Alternatively download the iaxmodem-1.2.0.tar.gz source file and extract it yourself (iaxmodem.fedora)

#!/bin/sh
# Startup script for iaxmodem
#
# chkconfig: 2345 95 05
# description: IAXModem for asterisk <-> Hylafax gateway 

# Source function library.
. /etc/rc.d/init.d/functions

[ -f /usr/local/sbin/iaxmodem ] || exit 0

prog="IAXmodem"

start() {
    echo -n $"Starting $prog: "
    daemon /usr/local/sbin/iaxmodem
    RETVAL=$?
    echo
    return $RETVAL
}

stop() {
    if test "x`pidof iaxmodem`" != x; then
        echo -n $"Stopping $prog: "
        killproc iaxmodem
        echo
    fi
    RETVAL=$?
    return $RETVAL
}

reload() {
   if test "x`pidof iaxmodem`" != x; then
      echo $"Reloading $prog"
      kill -HUP `head -1 /var/run/iaxmodem.pid`
   fi
}

case "$1" in
        start)
            start
            ;;
        stop)
            stop
            ;;
        status)
            status iaxmodem
            ;;
        reload)
            reload
            ;;
        restart)
            stop
            start
            ;;
        condrestart)
            if test "x`pidof iaxmodem`" != x; then
                stop
                start
            fi
            ;;

        *)
            echo $"Usage: $0 {start|stop|reload|restart|condrestart|status}"
            exit 1

esac

exit $RETVAL

Don't forget to change the ownership and permissions if necessary

chown root:root /etc/rc.d/init.d/iaxmodem
chmod 766 /etc/rc.d/init.d/iaxmodem