FAQ

This is a living list of frequently asked questions about the HylaFAX fax software system.

Your comments, additions and fixes to the FAQ are welcome: please send them to faq@hylafax.org. You can also give feedback on specific questions through links provided on each individual page. If you cannot find the information you need here or in the archives, please subscribe to the community mailing list and ask for help there.

HYLAFAX

What is HylaFAX?

See About HylaFAX for more information.

Where did HylaFAX/FlexFAX come from?

Sam Leffler, while working at Silicon Graphics (SGI), wrote a fax server for SGI's IRIX servers called FlexFAX and released it to the public in 1991. Sam and others worked for several years on FlexFAX, adding new features and porting the software to new platforms. In 1995 FlexFAX was renamed HylaFAX to avoid potential trademark issues. Sam eventually decided to leave the project to pursue other interests which, even with the best intentions of the HylaFAX developers, caused development to slow dramatically. In 1998 HylaFAX development was revitalized by the creation of hylafax.org, a central repository for HylaFAX development, downloads, documentation, etc. and the project remains very active to this day.

So, to answer the question: HylaFAX, nee FlexFAX, was born of Sam Leffler and through the hard work and contributions of many, many people has grown to become what it is today.

Some old newgroup postings that may be of interest:

Original FlexFAX announcement (mirrored here)

Announcement of hylafax.org (mirrored here)

Why is it called HylaFAX?

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.

Why should I use HylaFAX instead of some other fax package?

HylaFAX is designed to be very robust and reliable. The fax server is designed to guard against unexpected failures in the software, in the configuration, in the hardware, and in general use. HylaFAX uses an intelligent scheduling policy that attempts to recognize different types of failures and optimize retry attempts. An important design goal is that users must never worry about transmit jobs being lost or mishandled: jobs are either completed successfully or the submitter is notified what happened to their job and why the job failed. If you are willing to shepherd your facsimile transmissions then other software packages may be more suitable for you.

HylaFAX supports a wide variety of modems and is designed to support any Class 1, 1.0, 2, 2.0, or 2.1 modem without modification to the source code. If you have a modem that provides only a Class 1 interface then HylaFAX is likely to be the only freely available software package that will work with your modem.

HylaFAX supports multiple modems and heavy traffic load. If you expect to send or receive more than 1 or 2 facsimile a day, then HylaFAX is likely to be the best package for you to use.

HylaFAX is expressly designed to be highly configurable without modification or access to the source code. The software comes with extensive documentation to assist in understanding how the software functions and how to configure it.

HylaFAX is freely available. There is no GNU copyleft policy. There are no requests for remuneration, constraints on use, or constraints on incorporation into products (compare this with other "freely available fax packages"). There are binary distribution packages or other formats for several Unixes.

Which modems can I use with HylaFAX?

HylaFAX is intended to be used with fax modems. Fax modems are not the same as data modems though most contemporary data modems also include support for fax communication. HylaFAX should work with any Class 1, 1.0, 2, 2.0 or 2.1 fax modem. Wherever possible HylaFAX works around known modem problems or restricts modem usage in order to provide a functioning system.

See Handbook:Choosing a Modem for more information.

What machines does HylaFAX run on?

HylaFAX is intended to run on any UNIX system that supports a particular set of features: FIFO special files, BSD-style sockets and the TCP/IP communication protocols, BSD-style file locking (flock) or equivalent functionality from which it can be emulated (fcntl, lockf), and POSIX 1003.1-style interfaces, including termios for manipulating tty devices.

The following systems are known to have these features: AIX v3.x, v4.x BSD/386, FreeBSD, HP-UX 9.x, 10.x IRIX, ISC4.0, Linux, OSF/1 V1.3 and V3.0, SCO 3.2v4 with TCP/IP, SCO ODT 3, SCO 5.0, Solaris 2.x, SunOS 4.1.x, SVR4.x on an Intel x86 and MIPS (UnixWare, Onsite, SINIX, ...), Ultrix 4.4.

How to tell which HylaFAX version you have?

If you have need to refer to this specific software, you should identify it as:

HylaFAX v<version><n>

where <version> is found in the file VERSION and <n> is the number recorded in dist/hylfax.alpha. 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 syslog messages are recorded).

What documentation is available?

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.

How should I report bugs?

Unconfirmed HylaFAX bugs and related questions should be sent by mail to the HylaFAX mailing list hylafax-users@hylafax.org.

Confirmed bugs and discussion items regarding security or technical-level matters should either be sent by mail to the HylaFAX development mailing list hylafax-devel@hylafax.org or posted directly to HylaFAX Bugzilla, http://bugs.hylafax.org/bugzilla.

When corresponding about the software please always specify:

• What version of HylaFAX you have
• What compiler (including version) your are using
• What system you are running on: system type and OS version
• What kind of modem and the modem firmware revision
• A description on how to reproduce the problem
• A minimal trace log that shows your problem

For example: "HylaFAX v4.0pl2 under Solaris 2.3 with gcc 2.7.2; ZyXEL 1496E with 6.11a firmware."

Do not send large trace log or PostScript files to the mailing list; the list is quite large.

Do not send traces with binary i/o or timer tracing.

Do not send traces without time-stamps and do not remove lines in the trace.

Can I run HylaFAX on my NT/Windows Server?

Date: Tue, 10 Dec 1996 07:49:56 +0100 (MET) From: Matthias Apitz <guru@softcon.de > Subject: Re: HylaFax

>Mark Bradley wrote:

>Can I run HylaFax on my NT 4.0 Server? >S.Mark Bradley >Compucare Services

NO. (NT is not the answer, it's the question and the answer is NO :-))

matthias

Is HylaFAX able to receive/send 1000s of faxes/day?

Yes. When HylaFAX is described as "Enterprise Class" we mean it. The software itself is more than capable of handling the most demanding fax traffic requirements; 96 channels per server is routinely achieved. For high-density fax servers it is recommended to look at digital (TE/E1) fax boards.

Building From Source and Installation

Note: This is a c/p from http://www.hylafax.org/building.html, converted to Wikitext markup by http://www.katrinahelp.info/rdata/people/convertHtmlToWiki and with some minor edits which jumped out at me. Revise as you see fit... at least this section isn't blank anymore! 08:36, 8 March 2008 (EST)

BUILDING HYLAFAX FROM SOURCE CODE

This chapter contains the information needed to configure and build HylaFAX from the source distribution. The following sections are available here:

• Before You Start
• The Build Procedure
• Build Trees
• Configuration Files
• Configuring Packages
• Configuring the HTML Documentation
• Upgrading From FlexFAX
• A Sample Configuration Session
• Configuration Parameters
• Troubleshooting Build Problems

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 [#Guidance 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 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.

sed

Many of the shell scripts included in this software make use of sed. Certain systems are known to have versions of sed that do not handle the shell scripts. If you encounter problems, the latest GNU sed should be substituted.

/bin/test

The software configuration shell script (configure) and the modem configuration shell script (faxaddmodem) make heavy use of the test program. On some systems the /bin/test program does not support options such as -c (test if a file is a character special device). Source for a contemporary, public domain, test program is available by public FTP from ftp.uu.net.

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.

The Build Procedure

To build the software you need to first run the configure shell script that is located in the top level of the source directory. This script probes the target system for necessary tools and functions and constructs a build environment in which the software may be compiled. Once configuration is done, you simply run make to build the software and then make install to do the installation; for example:

• hyla% cd hylafax-v3.0beta099
• hyla% ./configure
  • ...lots of messages...
• hyla% make
  • ...lots of messages...
• hyla% su # NB: installation must be done by the super-user
• hyla# make install

In general, the software is designed such that the following should be ``make-able'' in each directory:

Note that after running "make clobber" or "make distclean" the configure script must be run again to create the Makefiles and other build-related files.

Build Trees

There are two schemes for configuring and building the software. If you intend to build the software for only one target system, you can configure the software so that it is built in the same directories as the source code.

hyla% cd hylafax-v4.0beta011 hyla% ls COPYRIGHT config dist faxrm sendfax Makefile.in config.guess distrules faxstat sendpage README config.h.in etc hfaxd sgi2fax README.ultrix config.site faxalter html util TODO config.sub faxcover man VERSION configure faxd port afm defs.in faxmail rules.in hyla% ./configure

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.

hyla% cd hylafax-v4.0beta011 hyla% mkdir obj obj/mycpu hyla% cd obj/mycpu hyla% ../../configure

This second scheme is useful for:

• building multiple targets from a single source tree
• building from a read-only source tree (e.g. if you receive the distribution on CD-ROM)

Beware that if you choose to use the second scheme for configuring the software you must not use an absolute pathname when you run configure (i.e. a pathname that begins with ``/) and the make that you use to build the software must correctly support the VPATH facility. 

Configuration Files

The configuration process is critical to the proper compilation, installation, and operation of the software. The configure script runs a series of tests to decide whether or not the target system supports required functionality and, if it does not, whether it can emulate or workaround the missing functions. This procedure is fairly complicated and, due to the nonstandard nature of most UNIX systems, prone to error. The first time that you configure the software for use you should check the output from the configure script and look for anything that does not make sense for your system. A sample configure run is shown below together with an explanation of the work that is done.

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.

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:

2. Parameters suitable for BSD/OS 1.1

DIR_AFM="/usr/contrib/lib/flexfax/afm" # reuse existing files DIR_BIN="/usr/contrib/bin" # directory for client apps DIR_SBIN="/usr/contrib/bin" # directory for system apps DIR_LIBEXEC="/usr/contrib/bin" # directory for libraries&hidden apps DIR_LIBDATA="/usr/contrib/lib/hylafax" # directory for client data DIR_MAN="/usr/contrib/man" # directory for manual pages DIR_SPOOL="/var/spool/hylafax" # directory for spooling area DIR_HTML="/usr/contrib/html/hylafax" # directory for HTML documentation DIR_CGI="/usr/contrib/html/cgi-bin" # directory for CGI scripts

The complete list of configuration parameters is given in the sample config.site file provided in the source distribution. Also, the sections below on ``[#Packages Configuring Packages] and ``[#Parameters 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.

Configuring Packages

HylaFAX uses the notion of a package to control which pieces of software are included in a build. Some packages are optional and are installed only as needed, or only if specifically requested at the time the configure script is run. Other packages may select one of several incompatible choices that must be made when the software is built. Packages can be specified in a config.site or config.local file, or by using a -with-package option when invoking configure; e.g. configure -with-AFM to request the AFM package. Most packages are automatically configured according to the characteristics of the system where HylaFAX is being built; this may not be appropriate when preparing binary distributions for multiple systems in which case they can be explicitly enabled or disabled.

Configuring the HTML Documentation

HylaFAX comes with extensive documentation written in HTML, the language used to author many documents found on the World Wide Web (WWW). These materials can be viewed at the main WWW site http://www.hylafax.org/, they can be installed on a local WWW server, or they can be viewed directly from the source area. Viewing the documentation through a WWW server is preferred because the materials include links to reference manual pages that are accessed through CGI scripts, and these links will not be available when the documentation is accessed directly from the source distribution.

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:

(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 @CGIPATH@ 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:

1. ! /bin/sh

ROOT=${1-/hylafax} CGI=${2-/cgi-bin} PATTERN="@[a-zA-Z][a-zA-Z]*@" patch() {

  chmod +w $1
  ed - $1<<EOF

g;@HTMLPATH@;s;;$ROOT;g g;@CGIPATH@;s;;$CGI;g w q EOF

   chmod -w $1

} FILES=`grep -l "$PATTERN" *.html */*.html` test "$FILES" && {

  for i in $FILES
  do
      echo $i; patch $i;
  done

}

There are a few other issues to consider when installing the CGI scripts:

• The manpage script that provides access to the UNIX manual pages may require some tailoring if manual pages are installed in non-standard locations or if the normal system man command does not support the expected options. If you have problems consult the script.
• If local support is to be provided, it may be worthwhile to alter the electronic mail addresses embedded in several of the CGI scripts.

Upgrading From FlexFAX

If you were previously using FlexFAX beware that several things have changed in incompatible ways. The following is a list of things you should be aware of when configuring the latest distribution:

• The default server operation parameters set in config.h have changed; for example the default kill time for a fax job is now 3 hours instead of 24 hours. Verify the parameters in config.h are what you want.
• Numerous pathnames may have changed. The source-based installation procedure does not remove previously installed files unless they are to be overwritten; this can result in multiple versions of applications such as faxaddmodem being installed. Verify the parameters used for installation; you may want to tailor them to your environment by creating a config.local file with local configuration parameters.
• HylaFAX includes an improved install.sh script that is used to install files on non-IRIX systems. Certain files in the distribution are treated as configuration-specific files and are not overwritten if they appear to have local modifications. Instead the install.sh script will install the new file with a .N suffix and print a warning message. Be sure to reconcile these conflicts by comparing the old and new file contents with a program like diff(1); in most cases you should incorporate any local modifications into the new file and install it for use.

There are other issues with upgrading from FlexFAX; they are discussed in the chapter that describes [setup.html 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.

   ...stuff deleted...

Configuration Parameters

This section gives a brief description of the less obvious configuration parameters. Consult the distributed config.site for a complete list of parameters. The list here is sorted alphabetically.

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.

where: <organization> is either bsd for BSD-style section organization (e.g. file formats in section 5) or sysv for System V-style organization (e.g. file formats in section 4). <formatting> is either nroff to force installation of formatted materials (using nroff) or source to get the nroff source installed. <compression> is either the name of a program to compress the manual pages (gzip, compress, pack) or cat for uncompressed data. <suffix> is either the file suffix to convert installed pages to (e.g. 0.gz for gzip-compressed pages under BSD) or strip to force the normal ".4f" suffix to be converted to ".4" (or ".5" if using the BSD organization). If no -<suffix> is specified then filenames are not converted when they are installed.

Troubleshooting Build Problems

Most compilation problems are because the configure script did not properly setup the software for building. If you have problems compiling the software on a supported system check the output from configure and the contents of the port.h file generated by configure to make sure it makes sense. Another byproduct of the configuration procedure is the config.log file that is found at the top of the build tree. This file contains information about the tests done by the configure script; it should also be studied to check for problems.

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.

System-specific Guidance

This section contains some build-related issues that are dependent on the operating system installed on the build machine. The information included here is by no means exhaustive; it reflects feedback from users accumulated over multiple HylaFAX versions and/or operating system releases.

AIX Guidance

To use the IBM xlC C++ compiler you must have a version that supports the -+ option so that filenames with a .c++ extension are processed properly by the compiler.

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.

DIR_BIN="/usr/contrib/bin" # client apps DIR_MAN="/usr/contrib/man" # manual pages DIR_AFM="/usr/contrib/lib/hylafax/afm" # AFM files DIR_LIBDATA="/usr/contrib/lib/hylafax" # client data DIR_LIBEXEC="/usr/contrib/lib/hylafax" # libs&hidden apps DIR_SBIN="/usr/contrib/bin" # system apps DIR_SPOOL="/var/spool/hylafax" # spooling area PATH_GSRIP="/usr/contrib/bin/gs" # Ghostscript RIP

Note that you will also need to specify the location of the TIFF software because the version distributed with BSD/OS 2.1 is too old to use.

Dell SVR4 Guidance

On some releases <sys/mkdev.h> includes static functions with non-ANSI C definitions; these must be manually corrected before building the software. (The GNU gcc installation procedure attempts to correct this file but does not.)

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).

Under Caldera OpenLinux 1.3 (and probably previous 1.x versions) the configure script fails when testing for TIFF support. To work around the problem use --with-LIBTIFF="-ltiff -ljpeg -lz".

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

These notes pertain to SCO 3.2 v4.2; they may also be relevant to other versions.

With gcc 2.7.2.1 one gcc include file needs to be patched to include missing function prototypes:

• • • /usr/local/lib/gcc-lib/i486-unknown-sco3.2v4.2/2.7.2.1/include/sys/signal.h Thu Sep 5 18:26:45 1996

--- /usr/local/lib/gcc-lib/i486-unknown-sco3.2v4.2/2.7.2.1/include/sys/signal.h.old Thu Sep 5 18:28:56 1996

• • • 214,221 ****

 #else
 	int kill(short, int);
 #endif

! int (*ssignal(int, int(*)(int)))(int); ! void (*sigset(int, SIG_TYP))(int);

 	int sigpause(int);	/* These 4 are SVID functions as well */
 	int sighold(int);

--- 214,221 ----

 #else
 	int kill(short, int);
 #endif

! int (*ssignal(int, int(*)(int)))(); ! void (*sigset(int, SIG_TYP))();

 	int sigpause(int);	/* These 4 are SVID functions as well */
 	int sighold(int);

When running configure disable the use of ranlib by specifying -with-RANLIB=true on the command line or in a config.local file.

Some of SCO's system include files have incorrect function prototypes that cause compilation to fail; other include files are not properly setup to deal with their being included multiple times. The following diffs may be applied to the problematic system include files or one may create patched copies of these files in a private sys directory under the top level of the HylaFAX build tree.

• • • /usr/include/sys/stat.h Wed Mar 9 00:00:00 1994

--- sys/stat.h Thu Sep 5 18:45:25 1996

• • • 147,153 ****

 extern int  lstat(const char *, struct stat *);
 extern int  fstat(int, struct stat *);
 extern int  mkdir(const char *, mode_t);

! extern int mkfifo(char *, mode_t);

 extern mode_t  umask(mode_t);
 #ifdef __cplusplus
 };

--- 147,153 ----

 extern int  lstat(const char *, struct stat *);
 extern int  fstat(int, struct stat *);
 extern int  mkdir(const char *, mode_t);

! extern int mkfifo(const char *, mode_t);

 extern mode_t  umask(mode_t);
 #ifdef __cplusplus
 };

• • • /usr/include/sys/time.h Fri Mar 27 05:05:45 1992

--- sys/time.h Thu Sep 5 19:42:08 1996

• • • 32,41 ****

--- 32,44 ----

 #ifndef __sys_time_h__
 #define __sys_time_h__

+ #ifndef _STRUCT_TIMEVAL_ + #define _STRUCT_TIMEVAL_

 struct timeval {
 	long            tv_sec;	/* seconds */
 	long            tv_usec;/* and microseconds */
 };

+ #endif /* _STRUCT_TIMEVAL_ */

 struct timezone {
 	int             tz_minuteswest;	/* minutes west of Greenwich */

• • • /usr/include/sys/select.h Wed Mar 9 00:00:00 1994

--- sys/select.h Thu Sep 5 19:41:13 1996

• • • 38,47 ****

--- 38,50 ----

 /*
  * Structure used to specify timeout in select(2) system call.
  */

+ #ifndef _STRUCT_TIMEVAL_ + #define _STRUCT_TIMEVAL_

 struct timeval {
 	long	tv_sec;		/* seconds */
 	long	tv_usec;	/* and microseconds */
 };

+ #endif /* _STRUCT_TIMEVAL_ */

 #ifndef _INKERNEL
 #ifdef _NO_PROTOTYPE

These notes pertain to SCO 3.2 v5.0

One of SCO's system include files has incorrect function prototypes that cause compilation to fail; The following diff may be applied to the problematic system include file or one may create a patched copy of the file in a private sys directory under the top level of the HylaFAX build tree.

• • • /usr/include/sys/syslog.h Thu Dec 26 04:42:27 1996

--- sys/syslog.h Fri Dec 27 17:05:11 1996

• • • 198,204 ****

 void closelog __P((void));
 void openlog __P((const char *, int, int));
 int setlogmask __P((int));

! int vsyslog __P((int, char *, va_list ));

 __END_DECLS

 #endif /* !INKERNEL */

--- 198,204 ----

 void closelog __P((void));
 void openlog __P((const char *, int, int));
 int setlogmask __P((int));

! int vsyslog __P((int, const char *, va_list ));

 __END_DECLS

 #endif /* !INKERNEL */

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):

123,125d122 < #if !defined(_POSIX_SOURCE) < #define tcsetattr(fildes,action,termios_p) \ < ioctl(fildes,action,termios_p) 127,133d123 < #define tcgetattr(fildes,termios_p) \ < ioctl(fildes,TCGETP,termios_p) < #else < extern int tcsetattr(); < extern int tcgetattr(); < #endif

< 147,152d136 < #if !defined(_POSIX_SOURCE) < #define tcdrain(fildes) \ < ioctl(fildes,TCSBRK,-1) < #else < extern int tcdrain(); < #endif 161,166d144 < #if !defined(_POSIX_SOURCE) < #define tcflush(fildes,queue) \ < ioctl(fildes,TCFLSH,queue) < #else < extern int tcflush(); < #endif 176,181d153 < #if !defined(_POSIX_SOURCE) < #define tcflow(fildes,action) \ < ioctl(fildes,TCXONC,action) < #else

< extern int tcflow(); < #endif 183,189d154 < /* < * Get input and output baud rates. < */ < #if !defined(_POSIX_SOURCE) && !defined(_XOPEN_SOURCE) < #define OBAUD (CBAUD << 16) < #define cfgetospeed(termios_p) \ < (((termios_p)->c_cflag & OBAUD) >> 16) 191,198c156,160 < #define cfgetispeed(termios_p) \ < ((termios_p)->c_cflag & CBAUD)

< #else < extern speed_t cfgetospeed(); < extern speed_t cfgetispeed(); < extern int cfsetispeed(); < extern int cfsetospeed(); < #endif --- > extern int tcsetattr(int, int, const struct termios*); > extern int tcgetattr(int, struct termios*); > extern int tcdrain(int); > extern int tcflush(int, int); > extern int tcflow(int, int); 199a162 > extern int tcsendbreak _PARAMS((int, int));

/usr/include/sys/socket.h needs to be protected against multiple inclusion:

2a3,4 > #ifndef _SOCKET_ > #define _SOCKET_ 237a240 > #endif /* _SOCKET_ */

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 configure

There 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).

UnixWare Guidance

One system include file needs to be patched to correct function prototypes:

*** /usr/include/netdb.h	Mon Dec 11 05:25:35 1995
--- netdb.h	Wed Oct 30 14:05:35 1996
***************
*** 90,105 ****

  #ifdef __STDC__

! extern struct hostent	*gethostbyname(char *);
  extern struct hostent	*gethostbyaddr(char *, int, int);
  extern struct hostent	*gethostent(void);
  extern struct netent	*getnetbyname(char *);
  extern struct netent	*getnetbyaddr(long, int);
  extern struct netent	*getnetent(void);
! extern struct servent	*getservbyname(char *, char *);
  extern struct servent	*getservbyport(int, char *);
  extern struct servent	*getservent(void);
! extern struct protoent	*getprotobyname(char *);
  extern struct protoent	*getprotobynumber(int);
  extern struct protoent	*getprotoent(void);
  extern int		endhostent(void);
--- 90,105 ----

  #ifdef __STDC__

! extern struct hostent	*gethostbyname(const char *);
  extern struct hostent	*gethostbyaddr(char *, int, int);
  extern struct hostent	*gethostent(void);
  extern struct netent	*getnetbyname(char *);
  extern struct netent	*getnetbyaddr(long, int);
  extern struct netent	*getnetent(void);
! extern struct servent	*getservbyname(const char *, const char *);
  extern struct servent	*getservbyport(int, char *);
  extern struct servent	*getservent(void);
! extern struct protoent	*getprotobyname(const char *);
  extern struct protoent	*getprotobynumber(int);
  extern struct protoent	*getprotoent(void);
  extern int		endhostent(void);

On some versions the configuration parameter CONFIG_SOCKARGLENTYPE needs to be set to size_t to force the argument type for call-by-reference parameters to the socket-related system calls; this should automatically be done by configure.

webmaster@hylafax.org. Last updated $Date: 2002/05/02 22:02:56 $.

Which Linux distributions contain HylaFAX?

Please see (and contribute to) the Distribution List.

Sending Faxes

How do I print a watermark on my faxes?

Thorsten Garrels wrote:

> I'd like to have a kind of "static" graphic in the background of every
> page hylafax sends. This could be a company-logo, for instance but as
> well a complete "letter-template". Insteed of printing the text via a
> printer on this template you should be able to "print" your text
> directly on a virtual paper which already contain the company logo and
> locations.

Date: 13 March 2000 18:46
From: Frank Terhaar-Yonkers <fty@cisco.com>
Subject: Re: flexfax: background graphic for every sent page

What you want is a "watermark." This little postscript snippet prints CONFIDENTIAL diagonally across the page:

/wp$y 792 def
/wp$x 612 def
%-------Customize Here-------
/font /Helvetica-Bold def
/pointsize 96 def
/text1 (CONFIDENTIAL) def
%-------End Customization----
/center {dup stringwidth pop
2 div neg 0 rmoveto} def
wp$x 2 div wp$y 2 div pointsize 2 div sub moveto
.85 setgray
font findfont pointsize scalefont setfont
45 rotate
0 0 text1 center ashow
%

Merge something like this (a exercise left to someone else) with the postscript sent to Hylafax.

- Frank

How do I keep private information off the cover page?

To keep private information off of the fax cover sheet and out of the publicly displayed information (such as the queue listings shown by faxstat) you need to create a dialrules file that's used on systems where HylaFAX client applications are run.

For example, if calling card information is specified as a trailing comma-prefixed number string (perhaps with trailing whitespace) then the following rules would strip it off when creating an displayable representation of the dial string:

DisplayNumber = [
 ",[0-9]+[ 	]*" = ! strip calling card info and trailing ws
]

You can use the dialtest program to test the new rules.

If you don't use sendfax to submit your faxes, you will have to look in your submitting software manual for how to set this.

Note that on the server the session logs must be protected to insure the complete dialstrings are not readable by normal users. This is done using the LogFileMode configuration parameter; e.g. LogFileMode: 600 # protect logs with calling card info

Why are my faxes failing with "Kill time expired"?

The default kill time of a job is 3 hours. If HylaFAX can't send a fax before that deadline, it is rejected. There are two major reasons for this to happend:

• No faxes are being sent at all. This is generally because faxgetty is not running and you didn't use faxmodem so HylaFAX has no modem available to send the job. The solution is to start faxgetty.

• You sent a big batch of faxes and some were rejected with this reason. You need to set a bigger killtime for the job if you want to send big batches of faxes. With sendfax, it can be set on the command line with -k as in sendfax -k "now + 7 days" or in hyla.conf (or sendfax.conf) with KillTime: "now + 7 days".

This setting in hyla.conf only applies to the clients that come with HylaFAX (faxmail, sendfax). Overwrite Client-settings with Per-job Controls (JobControl).

Why are my faxes failing with "Blacklisted" errors?

Some countries have legislations requiring modem manufacturers to ensure modems can't dial a failed number too often in a short period of time. Even busy numbers may count toward the blacklist in some countries.

Some modem have commands to either disable blacklisting or to clear the blacklist table. You can try one of the following dialing commands in your device config file:

ModemDialCmd: AT%%TCBDT%s [for Rockwell/Conexant modems]
ModemDialCmd: AT%%T21,1d,0DT%s [for Lucent/Agere modems]
ModemDialCmd: AT%%D0DT%s [for TOPIC chipset modems]

If none of those are applicable, you can configure your modem with a different country setting, one that doesn't blacklist numbers. If the dial tone in use in your country differ from the one your modem is configured to use, it may be unable to detect dialtone. Changing the dialing command to add X3 should bypass this problem:

ModemDialCmd: ATX3DT%s

Some modem can have their blacklist cleared with an AT command, while others require the modem to be power cycled.

Receiving faxes

receive faxes

You can find a list of fax viewers at Fax Viewer Software.

Another possibility is to convert the received fax to PostScript or PDF and use a PostScript/PDF viewer.

I have trouble viewing faxes received in JBIG format

Newer versions of HylaFAX can receive faxes in JBIG format, yet tiff utilities may not be able to do anything with such faxes (libtiff needs to be patched to support JBIG faxes). No tiff viewer are known to be able to read such files either.

You can disable JBIG support by setting "Class1JBIGSupport: no" in your modem config file until you have utilities to work with JBIG tiff files.

See http://bugs.hylafax.org/bugzilla/show_bug.cgi?id=730 for more information on this.

Running a HylaFAX Server

"Service not available, remote server closed connection?"

> After running
> faxmodem to setup my modem, I run faxstat to make sure that it's up, and
> receive the following msg:
>
> Service not available, remote server closed connection
>
> Telneting in to the machine on port 4559 gets a "Connection closed by
> foreign host." message.

Looks like hfaxd(1) isn't running on your machine. You have to make sure that hfaxd(1) and faxq(1) is running before you get any decent response with faxstat(1).

Do I have to restart a server after changing the modem config file?

No. The HylaFAX servers will re-read a config file (if needed) before each send and on any reset. This means you only need to explicitly restart a server if you change it before doing a receive. You can also avoid restarting it if you use cu/tip to talk to the modem since this will cause the server to wakeup and then reset itself when you exit from cu/tip.

How do I suppress or amend the "Fax Usage Report" which is emailed to FaxMaster daily?

Chances are you've installed a HylaFAX package, such as an RPM, that has set this report up as a cron job. On Red Hat, look at /etc/cron.daily/hylafax, and comment out the faxcron line. Each package/distro will be different, but the genral process is the same - find the cron job and deactivate (or customize) the running of it.

What hardware is supported by HylaFax?

That's hard to answer. Most Class 1, 1.0, 2, 2.0, and 2.1 fax devices will work with HylaFAX with varying levels of success. You can get a relatively good idea of the best hardware to use with HylaFAX via the Hardware Compatibility List or at http://shop.ifax.com.

Troubleshooting

Is support available for HylaFAX?

There are many support options, both free and commercially provided. Please see the Support page for more information.

Why are all my received TIFFs corrupted?

If you're not able to open received TIFF files and when you try to convert them to ps using tiff2ps or fax2ps, you get errors like:

Fax3Decode2D: fax00013.tif: Bad code word at scanline 0 (x 89).
Fax3Decode2D: fax00013.tif: Uncompressed data (not supported) at scanline 0 (x 0).
Fax3Decode2D: Warning, fax00013.tif: Premature EOL at scanline 0 (got 89, expected 1728).

Check the verison of libtiff you're running. If it's 3.6.0 or 3.6.1, this may be your problem.

Solution: Downgrade libtiff to 3.5.7.

Why do faxes sometimes go to the wrong number?

One possibility is that you have another device on the same line that tried to call that wrong number just before HylaFAX tried to send it's fax. When HylaFAX dialed it's number, the call was already dispatched to the wrong number and the tone sent by HylaFAX's modem did nothing (they may make the other device to hang up). Then when the party called by the other device answered, the call was established with HylaFAX and you get a fax sent to the wrong number.

There exist line sharing devices that you can use so that this won't happen. The device gives a busy signal when the line is already in use by another device.

How to fix HDLC errors with t38modem?

Not all versions of t38modem use the default Class1FrameOverhead of 4 (which is normal for a modem correctly implementing the Class 1 interface). Try adding the following line in your device config file:

Class1FrameOverhead:   2

If you already have this line, try commenting it.

Why aren't emails being sent when using faxrcvd on the command line works?

Your rights setting for sendmail is probably incorrect. This means that your group rights doesn't change to smmsp and you therefore don't have rights to /var/spool/clientmqueue. Check the sticky bit for the group used by the sendmail program.

/usr/sbin/sendmail may point to /etc/alternatives/mta which probably points to /usr/sbin/sendmail.sendmail

ls -l /usr/sbin/sendmail.sendmail should list

-rwxr-sr-x ? root smmsp ???? ?? ???? /usr/sbin/sendmail.sendmail

If the s bit is not set or group is not smmsp then use following commands.

chgrp smmsp /usr/sbin/sendmail.sendmail

chmod g+s /usr/sbin/sendmail.sendmail

Notification messages with other languages (I18N)

To change the language in the e-mail notification messages from the server you can do the following (since version 4.3.0).

Edit the files

/var/spool/fax/bin/FaxDispatch 
/var/spool/fax/bin/faxrcvd 
/var/spool/fax/bin/notify

write the line:

TEMPLATE=de

(as example for german language). That replace the path-var $TEMPLATE in the scripts.

The file ./FaxDispatch you can read in the faxrcvd man page.

In the /var/spool/fax/etc/templates directory resides the language specific subdirs. Here you can change whatever you want. Note: make a backup before change!

Sendpage - SMS & Pager Gateway

The log shows that the SMS is sent correctly, but it never gets delivered to the adressed cell phone

Check for trailing spaces in the pagermap file

When calling the SMS Call Center (D1, D2, E-plus) I get an 'No initial ID response paging central'

Check the file for the Call Centers Number in hylafax info dir, there should be an option &pagerTTYParity:"none" in there if there isnt add it and try again

When calling D2 i get an 'No initial ID response from paging central' but I have added &pagerTTyParity:"none" to the file in info

Check if you have added &pagingProtocol:"ucp" to the info file

The call center is rejecting my messages Blocks

Check if you are really sending plain ASCII files, this happened to me when working with templates generated on an windows box and it turned out the templates werent plain ASCII

Does HylaFAX support the UCP protocol for SMS?

Yes. See hylafax(1):

Support is provided for transmitting alpha-numeric mes-
sages to pager devices or GSM mobiles using the  Simple
Network  Paging Protocol (SNPP) and the IXO or UCP pro-
tocol (for message delivery).

Is there an application to redirect emails to pages?

Date: Tue, 1 Oct 1996 15:01:55 -0600 (MDT)
From: Jason Kohles <robobob@xmission.com>
Subject: Re: Sendpage and Mail

On Tue, 1 Oct 1996, Ravi Pina wrote:

> Is there a mail2page application that exists where there is an alais
> setup to redirect mail messges to pages?

I use filter (the mail filtering software that comes with elm) with a filter like this:

### email pager - bitchin
if [ SUBJECT CONTAINS "URGENT" ] then executec "/usr/local/bin/sendpage 
-p XXXXXXX MP:%s"

this sends "MP: the subject line" to my alpha pager.

Jason Kohles -- System Administrator -- XMission Internet Access
robobob@xmission.com (at work) robobob@mindwell.com (at play)

Email to Fax

How do I setup HylaFAX as an email-to-fax gateway?

(An Email to Fax Gateway allows a user to send an email to a predefined email account which then processes and faxes out the document through a fax modem.)

See the HylaFAX Handbook's section on Email-To-Fax.

Which document types can I fax using HylaFAX's email-to-fax capability?

By default faxmail, HylaFAX's email-to-fax gateway application, supports plain text and Postscript attachments. Faxmail also includes the ability to use external processors for other document types. Please see the faxmail man page for more information.

Fax to Email

How do I setup HylaFAX as an fax-to-email gateway?

For a simple example see the faxrcvd man page.

Miscellaneous Stuff

Is there a way to integrate Asterisk and HylaFAX?

Your best option presently is to use Lee Howard's IAXmodem with Steve Underwood's spandsp library. For more information, see:

http://voip-info.org/tiki-index.php?page=Asterisk%20fax

How can I fax Microsoft Office files?

One way to easily fax Windows files is by using a HylaFAX Windows client. Please see the Client Software page for a complete list of free and commercial clients.