| Latest Distribution: | v4.0beta020 |
| Latest Release: | v3.0pl1 (Version 3.0 patch level 1) |
| Master FTP Site: | ftp.sgi.com (192.48.153.1), directory sgi/fax |
| Home Page: | http://www.vix.com/hylafax/ |
| HylaFAQ Page: | http://www.vix.com/hylafax/FAQ/ |
| Mailing List: | flexfax@sgi.com (archives are kept at ftp.celestial.com) |
 |
If you want to use the software and are impatient, try this synopsis. |
|
If you have a problem with the software, check out the troubleshooting chapter. |
|
If you have a question, consult the HylaFAQ or search the mailing list archives. |
|
If you are looking for a source or binary distribution, read these instructions. |
|
If you want an annotated list of all online documentation, check out the table of contents. |
If this is your first encounter with this software you should
start with the overview section and
follow the 
button
at the bottom of each page to get a top-to-bottom
reading of the most important material.
You will also find that each page has a
button
that takes you to an annotated table of contents
for this documentation.
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). Any modem that supports one of the standard interfaces for facsimile operation can be used; i.e. any Class 1, Class 2, or Class 2.0 modem.
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 is supported and users can easily tailor cover pages to their environment. A simple text-based phonebook database is supported by the sendfax program. Information is also provided on how to trivially setup an email to fax gateway service.
Incoming facsimile are stored in a receiving area as TIFF/F (read ``TIFF Class F'') files and may be automatically delivered by mail and/or printed. A fax server status program, faxstat, can be used to monitor the send and receive queues, as well as the state of facsimile servers.
Fax modems are shared with outgoing data communication applications that honor the UUCP locking protocol. These applications typically include: cu, tip, kermit, uucp, slip, and ppp. The software can also be configured so that incoming data calls cause HylaFAX to invoke the standard system getty program.
The software is structured around a client-server architecture. Fax modems may reside on a single machine on a network and clients can submit outbound jobs from any machine that can communicate with the machine on which the modems reside. 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.) An access control mechanism is included to control which users on which machines may access a server. Clients and servers communicate using well-defined publicly specified protocols: for facsimile the HylaFAX Client-Server Protocol and for alpha-numeric pages the Simple Network Paging Protocol (SNPP) specified by RFC 1861.
Multiple modems on a single server machine are effectively scheduled for high throughput. Broadcast faxing is well-supported through optimal imaging of transmitted documents and the effective scheduling of modem resources. Support is provided for scheduling jobs during off-peak hours based on the destination phone numbers (e.g. long distance calls may be scheduled for off-peak phone rates). An access control mechanism can be used to restrict the class of phone numbers called so that, for example, calls to emergency services such as 911 can be rejected out of hand.
The server requires a PostScript to facsimile imaging utility for useful operation (otherwise, only pre-imaged facsimile may be transmitted.) A Display PostScript-based imager is provided for IRIX 4.x- and 5.x-based systems. For other systems, a Ghostscript-based version can be built from the GNU sources.
HylaFAX is freely available under copyright in complete source form. It may be used in commercial applications in part or in whole without charge.
HylaFAX comes with extensive documentation in two forms: this HTML-based documentation that is designed for on-line use and general guidance, and a complete set of UNIX manual pages that contain reference information in a more terse but precise format. The HTML documentation contains links to the manual pages providing a complete hypertext connection between the two forms of documentation.
The HylaFAX documentation is intended to support users of binary distributions; it is complete enough that access to the source code is not needed.
The name of this software package is ``HylaFAX'', not ``hylafax'', ``Hylafax'', or anything else. Also, do not call this software by its old name ``FlexFAX'' because that name is a trademark of another fax product and the folks that own that trademark are possessive. Please also note that ``HylaFAX'' is a trademark of Silicon Graphics and it should be treated as such when used in documentation.
Regarding the name, it is derived from the word hyla which is defined as ``Any of a genus of (Hyla) of frogs, especially the tree frog.'' Hence the logo found on the home page for this software.
Finally, please recognize that this is free software that represents the work of many people. The section of ``Acknowledgements'' lists those people that have made significant contributions.
There are two mailing lists for HylaFAX users; information on how to subscribe is found in the chapter ``HylaFAX Mailing Lists and Other Final Words''.
ftp.sgi.com sgi/fax/source/
(192.48.153.1)
For example,
% ftp -n ftp.sgi.com .... ftp> user ftp ... <type in password> ftp> cd sgi/fax/source ftp> binary ftp> get hylafax-v3.0beta099-tar.gzSoftware is available in released form (none presently available), and in beta form, (v3.0beta036). Beta software differs from released software mainly in the level of testing that has been done on non-Silicon Graphics platforms. Any files in the source directory of the form:
hylafax-<version>-patch-<XX>are shell scripts that can be used to apply patches to the specified <version>.
 |
If you are uncertain about what a patch script does just look at its contents; there is a comment at the top that says what version of the software the script is intended to patch. The HylaFAX home page also contains a link to release notes for the latest patch file. |
The <XX> sequence numbers in the patch filenames indicate the order in which the patches must be applied; e.g. hylafax-v3.0-patch-01 must be applied before hylafax-v3.0-patch-02.
ftp.sgi.com sgi/fax/binary
(192.48.153.1)
These include:
Alternate sites that either mirror the master FTP site or that have specific binary distributions are:
 |
Some of these sites had binary distributions of FlexFAX or HylaFAX 3.0, they will presumably have HylaFAX 4.0 distributions soon. |
FreeBSD binary distributions are available from:
ftp.freebsd.org pub/FreeBSD/ports-current/comms/hylafax/
(165.113.58.253)
NetBSD binary distributions are available from:
ftp.netbsd.org pub/NetBSD/packages/binaries/NetBSD-current/i386
(206.86.8.12)
If you are unable to locate the materials you want at one of the above sites, consult the archie resource location service to find copies close to your system.
% inst -f dist.engr.sgi.com:/sgi/hacks/hylafax
to install the latest version of the software on your machine.
HylaFAX v<version><n>where <version> is found in the file VERSION and <n> is the number recorded in the file dist/hylfax.alpha of the source distribution. This string is also prominently displayed when you run the configure script to setup the software for compilation and each time the faxq scheduler process is started (look in the file where system messages are recorded).
If you have a binary distribution for a Silicon Graphics machine, <version> and <n> are displayed in "versions -n hylafax.sw"; for example:
Note that HylaFAX is distributed in two versions: a released version with patch levels to fix small bugs or problems and a beta version. Released versions represent software that has been carefully tested on all supported platforms and is believed to compile, install, and function correctly (except where noted in the documentation). Released versions take a long time to create. The last few released versions have been at least 12 months apart. Beta versions are test versions of the software that are distributed more frequently than released versions. These versions include new facilities and/or support for new systems. They are typically tested on one or two systems, but not as thoroughly as released versions and not on all supported systems. The current released and beta versions can always be found on the HylaFAX home page.
Modems that support multiple classes can be configured to use any single class but not multiple classes. Wherever possible HylaFAX works around known modem problems or restricts modem usage in order to provide a functioning system.
The table below lists modems that have been used with HylaFAX. There are likely others modems that have been tried and/or are being used with HylaFAX; this list shows only those that have some form of support in the distribution or that have been publicly reported as functional (though beware that what is functional to one person may not be functional to you). Consult the Modems section of this documentation for known modem bugs and gotchas or follow the links in the table to find information for a particular modem.
Modems in the list below that are marked with a
are recommended for use with this software.
This is not to say that modems not listed below or not marked as
recommended will not work well; only that the noted modems have
performed reliably in extended use with the software.
Beware however, that modems only work as well the firmware that
controls them; be sure to use up to date firmware in a modem.
|
If you are selecting a modem to use with this software you will do best if you use one of the recommended Class 2 or Class 2.0 modems; rather than a Class 1 modem. |
Note that modems based on off-the-shelf parts (as opposed to custom DSP-based implementations) such as those produced by Rockwell are usually plug compatible when it comes to fax usage. HylaFAX includes configuration files for modems based on modem parts from Rockwell: RC96AC, RC144AC, RC144DP, RC32ACL, RC224A, and RC288DPI parts; Exar; and Cirrus Logic. Writing a configuration file for a modem that is not directly supported is straightforward.
| Manufacturer | Model | Class1 | Class2 | Class2.0 | Notes |
|---|---|---|---|---|---|
| AIWA | PV-BF288 | Yes | Yes | No | |
| Archtec | SmartLink V.32Te | Yes | Yes | No | |
| SmartLink 1419AV | Yes | Yes | No | ||
| AT&T Paradyne | DataPort 14.4 | Yes | Yes | No | |
| DataPort 14.4 Express | Yes | Yes | No | ||
| BAUSCH | MOD 144 | Yes | Yes | No | |
| Boca Research | M1440E | Yes | Yes | No | |
| M1440E/RC32ACL | Yes | Yes | No | @ | |
| MV.34I | Yes | Yes | No | ||
| BEST Communication | BEST 28800 EC | Yes | Yes | No | |
| CPI | ViVa 14.4/FAX | No | Yes | No | |
| Digicom | Scout+ | Yes | No | No | |
| Dynalink | Dynalink 1414VE | No | Yes | No | |
| Elsa | Microlink 14.4TL | No | Yes | No | |
| E-Tech, Inc. | P1496MX 5.06-SWE | No | Yes | No | |
| Bullet E-288 MX | No | Yes | No | ||
| Everex | EverFax 24/96D, 24/96E | No | Yes | No | |
| GVC | MaxTech 28800 | Yes | Yes | No | |
| Hayes | Optima 144, Optima 28800 | Yes | No | No | |
| Optima 2400+Fax96 | No | Yes | No | ||
| Acura 144, Accura 288 | No | Yes | No | ||
| Intel | SatisFAXtion 400e | Yes | No | No | |
| JVC | F-1114V/R6 | Yes | Yes | No | |
| Logicode | Quicktel Xeba 14.4 | No | Yes | No | |
| Maestro | Vfast | No | Yes | No | |
| Microcom | DeskPorte FAST ES 28.8 | Yes | Yes | No | |
| Motorola | Lifestyle 28.8 | Yes | No | No | |
| Power 28.8 | Yes | No | No | ||
| Multi-Tech | MT1432BA, MT224BA, MT2834BA | No | Yes | No | , * |
| MT1432BG | No | Yes | No | |
|
| MT1932ZDX, MT2834ZDX | No | Yes | No | |
|
| NetComm | M7F | No | Yes | No | |
| Nuvo | Voyager 96424PFX | Yes | No | No | |
| Olitec France | Olicom Poche Fax Modem 2400 | No | Yes | No | |
| Power Bit | Power Bit | Yes | Yes | No | |
| Practical Peripherals | PM14400FXMT, PM14400FXSA | No | Yes | No | |
| PM28800XFMT, PM288MT II | No | Yes | No | ||
| Supra | SupraFAX v.32bis | Yes | Yes | No | |
| SupraFAX v.32bis/RC32ACL | Yes | Yes | No | @ | |
| Express 288 | Yes | Yes | No | ||
| Telebit | T3000, WorldBlazer | No | Yes | No | |
| QBlazer | No | Yes | No | ||
| Telejet | 14400 | Yes | Yes | No | |
| TKR | Terbo Line 19K2/005-Q | No | Yes | No | |
| Tricom | Tornado28/42 | Yes | No | No | |
| Twincom | 144/DF | Yes | Yes | No | |
| UDS | FasTalk Fax32 | Yes | No | No | |
| USRobotics | Courier v.Everything | Yes | No | Yes | |
| Courier HST | Yes | No | No | ||
| Sportster 28.8 | Yes | No | Yes | ||
| Sportster 14.4 | Yes | No | No | ||
| Well/Xtrum | AT-2814SAM | Yes | Yes | No | |
| Yocom | 1414E | No | Yes | No | |
| Zoom | VFX, VFP 14.4V, 14.4X | Yes | Yes | No | |
| Zero One Networking | ZyXEL U1496 | Yes | Yes | Yes | |
| ZyXEL Elite 2864, Elite 2864I | Yes | Yes | Yes |
Legend:
The response time requirements are important for insuring that T.30 protocol messages are received in a timely fashion. On a loaded system the protocol process may be preempted by other activities and not be scheduled fast enough to satisfy the protocol timing requirements. This can usually be guarded against by assigning the facsimile process a high scheduling priority. Unfortunately most UNIX systems do not support such facilities and so even if it is possible to receive serial line input with the minimum of delay, protocol timing requirements may not be met because of delays in scheduling the execution of the fax server process. For this reason the facsimile server processes attempt to raise their scheduling priority while actively sending or receiving facsimile. At other times, such as when doing queue management operations, processes run at a normal priority. On Silicon Graphics systems the ``high priority'' is a nondegrading scheduling priority that is above the priorities of the normal system processes. On SVR4-derived systems the ``high priority'' is a real-time scheduling priority. On other systems the server currently always runs at the same (normal) scheduling priority. For more details consult the setProcessPriority routine in faxd/ModemServer.c++.
In summary, If you want to use a Class 1 modem with this software and your system does not provide support for low latency serial line input you are likely to have troubles. If your system does not provide a mechanism for raising process scheduling priority (note that this is not the same as the UNIX ``nice'' parameter), then you may see problems when the server is under load. Exactly how much load will cause trouble is dependent on the system configuration and processing power.
The Class 2 driver has been extensively tested with a wide variety of Class 2 modems. The software attempts to work around many incompatibilities and mistakes in modem firmware. A common problem that requires special attention is that some modems are incapable of accepting an AT+FDIS command to set the session parameters between the time a call is placed and a page is transmitted. Modems with this sort of problem may ignore the AT+FDIS command which causes incorrect session parameters being used to interpret the page data (often resulting in ``squished pages''), or abort the session, returning a +FHNG: status message to the host. If you encounter this problem use the Class2DDISCmd configuration parameter to enable workaround support in the fax server; e.g.
Class2DDISCmd: AT+FDIS
The system is written almost entirely in contemporary C++. It uses nested types and in several places assumes the compiler generates code according to the ANSI C++ Reference Manual (ARM). The normal development environment for the software is based on compiler products from Silicon Graphics. Every effort is made to insure the code builds correctly under all contemporary C++ compilers, including the GNU gcc compiler distribution. Beware however that not all compilers will compile this software.
|
Versions of gcc prior to 2.6.1 will not correctly build this software; gcc 2.6.3 and libg++ 2.6.2 are the recommended versions of the GNU tools to use though later versions work also. |
To build this software your system must have the following functionality or be capable of emulating those items that are missing:
When the software is configured for building any function that is not located will be emulated if it is known how. If a required facility is not found and no emulation or workaround is known, then the configuration procedure will abort.
The Class 1 modem driver requires sub-second timer facilities and a minimum latency interface to serial input. The server uses the BSD-style setitimer calls for the timer support and system-specific calls to enable low latency input from serial ports. If your system does not support the BSD timer calls, then the server will fall back to using the alarm system call that only has 1 second granularity (and the driver is unlikely to work reliably). If your system buffers serial input and does not provide a mechanism for defeating this, then the Class 1 driver will not work reliably. See the section above for specific requirements of the Class 1 support.
There is support in the fax server for handing inbound data calls to the system getty program. This support must be configured according to the requirements of the target platform; either System V-style or BSD-style. Only one of these two styles may be configured for use; the one that is appropriate to the target system should automatically be selected when the software is configured for building.
|
Beware of taking binary distributions from sites that are not on this list. HylaFAX includes several programs that are either started by the super-user or are installed as setuid root; thus installing untrusted distributions can be risky. |
Many binary distributions are available on the master FTP site:
ftp.sgi.com sgi/fax/binary
(192.48.153.1)
These currently include:
Alternate sites that either mirror the master FTP site or that have specific binary distributions are:
|
These sites had binary distributions of FlexFAX or HylaFAX 3.0, they will presumably have HylaFAX 4.0 distributions soon. |
FreeBSD binary distributions are available from:
ftp.freebsd.org pub/FreeBSD/ports-current/comms/hylafax/
(165.113.58.253)
NetBSD binary distributions are available from:
ftp.netbsd.org pub/NetBSD/packages/binaries/NetBSD-current/i386
(206.86.8.12)
The binary distributions come with their own instructions. The following guidelines describe how to interpret the filenames to understand the format and contents of each distribution.
Distribution filenames are of the form: hylafax-<target>-<version>-<format>; where <target> describes the target system, <version> specifies the HylaFAX version the distribution was built from, and <format> specifies the format of the distribution as follows:
So, for example, hylafax-irix5-v3.0beta099-inst.tar is a binary distribution for machines running IRIX 5.x and the distribution is provided as IRIX inst images collected together in a single archive created by the tar program.
In addition to the binary distributions, there may also be two other files present for each target system. Files of the form INSTALL-*-* are installation instructions for a specific binary distribution. Files of the form gs*-*-tar.gz are binary distributions of Ghostscript, the Ghostscript fonts, and any associated .ps files; configured for use with HylaFAX.
The remaining items are relevant to client and server installations:
There are some build-related issues that are dependent on the operating system present on the machine. Some system-specific guidance is sprinkled throughout these materials; the remainder is in a section on system-specific guidance that is found at the end of this chapter.
Before You Start
Before you build the software you may
need to obtain certain other
software distributions. All the software packages described here
are available by public FTP from a variety of Internet hosts;
consult the
archie
resource location service to find copies
close to your system.
TIFF
HylaFAX requires version 3.4 or later of the freely available
TIFF software distribution.
The master FTP site for this distribution is
ftp://ftp.sgi.com/graphics/tiff.
Note that the TIFF distribution must be installed before building
HylaFAX from source code or HylaFAX must be specially configured
to search for TIFF include files and libraries in non-standard locations.
gcc
You need a contemporary C++ compiler to build this system.
gcc version 2.6.3 is the current recommended version to use;
though later versions are also known to work.
Versions of gcc prior to 2.6.1 will not work.
When installing gcc beware of the make install step. On some systems and/or
with some versions of gcc, the fax software may not compile properly if
the include files are wrong (function prototypes that would normally
cause type casts to be done may be missing).
C++ runtime libraries
HylaFAX requires only minimal C++ runtime support; basic dynamic
memory allocation facilities and support for creating global static
objects;
it does not use any of the newer C++ runtime facilities such as
exception handling.
Most C++ compiler packages include everything that you need in the
way of a runtime library.
When using GNU gcc you may also need the libg++ distribution
which is packaged separately from gcc.
On some systems where gcc is used these facilities can be satisfied
without linking against -lg++ or -liberty,
but on others one or both of these libraries are needed
for certain library routines that are normally found in the
C runtime library.
The configuration procedure will abort if libg++
is needed but is not present on the build system.
If libg++ is required you should use the version that is
appropriate for the compiler.
When using gcc version 2.6.3, libg++2.6.2 is the
recommended version to use.
ghostscript
If you are not on a Silicon Graphics machine (and maybe even if you are),
then you will need the
Ghostscript PostScript interpreter software to build a PostScript
imaging engine to be used by the facsimile server.
(This imaging engine is frequently referred to as a
Raster Image Processor or RIP.)
Ghostscript comes in three flavors, two of which are
important to us: GNU PostScript,
a version governed by the GNU Public License (GPL),
and
Aladdin Ghostscript,
a version covered by the Aladdin Free Public License.
Both versions are copyrighted work and are not shareware or
in the public domain.
Aladdin Ghostscript is free for use by end users but
does not allow commercial distribution; to do this
you must arrange for a commercial license.
Versions of GNU Ghostscript are distributed approximately
a year following the corresponding Aladdin Ghostscript version.
For more information on these and other issues consult the
information located at http://www.cs.wisc.edu/~ghost/ghostscript/.
Ghostscript Version 2.6.1 and later are known to work.
If you use version 2.6.1 however, be certain to apply patches 1-4.
If you do not apply the patches you will encounter a bug in the clipping
code that is triggered by the default cover page distributed with this
software.
Also beware that if you use a version of Ghostscript
prior to 3.12 (inclusive) that
there is a tiffg32d driver that writes incorrect 2D-encoded facsimile
data; either do not configure this driver for use or disable its
use by setting Use2D in the HylaFAX scheduler configuration
file so it does not try to generate 2D-encoded facsimile data for
outbound jobs.
gmake
The make files are extensive and work untouched with the system make
under many systems. If your make does not understand them, then you
should be able to use the GNU make (gmake) instead. If you decide to
use gmake, be sure to get version 3.63 or newer; otherwise you may
encounter problems (especially with the rules that automatically generate
source code dependency information).
gawk
Several of the shell scripts included in this software make use of
awk. These uses are reasonably simple, but will not work if your
awk is old enough that it does not support functions or the -v
command line option for setting variable values before the BEGIN
action is executed.
If you encounter problems using the standard awk on your system,
try the GNU awk: gawk.
|
When using gawk be sure to use version 2.15 or later; HylaFAX is unable to detect versions of gawk that do not work correctly. |
ps2fax binary for IRIX systems
The Display PostScript-based imager for Silicon Graphics
systems is included in the
binary distribution images provided on ftp.sgi.com.
If you choose to work
from the source code on an IRIX system you may want a copy of the
ps2fax program: it is available separately on ftp.sgi.com in the
HylaFAX source distribution area:
ftp://ftp.sgi.com/sgi/fax/source.
Note that this is a COFF executable for IRIX 4.x and 5.x systems
and requires that the IRIX dps_eoe package be installed for proper use.
| Target | Purpose |
| all | build everything that is to be installed (default) |
| depend | build dependency information |
| install | build and install everything normally installed |
| clean | remove .o files and cruft, but not executables |
| clobber | remove everything that can be recreated |
| distclean | remove absolutely everything that can be recreated |
Otherwise, you can configure a build tree that is parallel to the source tree hierarchy but which contains only configured files and files created during the build procedure.
|
HP-UX 9.05: The standard make incorrectly processes VPATH; either use gmake or configure builds in the source tree. |
|
Solaris 2.3: The standard make does VPATH processing incorrectly for files passed to the make dependency generator script (the last file in the list is not converted to a pathname relative to the source directory); this causes lots of messages that can be ignored. |
A second function of the configure script is to set configuration parameters for the software. Many of these values are just default settings that can be changed after configuration through files that programs read at runtime, but some settings cannot be changed without rerunning the configure script. For example, by default the software is configured for installation in the /usr/local hierarchy; this cannot be changed without rerunning the configure script.
The configure script reads two configuration files to get configuration parameters: a site-wide configuration file that has settings that are to be applied to all systems at a particular site, and a target-specific configuration file that has settings for a specific system. Site-wide configuration files are named config.site and are automatically searched for first in any directory specified on the command line to configure with the -site option, or if that fails, in the directory in in which the configure script is located. Target-specific configuration files are named config.local and are looked for first in the top-level build directory, or, if that fails, in the directory in which the configure script is located.
|
configure reads any config.site file first, and then any config.local file. This permits target-specific definitions to override site-wide definitions. |
Configuration files are actually just shell scripts (written in the Bourne shell syntax) that define well-known shell variables that are used in the configuration process. For example, the following file might be used on a BSD/OS system to configure the software for installation in the /usr/contrib area and to make use of the Adobe Font Metric files that are already distributed as part of the BSD/OS 1.1 distribution:
The complete list of configuration parameters is given in the sample config.site file provided in the source distribution. Also, the sections below on ``Configuring Packages'' and ``Configuration Parameters'' have information on the most important or obscure parameters.
Finally, take note that there are two other configuration-related files that may be useful. The file named config.cache has all the configuration parameter settings that were selected the last time configure was run. This file is automatically read in by configure when it starts up to speed the configuration process. config.cache may be safely removed at any time. Cached settings are also automatically ignored if new settings are set through command line arguments to configure or through a config.local or config.site file.
The other file of interest is config.log. This file contains information and messages related to the various tests that configure does when constructing a build environment. If the configuration process fails for some reason or configure does something unexpected this file should be used to debug the problem.
|
Beware that the configure script is designed to be similar to scripts generated by the GNU autoconf facility but it is not 100% compatible. Use the -help option to configure for a list of the available options. |
| Name | Default | Description |
|---|---|---|
| Adobe Font Metrics | AFM=auto | This package contains Adobe Font Metric files that came from the public dvips distribution. AFM files are required by the textfmt(1) and faxmail(1) programs for converting ASCII text to PostScript. The AFM files should reflect the characteristics of the fonts that are used for imaging PostScript on the fax server. However if the PostScript RIP used to image text does not come with AFM files for its fonts, then this package can be substituted with only minimal degradation in the formatting of the imaged text. By default this package is configured for installation only if font metric files do not appear to be present on the build machine. |
| Display PostScript RIP | DPS=no | Whether or not to build and install a DPS-based PostScript imager for IRIX 4.x and 5.x systems from sources present in the HylaFAX build tree. This option is intended for people building binary distributions. |
| Dynamic Shared Object Support | DSO=auto | This package controls whether or not to configure the building of Dynamic Shared Objects (DSOs) for utility routines used by both client and server applications, and for a nucleus of common code used by server applications. Use of DSOs can significantly reduce the disk space needed for the HylaFAX software. If DSOs are not used then the code is statically linked into each application that requires it. By default this package is configured only if the build system appears to suport DSOs in a way that fits into the normal build scheme. If DSO support is explicitly enabled and there is no support for using DSOs in the expected way then DSOs are not used. Beware that DSOs can only be used when the compiler and runtime system support the runtime instantiation of global C++ objects that have constructors; something that few systems support. |
| Getty Support | GETTY=auto | This package controls whether or not to configure BSD- or System V-style getty support for handling incoming data connections. By default this package is configured according to the requirements of the target system. |
| Ghostscript RIP | GS=no | Whether or not to build and install a PostScript imager from Ghostscript sources present in the HylaFAX build tree. This option is intended for people building binary distributions. |
| Impressario RIP | IMP=no | Whether or not to build and install an Impressario 2.1 plug-in DSO from sources present in the HylaFAX build tree. This option is intended for people building binary distributions. |
| HTML Documentation | HTML=no | This package contains this HTML documentation about HylaFAX. By default this package is not configured for installation. HTML documentation can be viewed directly from the source directory; otherwise all the documentation can be viewed from the main WWW site at http://www.vix.com/hylafax/. This option is intended for people building binary distributions. |
| PostScript RIP | PS=auto | This package selects which RIP to use for imaging PostScript on the server. Possible values are: gs for Ghostscript, dps for the Display PostScript-based RIP provided for IRIX 4.x and 5.x systems, or imp for a plug-in DSO for Impressario 2.1 under IRIX. By default the DPS support is selected for IRIX systems; otherwise Ghostscript is used. |
| Regular Expression Support | REGEX=yes | This package controls whether or not to use the regular expression package included with the software. On systems where there is POSIX regular expression support in the standard system library use of this package may be disabled. Note that if this package is disabled the location of the include files and library containing the regular expression support must be specified; see the REGEXINC and LIBREGEX configuration parameters. |
| SGI RGB Image Converter Support | SGI2FAX=auto | This package controls whether or not to configure the sgi2fax program that converts SGI RGB images to TIFF/F (for direct transmission as facsimile). By default this package is configured for installation only if the build system appears to have support for the SGI Image library that sgi2fax uses to read RGB images. If this package is not installed then SGI RGB images must be converted to a form suitable for transmission using some other mechanism. |
| System V Init Support | SYSVINIT=auto | This package controls whether or not to configure the System V-style support for automatically starting the HylaFAX queuer process from init(1). By default this support is configured for installation only if the target system appears to use a System V-style init (auto); i.e. the /etc/rc0.d and /etc/rc2.d directories exist. |
| UTMP/WTMP Support | UTMP=auto | This package controls whether or not system accounting work should be done using the normal utmp files and data structures or the extended utmpx facilities. By default the appropriate support is chosen based on whether or not the build system has the <utmpx.h> file (auto). Explicit support can also be chosen by setting this parameter to utmp (normal accounting) or utmpx (extended accounting). |
| zlib Support | ZLIB=yes | This package controls whether or not to use the zlib compression package included with the software. On systems where the zlib distribution has already been installed this package may be disabled. Note however that if this package is disabled the location of the include files and library for the zlib distribution must be specified; see the ZLIBINC and LIBZ configuration parameters. |
To configure the build environment so that it will install the HTML documentation, you need to request the ``HTML package'' when running the configure script. This is done by specifying -with-HTML as a command-line option to configure or by setting HTML=yes in a config.site or config.local file. When the HTML package is setup for installation there are four other parameters that should be defined according to local conventions:
| Parameter | Default | Description |
| DIR_HTML | /var/httpd/hylafax | The directory where HTML materials should be installed. |
| DIR_CGI | /var/httpd/cgi-bin | The directory where CGI scripts should be installed. |
| CGIPATH | /cgi-bin | The pathname to use in HTML documents to reference scripts installed in DIR_CGI. |
| HTMLPATH | /hylafax | The pathname to use in HTML documents to reference materials installed in DIR_HTML. |
(NB: the default values are suitable for the NCSA HTTP server).
Finally, to complete the installation the HTML documents must be edited to fix pathnames that are found in the HTML files. All instances of @HTMLPATH@ and @CGIBIN@ must be replaced with the values of DIR_HTML and DIR_CGI, respectively. (This was done automatically in previous versions of HylaFAX but must now be done manually.) A shell script to do this is:
There are a few other issues to consider when installing the CGI scripts:
There are other issues with upgrading from FlexFAX; they are
discussed in the chapter that describes
setting up the server.
A Sample Configuration Session
This section shows a sample configuration session and describes
the work done. The session on the left in a fixed width
font with user-supplied input in a bold font.
Commenttary is shown on the right in a normal or italic font
or across both columns.
Blank space is present in the session output
where it is needed to fit comments on the page; in
normal operation the output from configure does not include
this white space.
This session was collected on a 486 machine running BSD/OS 1.1.
|
A build tree separate from the source tree is used here.
In fact, in this case the distribution is accessed from
a read-only NFS-mounted filesystem.
|
|
|
Note that the version and the
deduced target configuration (i386-unknown-bsdi1.1) are printed.
The file config.log should be checked if something goes
wrong during configuration; it has output from the tests that configure does.
|
|
| configure checks the normal shell search path for ANSI C compilers. A compiler is selected if it properly compiles a small test program. A specific compiler may be selected by setting the CC environment variable to the appropriate pathname, by supplying the parameter on the command line, e.g. -with-CC=gcc, or by setting CC in a configuration file. | |
|
Note that an ANSI C compiler is required to build the software.
If a C compiler requires options to enable ANSI C compilation, these
options can be specified with the ENVOPTS parameter.
|
|
|
A C++ compiler is selected using a scheme similar to
the one used to find a C compiler. Likewise there is a CXX
parameter that can be set to explicitly select a C++ compiler.
|
|
|
The make selected must support include files. configure can
deduce several different syntaxes for specifying include files.
Note that a large number of configuration parameters can be changed
by editing the top-level defs file that is included by
each Makefile in the distribution.
A MAKE parameter can be used to control which make to use.
|
|
|
All the HylaFAX shell scripts are written using Bourne shell syntax.
The standard shell on many systems is incapable of processing these
scripts so configure prefers bash to ksh to sh.
|
|
| Various system-specific libraries that may or may not be needed are checked for. If your system requires a library that is not automatically included it can be specified by setting the MACHDEPLIBS parameter. | |
|
Creating port.h. The port.h file is included by all the C and C++ code in the system. It includes definitions for functions and types that are missing from system include files, #defines to enable or disable system-specific functionality, and other odds and ends. |
|
| This file can take a long time to generate so configure creates the file only when it is needed, either because the file does not exist or because a different target or compiler is to be used. Note that running "make distclean" in the top-level directory of the build tree will remove the port.h file (along with all the other files generated by configure). | |
|
Selecting emulated library functions. Certain functions used by HylaFAX are not present on all systems but can be emulated using other system functionality. configure checks for the presence of required functions and if they are missing, will configure emulation code from the port directory to use instead. Building HylaFAX on unsupported systems may require adding to the code to the port directory. |
|
|
If a routine must be emulated and configure does not automatically
check for it, the routine name can be specified using the PORTFUNCS
parameter. To add emulation support for a new function foo,
create a file port/foo.c that contains the emulation code
and then set PORTFUNCS=foo in a configuration file or modify
the configure script to automatically check for the missing function.
|
|
| HylaFAX uses the TIFF library extensively. By default the TIFF library and tools are assumed to be instaled in the default location used by the TIFF distribution. | |
|
If the TIFF library is installed as a DSO
then the test done by configure will fail unless the
DSO is in a well-know location or is explicitly searched for;
e.g. with the LD_LIBRARY_PATH environment variable.
|
|
| If the DSO package is enabled (DSO=auto or DSO=IRIX), then configure will verify the system and compiler are capable of constructing DSO's in the expected way. Note that while a system may support DSO's the compiler may not be capable of generating the required position-independent code and/or the compiler may not pass the needed options through to the loader. | |
| Selecting utility programs. configure locates various system utility programs that are used by the software. Note that absolute pathnames are selected because several scripts and programs excute with super-user privileges. | |
| Several things to note: The awk program selected for use must support functions using the POSIX-style syntax (i.e. using function and not the older func keyword). configure will not select an awk program that does not support the syntax used by the awk scripts included in the distribution. Mail delivery is done using sendmail; a different mailer cannot be substituted without changing certain scripts because a number of sendmail-specific command line options are used. | |
|
Selecting default configuration parameters. The remainder of the work done by configure involves setting up configuration parameters that are mainly used during the operation of the fax software. These parameters can be set during configuration or, in most cases, they can be set through runtime configuration files. |
|
| The egetty and vgetty programs are not part of HylaFAX; they are ``hooks'' for developers to integrate programs that implement voice-oriented capabilities. | |
|
At this point you can interactively modify any of the
displayed parameters. Hitting a carriage return or typing
yes will accept the current parameters. Typing one
of the numbers displayed along the left hand side causes
configure to prompt for a new value of the specified parameter.
Typing anything else causes configure to prompt for a new
value for each parameter.
In general hitting carriage return will accept the current
value and typing anything that is unacceptable will cause a
help message to be displayed.
See below for descriptions of the parameters.
|
|
| Once parameters are setup configure generates all the files that depend on these parameters. Note that certain files may or may not be created based on the selection of optional packages and/or the functions supported by target system. | |
|
The default setting for most configurations parameters is usually correct. Be especially careful about enabling or overriding parameters that control workarounds for system bugs; certain problems can cause server processes to go into infinite loops! |
Note that HylaFAX is composed of client and server applications. Client applications are programs that normal users invoke to send facsimile, query the status of facsimile servers, etc. Server applications are programs that reside only on the machine where the fax modems are present.
| Parameter | Description |
|---|---|
| AROPTS | The options passed to ar when creating an archive. Note that configure will automatically check to see if ar supports an s to create a symbol table instead of using ranlib. |
| CONFIG_ABORTBUG | On some systems the logic used by the server processes to poll for messages on a FIFO special file while actively doing work can cause the process to go into an infinite loop. Setting this parameter to yes causes the server processes to not poll for messages. Enabling this workaround means that the faxgetty process will not recognize messages to abort a facsimile while it is being received. |
| CONFIG_BADEXECVEPROTO | On some systems the prototype function declaration for the execve system call is wrong (it does not list certain parameters as const). Setting this parameter to yes causes the software to work around this problem. |
| CONFIG_BADEXECVPROTO | On some systems the prototype function declaration for the execv system call is wrong (it does not list certain parameters as const). Setting this parameter to yes causes the software to work around this problem. |
| CONFIG_BADGETOPTPROTO | On some systems the prototype function declaration for getopt is wrong (it does not list certain parameters as const. Setting this parameter to yes causes the software to work around this problem. |
| CONFIG_BADSELECTPROTO | On some systems the prototype function declaration for select passes sets of file descriptors as int* instead of fd_set*. Setting this parameter to yes causes the software to assume the int* form is required. |
| CONFIG_FIFOBUG | Whether or not to enable a workaround for a kernel bug that causes select system calls to return prematurely after a process closes the ``client side'' of a FIFO special file. Setting this parameter to yes causes server processes to close and reopen FIFO special files after each received message. Note that aside from the additional overhead incurred in the server processes, this problem can also cause client programs to be temporarily unable to reach a server process. To minimize this possibility, the client code tries to reach a server process up to 5 times before giving up; this can introduce noticeable delays in applications such as faxstat. |
| CONFIG_NOREOPEN | Whether or not to reopen the tty device that a modem is connected to after raising and lowering the DTR signal (to reset the modem). This is done because on some systems lowering DTR causes the device to be placed in an unusable state. It may be desirable to disable this action however; for example when a modem is connected to an Ethernet-based terminal server. Setting this parameter to yes causes the modem to be reopened after reset. By default this parameter is set according to the target system. |
| CONFIG_NOSTDINDUP | On some systems, if the standard output is redirected to be the same as the standard input, then the stty program will emit a warning message. This is necessary for some older systems because it is the only way to force stty to change parameters on a tty device that is not the controlling tty. Setting this parameter to yes causes the ondelay program to not set stdout to stdin. Enabling this workaround can break the faxaddmodem program; it should be used only on systems where stty supports the -f option to select a tty device other than the controlling tty. |
| CONFIG_OPENFIFO | The mode to use when opening a FIFO special file in a server process. Normally this should be O_RDONLY, but on some systems this must be O_RDWR to avoid kernel bugs that cause select system calls to return prematurely after a process closes the ``client side'' of a FIFO. By default this parameter is set according to the target system. |
| CONFIG_SELECTBUG | On some systems where the FIFO select bug (see above) exists the select system call may return bits set in the read, write, and exception masks even if they were not requested; this in turn can cause the Dispatcher code to abort. Setting this parameter to yes causes the Dispatcher to ignore any bits set in bit vectors returned by select if the bits were not requested. Enabling this workaround adds additional overhead to each server process. |
| CONFIG_SOCKARGLENTYPE | On some systems the type of call-by-reference parameters that specify the size of variable-length buffers in socket-related calls is wrong (the type is something other than int*). This parameter can be set to the C type that should be used for length parameters; e.g. ``unsigned long''; otherwise int is assumed. Setting this parameter incorrectly should result in compilation errors. |
| CONFIG_TIOCMBISBYREF | Whether to pass the argument to the TIOCMBIS ioctl by value or by reference. On most systems the value is passed by reference; consult termio(7) for your system if you are unsure how your system works. Setting this parameter to yes is the default and generates code for passing the argument by reference. |
| CONFIG_WINSZHACK | On some systems the TIOCWINSZ ioctl is defined, but its use requires the inclusion of two non-standard files. Setting this paramter to yes causes the inclusion of these files. |
| CXXFILE | The options to the C++ compiler required to get the compiler to process a file with a .c++ suffix as C++ source code. configure automatically sets this parameter to "-x c++" for gcc and to "-+" for the IBM xlC compiler under AIX. |
| DEFVRES | The default vertical resolution in lines/inch that clients should use for submitted facsimile. Choices are 98 and 196. |
| DIR_AFM | The directory where client applications should find Adobe Font Metric (AFM) files. These files are used by various HylaFAX programs when converting text to PostScript. |
| DIR_BIN | The directory where client applications should be installed; by default this is /usr/local/bin. |
| DIR_CGI | The directory where CGI scripts used by the HTML-based HylaFAX documentation should be installed; by default this is /var/httpd/cgi-bin (usually appropriate for the NCSA HTTP server). |
| DIR_HTML | The directory where HTML-based HylaFAX documentation should be installed; by default this is /var/httpd/htdocs/hylafax (usually appropriate for the NCSA HTTP server). |
| DIR_LIBDATA | The directory to install data files that are required by client applications; by default this is /usr/local/lib/fax. |
| DIR_LIBEXEC | The directory to install executable programs that are invoked by other applications and not from the command line (e.g. the textfmt program invoked by sendfax to convert text to PostScript when submitting a fax job); by default this is the same as DIR_SBIN. |
| DIR_LOCKS | The directory in which to create UUCP lock files. |
| DIR_MAN | The top-most directory of the manual area where client/server manual pages should be installed. |
| DIR_SBIN | The directory where system applications such as servers should be installed; by default this is /usr/local/sbin. |
| DIR_SPOOL | The directory in which the HylaFAX server spooling area should be setup; by default this is /var/spool/fax. |
| DSODELAY | When DSO's are built, the option to specify to CC and/or CXX to note that a library should be loaded only as needed. This option is used to delay the loading of the TIFF library for applications that may use it infrequently. |
| DSOOPTS | When DSO's are built, the options to specify to CC and/or CXX to create a DSO. |
| DSOSUF | When DSO's are built, the filename suffix for a DSO. If this is set to "a" then statically linked archives are used. |
| ENVOPTS | Options to pass to CC and CXX to force ANSI C compilation. |
| FAXGID | The group ID to use for the fax user; by default this is selected according to the target system. |
| FAXUID | The user ID to use for the fax user; by default uucp. |
| FILLORDER | The order of bits in a byte on the server machine; either LSB2MSB or MSB2LSB. This is normally selected according to the target system. |
| GCOPTS | Special options to pass the C compiler. If this parameter is set, then configure may append other options to this list. |
| GCXXOPTS | Special options to pass the C++ compiler. If this parameter is set, then configure may append other options to this list. |
| INSTALL | The pathname of the install program to use. Note that this program must emulate the command line interface used by the IRIX install program. |
| LIBMALLOC | Whether or not to use -lmalloc in building the software. By default (auto) configure will probe the system to see if the library is present; if it is then the software will be configured to use it when building. Other possible values are: yes and no to enable and disable use, respectively. On systems that support DSOs it may be important to disable the use of -lmalloc to avoid conflicts with the normal memory alocation routines present in the standard C library. |
| LIBPORT | The pathname of the library that holds code to emulate missing system functionality. Normally this parameter is set by configure based on whether or not emulation code is required for the target. |
| LIBSUN | Whether or not to use -lsun in building the software. By default (auto) configure will probe the system to see if the library is present; if it is then the software will be configured to use it when building. Other possible values are: yes and no to enable and disable use, respectively. |
| LIBREGEX | The command line parameter(s) to use to link the library containing regular expression support. This parameter is set by default to reference the software included in the distribution. |
| LIBTIFF | The command line parameter(s) to use to link against the TIFF library. This parameter is set by default to the default installation location used by the TIFF software distribution. |
| LIBZ | The command line parameter(s) to use to link against the zlib library. This parameter is set by default to reference the software included in the distribution. |
| LLDOPTS | Extra command line options passed to CC and CXX when linking an executable. This option is usually set only when DSO support is enabled (to force the executable to search for the HylaFAX-specific DSO's in non-standard locations in the filesystem.) |
| LOCKS | A specification of the default type of UUCP lock files to use. This parameter is usually one of ascii, binary, -ascii or +ascii; consult the config(4F) manual page for a description of the UUCPLockType configuration parameter. |
| MACHDEPLIBS | Target-dependent libraries that should be used when linking applications. Note that if this parameter is specified configure will append to the list of libraries. |
| MAKECXXOVERRIDE | A special parameter used by configure when constructing Makefiles. This parameter is required when compiling the software with the SunPRO C++ compiler; it works around limitations in the SunPRO compilation environment. |
| MAKEDEPINCLUDE | The keyword used to specify the inclusion of a make dependency file when constructing Makefiles. This parameter is set to MAKEINCLUDE if make dependendcies are to be constructed by the software; otherwise it is set to # so that no make dependency rules are included (and used). |
| MAKEDSOINCLUDE | The keyword used to specify inclusion of a file containing rules for building DSO's. This parameter is set to MAKEINCLUDE if DSO's are to be built; otherwise it is set to # so that nothing is included. |
| MAKEINCLUDE, MAKELQUOTE, MAKERQUOTE | The syntax used to specify an include file for make; e.g. @MAKEINCLUDE@ @MAKELQUOTE@file@MAKERQUOTE@. These parameters are normally deduced by configure depending on the capabilities of the make program to use. |
| MANSCHEME |
The scheme to use when preparing and installing manual pages.
Schemes are constructed according to:
|
| PAGESIZE | The default page size that client applications will use for submitted facsimile. Page sizes are specified by name and checked against the pagesizes database installed in the DIR_LIBDATA directory. See also pagesizes(4F). |
| PATH_DPSRIP | The absolute pathname of the Display PostScript-based imager program. |
| PATH_EGETTY | The absolute pathname of suitable getty program to exec to deduce the type of an inbound call. Note that this parameter must be set correctly before the software is built; there is no mechanism for doing this through a runtime configuration file. This program is not part of HylaFAX; it is provided as a ``hook'' for developers to integrate voice capabilities. |
| PATH_GETTY | The absolute pathname of suitable getty program to exec to handle an inbound data call. Note that this parameter must be set correctly before the software is built; there is no mechanism for doing this through a runtime configuration file. |
| PATH_GSRIP | The absolute pathname of the Ghostscript-based imager program. Beware that this must be a version of the gs program that includes the tiffg3 device driver. |
| PATH_IMPRIP | The absolute pathname of the Impressario 2.1-based imager program available for IRIX 6.2 (and beyond) systems. |
| PATH_SENDMAIL | The absolute pathname of the sendmail program on the server machine; sendmail is used by HylaFAX to post mail messages for a variety of reasons. |
| PATH_VGETTY | The absolute pathname of suitable getty program to exec to handle an inbound voice call. Note that this parameter must be set correctly before the software is built; there is no mechanism for doing this through a runtime configuration file. This program is not part of HylaFAX; it is provided as a ``hook'' for developers to integrate voice capabilities. |
| PORTFUNCS | A list of non-standard functions that should be emulated. Normally this list is constructed by configure based on checks it does. If this parameter is set, configure will append to the specified list. |
| PROTOTYPES | Options that should be passed to the C compiler to force it to check for function prototype mismatches. This parameter should not be needed because ANSI C compilers should do this automatically. |
| REGEXINC | The pathname of the directory containing include files for the regular expression package. By default this parameter is set to reference the package included with this distribution. |
| SCRIPT_SH | The absolute pathname of the shell program to use when building HylaFAX and to use to execute certain command scripts. This shell must support the Bourne shell command syntax. Beware that many versions of bash have bugs in them that make them unsuitable for use. |
| SETMAKE | If make does not automatically set $MAKE to the name of the make program to invoke for subdirectories, then configure will create an explicit definition. If this parameter is set, then it will be used instead. |
| SHDLIBC | A special library to use in place of the standard -lc implicitly provided by CC and/or CXX. |
| SIGHANDLERTYPES | The type signatures to use when checking for the correct type for a signal handler. If this parameter is set then configure will check these types before it checks a builtin list of well-known values. |
| SYSGID | The group ID to use for installing non-setgid programs; by default this is chosen according to the target system. |
| SYSUID | The group ID to use for installing non-setuid programs; by default bin is used. |
| TIFFBIN | The pathname of the directory where the TIFF software distribution tools have been installed. |
| TIFFINC | The pathname of the directory where the TIFF software include files have been installed. |
| ZLIBINC | The pathname of the directory containing include files for the zlib distribution. By default this parameter is set to reference the package included with this distribution. |
The most common problem encountered during building, which is frequently not recognized until later when a program does not work correctly, is when the system include files are lacking proper ANSI C function prototypes. In particular beware of compilation warnings about ``passing an object as an argument to a function'', this usually means that a function was defined without a function prototype and then a C++ object was passed through the interface as an argument. For example, if the C library strchr function is declared as
extern char* strchr();instead of the expected
extern char* strchr(const char*, int);then the C++ compiler will not know to do the implicit cast of the first parameter to a const char*; almost certainly causing problems. Unfortunately many older systems do not have system include files that include ANSI C function prototype declarations; if this is true of your system then you are unlikely to get HylaFAX to build correctly.
Under at least AIX 4.2 some socket-related function declarations
have been changed to use non-standard types.
To workaround compilation problems the CONFIG_SOCKARGLENTYPE
configuration parameter should be specified to reflect the appropriate
type of the call-by-reference length
parameter passed to accept, getpeername,
and getsockname.
BSD/OS Guidance
Beware that the standard BSD/OS distributions place many files
and applications in non-standard locations.
This can cause confusion when HylaFAX is installed because the
old applications distributed with BSD/OS may be accidentally run
and do the wrong thing.
Under BSD/OS 2.1 the following config.local file may be
used to configure a build tree that installs over top of the
standard BSD/OS distribution of HylaFAX.
The ttymon program is executable only by root; this may
cause the configure script to not select it as the getty program that is
started up for inbound data calls. To work around this problem
override the default selection through the interactive prompts
or by creating a config.local file that explicitly sets the
PATH_GETTY configuration parameter.
FreeBSD Guidance
FreeBSD 2.0 does not include the file <osfcn.h>.
If the software does not compile without this file
a copy can be obtained from the GNU
libg++ distribution: ftp://prep.ai.mit.edu/pub/gnu/libg++*.tar.gz,
libg++-2.6.2/libg++/src/osfcn.h.
HP-UX Guidance
Under HP-UX 9.05
the standard make incorrectly processes VPATH; either use gmake
or configure the software to be built directly in the source tree.
Some versions of HP-UX define the select system call with parameters that are of type int*; if so set CONFIG_BADSELECTPROTO=yes to work around the problem.
Some versions of HP-UX have the include file <utmpx.h> but do
not support the extended accounting facilities defined by this file.
This confuses the configure script; to work around the problem
set UTMP=utmp when configuring the build environment.
Linux Guidance
Under various versions of Linux;
when linking with the -g option; if the linker complains
about needing libc.so.4, then it is necessary to setup symbolic
links in /usr/lib so that: libg.a -> libc.a
and libg.sa -> libc.sa.
Some recent versions of Linux come setup so that when C++
programs are compiled the standard C functions strchr and
strrchr (and possibly others) have multiple definitions
based on the types of their arguments.
This overloading causes compilation problems because HylaFAX assumes the
ANSI C definition which specifies a single definition
for these functions.
To workaround this problem either correct the include file
<string.h> or re-install gcc and/or libg++
(the standard distributions do not cause problems).
IRIX Guidance
Older versions of the SGI C++ compiler do not correctly handle
nested types.
If configure complains that the compiler is unsuitable for use
or if the software does not build correctly verify that you have
an up to date version of the compiler.
When building the software to use DSOs it may be necessary to set LIBMALLOC=no to avoid conflicts between the memory allocation routines in the standard C library and those in -lmalloc.
Under IRIX 5.3 /bin/sh has a bug that causes the faxsetup
script to run correctly but terminate with an error.
It may be preferrable to set SCRIPT_SH=/bin/ksh
though it is not necessary.
SCO Guidance
Under SCO OS 5.0.0 compilation problems have been reported
because of a missing declaration for the C typedef id_t
used in the file faxd/ModemServer.c++.
A workaround is to disable the use of the realtime scheduling
support by setting the define HAS_PRIOCNTL to 0 in
the file port.h.
Solaris Guidance
Under (at least) Solaris 2.3
the standard make does VPATH processing incorrectly for files
passed to the mkdepend script (the last file in the list is not converted to
a pathname relative to the source directory); this causes lots of
msgs that can be safely ignored.
Some versions of Solaris include an old version of the
TIFF library with the OpenWindows software.
This can cause problems when running the configure script unless
the LD_LIBRARY_PATH environment variable is explicitly
set to reference the location of the newer TIFF library DSO
or the path is explicitly set with a -R flag in the
LIBTIFF configuration parameter.
Ultrix Guidance
[Ed: this information comes from Tom Lislegaard.]
Extensive work is required to get the software built and working. The following comments apply to at least Ultrix 4.4. These notes relate to building and running HylaFAX Version 3.0 with gcc-2.6.3 and libg++-2.6.2.
Two header files cause problems: termios.h and sys/socket.h.
termios.h defines tcsetattr, tcgetattr, etc in terms of macros that map to ioctl's; this causes problems with the configure script. As the real functions are present in libc, working around this problem is just a matter of bringing the include file up to date. (When compiling with GNU gcc the file to patch is normally /usr/local/lib/gcc-lib/mips-dec-ultrix4.4/2.6.3/include/sys):
/usr/include/sys/socket.h needs to be protected against multiple inclusion:
Many of the tools provided with Ultrix are outdated, functionally crippled, or just buggy. Affected here are sh, make, expr, and sed.
configure must be run by ksh; e.g.
% ksh configureThere is no hope for using /bin/sh, it does not support shell functions. The good news is that the current /bin/ksh handles all the scripts as well, so it is not necessary to install bash; simply use
SCRIPT_SH=/bin/ksh
A recent version of GNU make must be used (I have used version 3.67).
A replacement expr program is found in the GNU Shell Utilities package; it is needed in place of the default system version. Likewise for sed; I have used GNU Version 2.05.
The syslogd and printf programs are not available on Ultrix. On a host running only client software (no local modem) these may be ignored. On a server machine these are required.
The standard syslog support can not handle the HylaFAX server processes (or any other modern software for that matter). It should be replaced with a newer syslogd. Several alternatives are available, the stuff I have used can be found at ftp://gatekeeper.dec.com:/pub/DEC/jtkohl-syslog-complete.tar.Z.
(A note here: on my system I have done a complete replacement, including putting new syslog functions in my libc.a. This means that I have not tried to build with the port/syslog.c support included with HylaFAX; though it should be equivalent).
To setup Ghostscript do the following:
|
Note that on machines with dynamic shared libraries (e.g. SunOS), if you link Ghostscript with the X11 device driver and use shared X11 libraries that are not in a standard location, then you need to link Ghostscript with arguments that force it to specifically search these directories, or augment the HylaFAX util/ps2fax.gs.sh script; e.g. |
LD_LIBRARY_PATH=/usr/local/R5/lib:/usr/openwin/lib export LD_LIBRARY_PATH |
|
Beware that while many versions of Ghostscript between 2.6.1 and 3.12 have a tiffg32d driver that claims to support 2D-encoded facsimile data, but does so incorrectly. Ghostscript versions 3.13 and later generate correct 2D-encoded data. |
Finally, beware that recent versions of Ghostscript require several additional packages such as the Independent JPEG Group (IJG) distribution for the PostScript Level II support. These additional software packages may come bundled in archives separate from the basic Ghostscript distribution. Consult the Ghostscript documentation for specifics.
A system acting as a HylaFAX server usually runs at least two server processes: the HylaFAX scheduler process faxq and the client-server protocol process hfaxd. Server systems may also use the HylaFAX front-door process faxgetty to monitor each modem on the system and possibly receive incoming facsimile calls. A send-only system would run faxq and hfaxd but (probably) not faxgetty. A system that was not going to use the transmit capabilities would not run faxq.
In addition to the server processes that operate all the time HylaFAX comes with two programs that are intended to be run periodically. The faxqclean program is responsible for purging unwanted files from the spooling area on a server and the faxcron script monitors the spooling area and performs routine maintenance tasks such as truncating log files. These programs are usually invoked by the system cron program.
The remainder of this chapter discusses the basic steps required to setup a HylaFAX server machine:
When working from a binary distribution the technique required
to install the software programs varies based on the format used
to distribute the materials.
Each binary distributions of HylaFAX should include detailed
installation instructions that reflect the exact contents of the distribution
and any distribution-specific requirements.
Selecting a Facsimile Modem
Selecting a modem usually means purchasing a modem that is capable
of sending and receiving facsimile.
Most any fax-capable modem can be used with HylaFAX but not all are equal.
HylaFAX has drivers for Class 1, Class 2, and Class 2.0 facsimile
modems, but there are caveats on the use of
Class 1 modems.
Class 2 modems are the most common, but due to the non-standard
nature of the specification that they are implemented against
compatibility can be a problem.
Note also that the quality of Class 2 modems varies significantly.
Class 2.0 modems follow the latest standard, a ratified version of
the specification used in implementing Class 2 modems.
There are significantly fewer Class 2.0 modems available, though
the quality of these modems also varies significantly.
There is a (constantly growing)
list of modems
that have been tried with HylaFAX and
this list includes several modems that have been found to be
reliable for use in sending and receiving facsimile.
|
If you are buying a modem to use with this software you will do best if you use one of the recommended Class 2 or Class 2.0 modems; rather than a Class 1 modem. |
Verify that the modem you are using is a fax modem. This can be done by communicating directly with the modem using a communication program such as cu; for example:
|
Beware that although a modem may properly implement hardware flow control when doing data communication, it may not support hardware flow control during facsimile communication. Consult the modem information for specifics on some modems. |
If a prototype configuration file for your modem is included in the HylaFAX distribution then the appropriate default flow control scheme should be defined for the modem.
|
Note that some operating systems do not support RTS/CTS flow control unless carrier is present. In particular, some versions of SunOS and Solaris requires patches to correct this mis-behaviour; consult the sections below for system-specific guidance. |
|
Versions of IRIX prior to 6.2 have a bug in the device driver for the on-board serial ports on IP20 and IP22 systems that causes RTS/CTS flow control to be turned off by HylaFAX. Patch 475 (``RTS/CTS flow control busted when CLOCAL is set'') and its successors correct this problem and must be installed to use HylaFAX with hardware flow control. For complete details refer to the section below on IRIX-specific guidance. |
When in doubt or having trouble, configure the modem to use software
flow control for fax use.
Choosing a TTY Device
There are two things to beware of in selecting a tty device file to
use with your modem: flow control usage and port locking mechanisms.
On many systems different devices are used to select different flow control schemes and/or whether or not the system will monitor the DCD signal. For example, IRIX systems use ttym* and ttyf* device names to identify devices that monitor DCD but only the latter support RTS/CTS flow control. Similarly, the FAS driver for SCO uses a different names as does the standard HP-UX terminal driver.
On some systems inbound and outbound port use is interlocked by
using a pair of devices, one for inbound use and another for
outbound use. Typically this scheme works by stopping programs that
use the inbound device until an inbound call is received (and DCD
is raised by the modem).
Outbound usage is also interlocked against applications waiting
for the inbound device.
HylaFAX provides no direct support for this because this scheme
requires that a modem
auto-answer incoming calls (something that is hard to make work with
multi-mode--i.e. fax and data--modems).
When faced with a system that uses this scheme
most people elect to avoid the inbound device and run both incoming and
outgoing traffic on the outbound device, using the built-in interlocking
mechanism provided by HylaFAX.
In this case the appropriate device to use is typically named
/dev/cu*, but check local conventions.
Using faxsetup to Configure a Server Machine
Before any HylaFAX software can be used on a server machine the
faxsetup script
must be run.
This interactive script verifies the installation of the HylaFAX
software and also carries out a variety of one-time tasks that
prepare the system for use.
Running faxsetup is especially important when working from
a binary distribution because it checks that parameters setup at
the time the distribution was built are correct for the target
machine where the software is to be run.
faxsetup carries out a variety of tasks and then writes configuration information to two files in the HylaFAX spooling area. The file etc/setup.cache in the spooling area contains the parameter settings used by HylaFAX command scripts while the etc/setup.modem file contains settings and shell functions used by command scripts that communicate with modems.
|
The setup.cache and setup.modem files must be present for HylaFAX to function properly. If these files do not exist then HylaFAX server applications will terminate with an error message. |
The work done by faxsetup includes the items listed below. Note that faxsetup always prompts for permission before doing anything that might affect normal system operation (e.g. adding a new user to the password file).
faxaddmodem may be run directly from the command line or via the faxsetup script that is used to prepare a server machine for use with HylaFAX.
The remainder of this section shows a sample configuration session and describes the work done. The session is shown on the left hand side in a fixed width font with user-supplied input in a bold font. Comments are shown to the right in a normal or italic font, separated by horizontal rules. Blank space is present in the session output where it is needed to fit comments on the page; in normal operation the output from faxaddmodem does not include this white space. faxaddmodem displays the current/default setting for a configuration parameter enclosed in ``[]''; the current value is accepted by typing a carriage-return.
This session was collected on a Silicon Graphics Indy machine running IRIX 5.3 and communicating with a USR Courier v.Everything modem.
| If your modem is configured to communicate with the host at a fixed speed, then use the -s option to lock the host-modem baud rate. Note also that faxaddmodem must be run as root. | |
|
Collect server-specific configuration parameters. Per-modem configuration files contain parameters that pertain to the operation of the modem and parameters that control the function of the HylaFAX server software that controls the modem. The former parameters are termed modem-specific while the latter are referred to as server-specific. faxaddmodem collects server-specific parameters first and then modem-related parameters are setup based on the type of modem. |
|
|
The configuration file for the HylaFAX scheduler is automatically
read to get default settings for parameters such as the area code.
|
|
|
If a configuration file already exists for a modem, the
server-specific parameters will be carried over to the new configuration,
but the modem-specific parameters will not.
|
|
|
The area code may be set to a null string or omitted
in locations where one does not exist.
|
|
| This is the phone number associated with the modem. By default this number is passed as an identity to peer fax machines (see below) and it may also appear on tag lines created by the fax server. | |
|
Phone numbers should be supplied with a
complete international dialing specification:
``+<country code> <local part>''
(the <local part> includes an area code
where such a notion exists.)
|
|
| The local identification string is passed to peer fax machines during communication. If it is not specified, or set to a null string, then the canonical phone number of the fax modem is used instead. | |
|
Beware
that the facsimile communication protocol restricts
the local identification string to numbers, blank, and the ``+'' symbol.
In practice however, most facsimile machines will accept any ASCII string.
|
|
|
The dial string rules file holds rules
used to convert user-supplied
dialing strings (i.e. phone numbers) to a canonical format and to
prepare strings for delivery to a modem. The default rules do very
little. Specific dialing rules may be useful for your site or locale
based on how your modems are connected to the PTT. Consult the
section in the Advanced Server
Configuration chapter for more information.
|
|
| These parameters control the logging done by server processes. | |
|
It is important that tracing during send and receive sessions include
sufficient information to diagnose problems. For Class 1 modems this
parameter is usually set to 0x4f so that HDLC frames are
included in the logs. For Class 2 and Class 2.0 modems the default
setting of 11 is typically ok.
Consult the descriptions of ServerTracing and SessionTracing
in the
config(4F) manual page.
|
|
|
The default parameter selected here makes
all received facsimile accessible
only to the fax user. It may be desirable to set this parameter to
0644 so that anyone can look at received facsimile.
|
|
|
Note that if sensitive information such as credit card access codes
are supplied by users that they will appear in the session logs kept
on the server machine. For this reason the default protection mode
for session logs protects them from public access.
|
|
|
This parameter is used during inbound call handling. It
specifies the number of rings to wait before answering the phone.
See the section on inbound call handling for a discussion of
the different schemes that are supported for handling calls.
|
|
|
This parameter is also related to inbound call handling. It controls
whether or not to enable support for inbound data calls and should
not be set without first understanding how to setup your system
for incoming data usage.
|
|
|
The TSI access control list file can be used to restrict inbound
facsimile access. The default parameter causes all inbound calls
to be accepted. This parameter is discussed more below.
|
|
| Tag lines are an optional feature that cause each page of an outbound facsimile to be marked with a line of text. A proper description of the tag line support is provided in the Tagline Configuration section of the next chapter. | |
|
Note that in the United States some form of identification
of the sender of a facsimile is required by law; properly configured
tag lines are an acceptable form of identification.
Beware that the default tag line includes the phone number
defined above; make sure this number is correct!
|
|
|
This parameter controls the time that a HylaFAX server process
will wait before removing a UUCP lock file whose owner appears
to be gone. The default parameter forces these stale lock files
to be left around for just 30 seconds.
This is an appropriate value to use on systems where applications
that use UUCP lock files are known to be well behaved.
|
|
| More parameters associated with inbound facsimile jobs; consult the section below. | |
|
The syslog facility controls where HylaFAX directs server tracing-related
messages. By setting this parameter to a non-standard
value HylaFAX messages can easily be recorded in a file separate
from the normal system messages. Consult the
Troubleshooting chapter,
for more information.
|
|
|
This parameter should only need to be set on Silicon Graphics
systems. Consult the section on
IRIX-specific guidance for
a description of why this parameter might be used.
|
|
| This completes the collection of server-related parameters; the remaining steps identify and configure the modem for use. If the displayed parameters are unacceptable, typing something other than yes or a carriage return will cause faxaddmodem to prompt for new/changed parameter settings. | |
|
Setup modem-specific configuration parameters. faxaddmodem probes the modem to find out what type it is and what capabilities it has. The modem identity is then matched against a set of prototype configuration files to come up with modem-specific parameters that are appropriate to the modem and the style of flow control that is to be used between the host and modem. If the modem is not supported by an existing prototype configuration then faxaddmodem will prompt to get values for parameters. |
|
|
Use the -s option to avoid probing.
|
|
| Modems that support multiple classes can be configured to use any supported class. By default Class 2.0 is considered better than Class 2 which is preferred over Class 1. | |
| The flow control scheme requested is one of xonxoff for software flow control, rtscts for hardware flow control, or default for a setting that is appropriate for the modem and the tty device. | |
|
Beware of using an improper flow control scheme for the selected
tty device. On systems where faxaddmodem understands how
tty device names reflect flow control characteristics, selecting
a flow control scheme not supported by the device will cause
faxaddmodem to prompt for confirmation and/or to change the device
name or the flow control scheme.
|
|
| The modem-specific configuration parameters are obtained from prototype configuration files that reside in the config subdirectory of the HylaFAX spooling area. These parameters have been taken from working systems and should provide a functioning configuration based on the modem type and the selected flow control scheme. | |
|
If no prototype configuration file exists for a modem then faxaddmodem will prompt for settings. There are generic prototype configuration files for Class 1, Class 2, and Class 2.0 modems. Because there are many configuration parameters for modems it may be preferrable to use a normal text editor instead of faxaddmodem when constructing a configuration file for an unsupported modem, To do this simply accept the default parameters and then edit the generated configuration file before starting up a server for the modem. Once a working configuration file is created it is simple to create a prototype file from it; consult the faxaddmodem(1M) or config(4F) manual pages for information on doing this. |
|
| At this point faxaddmodem compares the parameters setup for the modem against the parameters setup for the HylaFAX scheduler process. If any parameters are incompatible it prompts to see if they should be used to create a new file for the scheduler. | |
Specifying modems with faxmodem is useful when HylaFAX is to be used in a send-only configuration. Doing this however limits the functionality of the scheduler because it will not know the true state of each modem; e.g. when a modem is in use by an outbound application such as uucp or tip. Instead faxq will assume that each modem is ready for use except when it is actively being used by HylaFAX to transmit a facsimile or alpha-numeric page.
A modem specified with faxmodem is identified by the tty device it is attached to. Thus, to notify the scheduler that two modems are available for use, the following might be used:
Modem capabilities are specified through faxmodem with the syntax used by Class 2 and Class 2.0 modems. This makes it easy to setup a Class 2/2.0 modem: all you need to do is make a simple query to the modem to get the capabilities string to pass to faxmodem. For example, for a Class 2.0 modem the following commands would be used:
For a Class 2 modem the commands are slightly different:
For a Class 1 modem an entirely different procedure is needed because the modem only implements a small portion of the facsimile protocol. This means that the capabilities are mostly dependent on the HylaFAX software and not on the modem. The only information needed from the modem is which signalling rates are supported for transmitting fax data; this is obtained with:
When faxq is used in conjunction with faxgetty no modems need
to be specified using faxmodem.
If modems are specified however; faxq will
just treat the modems as ready for use until it receives more up to date
information from the faxgetty processes.
Setting up Inbound Service
To setup HylaFAX for inbound facsimile or data service a
modem configuration file must be setup and
a faxgetty program must be started to listen for input on the tty device.
The configuration file setup is usually done at the same time
that outbound service is configured; i.e. when faxaddmodem is run.
A faxgetty server for the modem should be setup to be run by the
init(1M)
process according to local system conventions.
For System V-based systems this is done by editing the
/etc/inittab file to spawn faxgetty on the appropriate port.
For example, if a modem is to be started on /dev/ttyf2 the
following line might be appropriate:
t2:23:respawn:/usr/local/sbin/faxgetty ttyf2
cua0 "/usr/local/sbin/faxgetty /dev/cua0" dialup on
In general it is desirable to run faxgetty because faxgetty informs the HylaFAX scheduler process whenever modems are in use and because it identifies modems' capabilities (passing them on to the scheduler so that it can make informed scheduling decisions). faxgetty also includes support for screening calls based on caller-ID information (consult the section ``Caller-ID Support'') and for automatically routing calls based on distinctive ring when these services are provided by the local PTT (consult the section ``Distinctive Ring Support'') . For this additional functionality, and because faxgetty does a reliable job of reseting and configuring recalcitrant modems, it may even be desirable to run faxgetty on non-fax modems.
The following sections discuss HylaFAX support for
servicing particular types of inbound calls.
Facsimile Service
In normal operation HylaFAX's faxgetty process
will automatically answer inbound phone
calls and receive facsimile.
Received facsimile are written to files in the recvq directory
in the spooling area on the server machine.
Facsimile data is stored as a TIFF Class F (TIFF/F) file and
protected according to the RecvFileMode configuration parameter
specified in the modem configuration file.
The RecvDataFormat configuration parameter can be used to
control the encoding of data stored in these files; consult the
section on
``Transcoding of Received Facsimile''
for more information on this facility.
The maximum number of pages that will be received in a single
call can also be controlled with the MaxRecvPages
configuration parameter.
Finally, HylaFAX provides an access control list mechanism for
restricting recived facsimile according to the TSI
string passed as part of the facsimile protocol;
consult the section on
``Rejecting Junk Facsimile''
for more information.
Data Service
By default HylaFAX does not enable support for inbound data calls.
Data service is not enabled so that naive users do not accidentally
setup inbound access to their system before proper password controls
are in place.
To enable inbound data service the modem configuration file must
be setup to accept data calls and to invoke the normal system
getty program to process the incoming call.
Normally this involves enabling the use of
adaptive-answer functionality
and the setup of the GettyArgs parameter
in the configuration file.
Adaptive answer is the ability for a modem to determine whether an incoming phone call is for data, fax, or voice use. If a modem supports a good adaptive-answering facility then it should be enabled with the ModemSetupAACmd and the faxgetty process will automatically service fax, data, or voice calls as identified by the modem. Most Class 2 and Class 2.0 modems provide adaptive-answer support that distinguishes data calls from fax calls and the prototype configuration files that come with HylaFAX automatically enable it if it is provided by the modem. Most Class 1 modems do not provide adaptive-answer support, but HylaFAX provides adaptive-answer support in the server. Consult the section on ``Adaptive Answer Support'' in the next chapter for help on configuring adaptive-answer support.
Setting up the GettyArgs parameter requires an understanding of how to automatically startup the system getty program. HylaFAX will invoke the getty program when a data call is recognized and set up the standard input, output, and error descriptors to point to the appropriate tty device. The getty program should not reopen or reinitialize the modem before doing its work. Some getty programs are incapable of this and are unsuitable for use with HylaFAX. The parameters passed to the getty program must also identify the speed to use to communicate with the local modem. Some getty programs want to automatically detect this rate based on the CONNECT message that a modem sends to the host when a connection is established; these programs are unsuitable for use with HylaFAX. A getty program used with HylaFAX must be able to handle a fixed speed for host-modem communication, with the speed specified on the command line.
For System V-style getty programs the appropriate parameters are typically of the form:
For BSD-style systems, GettyArgs is usually of the form:
hfaxd is normally started up when the faxsetup program is run. faxsetup also arranges for hfaxd to be automatically started up each time a server machine is booted; either standalone by a script invoked by the init process or indirectly by the inetd process. The preferred way to run hfaxd is in a standalone mode as this gives optimal performance.
When hfaxd is started the command line arguments specify which of several client-server protocols it should offer. hfaxd currently has support for three protocols:
It is also possible to have the inetd program startup hfaxd. In this case only a single protocol can be requested since inetd advertises service and establishes the network connection. For example, the following entry might be used in the inetd.conf file to startup hfaxd to service SNPP requests:
It is possible to run hfaxd in a standalone mode as well as indirectly from inetd so long as this is done for separate protocols. Doing this however is of questionable value since it is much more efficient for a single standalone hfaxd process to support multiple protocols than to have multiple unrelated hfaxd processes.
|
Beware that hfaxd must either be started up by the super-user or be installed setuid-root for proper operation. |
Besides arranging for hfaxd to get started up when a server machine is booted, it is necessary to specify which client machines and users can have access to a HylaFAX server machine. This is specified by the contents of the etc/hosts file in the HylaFAX spooling area on the server machine. The contents of this file is specified in the hosts(4F) manual page. The default etc/hosts file that comes with HylaFAX permits anyone to have access through the localhost network interface; i.e. the hosts file contains:
localhost 127.0.0.1
|
The etc/hosts file must be owned by the fax user and be mode 0600 or hfaxd will not permit client access. |
The faxqclean program is responsible for removing old document and job description files from the spooling area on a server. These files are created when outbound jobs are created but are removed in a delayed fashion to permit clients to resubmit jobs without retransmitting all the information to the server and to allow imaged documents to be reused in unrelated facsimile transmissions. faxqclean is also responsible for archiving outbound jobs that have completed.
|
The faxqclean program in version 4.0 does not support job archiving; but consult the manual page to verify this (in case someone has done some local improvements). |
faxqclean must be run by the super-user. A sample entry for the cron program that runs faxqclean once each hour might be:
AT+FCLASS=0DT<phone number>
|
Note that when HylaFAX places an outbound facsimile call it automatically forces the modem into Class 1, 2, or 2.0 before issuing ModemDialCmd. Thus the old FlexFAX trick of changing the class in the ModemDialCmd parameter should not be used. |
The tty device that is used must reflect whether hardware or software flow control is to be used. Under IRIX, modem devices (i.e. those that monitor DCD) come in two flavors: ttyf* devices support RTS/CTS flow control while ttym* devices support XON/XOFF flow control. If you want to use hardware flow control to communicate with your modem you should use a ttyf* device, otherwise use a ttym* device. If you fail to use the correct device you may still get the correct flow control (because later versions of IRIX actually permit flow control to be switched irrespective of the device used), but you are likely to collide with other modem users such as cu, uucp, ppp, and slip that still use the old-style device names (so UUCP lock files may be created for a different name than the one HylaFAX is using).
|
USR modems work under IRIX 5.x only when patch 475 or a successor is installed and ClocalAsRoot is set to Yes in the modem configuration file. |
Versions of IRIX prior to 6.2 have a bug in the device driver for the on-board serial ports on several systems that causes RTS/CTS flow control to be turned off as a side effect of setting the CLOCAL flag on the associated tty device. Patch 475 (``RTS/CTS flow control busted when CLOCAL is set'') and its successors correct this problem and must be installed to use HylaFAX with RTS/CTS flow control (install the appropriate successor to patch 475). Also, when this patch is installed the ClocalAsRoot modem configuration parameter must be set to Yes for proper operation (see config(4F) for a detailed explanation of what this parameter does). If you do not have the appropriate patch installed on your system then you will either see flow control-related problems when transmitting facsimile or possibly some other problems related to modems dropping DCD when carrier is lost.
|
The DPS-based PostScript imager program distributed with HylaFAX is available only in COFF format. Because IRIX 6.2 does not support COFF executables this program cannot be used with HylaFAX. A Ghostscript-based RIP should be used under IRIX 6.2. |
The font metric files required by client applications are contained
in the dps_eoe.sw.dpsfonts image that is part of
the standard IRIX distribution.
SCO Guidance
The standard SCO serial I/O driver (SIO) does nothing with modem control
lines if CLOCAL is set on the tty device.
The usual workaround is to use the FAS driver instead.
Solaris Guidance
Versions of Solaris prior to 2.5 require a patch to correct the handling of RTS/CTS flow control with serial ports built around the Zilog ZS8530 chip.
Some versions of Solaris (2.3 is known to do this) silently truncate or discard syslog messages longer than about 120 characters.
Use the /dev/cua/* devices and not the /dev/term/* devices.
When using ttymon to service inbound data calls set the GettyArgs parameter to something like the following:
GettyArgs: "-g -h -d /dev/cua/a -l 38400 -m ldterm,ttcompat"
|
Be certain you are not running a ttymon with sac when using HylaFAX. Disable all ports that are to be used by HylaFAX with admintool or pmadm(1m). |
Versions of SunOS prior to 4.1.4 require a patch to correct the handling of RTS/CTS flow control with serial ports built around the Zilog ZS8530 chip. These patches are available at:
The following GettyArgs: configuration parameter is suitable for many SVR4-based systems:
GettyArgs: "-g -h -t 60 -l ff_%s"
Hardware flow control does not work in HylaFAX Version 3.0, modems must be configured to use software flow control.
Serial ports are conventionally called tty00, tty01, etc; see MAKEDEV(8) if you need to create devices.
This chapter describes how to configure some of the advanced features of HylaFAX. In addition it discusses how many of the modem-specific configuration parameters work together when sending and receiving facsimile. The set of per-modem configuration parameters provides a flexible mechanism for working around many modem and system limitations. This chapter includes the following sections:
LocalIdentifier: "Errno Consulting"
AT+FCLASS=2 OK AT+FLID=? (20)(32-127) OK
DialStringRules: etc/dialrules
Dial string rules are an important part of HylaFAX as they permit local PTT conventions to be handled entirely on the HylaFAX server machine (e.g. the need to dial ``1'' before certain numbers but not others). Client applications are then free to use a canonical format for phone numbers that is location independent. Dial string rules combined with the ModemDialCmd also permit modem-specific idiosyncrasies such as the syntax for doing a ``flash hook'' to be handled transparently. Finally, dial string rules can be used to provide dialing aliases such as mapping ``a-zA-Z'' to the corresponding numeric codes.
Consult dialrules(4F)
for detailed information.
Tagline Support
HylaFAX includes support for tag lines; a line of
text imaged at the top of each outgoing facsimile page.
Tag lines imaging requires the specification of:
|
A 100 dpi 18point Lucida Typewriter font from the X Window System is included in the HylaFAX distribution for use in imaging tag lines. Experiments indicate this is a reasonable font to use. You can however use an alternate font of your liking. |
On Silicon Graphics systems a tag line font can be installed by converting one of the compressed font files provided with the standard X server; e.g.
To enable use of the font and imaging of the tag lines setup the TagLineFont configuration parameter:
TagLineFont: etc/lutRS18.pcf
The default tag line format string is ``From %%n|%c|Page %%p of %%t'' which prints three fields containing the phone number of the server, the date and time of the outgoing job, and the page number and total pages for the job. Consult the TagLineFormat parameter description in config(4F) for information on configuring a different format string.
|
The tagtest(1M) program may be used to try out different tag line formats and fonts before they are configured for use by the server. |
Finally, be certain the host bit order is configured to reflect the
order of bits on your machine. The host bit order should be properly
setup at the time the configure script is run.
If the server has the wrong host
bit order then tag lines will be imaged incorrectly.
Adaptive Answer Support
Adaptive answer is the ability for a modem to determine
whether an incoming phone call is for data, fax, or voice use.
If a modem supports a good adaptive-answering facility
then it should be enabled with the ModemSetupAACmd
and HylaFAX will service fax, data, or voice
calls as identified by the modem and specified
in the modem configuration files. For example,
ModemSetupAACmd: AT+FAA=1
|
The adaptive-answer algorithm used by some modems can confuse some fax machines and/or data modems. If you do not intend to service both data and fax calls you may not want to configure adpative-answer for inbound calls. |
If a modem does not support adaptive-answering, then there are several options. If the modem is a Class 1 modem, then HylaFAX provides a simple adaptive-answering strategy whereby incoming calls are first answered as if they are for a fax machine and, if that fails, then answered as if they are for a data modem. This facility is enabled by specifying something like:
AdaptiveAnswer: yes # enable adaptive answer AnswerRotary: "fax data" # answer for fax, then data ModemAnswerCmd: AT+FCLASS=1;A # default is to answer as fax ModemAnswerDataCmd: ATH+FCLASS=0;A # hangup and answer as data Class1RecvIdentTimer: 10000 # timeout fax answer in 10 secs
Note also that by reversing the order of the items specified in the AnswerRotary parameter you can get HylaFAX to answer first for data and then for fax. If calls are answered first as data, then you may need to constrain the timeout used to recognize a data call so that time still remains to setup a fax connection. Consult your modem manual and the ModemAnswerResponseTimeout configuration parameter.
A second facility supported by the fax server in lieu of adaptive answering is a rotary of answering techniques. The general idea is that a list of alternative ways to answer the phone is supplied and the server will rotate through the list on consecutive inbound calls until it finds one that works. For example, one might specify something like:
AnswerRotary: "fax data"
AnswerRotary: "fax data" AnswerBias: 1
CIDNumber: "CALLER NUMBER: " # pattern string for phone number info CIDName: "CALLER NAME: " # pattern string for identity info
HylaFAX supports distinctive ring capabilities through the RingFax, RingData, and RingVoice modem configuration parameters. Modems that support distinctive ring send a different RING status message to the host depending on the ring pattern presented by the phone company. By setting the configuration parameters faxgetty will match the appropriate RING status message and use the information to treat the inbound call as fax, data, or voice before answering the call. For example,
RingFax: RING1 # treat ring pattern 1 as fax RingData: RING2 # treat ring pattern 2 as data
Copy quality checking is automatically done in the server for Class 1 modems. To configure copy quality checking directly in a Class 2 or Class 2.0 modem--when the modem is capable--setup the Class2CQCmd parameter for the modem. For example,
Class2CQCmd: "AT+FCQ=1;+FBADMUL=5;+FBADLIN=10"
Class2CQCmd: AT+FCQ=0
Copy quality checking in the server (for any style of modem) is controlled by two configuration parameters: PercentGoodLines and MaxConsecutiveBadLines; see config(4F) for more information. These parameters define the criteria by which the server decides if a received page has acceptable copy quality. Pages that are deemed unacceptable are rejected and the sender is told to resend the page.
Beware that many fax machines
are incapable of resending pages that have unacceptable copy quality
because they do not buffer a full page image.
If you encounter problems with the copy quality checking support you can disable it by setting either the PercentGoodLines or MaxConsecutiveBadLines parameters to 0; e.g.
PercentGoodLines: 0 # disable copy quality checking
By default HylaFAX does not enable continuation cover pages.
To enable use of this feature the ContCoverPage configuration
parameter must be set to the pathname of a cover sheet template
file to use in generating continuation cover pages.
This cover page template file is passed to the
mkcover(1M)
script, or to the program specified with the ContCoverCmd
configuration parameter; consult the mkcover manual page
for a description of this file.
Time-of-Day Usage Scheduling
HylaFAX can be configured so that outbound calls are placed only
during certain hours of the day.
This can optionally be configured on a
per-destination basis, making it easy
to reduce phone costs by processing toll calls only during the
time when off-peak rates are available.
By default outbound calls are permitted at any time. To constrain calls to a particular time or range of times the TimeOfDay parameter can be setup according to the syntax specified in config(4F). This syntax is consistent with the syntax used by the UUCP software. For example, to permit outbound calls only between 9AM and 5PM local time the following might be used:
TimeOfDay: "0900-1700"
Per-destination controls are especially useful for controlling which phone numbers can be called. For example, by specifying an entry of the form:
^911$ RejectNotice = "Calls to emergency numbers are not permitted"
Another useful feature of this facility is the ability to delay toll calls to off-hours so that off-peak phone rates may be used. Entries of the form:
^[+]1415.* TimeOfDay = "Any" ^[+]1510.* TimeOfDay = "Any" .* TimeOfDay = "Wk1700-0830,Sat,Sun"
Modem classes are defined with the ModemClass configuration parameter. Each definition specifies a name and a regular expression that identifies the set of modems that are to be included in the class. For example,
ModemClass: "any:.*"
Modem priorities are specified using the ModemPriority configuration parameter. Priority values are integer numbers in the range 0-255 with lower values meaning higher priority.
Modem priorities are passed to the HylaFAX scheduler by the faxgetty processes or with the faxmodem program. Priorities can be dynamically changed by using the faxconfig program to send a new priority to a faxgetty process (who in turn will notify the scheduler), e.g.
RecvDataFormat: "2-D MMR"
Another common request is to automatically print received facsimile as they arrive. This is easy to do by editing the faxrcvd script to use a program such as fax2ps or tiff2ps to convert the TIFF/F file and then submit the resulting PostScript; e.g.
For this scheme to work outbound callers must install a UUCP lock file before using a modem. This lock file must be created using the same conventions understood by HylaFAX. In particular the lock file name must be consistent and the file contents must include the process ID of the lock file owner written either as a binary or ascii value according to the system-specific conventions.
HylaFAX supports several schemes found on different systems.
The appropriate scheme is normally setup according to the target
system at the time that HylaFAX is configured for building.
It is possible, however, to override these parameters through
the runtime configuration files; consult the
config(4F)
manual page for information about the UUCPLockType
configuration parameter.
In addition to the lock type there are configuration parameters
that control the protection mode of the lock file (UUCPLockMode),
the directory in which lock files are created (UUCPLockDir),
and a timeout parameter used to purge stale lock files.
Again, consult config(4F) for
a full description of these parameters.
Modems that Lie about their Capabilities
Class 2 and 2.0 fax modems all too frequently have bugs in their firmware.
Sometimes it is possible to workaround firmware problems by restricting
a modems' capabilities.
To do this the Class2DCCQueryCmd configuration parameter may
be set in the per-modem configuration file.
By default this parameter holds the command to send the modem to
query its capabilities.
However if the query string has a leading ``!'' then no command is
sent to the modem and instead the remainder of the string is
treated as the response returned by the modem.
Thus to avoid using a particular modem capability all you need to
do is setup a capabilities string that has a restricted set of
modem capabilities.
Capabilities are returned using a syntax specified in the Class 2/2.0 specification:
(vr),(br),(wd),(ln),(df),(ec),(bf),(st)
| Param | Value | Description | Param | Value | Description |
|---|---|---|---|---|---|
| vr | 0 | 98 lines/inch | df | 0 | 1-D Modified Huffman |
| 1 | 196 lines/inch | 1 | 2-D Modified Huffman | ||
| br | 0 | 2400 bits/sec | 2 | 2-D Uncompressed Mode | |
| 1 | 4800 bits/sec | 3 | 2-D Modified Modified Read | ||
| 2 | 7200 bits/sec | ec | 0 | disable ECM | |
| 3 | 9600 bits/sec | 1 | enable T.30 Annex A, ECM | ||
| 4 | 12200 bits/sec | 2 | enable T.30 Annex C, half duplex | ||
| 5 | 14400 bits/sec | 3 | enable T.30 Annex C, full duplex | ||
| wd | 0 | 1728 pixels in 215 mm | bf | 0 | disable file transfer modes |
| 1 | 2048 pixels in 255 mm | 1 | select BFT, T.434 | ||
| 2 | 2432 pixels in 303 mm | st | 0 | scan time/line: 0 ms/0 ms | |
| 3 | 1216 pixels in 151 mm | 1 | scan time/line: 5 ms/5 ms | ||
| 4 | 864 pixels in 107 mm | 2 | scan time/line: 10 ms/5 ms | ||
| ln | 0 | A4, 297 mm | 3 | scan time/line: 10 ms/10 ms | |
| 1 | B4, 364 mm | 4 | scan time/line: 20 ms/10 ms | ||
| 2 | unlimited length | 5 | scan time/line: 20 ms/20 ms | ||
| 6 | scan time/line: 40 ms/20 ms | ||||
| 7 | scan time/line: 40 ms/40 ms |
An example use of this mechanism is found in the prototype configuration file for the AT&T DataPort modem. The rev C01.66.10 firmware for the DataPort returns an invalid string for the AT+FDCC=? query command so the prototype configuration file supplies a valid one instead:
Class2DCCQueryCmd: "!(0,1),(0-5),(0-4),(0-2),(0),(0),(0),(0-7)"
In normal operation HylaFAX will first reset a modem and then prepare it for use with a setup procedure appropriate for the modem. Modem reset involves the following steps:
ModemResetCmds any additional reset commands ModemEchoOffCmd disable modem echo of commands ModemVerboseResultsCmd enable verbose result codes ModemResultCodesCmd enable transmission of result codes ModemNoAutoAnswerCmd disable modem from auto-answering calls ModemOnHookCmd place modem ``on hook'' ModemPauseTimeCmd configure delay for "," in dial string ModemWaitTimeCmd configure time to wait for carrier modemflowcontrolcmd establish DTE-DCE flow control scheme ModemSetupDTRCmd force desired modem response to DTR transition ModemSetupDCDCmd force desired modem response to DCD transitionNote that these commands are sent as two separate AT commands, broken between ModemOnHookCmd and ModemPauseTimeCmd; this is done to avoid problems with certain modems.
|
Class 2/2.0 modems: | |
| Class2Cmd | force the modem into Class 2/2.0 | |
| class2FlowControlCmd | establish DTE-DCE flow control scheme | |
| Class2TBCCmd | select stream modem host-modem communication | |
| Class2BORCmd | set the bit order for HDLC and page data | |
| Class2PHCTOCmd | set the timeout during page transfer (Phase C) | |
| Class2CQCmd | enable copy quality checking | |
| Class2NRCmd | enable negotiation reporting (Class 2.0 only) | |
| Class2PIECmd | disable program interrupt handling (Class 2.0 only) | |
| Class2BUGCmd | enable HDLC frame reporting if requested | |
| Class2DCCCmd | initialize modem capabilities | |
| Class2RELCmd+ | enable reception of byte-aligned EOL codes | |
| Class2CRCmd+ | enable facsimile reception | |
| Class2LIDCmd+ | set local station identifier | |
| ModemSetupAACmd+ | enable adaptive-answer support | |
|
Class 1 modems: | |
| Class1Cmd | force the modem into Class 1 | |
| class1FlowControlCmd | establish DTE-DCE flow control scheme | |
| ModemSetupAACmd | enable adaptive-answer support |
(Commands marked with a ``+'' are optional and sent to the modem only if it is to be setup to receive calls.)
Flow control is explicitly set separately for Class 0 (data) operation and Class 1, 2, 2.0 (fax) operation. To configure the use of a different flow control scheme in each class simply override the default definition of the ClassXCmd parameter; e.g.
Class2Cmd: "AT+FCLASS=2<xon>"
To send a facsimile a phone call must be placed. HylaFAX takes the following actions:
|
Class 2/2.0 modems: | |
| Class2Cmd | force the modem into Class 2/2.0 | |
| class2FlowControlCmd | establish DTE-DCE flow control scheme | |
| Class2TBCCmd | select stream modem host-modem communication | |
| Class2BORCmd | set the bit order for HDLC and page data | |
| Class2PHCTOCmd | set the timeout during page transfer (Phase C) | |
| Class2CQCmd | enable copy quality checking | |
| Class2NRCmd | enable negotiation reporting (Class 2.0 only) | |
| Class2PIECmd | disable program interrupt handling (Class 2.0 only) | |
| Class2BUGCmd | enable HDLC frame reporting if requested | |
| Class2DCCCmd | initialize modem capabilities | |
| Class2LIDCmd | set local station identifier | |
| Class2SPLCmd | request polling status (if a polled receive is to be done) | |
| Class2DDISCmd | setup initial session parameters (optional) | |
| ModemDialCmd | place the call | |
|
Class 1 modems: | Class1Cmd | force the modem into Class 1 |
| class1FlowControlCmd | establish DTE-DCE flow control scheme | |
| ModemDialCmd | place the call |
Note that the modem is always switched into the appropriate class and flow control scheme before placing the call. For Class 2 modems that do not properly implement the AT+FDIS command the Class2DDISCmd parameter must be configured so that HylaFAX will setup initial session parameters before placing the phone call.
If the call completes and a facsimile transmit session is started then HylaFAX will send ModemSendBeginCmd to the modem. This parameter can be used to enable servicing that must be done only while Carrier Detect (CD) is asserted to the host. For example, on Sun systems it is not possible to enable RTS/CTS flow control on serial ports implemented with the ZS8530 unless CD is asserted; to workaround this problem for outbound calls one can use:
ModemSendBeginCmd: "<rts>"
The next phase in the processing of an outbound job is the selection of station capabilities. The receiver is required to transmit a series of messages that provide its identity and capabilities (e.g. whether it can accept 2D-encoded facsimile data). HylaFAX examines the received capabilities and compares them to the capabilities required for the job. If the receiver is capable of accepting the documents to be sent then HylaFAX proceeds with the transmission. Otherwise HylaFAX will disconnect and, either re-prepare the outbound documents according to the receiver's capabilities or reject the job because it cannot be sent.
Page transfer requires the selection of session capabilities that correspond to the page to be transferred and the actual transfer of the page data to the modem. HylaFAX handles documents with varying page characteristics. In particular this means that documents with a mixture of high res and low res data (e.g. a low res cover page followed by high res image or text) are handled transparently.
For Class 2 modems session parameters are set using the Class2DISCmd (note that this is not the same as Class2DDISCmd). If the negotiated session parameter needs to be changed then this command will be sent to the modem. The Class 2 specification requires that a modem accept this command at any time prior to an AT+FDT command. However because some modems do not properly implement this part of the specification the Class2DDISCmd is provided to workaround modem limitations. Beware however that modems that require Class2DDISCmd may not be capable of renegotiating session parameters at all; this can be an annoying problem.
For Class 2/2.0 modems, page data is transferred using the AT+FDT command. This command instructs the modem that a page of facsimile data will follow. The modem is released to negotiate session parameters (as needed) and HylaFAX then waits for a response that indicates page data may be transferred to the modem. Class 2 modems indicate they are ready for page data by sending CONNECT followed by XON (DC1) to the host. (The ModemWaitForXON configuration parameter controls whether or not HylaFAX should wait for XON because some Class 2 modems do not follow this aspect of the spec.) Class 2.0 modems indicate they are ready for page data by sending a CONNECT response to the host (but no XON). Class 2 modems return OK to the host when they have accepted all the page data. Class 2.0 modems do not return OK.
After a page of data has been transferred to the modem HylaFAX
indicates whether this is the last page to be sent and/or whether
more documents are to come.
A post-page message is then sent and a post-page response
is awaited.
Class 2/2.0 modems handle this exchange entirely within the modem.
For Class 1 modems HylaFAX implements this part of the protocol
on the host: the post-page message may be retransmitted as many
as three times.
A post-page response indicates whether a page was successfully received
and/or whether or not the receiver wants to resynchronize the
line due to a perceived loss in signal quality.
HylaFAX is capable of retransmitting pages that a receiver deems
unacceptable.
HylaFAX will automatically retransmit a page up to three times
if it does not receive a positive acknowledgement from the receiver.
Modem Parameter Usage for Inbound Calls
Inbound call handling is the most complicated part of the HylaFAX
software.
This is because modems vary so widely in the way they process inbound
calls for fax, data, and voice use.
Also, inbound calls typically require that a modem be configured
before a call is received and many modems do not accept
commands from the host until after a call has been recognized,
accepted, and processing initiated.
HylaFAX handles inbound calls in the faxgetty program. The modem is initialized as described above and faxgetty then waits for a ring status message from the modem. On receiving input from the modem the following processing takes place:
Host Modem
ATA -->
<-- DATA
<-- CONNECT
For fax operation faxgetty drops into the facsimile receive protocol.
More to be added.
This chapter describes how to configure the support for transmitting messages to alpha-numberic pager devices using the IXO/TAP protocol. This facility is implemented with the sendpage(1) client program, the hfaxd(1M) server program that implements the Simple Network Pager Protocol (SNPP), and the pagesend(1M) server program that does the actual delivery.
Alpha-numeric pages are transmitted by contacting a server machine that speaks SNPP and requesting that one or more messages be delivered to one or more paging terminals. HylaFAX implements SNPP within the framework of the hfaxd client-server protocol process (SNPP is one of several protocols it supports). Pager messages submitted through hfaxd result in jobs being submitted to the HylaFAX scheduler process and these jobs are in turn handed to the pagesend program for delivery by placing a phone call to a pager service provider and communicating the requests using the IXO/TAP protocol.
Note that by using SNPP to communicate between client and server,
client applications other than sendpage can be used to
submit pager messages. There supposedly are several client
applications for Mac and Windows-based systems that use SNPP to
submit pages and a growing number of pager service providers are
providing on-line SNPP services via the Internet.
Setting up SNPP
sendpage normally tries to contact an hfaxd server process at port
444 on a HylaFAX server machine.
To enable this service hfaxd must be started with a -s
option when run standalone or with a -S option when started
by the inetd process.
For example, as a standalone server hfaxd might be started by:
One of the tasks that hfaxd does in implementing SNPP is to map client-specified Pager Identifier Numbers (PINs) to a dialstring to use in contacting the service provider. This work is done using rules specified in a pagermap(4F) file. For example, the following pagermap file would accept only PINs with a leading ``Sky'' followed by a number and pass the number through as the PIN:
|
If hfaxd does not have a pagermap file then it will reject all requests to submit pager messages. |
Each page request received by hfaxd causes a
job to be submitted to the HylaFAX scheduler process.
The scheduling parameters for these jobs are defined by the
service level specified with the SNPP LEVE
request (typically through the -l option to sendpage).
hfaxd uses the service level to set a job's scheduling priority,
expiration time, and the time to delay in between retrying calls
to the service provider based on three maps that can
be specified with hfaxd configuration parameters.
The parameters are: PriorityMap, KillTimeMap,
and RetryTimeMap, respectively.
Consult the
hfaxd(1M)
manual page for complete information on these parameters.
Setting up Pagesend
There are several configuration parameters associated with the
IXO/TAP support.
The most important parameter is PagerSetupCmds which is
a set of commands to send to the modem to configure it for a call
to the pager service provider.
This command should usually be defined to constrain the modem to
connect at 1200 baud using V.22 (and no error correction protocol).
Other configuration parameters exist to control
esoteric aspects of the IXO protocol implementation
and should not need to be changed;
consult
config(4F)
for full details.
Besides the per-modem configuration parameters described above, the only other pager-related information that may need to be setup is information in the info(4F) database to constrain the maximum length of an alpha-numeric pager message, any password string that must be sent to the service provider during the initial login sequence, and any non-standard parity setting to use in communication. For example,
The most common problems are not setting up the PagerSetupCmds properly for the modem and service provider and service providers that do not implement the IXO protocol according to the specification; usually by using odd instead of even parity.
From the Source Distribution
From the source distribution configure and build the software
as described in the chapter
``Building HylaFAX From Source Code''
(NB: this will build both client and server software).
To install only the programs and files required on a client then do
Setting Up Defaults
With the applications and data files available on a client machine,
the only other work one might do on the client machine is to configure
default settings for the HylaFAX client applications.
The most important of these settings is the identity of the
machine to contact for service.
This can be specified in many ways.
HylaFAX client applications read configuration information from a
system-wide file named hyla.conf followed by a per-user
configuration file named .hylarc that is stored in the user's
home directory.
The Host, Port, Protocol, and Modem
configuration parameters can be setup to completely specify a
HylaFAX server and modem to use as a default.
Otherwise
the FAXSERVER and SNPPSERVER environment variables
can be used to override this information (the latter is used only
by the sendpage program).
If no configuration values are defined on a client machine then
HylaFAX uses values that are compiled into each program: service is
requested from the localhost at the port associated with
the hylafax service or at port 4559 if this service is not
defined in the system services database.
Consult the manual page for each client application for a full list of the configuration parameters that are used and the set of configuration files that are searched.
Setting up Server Access
Once a client machine is setup for use the server machine may need to
be configured to permit client access. Specifically, the file
etc/hosts in the spooling area on the server machine must be setup to
permit client access to HylaFAX services.
This documentation has a section on
``Setting up client access''
and the
hosts(4F)
manual page has reference information how this is done.
Customizing Cover Pages
The fax submission program
sendfax(1)
includes support for the automatic generation of cover pages for each
outbound job.
Cover pages are generated by invoking a program, by default
faxcover(1),
to create a PostScript cover page for a transmission.
Users can customize cover page generation in many ways.
The default faxcover program supports customization through the user
of template files that are parameterized with PostScript.
Alternatively the faxcover program itself can be replaced by
overriding its definition in a configuration file (either a
personal file or a system-wide file).
Finally clients may simply suppress the automatic cover page
support provided by sendfax and supply pre-constructed cover
pages of their own choice as normal documents that are to be
transmitted.
The only negative aspect of the last alternative is that cover
pages submitted in this manner may confuse the continuation
cover page support provided a the HylaFAX server.
Customizing Document Conversions
A HylaFAX server accepts PostScript or TIFF format files and converts
them to the appropriate format required to transmit them as facsimile.
Any other documents must be converted prior to submitting them to the
server for transmission.
In particular ASCII text must be converted before it can be submitted.
The fax submission program
sendfax(1)
uses a set of file type conversion rules
to decide how to prepare documents for transmission as facsimile
and HylaFAX includes several document conversion programs that are
used on client machines to prepare documents for transmission:
textfmt(1)
to formats text and convert it to PostScript and,
for IRIX systems,
sgi2fax(1)
to convert SGI RGB-format images to TIFF.
Users can customize the file type conversion rules as needed by
overriding the default set of conversion rules.
To do so just create a .hylarc file that specifies
a private set of file type conversion rules:
Under a System V-based operating system the normal installation procedure sets up the system so the faxq and hfaxd processes are started up by init(1M). On other systems you will need to arrange for this yourself (typically by editing /etc/rc.local or similar). faxgetty processes must be manually setup by editing the appropriate control file for init; usually either /etc/inittab or /etc/ttytab. hfaxd can be setup to be started by inetd when the faxsetup script is run to configure a system for use with HylaFAX.
If you need to start the faxq server by hand, consult the faxq(1M) manual page and the shell script etc/hylafax that is used on System V-based systems.
Incoming facsimile are placed in the recvq subdirectory of the spooling area and probably will need to be cleaned up periodically. Likewise there is logging information in the log subdirectory and accounting information in the etc subdirectory of the spooling area that may need some attention.
The
faxcron
script is designed to handle the
periodic maintenance of the spooling area. This script is designed to
be run from
cron(1)
every day.
If you want to do accounting check out the xferstats and recvstats scripts for a basic attack on how to process the etc/xferlog accounting file that has records of all facsimile transmissions and receptions. Note that faxcron uses these scripts to deliver statistics about facsimile that were recently transmitted and received.
Otherwise the only matter to be concerned with is the support for data connections. If your modems are capable of differentiating data connections from facsimile connections the fax server can be configured to startup a getty program whenever a call from a data modem is received. Alternatively, if your modem does not support an adaptive-answer facility, but it is a Class 1 modem, the server may be able to do adaptive answering in software. In any event, beware that if you enable data connections you should take the normal precautions you would take when there are dialup ports on your machine. Specifically, make sure that you have passwords, appropriate file protections, and proper configuration of uucp or similar.
If you encounter problems sending or receiving facsimile you can
enable copious tracing information by editing the HylaFAX
configuration files.
Consult the Troubleshooting
section and the
config(4F) manual page,
in particular, for help.
There is also information in the
HylaFAQ on problems one might encounter during
server operation.
Controlling Modem Usage
HylaFAX provides a great of flexibility in how modems on a server
machine are used.
Modems can be constrained for outbound-only use, inbound-only use, or both.
Modem priorities (see the section in the
``Advanced Server Setup'' chapter)
can be used to control the order in which modems are assigned to outbound
jobs.
Modems can also be dynamically taken off-line for either inbound or
outbound use by using the faxstate or faxconfig commands.
For example, to mark a modem as ``busy'' or ``down'' so that it is not
assigned to an outbound job the faxstate command would be used:
hyla# faxstate -s busy ttyf2
hyla# faxconfig -m ttyf2 RingsBeforeAnswer 0
Mail submitted through this gateway can include header lines in the envelope that control the various aspects of the transmission. For example, to have the facsimile sent at 196 lines/inch the header line:
X-FAX-Resolution: 196
|
The normal access control mechansims on submitting a facsimile for transmission are enforced; you may need to use them if you setup a fax gateway on your system! |
Dirk Husemann has contributed a more elaborate system; the README file is accessible in the user contributed software area on the master FTP server.
There are several components to the complete HylaFAX software package:
All client applications support a -v option to enable various levels of debugging. It is possible with one or more -v options to trace the protocol between the application and the hfaxd process on the server machine. hfaxd has a ServerTracing configuration parameter that controls various tracing support, including the protocol messages it receives. If you are in doubt whether a problem is on the client machine or the server, try the following:
Run faxstat to request server status. You should see something like:
|
Beware of settings that might be present in personal or system-wide configuration files. Some applications such as sendfax search an additional file as well. Consult manual pages for complete information about configuration file handling. |
On the server machine make sure that the hfaxd program is setup to run standalone or properly configured to be invoked by the inetd program. If run standalone then hfaxd should be running and have been started with a -i option (and possibly other options). hfaxd should also send messages to the system logging facility whenever it is started up and these messages should identify the client-server protocols it is servicing; e.g.
|
Be certain that inetd has ``reread'' its configuration file; either send it a SIGHUP or restart it. This should automatically happen when the faxsetup program is run on the server machine. |
|
Note also that the fax service must be defined on the server machine in order for inetd to startup the hfaxd program--check for this entry in the /etc/services file and/or the YP/NIS database. |
Note that hfaxd uses the chroot system call to confine clients to the HylaFAX spooling area on the server machine. On most systems only the super-user is permitted to do a chroot call so if hfaxd is not started by the super-user or the executable program is not setup to be setuid-root then it will not function properly. If this happens clients will usually be denied access with a message of the form ``Cannot set privileges.''.
You can also use an existing network program such as telnet or ftp to communicate with the hfaxd process;
If the network-related configuration is setup properly but faxstat still does not return an expected answer then use the -v option to trace the client-server protocol:
ServerTracing: 0x3 # enable protocol tracing
Once again, remember that inetd
will not see a change to the inetd.conf
file until it is restarted or sent a SIGHUP; and
that hfaxd logs
its debugging information through
syslog
(using the syslog facility setup in the hfaxd.conf
file, or the setting compiled into the program
when the software was built).
TROUBLESHOOTING: CLIENT ACCESS CONTROL PROBLEMS
If you are able to establish a network connection to the hfaxd server process then access control problems are either due to incorrect installation of the server software or misconfigured permissions on the server machine. Client access is defined by the contents of the etc/hosts file located in the HylaFAX spooling area on the server machine. This file must exist and must not be publicly readable or access will be denied to all clients.
|
Beware of the protection on the etc/hosts file when upgrading from HylaFAX 3.0. Previous versions of HylaFAX did not care if the file was publicly readable so it probably is. |
The hfaxd program confines clients to the spooling area on the server machine using the chroot(2) system call. This means that clients should not have access to any information on a HylaFAX server machine outside the spooling area (and hfaxd restricts access to only part of this area).
HylaFAX clients are assigned a ``fax user ID'' when they login to a HylaFAX server. This identifier is similar to the normal UNIX user ID but is maintained separately by HylaFAX and is independent of the normal system operation. Beware that hfaxd stores this ID as the group ID of files that are created on a HylaFAX server on behalf of a client. The fax user ID assigned to a client is defined by the information in the etc/hosts file; consult the manual page for more details. You can also find the user ID for a particular user by logging in with telnet and issuing a STAT request:
Client access may be controlled with passwords that are transmitted in the clear by a client across the network connection. This is obviously insecure and plans exist for improved security measures. The existing password facilities use the same crypt(3) function the system login facilities use and encrypted passwords are stored in the etc/hosts file in a format that is compatible with most systems' password files. This means that client passwords can be copied from a password file if desired (though this is obviously discouraged). The HylaFAX client-server protocol ADDUSER request includes a variety of checks for easy-to-guess passwords.
|
HylaFAX uses the standard system crypt function to implement client passwords. Systems without this routine may substitute the publicly available GNU version but then it may not be possible to copy encrypted passwords from the system password file. |
If a client is prompted for a password when contacting the server then it means the client is setup with a password in the etc/hosts file. Read the hosts(4F) manual page carefully to understand the format for this file.
Logging of client login and network connections can be controlled
separately by bits in the hfaxd ServerTracing configuration
parameter; consult the
hfaxd
manual page for details.
TROUBLESHOOTING: SERVER BASICS
One faxq process does the job scheduling and initiation of outbound calls; it handles many tasks:
Tracing information is broken up into two separate areas: server tracing and session tracing. Server tracing is the logging done by server processes when not in active conversation with another device such as a facsimile machine or paging service provider. This tracing covers modem initialization, scheduler operation, and general bookkeeping and maintenance work. Session tracing is the logging done while a server process is actively communicating with a remote device; e.g. the communcation work done to send or receive a facsimile. This split permits better control over the amount of information logged in a production environment. Typically once a system is setup and working the amount of server tracing information captured can be quite small while the session tracing logged needs to be more extensive to help debug any communication problems that might arise.
HylaFAX servers processes are controlled by a collection of configuration files. There is a configuration file for the faxq scheduler process, etc/config, and one file for each process that uses a modem, etc/config.device. (The hfaxd process that implements the client-server protocols also has its own configuration file.)
faxq tracing information is controlled by the ServerTracing and LogFacility configuration parameters. ServerTracing controls which work should be traced while LogFacility specifies the syslog(3) facility where the tracing messages should be directed. By default server tracing information is directed to the ``daemon'' facility.
Modem-related tracing information is controlled by ServerTracing, SessionTracing, and LogFacility parameters that are put in the per-modem configuration files. ServerTracing controls the logging done when one of these programs is not in active conversation with another device while SessionTracing controls the logging during other times. As before, LogFacility defines where server tracing messages get sent. Session tracing messages are not sent using syslog; they are written to session log files that are described separately below.
To capture server tracing messages you must enable the appropriate bits in a ServerTracing parameter and configure the syslogd process to capture messages sent to the daemon.debug facilitiy (or substitute for daemon to reflect the value of the LogFacility parameter).
|
By setting LogFacility to something like local5 it is easy to capture HylaFAX syslog messages in a separate file; just setup the syslog.conf file appropriately, e.g. |
HylaFAX requires a faxq process to be running for outbound transmissions to be done. The faxstat program should show this process running in its output:
FIFO-related problems usually happen when the FIFO special file is removed without first stopping the HylaFAX server processes. This can cause one or more processes to be left with an open file descriptor to a file that is no longer present in the filesystem, and hence unreachable. When doing maintenance work on a HylaFAX server it is a good idea to first shut down the server processes. This is simple to do with the hylafax shell script used on System V-style systems; simply do
If you believe that you are having problems with the messages exchanged by the various HylaFAX server processes ServerTracing bit 0x04000 can be set to force logging of all the messages sent and received through FIFO special files; usually you need to do this only for the faxq process.
Other than FIFO communication problems, the most common scheduler-related problem encountered is that no outbound jobs get scheduled for processing. faxq will only schedule an outbound job when it believes it has a modem available that is capable of handling a job's needs. A modem's existence and capabilities are signalled to faxq through messages received on its FIFO file. The two programs that send modem information are faxgetty and faxmodem. Processes that want to send faxq information about new modems must be able to access the file; this means the protection on the file must be such that clients can open it for writing (the default setup should make this happen). The order in which faxq and faxgetty are started does not matter; a handshaking protocol between faxq and faxgetty insures that modem status information will be exchanged no matter what order the processes startup in.
When in doubt about what is happening, or not happening, to jobs enable the job queue management tracing bit in the ServerTracing parameter for the faxq process; e.g.
ServerTracing: 0x201
Otherwise
there is very little that can go wrong with the scheduler
with respect to managing the queue of outbound jobs.
Setting the system time backwards
on the server machine can cause problems as timers managed by faxq
are calculated relative to the current time-of-day.
Jobs may be rejected
without a phone call if a rejectNotice entry is present for a
destination phone number in the
destination controls file
destctrls(4F).
Beware that multiple jobs to the same destination are usually
serialized to reduce phone calls.
Jobs that are blocked in this way have a
"Blocked by concurrent..." status.
You can change the maximum number
of concurrent jobs that will be scheduled to a destination with the
MaxConcurrentJobs configuration parameter.
TROUBLESHOOTING: SESSION TRACING
The SessionTracing parameter controls tracing information during the time HylaFAX is engaged in conversation with another device (fax machine, pager service provider, etc.) Tracing of this sort is done by faxgetty processes (when receiving facsimile) and by processes started up by faxq to process outbound jobs (faxsend, pagesend, etc.). Session tracing is controlled by configuration parameters specified in the per-modem configuration files. It is also possible to enable session tracing on a per-destination basis for outbound jobs through the per-destination DestControls facility provided by faxq.
Communication-related problems will be found in the information logged under session tracing. Session tracing information is stored in files in the log subdirectory in the spooling tree and is returned to users via electronic mail when notification is requested, or when an unrecoverable error is encountered. The log(4F) manual page has information on the meaning of many messages that might appear in these files.
A sample snippet from a session log is shown below. The trace was collected from a transmission through a Class 1 modem. The SessionTracing parameter was set to 0x4f. Notice that the format is very similar to the server tracing information collected through syslog (shown above). Beware that, unlike previous versions of HylaFAX, session logs are collected in individual files that are uniquely named according to a unique communication identifier. This can make locating the session log file a bit tricky; to find the appropriate log file you can look for a record in the etc/xferlog file or a server tracing message. Either should contain a communication identifier which can then be used to select the appropriate file from the log directory in the spooling area. (If only one call is being handled on a server you can also just look for the most recently changed file in the log directory.)
Session logs are straightforward to understand. Messages sent to the modem are identified by lines with a ``<--'' mark while data received from the modem are identified by lines with a ``-->''. Timestamps show the date and time, with time to the right of the decimal point displayed to 10 millisecond precision (the typical granularity of the realtime clock on a UNIX system). The number of characters in each message prefix the message itself. Unimportant binary data, usually the facsimile page data, is sometimes shown generically as ``data''.
|
When debugging modem-related problems, only enable the tracing that you really need. Enabling all tracing can affect the operation of the server processes by altering the timing of operations. |
Note that when capturing a trace for the purpose of submitting a bug
report, the less extraneous information that you include, the easier it
is for people to help understand the problem.
Most of the time HylaFAX will return the relevant session log for
a communication failure in the notification message sent to a user
when an outbound job fails. Note however that the contents of
this log is controlled by the value of the SessionTracing
parameter specified in the per-modem configuration files.
If this parameter is set too low then session logs may be returned
that do not show sufficient information to diagnose a problem.
TROUBLESHOOTING: POSTSCRIPT DOCUMENT PREPARATION
PostScript documents submitted for transmission as facsimile are converted to a binary format by the ps2fax(1M) script that is invoked by the scheduler. If this preparation fails it is either due to the submission of invalid PostScript or a problem in the setup of the PostScript RIP that does the conversion from PostScript to TIFF/F. faxq tries to return any error messages returned by the PostScript RIP to the user that submits a job but some programs make this difficult. In this case it may be easiest to see what is happening by invoking the ps2fax script directly using the same command arguments used by faxq; this information can be found in the faxq trace log. Beware however, that if faxq is started up by the init(1M) program that it may inherit a different shell environment. In particular, beware of problems with search paths when the PostScript RIP is linked with Dynamic Shared Objects (DSOs); e.g. when Ghostscript is linked with the the X11 driver and a DSO version of the X library.
|
On machines with dynamic shared libraries (e.g. SunOS), if you link Ghostscript with the X11 device driver and use shared X11 libraries that are not in a standard location, then you may need to augment the HylaFAX util/ps2fax.gs.sh script with something of the form: |
PostScript imaging problems may also result in the faxq process not being able to reopen the imaged document after the ps2fax script is run. After faxq invokes ps2fax to image a document it validates the resulting TIFF/F file to make sure the work was done correctly. This is necessary because some programs terminate with exit status 0 indicating a successful run even if an error was encountered.
Some other potential problems to be aware of. If Ghostscript is configured with a tiffg32d device driver to generated 2D-encoded data beware that versions of Ghostscript prior to 3.12 (inclusive) had a bug in this driver that caused invalid data to be generated. If you are in doubt you can disable the use of 2D-encoded facsimile data with the User2D configuration parameter to faxq:
Use2D: no
Versions of Ghostscript prior to about
3.63 permitted PostScript documents
to set the output page dimensions to arbitrary values.
Some applications such as Frame 4.0 and various PostScript drivers
found in Microsoft Windows used this facility to force the output
page to be 1734 pixels wide (8.5 inches at 204 pixels/inch).
This causes problems when HylaFAX requests that
documents be imaged with pages that are 1728 pixels wide.
The result is that documents will be submitted, imaged, and then
rejected during transmission because they have an incorrect page width.
The solution is to get a current version of Ghostscript or to
edit the PostScript documents to remove the setpagedevice
requests that (incorrectly) force the output page dimensions.
TROUBLESHOOTING: TIFF DOCUMENT PREPARATION
Like PostScript documents TIFF documents may need to be prepared
before they can be transmitted as facsimile.
This work is done by the
tiff2fax(1M)
script that is invoked by faxq.
The tiff2fax script depends on programs that are part of the separate
TIFF software distribution and, in some instances, the ps2fax script.
If you encounter a problem preparing a TIFF document for transmission
capture the command arguments to the tiff2fax script from the
faxq log and try running it by hand.
TROUBLESHOOTING: COMMUNICATION PROBLEMS
Communication problems refer to errors that occur during an outbound call handled by faxsend or pagesend, or an inbound call handled by faxgetty. Almost all communication problems can be diagnosed from the information in a session log. The only server tracing information that might be needed is for modem setup work done by faxgetty which does not appear in a session log.
If a problem occurs during modem setup by faxgetty, set ServerTracing to 11, or similar, in the modem configuration file and check the server trace log. Modem initialization for an outbound job is included in the session log and controlled by the SessionTracing parameter. Problems during modem setup are typically caused by:
Once a call is placed, facsimile communication happens in several phases. First the sender and receiver negotiate a set of session parameters to use during communication. These parameters define the format of data that is to be exchanged, the physical dimensions of the pages, and certain other parameters related to the communication work (speed at which to transfer data, modulation scheme, time to delay between raster scanlines to permit a receiver's printer to run properly, etc.). An example of this negotiation for a Class 2.0 modem is:
|
Beware that a common problem in Class 2 modems is for the modem to reject or ignore an AT+FDIS command to set the session parameters between the time a call is placed and a page is transmitted. When this problem occurs pages may appear ``squished'' or the session may be aborted abnormally. If you suspect this problem use the Class2DDISCmd configuration parameter to enable workaround support; e.g. |
The basic work described above occurs for all facsimile communication no matter whether it is done with a Class 1, 2, or 2.0 modem. Two things to understand from this abbreviated description:
When debugging a communication problem try to identify if the problem is transient or repeatable and if the problem always happens when communicating with the same sender/receiver. Also check the negotiated session parameters to see if there is any correlation, for example, to the negotiated data format (i.e. 1D-encoded data versus 2D-encoded data). Communication problems can be caused by many things including:
|
If communication problems persist to a specific receiver when using 2D-encoded data, you can disable its use through the info(4F) database. Note also that sendfax has a command line option that lets you select 1D-encoded data in any single transmission. |
The HylaFAQ contains
information on some common communication problems
that might be encountered.
It is also important to monitor the operation of a server to detect
trends that might indicate modem or telecommunication problems;
the faxcron(1M)
script is useful for doing this since it extracts
the transcripts of failed calls.
TROUBLESHOOTING: GETTY PROBLEMS
HylaFAX will invoke the getty program when a data connection is established and the GettyArgs parameter is set to a non-null string. When HylaFAX starts up a getty program it sets the standard input, output, and error descriptors to the modem device (closing all other descriptors), creates a new process group, and turns off the CLOCAL bit on the tty device so that if carrier is dropped the process group will receive a SIGHUP signal.
If you have a problem running the fax software together with other communication programs such as uucp, cu, tip, slip, ppp, etc. first verify that your data communication software is configured to use the correct modem initialization strings and that both HylaFAX and the program(s) in question are using the same device name. Many of the prototype modem configuration files for Class 2 and Class 2.0 modems will leave the modem idling in Class 2 or 2.0. This means that in order to place a data call the modem must first be reset to Class 0; e.g.
AT+FCLASS=0DT<phone number>
There is no need to subscribe to both
the flexfax and flexfax-announce
mailing lists; postings to
the announcement list are automatically fed to the normal
flexfax list.
If you want to subscribe to either of these lists you need to send electronic mail that includes only a subscribe request in the body of the mail; for example, to subscribe to the flexfax mailing list you might send:
To: flexfax-request@sgi.com
subscribe
To specify a mailing address other than the one used to post your
note, specify it in the mail; e.g. to subscribe the user
hopeless@lost.com to the flexfax-announce
mailing list use:
To: flexfax-announce-request@engr.sgi.com
subscribe hopeless@lost.com
When you have been added to the mailing list you will
receive confirmation by electronic mail at the subscribed address.
To unsubscribe from a list
send an unsubscribe request like the above to the
same mail address; do not send administrative requests
to the mailing list.
To subscribe to the
If you have not previously done so, please fill out and submit the
survey form.
The information provided in this form is purely for use in
assisting users of HylaFAX.
This software is more than 6 years old and is the product of many
folks' work. Robin Schaufler did the original scheme for delayed
submission and worked on the original client-server protocol.
More recently,
the following people have helped either by testing or by contributing
fixes and/or improvements:
Matthias Apitz Chris Beekhuis Peter Bentley
Marc Boucher Piete Brooks Bill Campbell
Brent Chapman Camden Clarke Tom Corson
Alan Crosswell Mark Diekhans Greg Ferguson
Steve Fine Andrew Ford Nico Garcia
Wolfgang Henke Viet Hoang Bert Hooyman
Ken Hornstein Dirk Husemann Brian Katzung
Masao Kitano Carsten Koch John T Kohl
Scott Kramer Rickard Linck Rick Lyons
Tom Lislegaard Rob MacKinnon Kevin McManamon
Les Mikesell Bill Morrow Andy Moskoff
Chris Munonye Rob Newberry Dag Nygren
Jonas Olsson Dave Packer Damon Permezel
David Pike Amir Plivatsky Andy Rabagliati
Eric Rescorla Marshall Rose Daniel Rosenblatt
Joel Rosi-Schwartz Tim Rylance Joseph E. Sacco
Thomas A. Szybist Brent Townshend Peter White
Steve Williams Scott Woodard David Vrona
Paul Vixie Christian Zahl
(and surely others). Also, a special thanks to Ed McCreight for
helping me understand the stuff between the lines
that's necessary to make a working Class 1 driver.
The home page artwork was sketched by Rob Myers.
I then butchered it with my handy use of the freely available
gimp program.
If you like the art send Rob a compliment.
If you don't like it blame me, or better yet,
send me
a better version to replace it (please).
Please note that the artwork is copyright Silicon Graphics Inc. and
is not to be used without written permission.
Regular Expression Support
The regular expression support is based on Henry Spencer's POSIX 1003.2
compliant regex package that has
Compression Support
The zlib package used in the client-server protocol has the following
copyright notice:
PCF Font Support
The code to read PCF fonts is distantly related to the X11R5 code that is
Text to PostScript Conversion
The
textfmt
program is very distantly
related to the lptops program written
by Nelson Beebe; there was no copyright notice on the version of the code
that textfmt grew out of.
Configuration Support
The config.guess and config.sub
scripts are part of the GNU autoconf
package and covered by the GNU Public License (GPL). Several ideas
in the configure script are directly "borrowed" from autoconf (and I
have tried to maintain as much compatibility as possible).
Sample PCF Font
The PCF font etc/lutRS18.pcf included for use with tag lines is a
compiled version of a LucidaTypewriter font that was contributed to X11
by Bigelow & Holmes. Redistribution of this font requires inclusion of
this copyright notice:
Silicon Graphics has seen fit to allow me to give this work away. It
is free. There is no support or guarantee of any sort as to its
operations, correctness, or whatever. If you do anything useful with
all or parts of it you need to honor the
copyright notice enclosed below which
basically says ``you can't use my name or Silicon Graphics'
name without our written permission''.
I would however be interested in knowing about any
interesting work with HylaFAX and, hopefully, be acknowledged.
Finally, note that HylaFAX is a trademark of Silicon Graphics, Inc.