2. Installation

Key to a proper HylaFAX installation is getting the proper HylaFAX source or binary for your system. Therefore, please take care that the the versions that you use during installation correspond with the versions noted here. This document will cite specific source, filename, and version number whenever possible to avoid any confusion in the matter.

If this document proves insufficient for your needs, you may also want to consult http://www.hylafax.org/setup.html which contains more, although possibly archaic, information.

2.1 Modems

This document will not discuss modem installation except to say that the modem must be installed prior to HylaFAX installation. In most cases if minicom, tip, or cu can ''talk'' to it with ATI commands then the modem is installed properly for HylaFAX use.

• External Serial Modems
  Almost without exception, external serial faxmodems will work with HylaFAX. External modems are nice because they generally have some type of display which indicates activity. This can be useful when troubleshooting. External modems use external power sources and cabling, so it is important that they be located where they are not likely to be bumped or jostled. Because the modem can be power-cycled independently, there is some risk of the modem "losing" its initialization and staying uninitialized if care is not taken to address that scenario (usually by "writing" the initialized state to be used by default after a reset). However, this also can be useful in that a hung modem may be power-cycled without rebooting the server. Unless you are using external modems on a multiport serial card (you're using the system board's built-in serial ports), and because HylaFAX's faxgetty continually accesses the modem (unable to share the IRQ) you are generally limited to a combination of only two external serial or internal ISA faxmodems.
• Internal ISA Hardware (Jumpered or PnP) Modems
  As with external serial modems, internal ISA hardware faxmodems work with HylaFAX almost without exception. There need be no fear of power or data cables being jostled with internal modems, but there are no lighted displays, either, and power-cycling a hung one requires a system reboot. Because non-PnP hardware ISA modems use the same memory addresses and IRQs as external serial modems, the same limitation to only two applies. However, if your system supports Plug-n-Play, then ISA hardware PnP faxmodems will likely work as well, and these PnP modems may provide a means to go beyond that limitation. Be cautious when purchasing a new ISA modem since many new ISA modems are Windows-software-driven and do not have a hardware serial controller. Consequently it may not be able to be "spoken" to as noted above. US Robotics/3Com ISA Winmodems are a good example of what not to buy.
• Internal PCI Hardware Modems
  Yes, these exist, and for the most part, using PCI hardware modems is the most common and inexpensive way to break the two-modem limitation had by the modem types mentioned above. PCI hardware modems also work well with HylaFAX. These can be different to set up on your system than more traditional modems. On Linux, you may need to understand the 'setserial' command. Specifically, PCI modems using the 3Com "Kermit" chipset or the Lucent "Venus" chipsets are hardware modems and have been tested with HylaFAX. Examples are the USR/3Com 3CP5610(A), the MultiTech MT5634ZPX-PCI, or the Zoom 2920.
• Internal PCI or ISA "Linmodems"
  As have been tested, Linmodems (software-driven modems with Linux-compatible drivers available) will work with HylaFAX. Examples are Lucent Winmodems, PCTel modems, Conexant modems (with the Linuxant driver), and Intel/Ambient modems. The key to their compatibility is the quality and functionality of the Linmodem driver. One significant drawback to note when using many Linmodems with HylaFAX is that you are often limited to that one Linmodem, both because the driver will not support multiple instances and because some Linmodem drivers modify the behavior of the Linux serial driver. Consequently, normal hardware modems will not function properly in the presence of those Linmodem drivers, and other Linmodems will also not function properly in the presence of a foreign Linmodem driver. Only the Linuxant driver (Conexant) at this time is known to support multiple instances (for use with multiple identical Linmodems) and not modify the standard Linux serial driver as mentioned.
• External USB Modems
  Those that have been tested work fine as long as they can be "spoken" to as mentioned above. Note that there are soft-USB modems out there (see Linmodems above). Using USB modems is another possible way to get more than two modems on a system without the possible expense of a multiport modem.
• Internal Serial "MultiPort" Modems
  Using multiport modems such as the Comtrol RocketModem (or RocketPort attached to multiple external serial modems), MultiTech ISI MultiModem, Digi Acceleport RAS, Equinox MultiModem, MainPine RockForce, or Perle Systems equipment (take care in selecting one - research the hylafax-users mailing list archives for others' experience) is probably the best way to get more than six faxmodems into a system at once provided that the device is supported by your operating system. As mentioned already, a good way to determine traditional compatibility is to know if ATI commands can be issued directly from a terminal program such as listed above.
• ISDN, T1, and Other High-Bandwidth Digital Modems (with an AT-compatible command-interface)
  The Eicon Diva Server is known to work well. The Patton 2977 using recent firmware from Patton also works well. As for others, some work, some don't, and some work better than others. Again, traditional compatibility requires the hardware to be accessible by a terminal-like program. Please consult the hylafax-users mailing list (and archives) for user experience with HylaFAX using digital modems.
• Proprietary Hardware Devices such as BrookTrout Fax Boards, AVM Fritz!, or other equipment without an AT-compatible command-interface
  Products without an AT-compatible command-interface generally require integration with proprietary API from the manufacturer. If compatible, these devices will generally have their own fax drivers (faxsend, faxgetty), and any session-related issues usually must be resolved by the provider of those drivers (not the resources here). For information on support of BrookTrout devices, visit iFax Solutions at http://www.ifax.com. For information on support of CAPI and AVM Fritz! devices, visit http://freshmeat.net/projects/capi4hylafax. For other equipment, please consult with the manufacturer.

Selecting a Modem

Really, this is all up to you and your intended use of the faxmodem with HylaFAX. In general, most users are going to fare better using Class 1/1.0 than using Class 2/2.0/2.1 with recent versions of HylaFAX. Even if you're going to try using Class 2/2.0/2.1 it is wise to look for a modem that also supports Class 1/1.0, because if you find a bug in the Class 2 firmware, then you likely will need to rely on the manufacturer for a fix (and experience has shown that this can be difficult to obtain). If the modem supports Class 2 (and you intend to use Class 2) make sure that it supports both 1-D and 2-D image compression and perhaps even 2-D MMR image compression. If the fax line is likely to be busy and resources are limited, then you may be wise to select a modem that supports V.34-Fax (also called SuperG3) which allows faxing at speeds up to 33,600 baud (MultiTech 5634-V92-series, MainPine RockForce, and Eicon Diva Server modems are known to support this).

There is rightfully some concern as to which modem models work (or work best) with HylaFAX. The answer to that question is difficult and will undoubtedly be influenced by one's own experience. However, history on the hylafax-users mailing list has shown that modems with an older Rockwell chipset (RC144DPi, RC288DPi, or K56 found on many various ISA, external serial modems, and Comtrol RocketModems), modems with a newer Conexant chipset (found on MultiTech modems, Comtrol RocketModem IIs, Equinox MultiModems, and Linuxant-driven Linmodems), or modems with a new Lucent/Agere chipset (a.k.a. "Venus" found on MultiTech, Zoom, and MainPine modems) all work very well in Class 1 and 1.0 (if the modem reports support for it via the AT+FCLASS=? command). The Eicon Diva Server is known to work well in Class 2, and the MultiTech 5634-series modems are known to also work well in Class 2.0/2.1 in addition to Class 1/1.0 (especially when using newer firmwares).

As for things to avoid, shipped firmwares for Digi modems will not work in Class 1, and, although functional, the Class 2/2.0 implementation has some known bugs. Also in the functional-but-buggy category are USR/3Com modems; they tend to work better in Class 1 than in Class 2.0, but it still isn't ideal. (USR doesn't seem to be fixing these things, either.) If you use one of these modems and experience problems do not be surprised to learn that it is an issue with the modem itself.

As for anything else, HylaFAX has a fair number of pre-made configuration files for many common modem types. Modem type is determined by ATI0 and ATI3 commands in Class 1, AT+FMFR? and AT+FMDL? commands in Class 2, and AT+FMI? and AT+FMM? commands in Class 2.0 and 2.1. Click here for the current list of modems with default prototype configuration files in HylaFAX. However, if you're willing to work on a configuration file, then almost any faxmodem should generally work. The following links contain modems that have been used with some degree of success and with some version of HylaFAX. Note that modems can vary greatly between model numbers and firmware revisions.

http://hyla.xtremeweb.de/cgi-bin/hyla/hylaeng.pl/HowToMake

More modem compatibility information can be found at: http://www.hylafax.org/modems.html and http://www.hylafax.org/Modems/.

2.2 Source Installation

• 2.2.1 - HylaFAX Prerequisets
  • libtiff - get it at http://www.remotesensing.org/libtiff/
    LZW compression is not required. BSD needs at least version 3.5.6 to compile. Do not use an unpatched version 3.6.1.
  • Ghostscript - get it at http://www.cs.wisc.edu/~ghost/
    SGI IRIX users may use Impressario or DPS.
  • zlib - usually available with libtiff or Ghostscript
  • awk, gawk, mawk, or nawk - get mawk at ftp://ftp.whidbey.net/pub/brennan/
    Many distributions come with one of these already.
  • sendmail or compatible SMTP - get it at http://www.sendmail.org/
    Many distributions come with one.
  • metamail, uuencode, or base64-encode
    For optional use in fax-to-mail gateways.

• 2.2.2 - Download and Extract the Source Code

  Get and extract the HylaFAX source from: ftp://ftp.hylafax.org/source/.
  Change directories to to /usr/src/ and extract the tarball via 'tar xzvf hylafax-version.tar.gz'. The tarball can now be deleted if so desired.

• 2.2.3 - Compile the Source Code and then Install HylaFAX

  Change the working directory to /usr/src/hylafax.
  Compile and install HylaFAX as traditionally done by most source installations:

  ./configure (use all of the defaults)
  make
  make install (must be root or equivalent)
  

  If you are using an environment that supports DSOs and HylaFAX supports DSOs in your enviornment (i.e. Linux), then you must ensure that your /etc/ld.so.conf (or equivalent) file contains a reference to /usr/local/lib or wherever libfaxserver.so and libfaxutil.so were installed. (Remember that if you alter /etc/ld.so.conf you must run ldconfig afterwards.)

• 2.2.4 - Run faxsetup and faxaddmodem

  With root permissions, execute '/usr/local/sbin/faxsetup'. When finished, faxsetup will automatically run faxaddmodem for you. Generally, you can follow all of the defaults except those for FaxMaster, the local fax number(s), TSI, and any modem-specific information in faxaddmodem.

• 2.2.5 - Starting the hfaxd, faxq, and faxgetty Daemons

  This procedure may vary depeding on your specific operating system and init type. Be cautious to follow what is appropriate for your environment.

  On BSD-init (non-SysV-init) systems, you may need to edit etc/setup.cache and change the appropriate lines to read:

  FAXQ_SERVER='yes'
  HFAXD_SERVER='yes'
  SYSVINIT='/usr/local/sbin/hylafax'
  

  Edit /etc/rc.d/rc.local and add the lines:

  # Starting the HylaFAX hfaxd and faxq Daemons at Boot.
  /usr/local/sbin/hylafax start
  

  Edit /etc/inittab and add a line(s) similar to:
  m0:2345:respawn:/usr/local/sbin/faxgetty ttyS0
  where 'm0' is unique in inittab and 'ttyS0' matches the device name(s) used at the outset of the faxaddmodem script.

• 2.2.6 - faxcron and faxqclean

  It would be wise to run faxcron and faxqclean regularly from cron so that the queue directories do not clutter up and fill the storage device. Many installations run faxqclean every hour and faxcron every day. Insert something like this into your uucp or root crontab file:

  0 * * * * /usr/local/sbin/faxqclean
  0 0 * * * /usr/local/sbin/faxcron | mail -s "HylaFAX Usage Report" faxmaster
  

• 2.2.7 - Finishing Up

  Either restart the system, or alternatively, execute the following commands:

  /usr/local/sbin/hylafax start
  /sbin/init q
  

  Now you're done with a basic HylaFAX installation. Check things out with faxstat and various other tests as noted in this document. You'll also likely want to configure faxcron and faxqclean. See 6. General Tweaking and Customization Hints for those instructions.

2.3 Binary Installation

If HylaFAX binaries are available for your environment, many times installing them will prove to be much easier than performing a source installation. Also, binary installations generally will provide a more uniform installation layout similar to other packages already on the system. A binary installation generally maintains the integrity of the system's package management system, especially in the case of RPM, which gives good vigilence over conflicts, requirements, and makes upgrading or uninstallations simple. If current HylaFAX binaries are available for your environment, it is generally recommended to use them or make them yourself for installation.

Note, however, that when using binaries made by others that you are often required to use specific versions of dependant packages (i.e. libtiff or awk) based on the packager's configuration.

2.3.1 RedHat Linux, Linux Mandrake, and Turbo Linux Installation (i386)

This installation has been used on RedHat 6.1 (Cartman), 6.2 (Zoot), 7.0 (Guinness), 7.1 (Seawolf), Linux Mandrake 7.1, and Turbo Linux 6.0.

2.3.1.1

Get the HylaFAX RPM file from:
ftp://ftp.hylafax.org/binary/linux/redhat/RPMS/i386/

2.3.1.2

The following packages should be properly installed before HylaFAX. You can test by executing 'rpm -q packagename'.

• libtiff-3.5.5 or better
  (get it at ftp://ftp.redhat.com/pub/redhat/updates/6.2/i386/libtiff-3.5.5-2.i386.rpm)
• ghostscript-5.50 or better
  (get it at ftp://ftp.redhat.com/pub/redhat/redhat-6.2/i386/RedHat/RPMS/ghostscript-5.50-1.i386.rpm)
• ghostscript-fonts-5.50 or better
  (get it at ftp://ftp.redhat.com/pub/redhat/redhat-6.2/i386/RedHat/RPMS/ghostscript-5.50-1.i386.rpm)

Uninstall mgetty-sendfax if it is installed via 'rpm -e mgetty-sendfax'.

(Please note that the package versions listed above may not necessarily be the minimum requirement. These are tested versions.)

2.3.1.3

Install the HylaFAX RPM file(s) via 'rpm -Uvh hylafax*rpm'.

Run /usr/sbin/faxsetup and then /usr/sbin/faxaddmodem and answer the questions appropriately. Note that it is critical to be consistent in the nomenclature for the modem. RedHat likes to set up /dev/modem as a symbolic link to the real serial port (for example /dev/ttyS1), however, I would recommmend that /dev/ttySx be used religiously during the HylaFAX setup.

If faxaddmodem does not detect your modem type automagically then you will likely need to create a config file in /var/spool/hylafax/config for your modem and re-run faxaddmodem. See Section 6.1, ''Modem Config Files''.

2.3.1.4

Add the line: 'mo:2345:respawn:/usr/sbin/faxgetty ttySx' to /etc/inittab where ttySx is the name of your /dev device used in faxsetup and faxaddmodem.
Also, run '/usr/sbin/ntsysv' and make sure that the ''hylafax'' service is set to be started. This service can be started, stopped, and restarted as any other service via '/etc/rc.d/init.d/hylafax'.

2.3.1.5

HylaFAX faxsetup created a mail alias called FaxMaster. Edit this alias to direct mail to the intended recipient of fax information and incoming faxes. For example, 'pico /etc/aliases' and change the appropriate line to 'FaxMaster: faxuser@mydomain.com' where faxuser@mydomain.com is the intended e-mail address of the incoming fax recipient. (Actually, this could have been configured during faxsetup, but it likely got missed.) Then execute '/usr/bin/newaliases'.

2.3.1.6

The HylaFAX installation is now complete. However, you'll likely only be able to receive one fax without re-executing '/usr/sbin/faxgetty ttySx' each time. So, the easiest way to get the /etc/inittab changes functioning is to restart the server, 'shutdown -r now' or to restart init via '/sbin/init q'.

If this section proves insufficient for your needs, you may wish to consult http://cirl.meei.harvard.edu/hylafax/linux/INSTALL-linux-4.1beta2.html for more, although possibly outdated, information.

Thanks for this section additionally goes to Anil for his comments.

2.3.2 SuSE Linux Installation

2.3.2.1

If using SuSE Linux versions 6.3 or earlier, you need to update your libtiff packages to versions 3.5 or greater. These are available at ftp://ftp.suse.com/pub/suse/i386/6.4/suse/gra1/libtiff.rpm

The RPM packages should be updated using YaST or directly with rpm and the option -U. If you have an internet connection then you can simply say:

'rpm -U ftp://ftp.suse.com/pub/suse/i386/6.4/suse/gra1/libtiff.rpm'
or if the file is in your current directory:
'rpm -U libtiff.rpm'

2.3.2.2

Go into YAST and make sure that the packages mgetty and sendfax or not installed. mgetty can conflict with HylaFAX. If you already installed mgetty and sendfax, then uninstall them. Uninstall the old HylaFAX via YAST, if you already installed it.

Now get the SuSE HylaFAX RPM at ftp://ftp.hylafax.org/binary/linux/suse/

Go into YAST. "Choose/install packages"->"Install packages" Hit Type in the directory path where the downloaded HylaFAX rpm is. Hit to show a list of all files. Choose and install.

2.3.2.3

Make sure HylaFax and Faxgetty are not running.

• Make sure that HylaFax is not running at bootup. Go into YAST "system administration" -> "Change configuration file" and set START_HYLAFAX to "no"
  Note: This is temporary.
• Make sure that Faxgetty is not running at bootup. Go into /etc/inittab and make sure that the faxgetty line is commented out.
  Note: This is temporary.
  Here is what mine looks like when commented out.

  <snip>
# fax getty (hylafax)
# mo:2345:respawn:/usr/lib/fax/faxgetty /dev/ttyS1
<snip>

  (your 'mo' line may end with ~/modem, ~/ttyS2, etc.)

2.3.2.4

Preparation advice before running faxsetup and faxaddmodem.

A.

The following question is asked by faxsetup in the beginning of the configuration :

    There is no entry for the hylafax service in /etc/inetd.conf.



    The HylaFAX client-server protocol process can be setup to run

    standalone or started by the inetd program. A standalone setup

    is preferred for performance reasons, especially if hfaxd is to

    support multiple protocols (e.g. SNPP); however it may require

    manual setup if your operating system does not have a System-V

    style init program.



    Should an entry be added to /etc/inetd.conf [no]?

You must answer 'no' to this question! If you have nethertheless answered with 'yes', then remove the entry:
'hylafax stream tcp nowait fax /usr/lib/fax/hfaxd hfaxd -I'
from /etc/inetd.conf! It will be the very last line in the file.

B.

If you answered 'etc/cover.templ' to 'continuation cover page...' (as suggested by the printed manual), make sure that it works. It failed for me. I deleted this from the config file because i do not need cont cover pages. I do not know how to make them work.

C.

During faxaddmodem you will be asked 'Which device is your modem set to?' Do not answer '/dev/modem' or '/dev/ttySx' etc. Simply answer 'modem' or 'ttySx'. It is better to choose 'ttySx', this way you won't run into lock file problems. If you do choose 'ttySx', then you will want to make sure that all other programs are set direct to the /dev/ttySx, not to /dev/modem. I, for instance, was using /dev/modem for ppp connection to the internet. In faxaddmodem, I chose ttyS1 . Afterwards, my ppp connection would not work. I simply set my modem settings to /dev/ttyS1 also, in my ppp settings. That fixed it. You have to choose one method for all your programs. You can't mix them up with /dev/modem here and /dev/ttySx there.

D.

When faxaddmodem asks which modem fax class to use, you may want to consult with others with the same modem model and HylaFAX to see which class they use successfully. If things aren't working for some reason in one class, then try the other. Generally speaking, if a modem works well in both Class 1 and Class 2/2.0, then choose Class 2/2.0.

2.3.2.5 - Let's change some things.

A.

Edit the file /var/spool/hylafax/etc/config. If you have HylaFax 4.1 are higher installed, you should see a line that looks like ModemGroup: "any" change it to ModemGroup: "any:.*"

B.

Make sure that HylaFax is running at bootup. Go into YAST "system administration" -> "Change configuration file" and set START_HYLAFAX to "yes"

C.

Make sure that Faxgetty is running at bootup. Edit /etc/inittab and make a faxgetty line. Note that mingetty is not a fax program. Add this line: 'mo:2345:respawn:/usr/lib/fax/faxgetty /dev/ttySx'. Remember that /dev/ttySx refers to the device you used earlier during faxsetup. It could possibly be /dev/ttyS1 or /dev/modem, depending on where your modem is set to.

Also note that some people use 'mo' or 'fx' or 'S0' or 'S1' as the first two characters in the faxgetty command line. You can use any two characters you want as long as they are unique and do not interfere with another command line.

2.3.2.6 - Let's Check Things Out

Create some small ASCII text file called 'testpage'. To test HylaFAX, enter:
'sendfax -n -D -d 123-4567 testpage'
where 123-4567 is the number of some remote fax machine. Everything should have gone as expected. If not, consult the Using HylaFAX Server-faxstat and Troubleshooting sections of this HOW-TO. The HylaFAX installation is now complete.

If this section proves insufficient for your needs, you may wish to consult the printed SuSE installation manual which documents well the HylaFAX installation.

Thanks for this section additionally goes to Bernd Proissl news@proissl.de for his help and George Zeigler genz1968@mtu-net.ru for his FAQ.

2.3.3 Debian Linux

Run apt-get install hylafax-server and follow the general outline for other systems detailed above.

2.3.4 Other Binaries

Other binaries are known to exist for the following operating systems. Note that they may be not be made from current HylaFAX source or contain proprietary configurations.

• Debian Linux - http://packages.debian.org/hylafax-server
• FreeBSD - http://www.freebsd.org/ports/comms.html
• Linux Mandrake
• SCO - ftp://ftp.multitalents.net/pub/hylafax/
• SuSE Linux - ftp://ftp.suse.com/pub/suse/i386/update/6.4/n1/

2.3.5 Packagers

This is a table of the various persons who package HylaFAX binary distributions listed above.

Host Organization	Binary Type	Packager(s)
hylafax.org	RedHat RPM	Darren Nickerson <darren@dazza.org>
hylafax.org	SuSE RPM	Bernd Proissl <lists@proissl.de>
SuSE Linux	SuSE RPM	Carsten Hoeger <choeger@suse.de>
Linux Mandrake	Mandrake RPM	Thierry Vignaud <tvignaud@mandrakesoft.com>
Debian Linux	Debian DEB	Giuseppe Sacco <eppesuig@debian.org>
multitalents.net	SCO binary	Tim Rice <tim@multitalents.net>
Gentoo Linux	Gentoo ebuild	Steve Arnold <nerdboy@gentoo.org>

2.4 CVS Source Installation

If you have a CVS client, and if you wish to be on the cutting/bleeding edge of HylaFAX progress or participate in testing or development, then you can use CVS source from which to build HylaFAX.

Full details are available at http://www.hylafax.org/cvs.html, however, essentially you execute:

    cvs -d ":pserver:cvs@cvs.hylafax.org:/cvsroot" login
    cvs -d ":pserver:cvs@cvs.hylafax.org:/cvsroot" get hylafax

Last updated $Date: 2005/07/20 00:31:16 $.