[This document augments the normal materials provided with the
HylaFAX v4.0pl0 source distribution.
All HylaFAX v4.0pl0 documentation is available on-line on the
World Wide Web (WWW) at the HylaFAX Home Page
http://www.vix.com/hylafax/]
HylaFAX is a fax system for UNIX systems. It supports:
Faxes can be any size (e.g. A4, B4), either 98 or 196 lpi, and transmitted/received as either 1D-encoded or 2D-encoded fax data (2D-encoded data is frequently more compact and hence takes a shorter time to communicate).
Outgoing documents can be text, postscript, or TIFF/F. This is easily extended to handle other formats (typerules(1)) in a way similar to the System V /etc/magic file to deduce document types and to decide how to convert each document to a form suitable for transmission (either PostScript or TIFF/F). Automatic cover page generation (faxcover(1)) is supported and users can easily tailor cover pages to their environment. A simple text-based phonebook database is supported by sendfax. Information is also provided on how to easily setup an email to fax gateway service (faxmail(1)).
Incoming faxes are stored in a receiving area as TIFF/F files and may be automatically delivered by mail and/or printed; see faxrcvd(1M). A fax server status program, faxstat(1), can be used to monitor the send and receive queues, as well as the state of fax servers.
Fax modems may be shared with outgoing data communication applications that honor the "uucp locking protocol". These applications typically include: cu, tip, kermit, uucp, slip, and ppp. The system can also be configured to enable incoming data calls to cause the system to invoke the standard system getty program.
The software is structured around a client-server architecture. One fax server process (faxgetty(1M)) exists for each fax modem on a network and one server process (faxq(1M)) for each fax-queue on a computer on a network. Clients may send fax from any machine that can communicate with the machine(s) on which the server(s) reside. The server side of the protocol is handled by the daemon (hfaxd(1M)) the protocol itself is implemted in form of the standard FTP protocol. Client software is designed to be lightweight and easy to port; imaging can be offloaded to the server or done on the client. (Imaging is, however, typically done on the server because it simplifies administration.) Multiple modems may be located on a single machine. An access control mechanism is included to control which users on which machines may submit documents for transmission.
The system supports a wide variety of fax modems. Almost any Class 1, Class 2, Class 2.0 modem should work with the system.
There is also support for pager devices.
Please report all problems & bugs regarding this particular binary distribution to me, Nico Garcia.
Disclaimer: THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
In addition for the binary distribution:
IN NO EVENT SHALL NICO GARCIA OR HIS EMPLOYERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
The binary distribution package of HylaFAX v4.0 is available in gzipped tar format and was compiled under SunOS 4.1.4 with GNU gcc version 2.7.2.1 and libg++ 2.7.2. The package contains a complete set of server and clients together with some goodies to ensure a complete and ready to use system.
The installation and execution of previous versions of Hylafax worked on the following SunOS systems and HylaFAX v4.0 should work on them as well (please let me know):
To install and run HylaFAX v4.0 you need the following ressources on your system:
In addition there is some publicly available software necessary to run HylaFAX on your computer. You need version 2.6.1 or later of ghostscript. This package is under the GNU Public License and the source for it can be retrieved by ftp from its distribution site, ftp://ftp.cs.wisc.edu/pub/ghost/. I strongly recommend the Aladdin version 4.00 with its fonts, at ftp://ftp.cs.wisc.edu/pub/{ghost/aladdin, rather than the GNU version (which is less recent). There are other useful features available there, such as JPEG and dll and certain GNU drivers which are very nice to have, although they are not strictly necessary for Hylafax.
There is also an optimizer bug with gcc-2.7.2 that is tripped by ghostscript-4.00. This has been patched in gcc-2.7.2.1 in case you wish to recompile your gcc installation.
A full ghostscript binary and fonts in gzipped tar,
with all the drivers, is also available at
ftp://sgi.com/sgi/fax/binary/gs-sunos414-gs4.00-tar.gz
You need a recent version of gawk, since the SunOS awk command cannot handle some of the needs of the hylafax shell scripts. The latest version is gawk-3.0.0, and is available from the Free Software Foundation ftp site. Version 2.11 is confirmed as definitely *not* working with Hylafax
GETTING THE DISTRIBUTION PACKAGE
The package is available free from ftp://sgi.com/sgi/fax/binary/hylafax-bsunos4.1.4-v4.0pl0-tar.gz, where Sam Leffler, the creator of Hylafax, has graciously agreed to keep some binaries.
If you retrieve the package from any ftp-server you should check the sum(1) or the MD5 value of the package: (note you're going to install setuid software) The correct values are:
sum(1): 45459 2291 hylafax-sunos4.1.4-v4.0pl0-tar.gz MD5: d365025d5010282c3babc1b8a5c97331 hylafax-sunos4.1.4-v4.0pl0-tar.gz
If you have already installed an older binary distribution of FlexFAX or HylaFAX on your system backup your old spooling area (e.g. with tar(1)) and simply delete the entire old distribution.
Please note that the SunOS binaries do not use the default Hylafax software and spooling directories, because SunOS typically has a rather small /var partition which will overflow with big printer spools or software it. Instead, I've transferred them to the /usr/local/hylafax and /usr/local/spool/hylafax directories and installed symbolic links to them in /var and in /usr/local/bin.
To install the binary SunOS distribution of Hylafax perform the following steps as root:
prompt# gzcat hylafax-sunos4.1.4-v4.0pl0-tar.gz | tar xvpf - -C /
If you also need to install ghostscript, use this:
prompt# gzcat gs-sunos4.1.4-4.00-tar.gz | tar xvpf - -C /
This HylaFAX distribution was compiled with the following configuration parameters:
HylaFAX configuration parameters are:
[ 1] Directory for applications:
/usr/local/hylafax/bin
[ 2] Directory for lib data files:
/usr/local/hylafax/lib
[ 3] Directory for lib executables:
/usr/local/hylafax/lib
[ 4] Directory for system apps:
/usr/local/spool/hylafax/bin
[ 5] Directory for manual pages:
/usr/local/hylafax/man
[ 6] Directory for HTML documentation:
/usr/local/httpd/htdocs/hylafax
[ 7] Directory for spooling:
/usr/local/spool/hylafax
[ 8] Directory for font metrics:
/usr/openwin/lib/fonts/afm
[ 9] Directory for uucp lock files:
/var/spool/locks
[10] Uucp lock file scheme:
ascii
[11] PostScript imager package:
gs
[12] PostScript imager program:
/usr/local/bin/gs
[13] Manual page installation scheme:
bsd-source-cat-strip
[14] Default page size:
North American letter
[15] Default vertical res (lpi):
196
[16] Location of getty program:
/usr/etc/getty
[17] Location of voice getty program:
/bin/vgetty
[18] Location of sendmail program:
/usr/lib/sendmail
[19] Location of TIFF tools:
/usr/local/bin
Several of the above pathnames are
compiled into applications included in this binary distribution.
If any of these pathnames are unacceptable, your best options
are to create a symbolic link to the installed directory hierarchies
or to retrieve the HylaFAX source distribution and recompile from scratch.
Fortunately, compilation is very easy with this software. You need a good
ANSI C++ compiler like gcc-2.7.2.1 and libg++-2.7.2, from the Free Software
Foundation
ftp site
If you decide to recompile, there is a file in the source distribution called hylafax-v4.0pl0/config.site that can be edited, or it can be copied to hylafax-v4.0pl0/config.local and edited there to store these changes. Options include the compiler, flags, whether and where to install local html pages, etc. In general, there is little reason to modify them. The configuration scripts are very good at detecting and using appropriate settings without interference.
Some of the above parameters can also be changed after installation by editing various configuration files, see also config(4F).
If you have access to the World Wide Web, go to the HylaFAX Home Page at http://www.vix.com/hylafax/ and read the documentation. In particular, read the information that describes how to setup a fax server.
Online documentation is also available through the manual pages; consult hylafax(1) and hylafax(4F) for introductory information on the client applications and the server setup, respectively.
In order to run HylaFAX you need a modem with fax support (Class 1, Class 2, or Class 2.0). This modem must be connected to your system on an RS232 serial port or must be an internal modem card and you have to know, to which port (e.g. ttya) it is connected. (Many users have reported good success with terminal servers as well, although I have not tried it myself). For the modem-configuration part of the installtion you must know a little bit about your modem and the AT commands to control various settings in the modem. If you are in doubt ask a guru or consult the documentation that comes with your modem (don't buy a modem without documentation.)
If you don't have any of these (documentation or guru) handy you are on your own; try configuring the modem and if you have a problem consult the WWW documentation or ask for help on the HylaFAX mailing list (see below). There is also a new Modems for Dummies out: look for it in your local bookstore.
You should consult the FAQ of HylaFAX before asking questions already answered.
It is a good idea to first check out your serial port with a terminal emulation program (e.g. kermit or cu) to test the modem and the name of the tty. Remember that you should use the same tty names for ALL modem programs.
If the modem is properly connected to your computer and your software installed, login as root and run faxsetup(1M):
prompt# sh /usr/local/spool/hylafax/bin/faxsetup
Here is the log of the messages, questions and answers during faxaddmodem. At any time you might safely interrupt the faxaddmodem without causing any problems.
Setup program for HylaFAX (tm) v4.0pl0.
Created for sparc-sun-sunos4.1.4 on Fri Aug 30 09:00:35 EDT 1996.
Checking system for proper client configuration.
Checking system for proper server configuration.
Warning: /bin/vgetty does not exist or is not an executable
program!
The file:
/bin/vgetty
does not exist or this file is not an executable program.
The HylaFAX software optionally uses this program and the
fact that it does not exist on the system is not a fatal
error. If the program resides in a different location and
you do not want to install a symbolic link for /bin/vgetty
that points to your program then you must reconfigure and
rebuild HylaFAX from source code.
Warning: /bin/egetty does not exist or is not an executable
program!
The file:
/bin/egetty
does not exist or this file is not an executable program.
The HylaFAX software optionally uses this program and the
fact that it does not exist on the system is not a fatal
error. If the program resides in a different location and
you do not want to install a symbolic link for /bin/egetty
that points to your program then you must reconfigure and
rebuild HylaFAX from source code.
Warning: No hylafax service entry found!
No entry was found for the hylafax service in the YP/NIS
database or in the /etc/services file. The software
should work properly without one (except if you want
to start hfaxd from inetd), but you will see warning
messages whenever you run a HylaFAX client application.
If you want to manually add an entry the following
information should be used:
hylafax 4559/tcp # HylaFAX client-server protocol
Should a hylafax entry be added to /etc/services [yes]? yes
Warning: No snpp service entry found!
No entry was found for the Simple Network Paging Protocol
(SNPP) service in the YP/NIS database or in the
/etc/services file. The software should work properly
without one (except if you want to start hfaxd from inetd),
but you will see warning messages whenever you run the
HylaFAX sendpage program. If you want to manually add an
entry the following information should be used:
snpp 444/tcp # Simple Network Paging Protocol
Should an snpp entry be added to /etc/services [yes]? yes
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]? yes
There does not appear to be an entry for the FaxMaster either
in the YP/NIS database or in the /usr/lib/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 /usr/lib/aliases [yes]? no
Modem support functions written to
/usr/local/spool/hylafax/etc/setup.modem.
Configuration parameters written to
/usr/local/spool/hylafax/etc/setup.cache.
No scheduler config file exists, creating one from scratch.
Country code [1]? 49
Area code []? 89
Long distance dialing prefix [1]? 0
International dialing prefix [011]? 00
Dial string rules file (relative to
/usr/local/spool/hylafax) ["etc/dialrules"]?
Tracing during normal server operation [1]? 11
Default tracing during send and receive
sessions [0xffffffff]? 11
Continuation cover page (relative to
/usr/local/spool/hylafax) []?
Timeout when converting PostScript documents (secs) [180]?
Maximum number of concurrent jobs to a destination [1]?
Define a class of modems []?
Time of day restrictions for outbound jobs ["Any"]?
Pathname of destination controls file (relative to
/usr/local/spool/hylafax) []?
Timeout before purging a stale UUCP lock file (secs) [30]?
Max number of pages to permit in an outbound
job [0xffffffff]? 25
Syslog facility name for ServerTracing
messages [daemon]? local0
The non-default scheduler parameters are:
LogFacility: local0
CountryCode: 49
AreaCode: 89
LongDistancePrefix: 0
InternationalPrefix: 00
ServerTracing: 11
MaxSendPages: 25
SessionTracing: 11
Are these ok [yes]?
Creating new configuration file
/usr/local/spool/hylafax/etc/config...
Restarting HylaFAX server processes.
Should I restart the HylaFAX server processes [yes]? no
You do not appear to have any modems configured for use.
Modems are configured for use with HylaFAX with the
faxaddmodem(1M) command. Do you want to run faxaddmodem
to configure a modem [yes]? yes
Serial port that modem is connected to []? ttya
Ok, time to setup a configuration file for the modem.
The manual page config(4F) may be useful during this
process. Also be aware that at any time you can safely
interrupt this procedure. Reading scheduler config file
/usr/local/spool/hylafax/etc/config.
No existing configuration, let's do this from scratch.
<... modem specific part deleted ...>
Creating new configuration file
/usr/local/spool/hylafax/etc/config.ttya...
Creating fifo /usr/local/spool/hylafax/FIFO.ttya
for faxgetty... done.
Done setting up the modem configuration.
Checking /usr/local/spool/hylafax/etc/config
for consistency... ...everything looks ok; leaving
existing file unchanged.
Don't forget to run faxmodem(1M) (if you have a send-only
environment) or configure init to run faxgetty on ttya.
Do you want to run faxaddmodem to configure another modem [yes]? no
You do not appear to be using faxgetty to notify the HylaFAX scheduler
about new modems and/or their status. This means that you must use the
faxmodem program to inform the new faxq process about the modems you
want to have scheduled by HylaFAX.
Should I run faxmodem for each configured modem [yes]? no
Done verifying system setup.
Additionnally you may reconfigure any other type of modem later with faxaddmodem(1M).
Note: If the faxaddmodem(1M) script seems to hang, suspend it and look for fuser processes that have hung. Sometimes fuser simply hangs under SunOS. Kill them off, restore your faxaddmodem job, and ignore the complaints about missing fuser commands.
For SunOS 4.1.4, there are a number of configuration changes and patches will want installed.
SunOS recommends something called the split device trick for sharing modems for dial-in and dial-out. This absolutely does not work with Hylafax, nor does it work with Sbus serial expanders or a plethora of other increasingly popular setups. Hylafax will itself handle providing getty and sharing the modem with kermit, uucp, and tip: simply delete any /dev/cua* devices associated with your serial lines, and edit the /etc/uucp/Devices file to use your tty* modem lines instead of cu*
If you are using an older SunOS, you will also want the jumbo tty patch to provide hardware flow control and prevent certain problems with the serial lines getting wedged. Fortunately, SunOS 4.1.4 does not require this patch. These patches do require recompiling your kernel: if they are not installed and you are not comfortable doing this, you should definitely rethink whether you have the expertise to run a fax server.
These patches are available at ftp://sunsolve1.sun.com/pub/patches/100513-05.tar.Z for SunOS 4.1.[123] and ftp://sunsolve1.sun.com/pub/patches/101621-04.tar.Z for SunOS 4.1.3_U1
HOW TO STARTUP THE FAX DAEMONS
There are some other system related files to examine. An excellent script (/usr/local/spool/hylafax/etc/hylafax) is provided to startup the faxservice; this is not installed by the default software configuration, but is in the /etc directory of the source code. This script can be used to start or stop an hfaxd if you decide to do so by hand rather than configuring it in your /etc/inetd.conf". If you wish to use this script, you should pull it any hylafax entries from /etc/inetd.conf" and edit your /rc.local" to start it.
To start the daemons without rebooting the system simply do as root:
prompt# sh /usr/local/spool/hylafax/etc/hylafax start
GETTY AND TTYMON RELATED CHANGES
The fax daemon process is capable of distinguishing between fax- and data-calls. If you want to provide "Login:" capability on data-calls you need to do the following steps:
Check the GettyArgs: value in your modem config file. This file was created by faxaddmodem and the name is something like /usr/local/hylafax/spool/etc/config.<ttyname>
GettyArgs: "std.%s -"Create entries for different baudrates in /etc/gettytab. All the standard baud rates are already present there.
You can allways contact the HylaFAX Home Page at http://www.vix.com/hylafax/ if you want access to the online documents. The HTML material is not provided with the binary distribution, it is too bulky.
If you decide to compile from source you may alter the
QUICKLY TEST YOUR INSTALLATION
To test your installation once you've configured your fax server and modem, startup the fax server as shown above, log out as root, and log in again as a "normal" user.
First check with faxstat(1) to make sure the server is running:
prompt> PATH=$PATH:/usr/local/hylafax/bin export PATH prompt> faxstat -s
the hfaxd(1M) daemon should respond with something like:
prompt> faxstat -s HylaFAX scheduler on #####: Running Modem ttya (+1.###.####): Running and idle Modem ttyb (+1.###.####): Running and idle prompt>
then send a short fax (change +1.111.111.1111 below to the number of a nearby fax machine):
prompt> sendfax -n -d +1.111.111.1111 <<EOF Hello world. I like the binary distribution of HylaFAX v4.0pl0 EOF prompt>
If you run the faxstat with the flag "-s" again you should see the job listed in the queue as being processed.
If you have problems that are not answered by the documentation included with the distribution check the WWW information. A mailing list for users of this software exists; see http://www.vix.com/hylafax/FAQ/ how to subscribe.