[This document augments the normal materials provided with the
HylaFAX v4.0beta018 source distribution.
All HylaFAX v4.0beta018 documentation is available on-line on the
World Wide Web (WWW) at the HylaFAX Home Page
http://www.vix.com/hylafax/]
HylaFAX is a facsimile system for UNIX systems. It supports:
Facsimile can be any size (e.g. A4, B4), either 98 or 196 lpi, and transmitted/received as either 1D-encoded or 2D-encoded facsimile data (2D-encoded data is frequently more compact and hence takes a shorter time to communicate).
Outgoing documents can be any format; the sendfax program uses a rule-based definition file 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 easy setup an email to fax gateway service.
Incoming facsimile 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 facsimile 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 ttymon/getty program.
The software is structured around a client-server architecture. One facsimile 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 facsimile 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. 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 binary distribution to me, Matthias Apitz.
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 MATTHIAS APITZ OR SOFTCON GmbH 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 pkgadd(1M) format and was compiled under SINIX-N myhost 5.42 A0007 RM400 1/128 R4000 with GNU gcc version 2.7.7 and libg++ 2.7.1. Actually the package contains a complete set of server and clients together with some goodies to ensure a complete and ready to use system.
To install and run HylaFAX v4.0 you need the following ressources on your system:
In addition there is some public available software necessary to run HylaFAX on your computer. You need the font-distribution tree of ghostscript-2.6.1 (a special 2.6.1 based gs.fax binary with a tiffg3- driver comes with HylaFAX v4.0. This part of the package is under the GNU Public License and the source for it could be retrieved by ftp from ftp.aladin.com).
A font-distribution in pkgadd format is also available from
ftp://sgi.com/sgi/fax/binary/gs261-mips-sinix5.42-pkg.tar.gz
GETTING THE DISTRIBUTION PACKAGE
The package is available for free from ftp://sgi.com/sgi/fax/binary/. It is also available together with support from SOFTCON GmbH.
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): 50942 5581 MD5: f35807e96dd157a8cc94291e8b87e3c5
If you have already installed an older binary distribution of HylaFAX on your system you may want to save files like hosts(4) or xferlog(4). Backup your old spooling area (e.g. with tar(1)) and remove the old distribution before with pkgrm(1M) and the old spooling area with:
thias# pkgrm HylaFAX thias# rm -r /usr/local/lib/HylaFAX/spoolif this is not already done by the package removal (depends on the version of the old distribution you have had installed).
To remove an old HylaFAX v4.0betaXXX from your system type:
thias# pkgrm HylaFAXv4 thias# rm -r /usr/local/lib/HylaFAX-v4.0/spool
To install the image hylafax-mips-sinix5.42-v4.0beta018-pkg do the following steps as root:
thias# cp hylafax-mips-sinix5.42-v4.0beta018-pkg.tar.gz /tmp
thias# cd /tmp
thias# gzcat hylafax-mips-sinix5.42-v4.0beta018-pkg.tar.gz | tar xvf -
thias# pkgadd -d /tmp
The following packages are available:
1 HylaFAXv4 HylaFAX v4.0beta018 for SINIX 5.42 (mips)
(R4000) v4.0beta018
Select package(s) you wish to process (or 'all' to process
all packages). (default: all) [?,??,q]: 1
.......
thias# rm hylafax-mips-sinix5.42-v4.0beta018-pkg.tar.gz
thias# rm -rf HylaFAXv4
This will install the SINIX 5.42 (mips) binary distribution of HylaFAX and parts of ghostscript software under:
/usr/local/lib/HylaFAX-v4.0/... /usr/local/lib/ghostscript/fonts/...No other parts of your system will be touched during this step of installation (except the package related database files of your Unix OS).
This HylaFAX distribution was compiled with the following configuration parameters:
HylaFAX configuration parameters are:
[ 1] Directory for applications:
/usr/local/lib/HylaFAX-v4.0/bin
[ 2] Directory for lib data files:
/usr/local/lib/HylaFAX-v4.0/lib
[ 3] Directory for lib executables:
/usr/local/lib/HylaFAX-v4.0/sbin
[ 4] Directory for system apps:
/usr/local/lib/HylaFAX-v4.0/sbin
[ 5] Directory for manual pages:
/usr/local/lib/HylaFAX-v4.0/man
[ 6] Directory for HTML documentation:
/usr/local/lib/HylaFAX-v4.0/html
[ 7] Directory for spooling:
/usr/local/lib/HylaFAX-v4.0/spool
[ 8] Directory for font metrics:
/usr/local/lib/ghostscript/fonts
[ 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/lib/HylaFAX-v4.0/spool/bin/gs.fax
[13] Manual page installation scheme:
sysv-source-cat-strip
[14] Default page size:
A4
[15] Default vertical res (lpi):
196
[16] Location of getty program:
/usr/lib/saf/ttymon
[17] Location of voice getty program:
/bin/vgetty
[18] Location of sendmail program:
/usr/ucblib/sendmail
[19] Location of TIFF tools:
/usr/local/lib/HylaFAX-v4.0/tiffbin
Several of the above pathnames are compiled into applications included in this binary distribution. If any of these pathnames are unacceptable, your only options are to create a symbolic link to the installed directory hierarchies or retrieve the HylaFAX source distribution and recompile from scratch.
Some of the above parameters can however be changed 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. /dev/term/ser1) it is connected. 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).
You should consult the FAQ of HylaFAX before asking questions already answered.
The system must be configured to NOT run a TTYMON or something other on the tty port where the fax software is configured; use sysadm(1M) to make this sure.
It is a good idea to first checkout your port with a terminal emulation program (e.g. kermit or cu) to test the modem and the name of the tty.
If the modem is properly connected to your computer login as root and run faxsetup(1M):
thias# sh /usr/local/lib/HylaFAX-v4.0/sbin/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.0beta018.
Created for mips-sni-sysv4 on Sat Jun 1 09:00:35 MST 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/lib/HylaFAX-v4.0/spool/etc/setup.modem.
Configuration parameters written to
/usr/local/lib/HylaFAX-v4.0/spool/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/lib/HylaFAX-v4.0/spool) ["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/lib/HylaFAX-v4.0/spool) []?
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/lib/HylaFAX-v4.0/spool) []?
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/lib/HylaFAX-v4.0/spool/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]? no
Use faxaddmodem(1M) to configure your modem. Don't forgett the parameter -s 19200 because the driver on SINIX will hang during a normal open(2)-call if no carrier is detected.
thias# sh /usr/local/lib/HylaFAX-v4.0/sbin/faxaddmodem -s 19200 Serial port that modem is connected to []? term/ser1 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/lib/HylaFAX-v4.0/spool/etc/config. No existing configuration, let's do this from scratch. <... modem specific part deleted ...> Creating new configuration file /usr/local/lib/HylaFAX-v4.0/spool/etc/config.term_ser1... Creating fifo /usr/local/lib/HylaFAX-v4.0/spool/FIFO.term_ser1 for faxgetty... done. Done setting up the modem configuration. Checking /usr/local/lib/HylaFAX-v4.0/spool/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 ttyFN01. 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, interrupt it and restart it with -s option.
HOW TO STARTUP THE FAX DAEMONS
There are other system related files to check. An example script (/usr/local/lib/HylaFAX-v4.0/spool/etc/S69HylaFAX) is provided to startup the faxservice. Please copy this to /etc/rc2.d/S69HylaFAX, make a link to /etc/rc0.d/K69HylaFAX and change it to reflect your system. Especially change the LINE= definition in this script:
#!/bin/sh
# Start HylaFAX daemon
# copy this file to /etc/rc2.d/
.....
LINE=/dev/term/ser1 # line from faxaddmodem
# # must be changed
#
FAXQUEUE=/usr/local/lib/HylaFAX-v4.0/sbin/faxq
HFAXD=/usr/local/lib/HylaFAX-v4.0/sbin/hfaxd
FAXGETTY=/usr/local/lib/HylaFAX-v4.0/sbin/faxgetty
FAXQUIT=/usr/local/lib/HylaFAX-v4.0/sbin/faxquit
PORT=hylafax
.....
Caution: Don't remove the "&" operators in this script - your system will never boot if you remove this !
To start the daemons without rebooting the system simply do as root:
thias# sh /etc/rc2.d/S69HylaFAX 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:" on data-calls you need to do the following steps:
Change the GettyArgs: value in your modem config file. This file was created by faxaddmodem and the name is something like /usr/local/lib/HylaFAX-v4.0/spool/etc/config.<ttyname>
GettyArgs: "-g -h -t 60 -l ff_%s"Create entries for different baudrates in /etc/ttydefs. An example for such entry is provided in /usr/local/lib/HylaFAX-v4.0/spool/etc/ttydefs.entry.
You can allways contact the HylaFAX Home Page at http://www.vix.com/hylafax/ if you want access to the online documents. All HTML material is also provided with the binary distribution. If you're running a http-daemon on your system you may configure your daemon to use the installed html documents. Add the following alias-definitions to your httpd-config files:
Alias /hylafax/ /usr/local/lib/HylaFAX-v4.0/html/ ScriptAlias /hylafax-cgi-bin/ /usr/local/lib/HylaFAX-v4.0/cgi-bin/
To test your installation once you've configured your fax server and modem, startup the fax server as shown above and then log out as root and log in again as a "normal" user.
First check with faxstat(1) to make sure the server is running:
thias% PATH=$PATH:/usr/local/lib/HylaFAX-v4.0/bin export PATH thias% faxstat -s
the hfaxd(1M) daemon should respond with something like:
thias% faxstat -s HylaFAX scheduler on thias: Running Modem term/ser1 (+49.89.xxxxx373): Running and idle thias%
then send a short fax (change +123456789 below to the number of a nearby fax machine):
thias% sendfax -n -d +123456789 <<EOF Hello world. I like the binary distribution of HylaFAX v4.0beta018 EOF thias%
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.