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>
HylaFAX table of contents