TROUBLESHOOTING
This section contains tips for dealing with the most common problems encountered when setting up and running the software. The following subsections cover specific areas: You can also consult the HylaFAQ for answers to common questions.


TROUBLESHOOTING: CLIENT BASICS

There are several components to the complete HylaFAX software package:

If you are having trouble first try to identify which component is failing. 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 faxd.recv process on the server machine. faxd.recv has a -d option that enables tracing of the protocol it receives and its general operation. If you are in doubt about where a problem lies, try the following:

Run faxstat to request server status. You should see something like:

or possibly, If you do not see something like this, then you are having problems communicating with the faxd.recv program on the server machine or there is a configuration problem on the server machine. If you cannot establish a connection to the faxd.recv process on the server machine, then verify that you have your FAXSERVER environment variable setup correctly (if the server is not on the machine where the faxstat program is run) and/or that both client and server programs are communicating on the same TCP port. On the server machine make sure that the faxd.recv program is properly configured to be invoked by the inetd program; check the contents of /etc/inetd.conf, or similar, for a line of the form: Be certain that inetd has ``reread'' its configuration file; either send it a SIGHUP or restart it. This work should automatically be done when the faxaddmodem 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 faxd.recv program--check for this entry in the /etc/services file and/or the YP/NIS database.

As a last resort, you can always use an existing network service such as telnet to communicate with the faxd.recv process;

[Ed: Ignore the protocol botch, this is just to show you that you can reach faxd.recv using telnet.]

If the network-related configuration is setup properly but faxstat still does not return one of the above lines; use the -v option to trace the client-server protocol:

A protocol and/or configuration problem should be evident from the trace information. You can also configure faxd.recv to log its operation through syslog by supply a -d option in the inetd.conf file: 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 faxd.recv logs its debugging information through syslog (using the syslog facility setup when the configure script was run to configure the HylaFAX software).


TROUBLESHOOTING: CLIENT ACCESS CONTROL PROBLEMS

Given a working client-server setup, problems that you encounter are either server-related or related to misconfigured permissions on the server machine. The faxd.recv program will process any client requests that do not create a new outbound job, alter an existing job's parameters, or remove a job from the queue. To do one of these privileged operations, a client must have access according to the etc/hosts file located in the spooling are on the server machine. Consult the manual page hosts(4F) for details on this file. Otherwise the only thing to beware of is that faxd.recv is started by inetd with the correct user ID; otherwise protected directories in the spooling area may not be accessible.


TROUBLESHOOTING: SERVER BASICS

One faxq process manages the scheduling and initiation of all outbound traffic; it carries out many tasks:

One faxgetty server process is usually run for each fax modem on a machine. These processes are responsible for handling inbound traffic; they also carry out many tasks: Proper setup of HylaFAX involves setting up the modem configuration files and the ancillary programs and command scripts that are invoked by faxq and by faxgetty. The setup of the ancillary programs should automatically be done when the software is configured and installed. The modem-related setup and much of the system-related configuration work should be done when the faxaddmodem command is used to create a modem configuration file. Problems that arise in the normal operation of a server typically fall into two categories: In either case HylaFAX provides extensive tracing facilities that should supply the information needed to locate and correct a problem.

With regard to the first problem, remember that faxq will only schedule an outbound job for modems that it knows about. This information is received either from a faxgetty process or by a modem specified on the command line when faxq is started. If faxq does not know about a modem through one of these mechanisms or if a job is submitted for a modem that is not known to faxq then the job will not be scheduled. Note that the latter is problematic because faxq cannot know a priori that a requested modem does not exist--the modem may simply ``not yet be ready''.

The tracing controls are completely described in the config(4F) manual page. faxq tracing information is controlled by two configuration parameters specified in the file etc/config in the spooling area: ServerTracing and LogFacility. The ServerTracing parameter controls which work faxq should trace. LogFacility specifies the syslog(3) facility where the tracing messages should be directed. By default server tracing information is directed to the ``daemon'' facility.

To capture server tracing you must enable the appropriate bits in the ServerTracing parameter and configure the syslogd process to capture daemon.info, daemon.debug, and daemon.err; or substitute for daemon to reflect the value of the LogFacility parameter. Note that 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.

A sample server trace log is shown below. The lines marked ``FaxQueuer'' are generated by the faxq process. The lines marked ``FaxGetty'' are generated by a faxgetty process. The process ID of each process is shown enclosed in ``[]''. Each line is marked with the date and time that it was generated.

Apr 1 12:25:31 6V:oxford FaxQueuer[307]: HylaFAX (tm) Version 3.0beta112 Apr 1 12:25:31 6V:oxford FaxQueuer[307]: Copyright (c) 1990-1995 Sam Leffler Apr 1 12:25:31 6V:oxford FaxQueuer[307]: Copyright (c) 1991-1995 Silicon Graphics, Inc. Apr 1 12:25:58 6V:oxford FaxQueuer[307]: MODEM ttym2 DOWN Apr 1 12:25:58 6V:oxford FaxGetty[477]: OPEN /dev/ttym2 Apr 1 12:26:03 6V:oxford FaxGetty[477]: MODEM TELEBIT T3000SA - Version LA7.20F/T3000SA - Version LA7.20F Apr 1 12:26:04 6V:oxford FaxQueuer[307]: MODEM ttym2 READY

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 DestControls facility.

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. Consult log(4F) for more information.

A sample snippet from a session log is shown below. The trace was collected from a transmission that used a Class 1 modem. The SessionTracing parameter was set at 0x4f. Note that the format is very similar to the information collected through syslog (as shown above). Beware that since HylaFAX supports multiple modems on a single machine, multiple calls to the same destination may be going on simultaneously and the session log files may have messages from multiple calls interspersed.

Messages sent to the modem are identified by a ``<--'' mark while data received from the modem are identified by 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).

Apr 01 09:01:09.78: [18302]: SESSION BEGIN Apr 01 09:01:09.80: [18302]: MODEM set DTR OFF Apr 01 09:01:09.80: [18302]: MODEM set baud rate: 0 baud (flow control unchanged) Apr 01 09:01:09.80: [18302]: DELAY 2600 ms Apr 01 09:01:12.40: [18302]: MODEM set DTR ON Apr 01 09:01:12.40: [18302]: MODEM set baud rate: 38400 baud, input flow RTS/CTS, output flow RTS/CTS Apr 01 09:01:12.40: [18302]: MODEM flush i/o Apr 01 09:01:12.40: [18302]: <-- [14:ATE0V1Q0S0=0H0] Apr 01 09:01:12.53: [18302]: --> [2:OK] Apr 01 09:01:12.53: [18302]: <-- [20:ATS8=2S7=60&K4&D2&C1] Apr 01 09:01:12.66: [18302]: --> [2:OK] Apr 01 09:01:12.66: [18302]: <-- [11:AT+FCLASS=1] Apr 01 09:01:12.78: [18302]: --> [2:OK] Apr 01 09:01:12.78: [18302]: <-- [4:ATM0] Apr 01 09:01:12.90: [18302]: --> [2:OK] Apr 01 09:01:12.90: [18302]: <-- [11:AT+FCLASS=1] Apr 01 09:01:13.02: [18302]: --> [2:OK] Apr 01 09:01:13.06: [18302]: DIAL 14159657824 Apr 01 09:01:13.06: [18302]: <-- [15:ATDT14159657824] Apr 01 09:01:23.85: [18302]: --> [7:CONNECT] Apr 01 09:01:23.92: [18302]: MODEM input buffering disabled Apr 01 09:01:25.45: [18302]: --> HDLC<26:FF C0 02 2C 4C 1C EC AC 6C 9C AC 8C 2C 8C D4 04 04 04 04 04 04 04 04 2C F7 7E> Apr 01 09:01:25.45: [18302]: --> [2:OK] Apr 01 09:01:25.45: [18302]: REMOTE CSI "+14159657824" Apr 01 09:01:25.45: [18302]: <-- [8:AT+FRH=3] Apr 01 09:01:25.45: [18302]: --> [7:CONNECT] Apr 01 09:01:25.79: [18302]: --> HDLC<10:FF C8 01 00 76 5F 00 C6 4A 7E> Apr 01 09:01:25.79: [18302]: --> [2:OK] Apr 01 09:01:25.82: [18302]: REMOTE best rate 14400 bit/s Apr 01 09:01:25.82: [18302]: REMOTE max page width 2432 pixels in 303 mm Apr 01 09:01:25.83: [18302]: REMOTE max unlimited page length Apr 01 09:01:25.83: [18302]: REMOTE best vres 7.7 line/mm Apr 01 09:01:25.83: [18302]: REMOTE best format 1-D MR Apr 01 09:01:25.83: [18302]: REMOTE best 0 ms/scanline Apr 01 09:01:25.83: [18302]: REMOTE does not support PostScript transfer Apr 01 09:01:25.83: [18302]: USE 14400 bit/s Apr 01 09:01:25.83: [18302]: USE 0 ms/scanline Apr 01 09:01:25.83: [18302]: SEND file "docq/doc19.cover;30" .... See log(4F) for more detailed information on the format and content of server and session log messages.


TROUBLESHOOTING: QUEUE MANAGEMENT

There is very little that can go wrong with the server 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.

Otherwise if a problem exists enable the queue management bit in the ServerTracing parameter for the faxq process; e.g.

There is also a separate bit for tracing low-level job queue operations; this should not be needed.


TROUBLESHOOTING: POSTSCRIPT DOCUMENT PREPARATION

When debugging problems related to the preparation of PostScript documents, collect the appropriate command line arguments to the ps2fax(1M) program from the syslog trace messages and invoke it directly on an offending document. Beware, however, that if the fax server 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 interpreter program is linked with Dynamic Shared Objects (DSO's); e.g. when Ghostscript is linked with the the X11 driver and a DSO version of the X library.

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

	LD_LIBRARY_PATH=/usr/local/R5/lib:/usr/openwin/lib
	export LD_LIBRARY_PATH


TROUBLESHOOTING: COMMUNICATION PROBLEMS

If a problem occurs during faxgetty initialization, set ServerTracing to 11, or similar, in the modem configuration file and check the syslog trace messages. 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:

Normal installation of HylaFAX will enable sufficient session tracing to debug session communication problems. Unexpected problems may require you to alter the value of the SessionTracing parameter.

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.

The default configuration files come with SessionTracing set to 11 which is a good setting for Class 2 modems (i.e. a lot of information is provided, but the load on the server should not keep it from operating properly). For Class 1 modems a setting of 0x4f will also cause HDLC frames to be collected. Beware of tracing timer operations and modem I/O; these trace flags are only useful if you are trying to debug a problem specifically related to a timer not going off, or a problem where data appears to be corrupted.

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.

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.

The HylaFAQ has information about other system-specific problems that you may encounter.


TROUBLESHOOTING: PROBLEMS WITH UUCP, CU, TIP, ETC.

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. In particular, beware that most of the prototype modem configuration files for the fax server will leave the modem ``idling'' in Class 1, Class 2, or Class 2.0. This means that in order to place a data call the modem must first be reset to Class 0. Other common problems involve the ownership and protection of the modem devices. When the fax server is running it forces the tty device to be owned by the ``fax'' user (typically the same UID as the ``uucp'' user) and to have the mode specified by the DeviceMode configuration parameter. Finally, beware that there are several different styles of UUCP lock files; verify that your UUCP and related programs use the same style that HylaFAX is configured to use. The UUCP lock file scheme used by HylaFAX may be specified with the UUCPLockType configuration parameter. If you specify this parameter be certain to put it in both the faxq configuration file and each modem configuration file; otherwise one HylaFAX server process may do the right thing while another may not.

HylaFAX table of contents.


Sam Leffler / sam@engr.sgi.com. Last updated $Date: 1995/04/08 21:46:14 $.