1HYLAFAX-SERVER(5F)                                          HYLAFAX-SERVER(5F)


6       HylaFAX - introduction to HylaFAX server operation and file formats


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.


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.
42       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.
58       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.


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.


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.
96       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.
101       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.
105       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.
110       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 if local
115       submission  is  to  be  permitted.   For   more   information   consult
116       hosts.hfaxd(5F).
118       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).
122       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.
129       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.
139       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.


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.
163       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.
171       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.


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.


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.
200       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.


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.


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).
227       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.
234       The faxstat utility provides (remote) status of jobs queued for  trans‐
235       mission, jobs received, and the general status of server processes.
237       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.
244       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.


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).
263       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.


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).
277       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).
285       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.


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.


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).
332       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.


340       Automatic routing of incoming facsimile is desirable.


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


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),
378       Extensive    documentation    is     available     in     online     at
379       http://hylafax.sourceforge.net/.
383                               January 18, 1996             HYLAFAX-SERVER(5F)