There are several components to the complete HylaFAX software package:
Run faxstat to request server status. You should see something like:
Server on localhost:FIFO for all modems: Running. Server on localhost:ttym2 for "+1 510 526-8781": Initializing server.or possibly,
Server on localhost:FIFO for all modems: Not running.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:
fax stream tcp nowait fax /usr/etc/faxd.recv faxd.recv
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;
hyla% telnet localhost fax Trying 127.0.0.1... Connected to localhost.asd.sgi.com. Escape character is '^]'. help error:Protocol botch, malformed line "help". Connection closed by foreign host.[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:
hyla% faxstat -v connect to oxford.chez (155.11.194.2) at port 4557 -> version:2 -> userID:sam -> serverStatus: -> userStatus:Sam Leffler -> . <- server:all modems:FIFO:Running <- server:"+1 510 526-8781":ttym2:Running and idle <- EOF Server on oxford.chez:FIFO for all modems: Running. Server on oxford.chez:ttym2 for "+1 510 526-8781": Running and idle.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:
fax stream tcp nowait fax /usr/local/sbin/faxd.recv faxd.recv -dOnce 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).
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:
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.
local5.* /var/spool/fax/etc/syslog
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.
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).
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.
ServerTracing: 0x201There is also a separate bit for tracing low-level job queue operations; this should not be needed.
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.
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
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.
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.