Introduction

From Enswitch 2.8 onwards, Hylafax/IAXmodem is the standard Enswitch fax sub-system, replacing SpanDSP/RxFAX which was removed in Enswitch 2.7. This was done for Asterisk 1.4 compatibility.

Installation and starting

On new 2.8 or newer installations, "enswitch install asterisk" also installs and starts Hylafax and IAXmodem automatically. This is not done for systems upgraded from 2.7. For these systems, "enswitch install hylafax" will install and start both. Once installed, they can also be started, etc, using "service hylafax start" or "invoke-rc.d hylafax start" depending on distribution. The init.d script starts and stops Hylafax, IAXmodems, and faxgettys at the same time.

Processes

In the default configuration, the following processes should be running:

[root@localhost ~]# ps -ef | grep -E '(fax|iax)' | grep -v grep
root     22504     1  0 12:01 ?        00:00:00 /opt/enswitch/current/sbin/enswitch_hylafax
uucp     22522     1  0 12:01 ?        00:00:00 /usr/sbin/faxq
uucp     22524     1  0 12:01 ?        00:00:00 /usr/sbin/hfaxd -i hylafax
uucp     22525 22504  0 12:01 ?        00:00:00 iaxmodem ttyIAX0
uucp     22526 22504  0 12:01 ?        00:00:00 faxgetty /dev/ttyIAX0
uucp     22527 22504  0 12:01 ?        00:00:00 iaxmodem ttyIAX1
uucp     22528 22504  0 12:01 ?        00:00:00 faxgetty /dev/ttyIAX1
uucp     22529 22504  0 12:01 ?        00:00:00 iaxmodem ttyIAX2
uucp     22530 22504  0 12:01 ?        00:00:00 faxgetty /dev/ttyIAX2
uucp     22531 22504  0 12:01 ?        00:00:00 iaxmodem ttyIAX3
uucp     22532 22504  0 12:01 ?        00:00:00 faxgetty /dev/ttyIAX3
uucp     22533 22504  0 12:01 ?        00:00:00 iaxmodem ttyIAX4
uucp     22534 22504  0 12:01 ?        00:00:00 faxgetty /dev/ttyIAX4

There is one "enswitch_hylafax" process which creates the iaxmodem and faxgetty configuration files on the fly, starts the other processes, and restarts iaxmodems and faxgettys which exit. There is then one "faxq" and one "hfaxd" process, which form the core of Hylafax. Then there is one "iaxmodem" and one "faxgetty" process for each configured concurrent fax call based on the "maximum_fax_channels" Enswitch configuration option.

Call flow

Due to the client/server nature of Hylafax, and the fact that Hylafax processes are running as the "uucp" rather than the "enswitch" user, the call flow is quite complex:

1. enswitch_routed decides that the call is fax to email or fax to mailbox based on the enswitch database.
2. enswitch_routed sets a number of Asterisk channel variables with information about the call, such as which mailbox to save the fax in. It sets "CALLERID(number)" to be the Asterisk uniqueid of the call, and saves a variable with the fax filename also containing this. This allows the correct .tiff file to be retrieved later.
3. enswitch_routed dials each iaxmodem via IAX2 to 127.0.0.1 in turn, starting with ttyIAX0, which listens on port set by the "iaxmodem_base_port" Enswitch configuration option. Each successive iaxmodem then listens on the next port. For example, ttyIAX0 listens on UDP port 4600, ttyIAX1 on 4601, ttyIAX2 on 4602, etc. Each iaxmodem can only handle one call at a time, and any busy iaxmodems will return a network congestion error to Asterisk, so enswitch_routed will then try the next in sequence until it either finds an idle one, or runs out. If it does run out, the call is hung up.
4. iaxmodem passes the call through a Unix tty to faxgetty. Each one always uses the corresponding faxgetty, so "iaxmodem ttyIAX0" will always use "faxgetty /dev/ttyIAX0". The /etc/iaxmodem/ttyIAX* files and /var/spool/hylafax/etc/config.ttyIAX* symlinks are created by enswitch_hylafax when it starts, as it knows how many to create based on maximum_fax_channels.
5. faxgetty receives the fax, logging to a file in /var/spool/hylafax/logs, and producing a TIFF file in /var/spool/hylafax/recvq.
6. hfaxd invokes /var/spool/hylafax/bin/faxrcvd, which is a symlink to /opt/enswitch/current/sbin/enswitch_faxrcvd.
7. enswitch_faxrcvd makes a symlink from the TIFF in /var/spool/hylafax/recvq to a file in /var/lib/enswitch_local/tmp, where enswitch_routed is looking for a created file. The symlink name is based on the callerid, which was previously set to match the Asterisk uniqueid of the call.
8. After doing billing at the end of the call, enswitch_routed polls /var/lib/enswitch_local/tmp for the fax file, once a second for 10 seconds.
9. enswitch_routed counts the number of pages in the fax using tiffinfo.
10. enswitch_routed converts the file to PDF using tiff2pdf.
11. enswitch_routed deletes the symlink in /var/lib/enswitch_local/tmp.
12. enswitch_routed moves the file to a mailbox if fax to mailbox.
13. enswitch_routed sends emails and SMS as necessary.
14. The received fax file is left in /var/spool/hylafax/recvq until cleaned up by cron. This also allows inspection of recent faxes for errors.

Settings

The following settings under System » Configuration are relevant. After changing these, enswitch_routed and hylafax should both be restarted.

• Enable fax. This enables or disables fax globally.
• IAXmodem based port. The UDP port that the first IAX modem will listen on. The other iaxmodems will listen on sequential UDP ports. All such ports must be free when Hylafax starts. The default is "4600".
• Maximum fax channels. The number of iaxmodems and faxgettys to start. No more than this number of concurrent fax calls can be received. Setting this number too high may use excessive memory. The default is "5".