Introduction

From Enswitch 3.14 onwards, SpanDSP is the standard Enswitch fax sub-system, replacing Hylafax/IAXmodem which is still available as an option and can run concurrently with the SpanDSP fax driver.

Installation and starting

"enswitch install hylafax" will install and start Hylafax and IAXmodem automatically. Once installed, they can also be started using "service hylafax start" (or "systemctl start hylafax.service" on systemd Linux distributions). The init.d script (or unit file on systemd distributions) 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.
• Set "Fax send driver" to "hylafax".
• Set "Fax receive driver" to "hylafax".
• Set "Enable fax server" to "Yes" if not already set so.
• Set "Group for Hylafax" to the actual process gid (group id) that the faxgetty processes are running as.
• In each desired role set "Send faxes" to "Yes".
• Ensure /etc/enswitch and /etc/enswitch/databases.ini are readable and executable by all users on the Asterisk server.
• Ensure /var/lib/enswitch_local is readable and executable by all users, and /var/lib/enswitch_local/tmp is readable, executable, and writeable by all users on the Asterisk server.
• 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".