1HYLAFAX-SERVER(5F) HYLAFAX-SERVER(5F)
2
6 HylaFAX - introduction to HylaFAX server operation and file formats
7
9 HylaFAX is a system for sending and receiving facsimile. It supports
10 queued transmission and asynchronous reception of facsimile. Ancillary
11 programs are invoked by the system for flexibility and configurability.
12 HylaFAX includes client and server programs to support remote submis‐
13 sion of jobs for transmission, remote removal of queued jobs, and to
14 remotely query the status of jobs queued for transmission. This docu‐
15 ment describes the organization of the filesystem spooling area in
16 which HylaFAX server and server-related processes operate, and intro‐
17 duces the various files that reside in the spooling area.
18
20 The spooling area is typically located under the directory
21 /var/spool/hylafax. Ancillary command scripts used by the server pro‐
22 grams faxq(8C), faxsend(8C), pagesend(8C), and faxgetty(8C) are located
23 in the bin subdirectory. Configuration, access control, and accounting
24 information are maintained in the etc and config subdirectories. Out‐
25 going jobs are described by files in the sendq subdirectory, while
26 received facsimile are deposited in the recvq subdirectory. The docq
27 and temp subdirectories are also used in the preparation of outbound
28 jobs; the latter holds files that may be freely purged while the former
29 holds client files that may reside on the server independent of an
30 associated job. The doneq subdirectory holds jobs that have completed
31 but have not yet been purged or archived. On systems with job archival
32 support, completed jobs that have been archived are placed in the ar‐
33 chive subdirectory. The pollq subdirectory holds documents that are
34 available for polled retrieval from the server. The info subdirectory
35 contains files that describe the capabilities of facsimile machines
36 that HylaFAX has called-this information is used in preparing documents
37 for transmission. The status subdirectory contains files that server
38 processes write their current status to. The log subdirectory contains
39 logging information about send and receive sessions. The client subdi‐
40 rectory contains FIFO special files used for communication with faxq.
41 HylaFAX supports multiple modems on a host. A single process acts as
43 central queueing agent for all outbound jobs. Typically each modem
44 also has a server process that monitors the modem status and handles
45 inbound phone calls. Per-modem server processes communicate with the
46 central queueing agent using FIFO special files; see mknod(2) or
47 mkfifo(2). Any other synchronization between server processes is done
48 using file-level locking. The faxq process listens for commands writ‐
49 ten to the file named FIFO, while each faxgetty process listens for
50 commands written to a per-device file named FIFO.devid (where devid is
51 an identifier derived from the name of the device special file to which
52 the modem is connected; e.g. ttym2 for /dev/ttym2, term_10 for
53 /dev/term/10.) To send a command to the queueing agent, one writes to
54 FIFO. This is useful, for example, for submitting a job for transmis‐
55 sion. To send a command to a specific faxgetty process, the FIFO.devid
56 file is used.
57 Client applications interact with a HylaFAX server machine using a com‐
59 munications protocol implemented by the hfaxd(8C) program. The hfaxd
60 program is typically started at system startup; it listens for client
61 requests for service and creates a process for each client. hfaxd sup‐
62 ports the submission of outbound jobs, querying the status of the send
63 and receive queues, and altering parameters of previously submitted
64 jobs. The hfaxd processes communicate with the faxq process through
65 FIFO special files. Commands sent to faxq are sent to FIFO and
66 responses are received on FIFO files that each hfaxd creates in the
67 client subdirectory.
68
70 Each HylaFAX server machine must run the faxsetup(8C) command prior to
71 starting up HylaFAX server processes. faxsetup verifies that the
72 HylaFAX software has been installed correctly and that any parameters
73 that were specified at the time the software was built are appropriate
74 for the system.
75
77 Each outgoing facsimile job has a job description file that is located
78 in the sendq subdirectory. This file contains all the information nec‐
79 essary to manage the transmission; c.f. sendq(5F). The actual docu‐
80 ments that are to be sent are usually located in the docq subdirectory
81 (though it is also possible to reference documents from the recvq
82 directory). HylaFAX accepts POSTSCRIPT, PDF, PCL, and TIFF documents
83 for transmission (support for PCL documents requires an external appli‐
84 cation). Documents are automatically converted to TIFF/F documents
85 prior to transmission according to the capabilities of the remote fac‐
86 simile machine: maximum page width and length, ability to handle 2D-
87 encoded data, and ability to handle high resolution (7 line/mm) data.
88 This remote machine capability information is stored in files in the
89 info subdirectory. If a machine has not been called before, HylaFAX
90 assumes the remote machine has the requested capabilities. If a capa‐
91 bilities mismatch is detected while sending a facsimile HylaFAX will
92 disconnect and re-convert the submitted documents according to the
93 newly discovered capabilities. Users may also restrict the session
94 parameters used to format documents on a per-job basis.
95 The actual transmission is handled by a faxsend(8C) process that is
97 initiated by the scheduler. This program may be substituted for by
98 specifying the FaxSendCmd configuration parameter in the faxq configu‐
99 ration file.
100 While a job is being processed by a server process, its job description
102 file is locked for exclusive use with flock(2). The hfaxd(8C) program
103 uses this information to tell if a job is actively being processed.
104 If the SessionTracing parameter in a server's configuration file is
106 non-zero, then tracing information for an outgoing job will be logged
107 in a file in the log subdirectory. Each destination machine has a sep‐
108 arate log file named by its canonical phone number.
109 The remote job submission facility includes host and user access con‐
111 trol. The file etc/hosts.hfaxd must be present and list those hosts
112 and users that are permitted to queue jobs for transmission or do other
113 operations that alter the status of a job. Note that it is necessary
114 to include the ``local host'' definition (usually 127.0.0.1) if local
115 submission is to be permitted. For more information consult
116 hosts.hfaxd(5F).
117 There are a number of controls on outbound calls that can be specified
119 using the JobControl feature in the faxq configuration file. This file
120 is described in jobcontrol(8C).
121 If an error is encountered during transmission and a subsequent
123 retransmission would not include the original cover page, then HylaFAX
124 can be configured to generate a continuation cover page that is
125 prepended to the retransmitted pages. Such cover pages are usually
126 generated by the bin/mkcover command; though the exact command to use
127 can be specified in the configuration file read by faxq.
128 HylaFAX can be configured to generate a line of status information
130 across the top of each page of an outbound facsimile. This informa‐
131 tion, termed a ``tagline'', typically includes the sender's identity
132 (i.e. phone number), the time and date of the transmission, and the
133 page number. The exact format of the tagline is configurable and
134 applications can override the default configuration parameters on a
135 per-job basis. Note that in the United States the law requires that a
136 tagline that identifies the sender's phone number must appear on each
137 transmitted page of facsimile.
138 Facsimile transmitted to receivers that accept variable-length pages
140 may have short pages ``chopped''. That is, if a page has a significant
141 amount of trailing whitespace and the receiver accepts variable-length
142 pages then only the top part of the page will be transmitted. faxq can
143 be configured so that only the last page of each document is poten‐
144 tially chopped, all pages are potentially chopped, or chopping is dis‐
145 abled. The minimum whitespace threshold is also configurable. Appli‐
146 cations can override the default configuration parameters on a per-job
147 basis.
148
150 faxgetty server processes can be configured to answer incoming phone
151 calls and automatically receive facsimile. Received documents are
152 placed in the recvq subdirectory as TIFF Class F files. The faxgetty
153 processes can be configured to make these files publicly accessible, or
154 they can be made private in which case an administrator must manage
155 their delivery and/or the assignment of ownership to particular users.
156 When a facsimile is received, the faxgetty process usually invokes the
157 bin/faxrcvd command; though the exact command to invoke can be speci‐
158 fied in the per-modem configuration file. The default notify command
159 is a shell script that sends a mail message to a well known user, the
160 FaxMaster, but one might also, for example, automatically spool the
161 document for printing.
162 HylaFAX supports a simple form of access control for receiving facsim‐
164 ile. Each faxgetty process may be configured to check the Transmission
165 Subscriber Identifiers (TSI) of the remote fax machine against an
166 access control list, typically etc/tsi. Only if the TSI is matched by
167 a regular expression pattern in the file, is the remote machine permit‐
168 ted to transmit a document. This mechanism can be used, for example,
169 to guard against junk fax.
170 HylaFAX can be configured to do copy quality checking on received fac‐
172 simile data. When this feature is enabled faxgetty decodes and ana‐
173 lyzes the received facsimile data as it is received. If data is
174 received with too many errors, according to the setting of the MaxCon‐
175 secutiveBadLines and PercentGoodLines configuration parameters, then
176 the sender will be told to retransmit the page. When copy quality
177 checking is enabled it is also possible to force received facsimile
178 data to be saved with a different compression scheme than was used for
179 transmission. This function is known as transcoding and can signifi‐
180 cantly reduce the space needed to store received facsimile.
181
183 HylaFAX supports the polled retrieval of facsimile documents. Docu‐
184 ments that are received because of a poll request are stored in the
185 recvq subdirectory and also delivered directly to the requester using
186 the bin/pollrcvd command; though the exact command to invoke can be
187 specified with the PollRcvdCmd configuration parameter. The pollrcvd
188 script typically encodes the binary facsimile data and returns it to
189 the user via electronic mail.
190
192 In environments where Caller-ID information is available, HylaFAX also
193 supports a call screening facility similar to the TSI access control
194 facility. faxgetty can be configured to check the phone number of each
195 caller against an access control list, typically etc/cid. Only if the
196 number is matched by a regular expression pattern in the file is the
197 call answered. All Caller ID information is logged, irregardless of
198 whether or not it is used to screen incoming calls.
199 faxgetty is also capable of using distinctive ring information to iden‐
201 tify whether an inbound call is voice, data, or fax. Consult the Ring‐
202 Data, RingFax, and RingVoice parameters in hylafax-config(5F) for a
203 description of this facility.
204
206 Most fax modems also support non-facsimile communication. HylaFAX uses
207 the locking mechanism employed by uucp(1C), cu(1C), slip(8C), and
208 ppp(8C). Any faxgetty processes will transparently ``get out of the
209 way'' when an application wants to use a modem for an outgoing call.
210 In addition, HylaFAX can be configured to deduce whether an incoming
211 call is for facsimile or data use. If a call from a data modem is rec‐
212 ognized and the GettyArgs parameter is specified in the configuration
213 file, faxgetty will invoke the getty(8C) program so that caller may
214 login to the system. Similar functionality is also available for
215 invoking a ``voice getty'' process, though auto-detection of inbound
216 voice calls is less extensive.
217
219 HylaFAX maintains status information in several forms. General status
220 information for each server process is maintained in the status subdi‐
221 rectory and returned to users by the faxstat(1) program. The syslog(3)
222 facility is used by all server processed for logging status and error
223 diagnostics. The server processes may also be configured to log vari‐
224 ous kinds of debugging and tracing information; c.f. the ServerTracing
225 parameter description in hylafax-config(5F).
226 Any problems encountered when transmitting a facsimile are described in
228 messages returned to the user by electronic mail. A user may also
229 request notification by mail when a job is requeued; for example,
230 because a call failed. Notification by electronic mail is implemented
231 by the bin/notify command script; though the name of the script may be
232 overridden with the NotifyCmd configuration parameter.
233 The faxstat utility provides (remote) status of jobs queued for trans‐
235 mission, jobs received, and the general status of server processes.
236 The file etc/xferfaxlog contains status information about all facsimile
238 sent and received on a machine. This file is in a simple ASCII format
239 that is easy to manipulate with programs such as awk(1), to generate
240 accounting information. See xferfaxlog(5F) for information about the
241 format. See xferfaxstats(8C) and recvstats(8C) for example scripts
242 that print summarized accounting information.
243 Finally, the hfaxd process supports a event monitoring facility that
245 can be access via the faxwatch(8C) program. This facility permits
246 clients to register interest in various events and receive ``realtime
247 notification'' when such events occur on the server. Using this facil‐
248 ity it is/should-be simple to construct applications that do things
249 like monitor modem status and use.
250
252 In normal operation each modem is managed by a HylaFAX server process
253 such as faxgetty. These processes communicate with the central sched‐
254 uler process to notify it when a modem is ready for use, busy for out‐
255 bound use, or possibly in an unusable state (either purposely marked
256 unavailable or potentially found to be wedged). Modem usage can be
257 explicitly controlled with the faxstate(8C) program. The faxconfig(8C)
258 program can also be used to dynamically make changes to configuration
259 parameters that may cause a modem to be treated differently (e.g. set‐
260 ting RingsBeforeAnswer to zero will cause faxgetty to not answer incom‐
261 ing calls).
262 When HylaFAX is used in a send-only configuration there are no faxgetty
264 processes and communication must be done directly with the faxq
265 process. The faxstate program can still be used to manipulate modem
266 use for outbound jobs but the faxconfig program is not frequently
267 needed.
268
270 Outbound jobs are scheduled by a single process. Jobs have a ``sched‐
271 uling priority'' that is assigned at the time the job is submitted.
272 This priority can be changed at any time the job is not actively being
273 processed using the faxalter(8C) program. A job's scheduling priority
274 may also be altered by faxq in response to certain scheduling events
275 (e.g. after a failed attempt to send).
276 Modems are assigned to outbound jobs if they are deemed ready for use.
278 Modem readiness is usually communicated to faxq by per-modem faxgetty
279 processes. In a send-only environment however this is not possible;
280 instead modems configured for use with faxmodem are considered always
281 ready for use unless they are presently assigned to an outbound job or
282 their state is explicitly changed through the faxstate(8C) program
283 (faxstate can also be used in a send-recv environment).
284 Each modem has a ``modem priority'' in the range [0..255]. Modems with
286 a lower priority number are assigned to outbound jobs first. Modem
287 priority is statically configured through configuration files, the fax‐
288 modem program, and the faxconfig program. If multiple modems share the
289 same priority value, then faxq(8C) will allocate jobs to them in a
290 round-robin fashion.
291
293 Outbound jobs are considered to be in one of several states that
294 reflect their treatment by the central scheduling process. Jobs are
295 initially created in a suspended state, and may be returned to this
296 state at any time that they are not actively being processed (e.g. a
297 faxsend program is running to process the job). Jobs that are sus‐
298 pended are not processed by the scheduler; and their internal state may
299 be safely altered by the owner or a system administrator. Suspending
300 and then releasing a job has the effect of requeueing the job, meaning
301 that it will end up at the bottom of queue for that job's priority.
302 Jobs that are ready for processing by the scheduler are ``submitted''
303 and their state is changed to be either pending (delayed waiting for a
304 future time to send), sleeping (delayed waiting for a scheduled time‐
305 out), blocked (delayed by concurrent activity to the same destination),
306 or ready (ready for transmission, waiting only for available
307 resources). When a job is actively processed by the faxsend program
308 its state is marked active. Jobs that have completed, either success‐
309 fully or unsuccessfully are placed in a done state and their job
310 description files are moved to the doneq subdirectory. Clients may
311 still access the state of jobs that are done; until a ``cleaner
312 process'' either purges them from the system or archives their state.
313 This delayed removal of a completed job's state permits clients to
314 resubmit failed jobs using previously transmitted documents and other
315 job state information. The exact mechanics of how and when done jobs
316 are processed is system-dependent; for example, how long a job is left
317 in the done queue before being purged, and whether job archival support
318 is present.
319
321 HylaFAX server programs read configuration information from a configu‐
322 ration file. Multiple files are used, one for the faxq program and one
323 for each modem. Long-running server programs all automatically re-read
324 their configuration file if it is modified. Typically this re-reading
325 is done frequently enough that administrators do not need to be aware
326 of exactly when it takes place. However in some esoteric cases the
327 file may not be read when expected (the one important case is that the
328 faxgetty process reads its configuration file only when answering a
329 call or when resetting a modem; this means that it will not recognize
330 changes when the modem is idle).
331 In addition to the static configuration files, HylaFAX server programs
333 accept commands on their FIFO special files to alter configuration
334 parameters in the running executable (the faxconfig(8C) program can be
335 used to dynamically change configuration parameters). Values set in
336 this way however are lost when the process exits or if the configura‐
337 tion file is re-read.
338
340 Automatic routing of incoming facsimile is desirable.
341
343 FIFO fifo for job submission
344 FIFO.<devid> fifo for communicating with a faxgetty process
345 /usr/sbin/faxinfo command that prints information about received facsimile
346 /usr/sbin/faxquit command to force server to quit
347 bin/faxrcvd faxd command for handling newly received facsimile
348 bin/mkcover faxd command for generating continuation cover pages
349 bin/notify faxd command for doing user notification
350 bin/pollrcvd faxd command for delivering facsimile received by poll
351 bin/ps2fax faxd command for converting POSTSCRIPT to TIFF
352 docq/doc* documents available for transmission
353 etc/setup.cache server setup file created by faxsetup
354 etc/cid caller id access control list
355 etc/config.<devid> configuration data for <devid>
356 etc/hosts.hfaxd hosts that may submit jobs for transmission
357 etc/tsi fax machine receive access control list
358 etc/xferfaxlog log of facsimile sent and received
359 info/* data base of remote fax machine capabilities
360 client/* FIFO special files created by client processes
361 config/* prototype configuration files used by faxaddmodem
362 log/* session logging records
363 recvq/fax* received facsimile
364 sendq/q* descriptions of jobs queued for transmission
365 doneq/q* descriptions of jobs that are done
366 status/* server status information
367 tmp/* temporary files created when submitting a job
368 archive/* database of archived jobs
369
371 faxsetup(8C), faxq(8C), faxgetty(8C), hfaxd(8C), faxsend(8C), faxr‐
372 cvd(8C), faxconfig(8C), faxmodem(8C), faxstate(8C), notify(8C), pollr‐
373 cvd(8C), recvstats(8C), xferfaxstats(8C), archive(5F), hylafax-con‐
374 fig(5F), dialrules(5F), doneq(5F), hosts.hfaxd(5F), hylafax-info(5F),
375 hylafax-log(5F), tsi(5F), recvq(5F), sendq(5F), status(5F), xfer‐
376 faxlog(5F),
377 Extensive documentation is available in online at
379 http://hylafax.sourceforge.net/.
380 January 18, 1996 HYLAFAX-SERVER(5F)