Handbook:Server Operation:Tweaking and Customization

Open-source software is all about customization. So don't be surprised when most HylaFAX users consider customization a part of installation. In many cases some customization of the config files and the default coverpage will be necessary for desired HylaFAX functionality.

Modem Config Files

In the future, HylaFAX may be capable of "auto-configuring" most faxmodems. But currently, unless you're fortunate enough to be using a faxmodem that has been used by a HylaFAX developer or can find a functional config file from another HylaFAX user, then you will need to work on a config file for each of your faxmodems that you intend to use with HylaFAX. This can be done step-by-step during the faxaddmodem script, or as I prefer, a config file can be created prior to running faxaddmodem.

The config file contains all of the unique settings for a faxmodem. There are "default" settings built-into HylaFAX, but chances are good that all of these "defaults" are not appropriate or optimal for your particular faxmodem's make, model, or firmware revision. There are many possible differences between one faxmodem and another, and in order to properly create a config file you will need your faxmodem's AT and AT+F command set. These should be in the manual that [hopefully] came with your faxmodem.

Begin by using one of the following three "template" config files. If you do not know what class your faxmodem uses, then you can usually send it the 'AT+FCLASS=?' command, and the faxmodem will report the possible classes to use. You may see something like '0,1', '0,1,1.0,2.0', or '0,1,2,80'. Class 0 is for data communication; Class 1, 1.0, 2, and 2.0 are fax protocols; and Class 80 is for voice communication. HylaFAX can utilize all of these classes, however, this document will only discuss faxing.

For Class 1 faxmodems, begin by using this file.
For Class 2 faxmodems, begin by using this file.
For Class 2.0 faxmodems, begin by using this file.

Start editing your config file by changing the '# $Id:' line. At a minimum, change the $Id name to something that identifies your config file and that is unique from all other config files usually found in the /var/spool/hylafax/config directory. The $Id name should also be the filename used for this config file. So, perhaps this line will appear as:
'# $Id: tweaking.html,v 1.28 2004/07/14 18:59:07 lhoward Exp $'

Next, change the '# CONFIG:' line to match your make, model, and intended flow control.
For Class 1, change ATI0 to match the result of 'ATI0' and ATI3 to match the result of 'ATI3'. Replace the two 'name's with anything to describe your modem.
For Class 2, change Manufacturer to match the result of 'AT+FMFR?' and Model to match the result of 'AT+FMDL?'.
For Class2.0, change Manufacturer to match the result of 'AT+FMI?' and Model to match the result of 'AT+FMM?'.
Replace flowcontrol with your desired flow control method, 'NONE', 'XONXOFF' (software), or 'RTSCTS' (hardware). Now, proceed through the Modem* and Class* commands and replace the default value with the appropriate value for your modem. If your desired values match the default values then that particular line may be removed (except for the *FillOrder and Class2AP* lines). More description of each value is given in the hylafax-config(5F) man page. When you have arrived at the bottom of the list, then save this config to a file named as your $Id name, and place it in the config directory (usually /var/spool/hylafax/config). Kill faxgetty if it is running. Now (re)run faxaddmodem. It should detect your modem appropriately by presenting you the config list rather than asking you for each setting. You now have a customized config file.

For more information please consult hylafax-config(5F) and faxaddmodem(8C).

Cover Page Customization

There are a few ways to customize a coverpage:

• make_faxcover is a simple sed script to munge an encapsulated postscript file, as created by tgif into the form required for a cover page for use with HylaFAX. Also included is a sample page as an example, before being run through the make_faxcover script. Read the README file for more information. Thanks to Thomas Erskine. Download and extract it from: ftp://ftp.sgi.com/sgi/fax/contrib/covers/make_faxcover.tar.Z. Note that because of changes in 4.1beta2 to the CommentX-commentsX faxcover variable, make_faxcover will not create comments sections appropriately. See Bug 81 for details.
• latex-cover from Rainer Krienke. latex-cover.sty offers a way to create custom coverpage templates for use with the faxcover application from the hylafax distribution. Download it at ftp://ftp.sgi.com/sgi/fax/contrib/covers/latex-cover-1.04.tar.gz. Read the README file for more information.
• You can manually follow the procedure used by make_faxcover with good success. First, you need to generate a simple Postscript or EPS document. In *NIXes you can use tgif. In Windows you can generate a simple Postscript document from any text editor such as Microsoft Word by configuring a new printer on the system using the Apple Laserwriter driver printing to a file. Make sure that in the driver properties under the "Postscript" options the EPS option is used. Create your document first, but using easily-found markers (such as "XXXX-to") to identify your intended dynamic (variable) fields. Then, print your document to a file using the newly installed printer driver. Using an ASCII text editor, edit the created Postscript file, changing marked sections into Postscript variables, usually by removing the marker and the accompanying parenthesis. For example, changing "(XXXX-from) SH" into "from SH". See faxcover(1) for an exact list of available faxcover variables. A sample BreakIntoLines routine can be seen at: http://www.hylafax.org/archive/2000-12/msg00090.html. For 4.1beta2 users, please review Bug 81.

For more information, refer to faxcover(1) and http://www.hylafax.org/HylaFAQ/Q202.html.

Reports Customization

faxcron is a command script that does routine upkeep tasks in a HylaFAX spooling directory hierarchy. This script is intended to be invoked from cron(8C) on behalf of the fax user once a day, with the standard output sent by mail to the HylaFAX administrator. In conjunction with recvstats, xferfaxstats, info, and other HylaFAX utilities, the fax administrator can receive informative daily fax reports.

See faxcron(8C), recvstats(8C), xferfaxstats(8C), and hylafax-info(5F) for details.

Mass Faxing, 1000+ daily

• For logging and error statistics, try Robert Colquhoun's errorstats script. See http://www.hylafax.org/HylaFAQ/Q344.html
• If you're using an old HylaFAX version, be aware of an applicable patch: http://www.hylafax.org/patches/posix-rename.patch.
• Matthias Reich rei@hagos.de is one of the mass-fax guys running HylaFAX on 10 servers with an output of up to 10,000 per day. He is running ten Suns with Solaris 2.4 and HylaFAX 4.0pl2 and one Linux box with HylaFAX 4.1beta2. He uses Multitech MT1432 BG, Multitech ZDX56 and some Elsa TQV33.6 Modems. He does error handling as follows:
  • The user gets a mail for each failed fax. It is the user's responsiblity to check that the number is right (BTW, the most common error is users sending faxes to wrong numbers).
  • The mail the user gets is "custom made". He changed the notify.awk script to give the user less detailed information e.g.: just the line was busy, no answer, or comm-failure.
  • A script scans the logs and filters out the comm-errors (t.30 and so on).
  • After getting this report he starts to investigate what is wrong. This begins with setting up the debuglevel for the dest-number, resending the fax, and having a close look in the log.
  • After hopefully recognizing the error, he changes some settings for the destination in the info-directory to make the faxes work. Mostly setting down the speed or changing the min-scanline-time brings success. In more severe cases he has had success with attaching those destinations to be only used with his Elsa modems. After two or three weeks, the work decreases dramatically, and now his error rate is below 1 percent.

• And if anyone feels up to a challenge, Bernd Proissl has a good developer's suggestion, http://www.hylafax.org/archive/2000-08/msg00464.html.

Caution: Unless you use the sendfax '-w' option in a loop to queue your outbound faxes, all of the faxes enter the fax queue at the same time, almost. A fax job can be in the queue idle for long periods of time and reach its "KillTime", waiting for other fax jobs to complete, without ever being attempted once. Therefore, if you queue enough faxes such that the last fax will not complete before the configured KillTime (default is three hours), some faxes will be removed from the send queue before ever being attempted, specifically all of the faxes that have not completed by the configured KillTime.

To compensate for this, it is advisable that you use the sendfax '-k' option, or that you modify KillTime in your ~/.hylarc, sendfax.conf, or hyla.conf files so that all of your faxes have time to complete. See sendfax(1) for details.

Multiple-Modem Configuration

Re-run faxaddmodem for each faxmodem in the system. By default, HylaFAX will route outgoing faxes through any available modem. Incoming faxes are not differentiated by HylaFAX by default. However, faxrcvd does receive the device name of the modem which received the incoming fax, and so some form of routing could conceivably be developed by means of a custom faxrcvd script. See http://www.hylafax.org/archive/2001-02/msg00026.html for an example.

Modems may be "grouped" so that any particular job by be performed by any modem in a particular ModemGroup. For specific information, see ModemGroup in hylafax-config(5F).

If you want a group of send-only modems and a group of receive-only modems, instead of using ModemGroup, consider setting RingsBeforeAnswer: 0 for the send-only modems and ModemReadyState: D for the receive-only modems.

Send-Only Environments

There are a couple of common ways to establish a send-only environment.

• The best way is to use faxgetty, but to set "RingsBeforeAnswer: 0" in the modem config file. This method will provide the user with more accurate faxstat information, and is the preferred method for establishing send-only environments when possible.
• Another way is to not use faxgetty at all, but rather use faxmodem instead. This should only really be used in cases where faxgetty is inappropriate (i.e. faxgetty conflicts with something or causes device conflicts).
  faxmodem sends a message to the HylaFAX queuer process faxq telling it that the specified modem is ready for use and informing it about its fax-related capabilities. Once a modem has been configured its status can be reconfigured using the faxstate program. faxmodem can also be used to alter the capabilities and usage priority of a previously configured modem.
  
  See faxmodem(8C) and faxstate(8C) for more information.
  
  

Thanks to Andreas Hoedle and Jay Ashworth for their input on this.

Facsimile Archiving

faxqclean is a program that processes completed HylaFAX jobs and expunges unreferenced document files. This program is intended to be invoked by cron(8C) on behalf of the super user (i.e. root) one or more times a day.

See faxqclean(8C) for more information.

Automatic Fax Printing

To automatically print incoming faxes to lpr, insert a line of code similar to

/usr/bin/tiff2ps -a $FILE | lpr

into your faxrcvd script, assuming that your printer is PostScript compatible.

Dieter Kluenter has added at line 112 of faxrcvd these lines for his printing:

if [ -n "$SENDTO" ]; then
	echo ""
    
  	echo "The facsimile was automatically dispatched to: $SENDTO."
    else
	$TIFFBIN/fax2ps $1 | lpr -Plp	 
     fi

Michael mwu@mail2.tercel.com.tw states:

Our printing environment is specific, a shared HP LJ1100 (A4 only).
To be able to print out various types of paper sizes, we use the
following code for printing (0.95 * A4 size):
    /usr/bin/tiff2ps -a -h 11.1082 -w 7.8543 $FILE | /usr/bin/lpr
If we use fax2ps, it would be complicated to handle the printouts of
different paper sizes.

Resetting the Job, CommID, and Other Queue Numbers

Empty the contents of these directories:

/var/spool/hylafax/doneq
/var/spool/hylafax/recvq
/var/spool/hylafax/log
/var/spool/hylafax/sendq
/var/spool/hylafax/docq
/var/spool/hylafax/pollq

Where /var/spool/hylafax is your $SPOOL directory.

• to reset the request id

/etc/init.d/hylafax stop
vi /var/spool/hylafax/sendq/seqf
/etc/init.d/hylafax start

Automatic Routing of Received Fax Notification

Create a shell script etc/FaxDispatch (usually /var/spool/hylafax/etc/FaxDispatch) which sets SENDTO to a valid e-mail address. By using FaxDispatch, the HylaFAX administrator can route received fax notifications and, if desired, the fax image directly to the intended recipient.

The following shell variables are available for use in FaxDispatch:

       CIDNUMBER       the CIDNumber value determined from faxgetty
       CIDNAME         the CIDName value determined from faxgetty
       DEVICE          the device name (i.e. ttyS1) of the receiving modem
       FILE            the filename (including path) of the tif fax image
       FILENAME        the filename (excluding path) of the tif fax image
       SENDER          the TSID of the fax sender
       FILETYPE        the type of file attachment to use (ps, tif, pdf)
       MIMENCODE       the program for UU-encoding binary mail attachments
       SENDTO          the destination e-mail address of the notification

These are all generally considered read-only values except for MIMENCODE (which defaults to mimencode), FILETYPE (defaults to ps), and SENDTO (no default). A good example is given in 'man faxrcvd', however, a simple usage would be:

       SENDTO=FaxMaster;
       FILETYPE=tif;

Return Delivery of Faxed Documents

Some users wish to have copies of the faxed documents returned to them via e-mail. In HylaFAX versions 4.2.0 and later this is natively configurable. To do this, create the file etc/FaxNotify in the HylaFAX spool directory containing these line:

       RETURNFILETYPE=pdf;

This will make any sent-job notifications (which occur based on the notification setting specified by the submission client) contain attachment with a copies of the faxed documents. See 'man notify' for more specific information.