Search:  
Gentoo Wiki

HylaFAX


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc

Contents

Introduction

HylaFax is a high-powered suite of software for sending and receiving faxes on Unix systems. It is the leading solution in this area, and supports scripting, spooling, routing, and a wide range of hardware. For more information, see the HylaFAX article on Wikipedia.

Hardware Requirements

You can run HylaFax with a wide range of hardware, from oldschool modems to dedicated ISDN interface cards to no hardware whatsoever (using software faxmodems like iaxmodem).

If it is your first time setting up a fax modem or you are young (ie: post BBS-era!), then you might want to read your modem manual first and have a play around with a serial communications program to figure out what kind of initialisation strings are required and how this sort of hardware works.

Common programs in this category include net-dialup/minicom and net-dialup/xc. Minicom is the oldschool.

Recommended hardware

I have had a great experience assigning software iaxmodems to HylaFax, which route through Asterisk to an E1 card from Sangoma. Using this type of setup, your pool of 30 lines can be shared through Asterisk and used for incoming/outgoing voice until the moment a fax needs to be sent or received. Note that one or more dedicated phone numbers or PBX contexts are required to reliably receive faxes: since many fax systems have issues with automating calls to PBX extensions, a dedicated phone number is highly recommended.

Setup

USE flags are:

Note: - To be checked: - faxonly and mgetty seem to be mutually exclusive.

emerge -av net-misc/hylafax

There are some modules that are not installed by the HylaFAX ebuild, however are of importance for an enterprise fax server. If possible also install:

emerge -av sys-apps/gawk sys-libs/zlib net-mail/metamail 

If one wants to convert the coming faxes into a pdf, the following modules would be necessary:

emerge -av media-libs/tiff app-text/ghostscript

Configure

After you successfully installed HylaFAX on the server, you must run faxsetup. faxsetup will ask several questions about your installation. Here an example with the faxes number +49,012,345 67 89:

# faxsetup
Setup program for HylaFAX (tm) 4.2.1

Created for i686-pc-linux-gnu on Sun Jan 16 02:56:50 CET 2005.

Checking system for proper client configuration.
Checking system for proper server configuration.

Make /var/spool/fax/bin/ps2fax a link to /var/spool/fax/bin/ps2fax.gs.


Make /var/spool/fax/bin/pdf2fax a link to /var/spool/fax/bin/pdf2fax.gs.



You do not appear to have a "fax" user in the password file.
HylaFAX needs this to work properly, add it [yes]? yes
Added user "fax" to /etc/passwd.


There does not appear to be an entry for the FaxMaster either in
the YP/NIS database or in the /etc/mail/aliases file.  The
FaxMaster is the primary point of contact for HylaFAX problems.
The HylaFAX client-server protocol server identifies this alias as
the place to register complaints and HylaFAX directs automatic mail
messages to this user when problems are identified on a server
machine or when the routine server maintainence scripts are run
(e.g. faxcron).

Should an entry be added for the FaxMaster to /etc/mail/aliases [yes]?
Users to receive fax-related mail [steveb]? fax
Rebuilt /etc/mail/aliases database.
Update /var/spool/fax/status/any.info.

        HylaFAX configuration parameters are:

        [1] Init script starts faxq:            yes
        [2] Init script starts hfaxd            yes
        [3] Start old protocol:                 no
        [4] Start paging protocol:              no
Are these ok [yes]? yes

Modem support functions written to /var/spool/fax/etc/setup.modem.
Configuration parameters written to /var/spool/fax/etc/setup.cache.

No scheduler config file exists, creating one from scratch.
Country code [1]? 49
Area code []? 12
Long distance dialing prefix [1]? 0
International dialing prefix [011]? 00
Dial string rules file (relative to /var/spool/fax) ["etc/dialrules"]? etc/dialrules.europe
Tracing during normal server operation [1]? 1
Default tracing during send and receive sessions [0xffffffff]? 0xffffffff
Continuation cover page (relative to /var/spool/fax) []? /var/spool/fax
Timeout when converting PostScript documents (secs) [180]? 180
Maximum number of concurrent jobs to a destination [1]? 1
Define a group of modems []?
Time of day restrictions for outbound jobs ["Any"]? Any
Pathname of destination controls file (relative to /var/spool/fax) []?
Timeout before purging a stale UUCP lock file (secs) [30]? 30
Max number of pages to permit in an outbound job [0xffffffff]? 0xffffffff
Syslog facility name for ServerTracing messages [daemon]? daemon

The non-default scheduler parameters are:

CountryCode:            49
AreaCode:               12
LongDistancePrefix:     0
InternationalPrefix:    00
DialStringRules:        etc/dialrules.europe
ContCoverPage:          /var/spool/fax
DestControls:           /var/spool/fax
TimeOfDay:              Any

Are these ok [yes]? yes

Creating new configuration file /var/spool/fax/etc/config...

Restarting HylaFAX server processes.
Should I restart the HylaFAX server processes [yes]? yes

/usr/sbin/faxq

You do not appear to have any modems configured for use.  Modems are
configured for use with HylaFAX with the faxaddmodem(8C) command.
Do you want to run faxaddmodem to configure a modem [yes]? no

Done verifying system setup.

You can change the configuration at any time in the file /var/spool/fax/etc/config with your favourite editor.

Add modems

To add modems to HylaFAX, you must use the program ``fax ADD modem`` made available by HylaFAX™.

Setup program for HylaFAX (tm) 4.2.1.

Created for i686-pc-linux-gnu on Sun Jan 16 02:56:50 CET 2005.

Reading cached parameters from /var/spool/fax/etc/setup.cache.

Checking system for proper client configuration.
Checking system for proper server configuration.

Make /var/spool/fax/bin/ps2fax a link to /var/spool/fax/bin/ps2fax.gs.


Make /var/spool/fax/bin/pdf2fax a link to /var/spool/fax/bin/pdf2fax.gs.

Update /var/spool/fax/status/any.info.

        HylaFAX configuration parameters are:

        [1] Init script starts faxq:            yes
        [2] Init script starts hfaxd            yes
        [3] Start old protocol:                 no
        [4] Start paging protocol:              no
Are these ok [yes]? yes

Modem support functions written to /var/spool/fax/etc/setup.modem.
Configuration parameters written to /var/spool/fax/etc/setup.cache.

Restarting HylaFAX server processes.

You have a HylaFAX scheduler process running.  faxq will be
restarted shortly, as soon as some other work has been completed.
Can I terminate this faxq process (11995) [yes]? yes
Should I restart the HylaFAX server processes [yes]? yes

/usr/sbin/faxq

You do not appear to have any modems configured for use.  Modems are
configured for use with HylaFAX with the faxaddmodem(8C) command.
Do you want to run faxaddmodem to configure a modem [yes]? yes
Serial port that modem is connected to []? ttyS0

Ok, time to setup a configuration file for the modem.  The manual
page config(5F) may be useful during this process.  Also be aware
that at any time you can safely interrupt this procedure.

Reading scheduler config file /var/spool/fax/etc/config.

No existing configuration, let's do this from scratch.

Country code [1]? 49
Area code [415]? 12
Phone number of fax modem [+1.999.555.1212]? +49.12.345.67.89
Local identification string (for TSI/CIG) ["NothingSetup"]? Mein Gentoo HylaFAX Server
Long distance dialing prefix [1]? 0
International dialing prefix [011]? 00
Dial string rules file (relative to /var/spool/fax) [etc/dialrules]? etc/dialrules.europe
Tracing during normal server operation [1]? 1
Tracing during send and receive sessions [11]? 11
Protection mode for received facsimile [0600]? 0600
Protection mode for session logs [0600]? 0600
Protection mode for ttyS0 [0600]? 0600
Rings to wait before answering [1]? 1
Modem speaker volume [off]? on
Command line arguments to getty program ["-h %l dx_%s"]? -h %l dx_%s
Pathname of TSI access control list file (relative to /var/spool/fax) [""]?
Pathname of Caller-ID access control list file (relative to /var/spool/fax) [""]?
Tag line font file (relative to /var/spool/fax) [etc/lutRS18.pcf]? etc/lutRS18.pcf
Tag line format string ["From %%l|%c|Page %%P of %%T"]? Absender %%l|%c|Seite %%P von %%T
Time before purging a stale UUCP lock file (secs) [30]? 30
Hold UUCP lockfile during inbound data calls [Yes]? yes
Hold UUCP lockfile during inbound voice calls [Yes]? yes
Percent good lines to accept during copy quality checking [95]? 95
Max consecutive bad lines to accept during copy quality checking [5]? 5
Max number of pages to accept in a received facsimile [25]? 25
Syslog facility name for ServerTracing messages [daemon]? daemon
Set UID to 0 to manipulate CLOCAL [""]?
Use available priority job scheduling mechanism [""]?

The non-default server configuration parameters are:

CountryCode:            49
AreaCode:               12
FAXNumber:              +49.12.345.67.89
LongDistancePrefix:     0
InternationalPrefix:    00
DialStringRules:        etc/dialrules.europe
SessionTracing:         11
RingsBeforeAnswer:      1
SpeakerVolume:          off
GettyArgs:              -h %l dx_%s
LocalIdentifier:        Mein Gentoo HylaFAX Server
TagLineFont:            etc/lutRS18.pcf
TagLineFormat:          Absender %%l|%c|Seite %%P von %%T
MaxRecvPages:           25
LockDataCalls:          yes
LockVoiceCalls:         yes

Are these ok [yes]? yes

Now we are going to probe the tty port to figure out the type
of modem that is attached.  This takes a few seconds, so be patient.
Note that if you do not have the modem cabled to the port, or the
modem is turned off, this may hang (just go and cable up the modem
or turn it on, or whatever).

Probing for best speed to talk to modem: 38400 19200 9600 4800 2400 1200
Unable to deduce DTE-DCE speed; check that you are using the
correct device and/or that your modem is setup properly.  If
all else fails, try the -s option to lock the speed.
Do you want to run faxaddmodem to configure another modem [yes]? no

Done verifying system setup.
Setup program for HylaFAX (tm) 4.2.1.

Created for i686-pc-linux-gnu on Sun Jan 16 02:56:50 CET 2005.

Reading cached parameters from /var/spool/fax/etc/setup.cache.

Checking system for proper client configuration.
Checking system for proper server configuration.

Make /var/spool/fax/bin/ps2fax a link to /var/spool/fax/bin/ps2fax.gs.


Make /var/spool/fax/bin/pdf2fax a link to /var/spool/fax/bin/pdf2fax.gs.

Update /var/spool/fax/status/any.info.

        HylaFAX configuration parameters are:

        [1] Init script starts faxq:            yes
        [2] Init script starts hfaxd            yes
        [3] Start old protocol:                 no
        [4] Start paging protocol:              no
Are these ok [yes]? yes

Modem support functions written to /var/spool/fax/etc/setup.modem.
Configuration parameters written to /var/spool/fax/etc/setup.cache.

Restarting HylaFAX server processes.

You have a HylaFAX scheduler process running.  faxq will be
restarted shortly, as soon as some other work has been completed.
Can I terminate this faxq process (11995) [yes]? yes
Should I restart the HylaFAX server processes [yes]? yes

/usr/sbin/faxq

You do not appear to have any modems configured for use.  Modems are
configured for use with HylaFAX with the faxaddmodem(8C) command.
Do you want to run faxaddmodem to configure a modem [yes]? yes
Serial port that modem is connected to []? ttyS0

Ok, time to setup a configuration file for the modem.  The manual
page config(5F) may be useful during this process.  Also be aware
that at any time you can safely interrupt this procedure.

Reading scheduler config file /var/spool/fax/etc/config.

No existing configuration, let's do this from scratch.

Country code [1]? 49
Area code [415]? 12
Phone number of fax modem [+1.999.555.1212]? +49.12.345.67.89
Local identification string (for TSI/CIG) ["NothingSetup"]? Mein Gentoo HylaFAX Server
Long distance dialing prefix [1]? 0
International dialing prefix [011]? 00
Dial string rules file (relative to /var/spool/fax) [etc/dialrules]? etc/dialrules.europe
Tracing during normal server operation [1]? 1
Tracing during send and receive sessions [11]? 11
Protection mode for received facsimile [0600]? 0600
Protection mode for session logs [0600]? 0600
Protection mode for ttyS0 [0600]? 0600
Rings to wait before answering [1]? 1
Modem speaker volume [off]? on
Command line arguments to getty program ["-h %l dx_%s"]? -h %l dx_%s
Pathname of TSI access control list file (relative to /var/spool/fax) [""]?
Pathname of Caller-ID access control list file (relative to /var/spool/fax) [""]?
Tag line font file (relative to /var/spool/fax) [etc/lutRS18.pcf]? etc/lutRS18.pcf
Tag line format string ["From %%l|%c|Page %%P of %%T"]? Absender %%l|%c|Seite %%P von %%T
Time before purging a stale UUCP lock file (secs) [30]? 30
Hold UUCP lockfile during inbound data calls [Yes]? yes
Hold UUCP lockfile during inbound voice calls [Yes]? yes
Percent good lines to accept during copy quality checking [95]? 95
Max consecutive bad lines to accept during copy quality checking [5]? 5
Max number of pages to accept in a received facsimile [25]? 25
Syslog facility name for ServerTracing messages [daemon]? daemon
Set UID to 0 to manipulate CLOCAL [""]?
Use available priority job scheduling mechanism [""]?

The non-default server configuration parameters are:

CountryCode:            49
AreaCode:               12
FAXNumber:              +49.12.345.67.89
LongDistancePrefix:     0
InternationalPrefix:    00
DialStringRules:        etc/dialrules.europe
SessionTracing:         11
RingsBeforeAnswer:      1
SpeakerVolume:          off
GettyArgs:              -h %l dx_%s
LocalIdentifier:        Mein Gentoo HylaFAX Server
TagLineFont:            etc/lutRS18.pcf
TagLineFormat:          Absender %%l|%c|Seite %%P von %%T
MaxRecvPages:           25
LockDataCalls:          yes
LockVoiceCalls:         yes

Are these ok [yes]? yes

Now we are going to probe the tty port to figure out the type
of modem that is attached.  This takes a few seconds, so be patient.
Note that if you do not have the modem cabled to the port, or the
modem is turned off, this may hang (just go and cable up the modem
or turn it on, or whatever).

Probing for best speed to talk to modem: 38400 19200 9600 4800 2400 1200
Unable to deduce DTE-DCE speed; check that you are using the
correct device and/or that your modem is setup properly.  If
all else fails, try the -s option to lock the speed.
Do you want to run faxaddmodem to configure another modem [yes]? no

Done verifying system setup.

System startup

Add the following to /etc/inittab, replacing ttyS0 with the serial port the fax is attached to.

# fax getty (HylaFax) 
f0:2345:respawn:/usr/sbin/faxgetty /dev/ttyS0

Reload inittab

telinit Q

Update the system startup configuration to automatically start "hylafax" on boot.

rc-update ADD hylafax default

Start the daemon

/etc/init.d/hylafax restart

Security

Create HylaFAX accounts for each user

faxadduser -p password -u uid username
File: /var/spool/fax/etc/hosts.hfaxd
# localhost is allowed to fax
@127.0.0.1$
^localhost$

# all machines from our net 192.168.0.* are allowed to fax
# pay attention to quote the dot
@192.168.0.[0-9]+$

# anyone in gentoo.local domain
^.*@.*.\.gentoo\.local$
^.*@gentoo\.local$

# client:uid:passwd:adminwd
faxadmin:10:0YsaizBYdCrcA:mjA2319tc3Ysk


Additional configuration

Server-side

PDF conversion

You may wish to set up incoming faxes to be archived to PDF. A demonstration script is included in the distribution.

Incoming fax routing

Fax routing is quite difficult to achieve reliably, since there is only really caller-ID, fax length, and incoming number to fall back on. The easiest way to route incoming faxes most effectively is by assigning multiple incoming fax numbers. Other methods include analysis based on fax length, time received or other data, stateful databases ('we have sent through a contract and expect a reply') and fully-fledged OCR. Due to the complexity of the problem space, all bu the smallest-sized servers will probably want some form of automation, and this will require programing. See the HylaFax documentation for more information.

Email routing

A common scenario is converting received faxes to PDF, then emailing them to someone. This combines both of the techniques above. Again, see the HylaFax documentation and example scripts.

Client-side

There are a large number of HylaFax clients of varying size, quality and degree of software freedom. Key features include notification of fax job success/failure, job status review (some clients include historical fax review), and destination phone number lookup support (varies in format: MySQL database, flat files, etc.)

For windows I can recommend WinPrint HylaFax, which appears as a printer. Once installed, it pops up a dialog box when the user prints to that printer and allows querying a flat-file database for the destination number. It also includes email notification. If you use this software, you probably want to use cron on your server to output your destination phone number database periodically (presumably from a real, structured database). Then you can share that file out to your windows users via Samba, map a network drive, and then assign the resulting path to WinPrint HylaFax to enable lookups.

I only recommend this because other products I have looked at were either commercial, bloated (.net 2.0 anyone?), featured complex or nonstandard interfaces, or a combination of the above, hopefully someone else will save some time...

Retrieved from "http://www.gentoo-wiki.info/HylaFAX"

Last modified: Tue, 19 Aug 2008 05:14:00 +0000 Hits: 5,352