Provided by: hylafax-server_6.0.6-6_amd64 bug

NAME

       HylaFAX - introduction to HylaFAX server operation and file formats

DESCRIPTION

       HylaFAX  is a system for sending and receiving facsimile.  It supports queued transmission
       and asynchronous reception of facsimile.  Ancillary programs are invoked by the system for
       flexibility  and  configurability.  HylaFAX includes client and server programs to support
       remote submission of jobs for transmission, remote removal of queued jobs, and to remotely
       query   the  status  of  jobs  queued  for  transmission.   This  document  describes  the
       organization of the filesystem spooling area in which HylaFAX  server  and  server-related
       processes operate, and introduces the various files that reside in the spooling area.

OVERVIEW

       The  spooling area is typically located under the directory /var/spool/hylafax.  Ancillary
       command scripts  used  by  the  server  programs  faxq(8),  faxsend(8),  pagesend(8),  and
       faxgetty(8)  are  located  in  the  bin  subdirectory.  Configuration, access control, and
       accounting information are maintained in the etc and config subdirectories.  Outgoing jobs
       are  described  by files in the sendq subdirectory, while received facsimile are deposited
       in the recvq subdirectory.  The  docq  and  temp  subdirectories  are  also  used  in  the
       preparation  of  outbound jobs; the latter holds files that may be freely purged while the
       former holds client files that may reside on the server independent of an associated  job.
       The  doneq  subdirectory  holds  jobs  that have completed but have not yet been purged or
       archived.  On systems with job archival support, completed jobs that  have  been  archived
       are  placed  in the archive subdirectory.  The pollq subdirectory holds documents that are
       available for polled retrieval from the server.  The info subdirectory contains files that
       describe  the  capabilities of facsimile machines that HylaFAX has called-this information
       is used in preparing documents for transmission.  The status subdirectory  contains  files
       that  server  processes  write  their  current  status  to.  The log subdirectory contains
       logging information about send and receive sessions.   The  client  subdirectory  contains
       FIFO special files used for communication with faxq.

       HylaFAX  supports  multiple  modems  on a host.  A single process acts as central queueing
       agent for all outbound jobs.  Typically each modem also has a server process that monitors
       the  modem status and handles inbound phone calls.  Per-modem server processes communicate
       with the central queueing agent using FIFO special files; see mknod(2) or mkfifo(2).   Any
       other synchronization between server processes is done using file-level locking.  The faxq
       process listens for commands written to the file named FIFO, while each  faxgetty  process
       listens  for  commands  written  to  a per-device file named FIFO.devid (where devid is an
       identifier derived from the name of  the  device  special  file  to  which  the  modem  is
       connected;  e.g.   ttym2  for /dev/ttym2, term_10 for /dev/term/10.)  To send a command to
       the queueing agent, one writes to FIFO.  This is useful, for example, for submitting a job
       for  transmission.   To send a command to a specific faxgetty process, the FIFO.devid file
       is used.

       Client applications interact with a HylaFAX server machine using a communications protocol
       implemented  by  the  hfaxd(8)  program.  The hfaxd program is typically started at system
       startup; it listens for client requests for service and creates a process for each client.
       hfaxd  supports  the  submission  of  outbound  jobs,  querying the status of the send and
       receive queues, and altering parameters of previously submitted jobs.  The hfaxd processes
       communicate  with  the faxq process through FIFO special files.  Commands sent to faxq are
       sent to FIFO and responses are received on FIFO files  that  each  hfaxd  creates  in  the
       client subdirectory.

SETUP

       Each  HylaFAX server machine must run the faxsetup(8) command prior to starting up HylaFAX
       server processes.   faxsetup  verifies  that  the  HylaFAX  software  has  been  installed
       correctly  and  that any parameters that were specified at the time the software was built
       are appropriate for the system.

SENDING

       Each outgoing facsimile job has a job description  file  that  is  located  in  the  sendq
       subdirectory.    This   file   contains  all  the  information  necessary  to  manage  the
       transmission; c.f.  sendq(5).  The actual documents  that  are  to  be  sent  are  usually
       located  in  the docq subdirectory (though it is also possible to reference documents from
       the recvq directory).  HylaFAX accepts  POSTSCRIPT,  PDF,  PCL,  and  TIFF  documents  for
       transmission  (support for PCL documents requires an external application).  Documents are
       automatically converted to  TIFF/F  documents  prior  to  transmission  according  to  the
       capabilities  of  the  remote facsimile machine: maximum page width and length, ability to
       handle 2D-encoded data, and ability to handle high  resolution  (7  line/mm)  data.   This
       remote  machine  capability information is stored in files in the info subdirectory.  If a
       machine has not been called before, HylaFAX assumes the remote machine has  the  requested
       capabilities.   If  a  capabilities mismatch is detected while sending a facsimile HylaFAX
       will disconnect and re-convert the submitted documents according to the  newly  discovered
       capabilities.   Users may also restrict the session parameters used to format documents on
       a per-job basis.

       The actual transmission is handled by a  faxsend(8)  process  that  is  initiated  by  the
       scheduler.  This program may be substituted for by specifying the FaxSendCmd configuration
       parameter in the faxq configuration file.

       While a job is being processed by a server process, its job description file is locked for
       exclusive  use with flock(2).  The hfaxd(8) program uses this information to tell if a job
       is actively being processed.

       If the SessionTracing parameter in a server's configuration file is non-zero, then tracing
       information  for  an  outgoing job will be logged in a file in the log subdirectory.  Each
       destination machine has a separate log file named by its canonical phone number.

       The remote job submission facility includes  host  and  user  access  control.   The  file
       etc/hosts.hfaxd must be present and list those hosts and users that are permitted to queue
       jobs for transmission or do other operations that alter the status of a job.  Note that it
       is  necessary  to  include  the  ``local  host''  definition  (usually 127.0.0.1) if local
       submission is to be permitted.  For more information consult hosts.hfaxd(5).

       If an error is encountered during transmission and a subsequent retransmission  would  not
       include the original cover page, then HylaFAX can be configured to generate a continuation
       cover page that is prepended to the retransmitted pages.  Such  cover  pages  are  usually
       generated  by the bin/mkcover command; though the exact command to use can be specified in
       the configuration file read by faxq.

       HylaFAX can be configured to generate a line of status information across the top of  each
       page of an outbound facsimile.  This information, termed a ``tagline'', typically includes
       the sender's identity (i.e. phone number), the time and date of the transmission, and  the
       page  number.   The  exact  format  of  the  tagline  is configurable and applications can
       override the default configuration parameters on a per-job basis.  Note that in the United
       States  the  law  requires  that  a tagline that identifies the sender's phone number must
       appear on each transmitted page of facsimile.

       Facsimile transmitted to receivers that accept variable-length pages may have short  pages
       ``chopped''.   That  is, if a page has a significant amount of trailing whitespace and the
       receiver accepts variable-length pages then  only  the  top  part  of  the  page  will  be
       transmitted.   faxq  can  be  configured  so  that  only the last page of each document is
       potentially chopped, all pages are potentially chopped,  or  chopping  is  disabled.   The
       minimum  whitespace threshold is also configurable.  Applications can override the default
       configuration parameters on a per-job basis.

RECEIVING

       faxgetty  server  processes  can  be  configured  to  answer  incoming  phone  calls   and
       automatically  receive facsimile.  Received documents are placed in the recvq subdirectory
       as TIFF Class F files.  The faxgetty processes can  be  configured  to  make  these  files
       publicly  accessible,  or  they  can  be  made private in which case an administrator must
       manage their delivery and/or the assignment of ownership  to  particular  users.   When  a
       facsimile  is  received,  the  faxgetty  process  usually invokes the bin/faxrcvd command;
       though the exact command to invoke can be specified in the per-modem  configuration  file.
       The  default  notify  command  is a shell script that sends a mail message to a well known
       user, the FaxMaster, but one might also, for example, automatically spool the document for
       printing.

       HylaFAX  supports  a simple form of access control for receiving facsimile.  Each faxgetty
       process may be configured to check the Transmission Subscriber Identifiers  (TSI)  of  the
       remote  fax machine against an access control list, typically etc/tsi.  Only if the TSI is
       matched by a regular expression pattern in the file, is the remote  machine  permitted  to
       transmit a document.  This mechanism can be used, for example, to guard against junk fax.

       HylaFAX  can  be  configured to do copy quality checking on received facsimile data.  When
       this feature is enabled faxgetty decodes and analyzes the received facsimile data as it is
       received.   If  data  is  received  with  too many errors, according to the setting of the
       MaxConsecutiveBadLines and PercentGoodLines configuration parameters, then the sender will
       be told to retransmit the page.  When copy quality checking is enabled it is also possible
       to force received facsimile data to be saved with a different compression scheme than  was
       used for transmission.  This function is known as transcoding and can significantly reduce
       the space needed to store received facsimile.

POLLING

       HylaFAX supports the polled retrieval of facsimile documents.  Documents that are received
       because of a poll request are stored in the recvq subdirectory and also delivered directly
       to the requester using the bin/pollrcvd command; though the exact command to invoke can be
       specified  with  the  PollRcvdCmd  configuration parameter.  The pollrcvd script typically
       encodes the binary facsimile data and returns it to the user via electronic mail.

INBOUND CALL HANDLING

       In environments where Caller-ID information is available, HylaFAX  also  supports  a  call
       screening facility similar to the TSI access control facility.  faxgetty can be configured
       to check the phone number of  each  caller  against  an  access  control  list,  typically
       etc/cid.  Only if the number is matched by a regular expression pattern in the file is the
       call answered.  All Caller ID information is logged, irregardless of whether or not it  is
       used to screen incoming calls.

       faxgetty  is  also  capable  of  using distinctive ring information to identify whether an
       inbound call is voice, data,  or  fax.   Consult  the  RingData,  RingFax,  and  RingVoice
       parameters in hylafax-config(5) for a description of this facility.

DATA CALLS

       Most  fax  modems  also  support  non-facsimile  communication.   HylaFAX uses the locking
       mechanism employed by uucp(1C), cu(1C), slip(8), and ppp(8).  Any faxgetty processes  will
       transparently  ``get  out  of  the  way''  when an application wants to use a modem for an
       outgoing call.  In addition, HylaFAX can be configured to deduce whether an incoming  call
       is for facsimile or data use.  If a call from a data modem is recognized and the GettyArgs
       parameter is specified in the  configuration  file,  faxgetty  will  invoke  the  getty(8)
       program  so  that caller may login to the system.  Similar functionality is also available
       for invoking a ``voice getty'' process, though auto-detection of inbound  voice  calls  is
       less extensive.

STATUS

       HylaFAX  maintains  status  information  in several forms.  General status information for
       each server process is maintained in the status subdirectory and returned to users by  the
       faxstat(1)  program.   The  syslog(3) facility is used by all server processed for logging
       status and error diagnostics.  The server processes may also be configured to log  various
       kinds  of debugging and tracing information; c.f.  the ServerTracing parameter description
       in hylafax-config(5).

       Any problems encountered when transmitting a facsimile are described in messages  returned
       to  the  user by electronic mail.  A user may also request notification by mail when a job
       is requeued; for example, because a call  failed.   Notification  by  electronic  mail  is
       implemented  by  the  bin/notify  command  script;  though  the  name of the script may be
       overridden with the NotifyCmd configuration parameter.

       The faxstat utility provides  (remote)  status  of  jobs  queued  for  transmission,  jobs
       received, and the general status of server processes.

       The  file etc/xferfaxlog contains status information about all facsimile sent and received
       on a machine.  This file is in a simple ASCII format  that  is  easy  to  manipulate  with
       programs  such  as  awk(1),  to  generate  accounting  information.  See xferfaxlog(5) for
       information about the format.  See xferfaxstats(8) and recvstats(8)  for  example  scripts
       that print summarized accounting information.

       Finally, the hfaxd process supports a event monitoring facility that can be access via the
       faxwatch(8) program.  This facility permits clients to register interest in various events
       and  receive  ``realtime  notification'' when such events occur on the server.  Using this
       facility it is/should-be simple to construct applications  that  do  things  like  monitor
       modem status and use.

MODEM STATE CHANGES

       In  normal  operation  each modem is managed by a HylaFAX server process such as faxgetty.
       These processes communicate with the central scheduler process to notify it when  a  modem
       is  ready  for  use,  busy  for  outbound  use,  or  possibly in an unusable state (either
       purposely marked unavailable or potentially found to  be  wedged).   Modem  usage  can  be
       explicitly  controlled with the faxstate(8) program.  The faxconfig(8) program can also be
       used to dynamically make changes to configuration parameters that may cause a modem to  be
       treated  differently  (e.g.   setting RingsBeforeAnswer to zero will cause faxgetty to not
       answer incoming calls).

       When HylaFAX is used in a send-only configuration there  are  no  faxgetty  processes  and
       communication must be done directly with the faxq process.  The faxstate program can still
       be used to manipulate modem use for  outbound  jobs  but  the  faxconfig  program  is  not
       frequently needed.

JOB SCHEDULING

       Outbound jobs are scheduled by a single process.  Jobs have a ``scheduling priority'' that
       is assigned at the time the job is submitted.  This priority can be changed  at  any  time
       the job is not actively being processed using the faxalter(8) program.  A job's scheduling
       priority may also be altered by faxq in response to certain scheduling events (e.g.  after
       a failed attempt to send).

       Modems are assigned to outbound jobs if they are deemed ready for use.  Modem readiness is
       usually communicated to faxq by per-modem faxgetty processes.  In a send-only  environment
       however  this  is  not  possible;  instead  modems  configured  for  use with faxmodem are
       considered always ready for use unless they are presently assigned to an outbound  job  or
       their  state  is  explicitly changed through the faxstate(8) program (faxstate can also be
       used in a send-recv environment).

       Each modem has a ``modem priority'' in the range [0..255].  Modems with a  lower  priority
       number  are  assigned  to  outbound  jobs  first.  Modem priority is statically configured
       through configuration files, the faxmodem program, and the faxconfig program.  If multiple
       modems  share the same priority value, then faxq(8) will allocate jobs to them in a round-
       robin fashion.

JOB MANAGEMENT

       Outbound jobs are considered to be in one of several states that reflect  their  treatment
       by  the  central scheduling process.  Jobs are initially created in a suspended state, and
       may be returned to this state at any time that they are not actively being processed (e.g.
       a  faxsend  program  is  running  to  process  the  job).  Jobs that are suspended are not
       processed by the scheduler; and their internal state may be safely altered by the owner or
       a  system administrator.  Suspending and then releasing a job has the effect of requeueing
       the job, meaning that it will end up at the bottom of queue for that job's priority.  Jobs
       that  are  ready  for  processing  by  the  scheduler are ``submitted'' and their state is
       changed to be either pending (delayed  waiting  for  a  future  time  to  send),  sleeping
       (delayed  waiting for a scheduled timeout), blocked (delayed by concurrent activity to the
       same  destination),  or  ready  (ready  for  transmission,  waiting  only  for   available
       resources).   When  a job is actively processed by the faxsend program its state is marked
       active.  Jobs that have completed, either successfully or unsuccessfully are placed  in  a
       done  state  and their job description files are moved to the doneq subdirectory.  Clients
       may still access the state of jobs that are  done;  until  a  ``cleaner  process''  either
       purges  them from the system or archives their state.  This delayed removal of a completed
       job's state permits clients to resubmit failed jobs using previously transmitted documents
       and  other  job  state  information.   The  exact  mechanics of how and when done jobs are
       processed is system-dependent; for example, how long a job  is  left  in  the  done  queue
       before being purged, and whether job archival support is present.

CONFIGURATION

       HylaFAX  server  programs  read  configuration  information  from  a  configuration  file.
       Multiple files are used, one for the faxq program and one for  each  modem.   Long-running
       server  programs  all  automatically  re-read  their configuration file if it is modified.
       Typically this re-reading is done frequently enough that administrators do not need to  be
       aware  of exactly when it takes place.  However in some esoteric cases the file may not be
       read when expected (the one  important  case  is  that  the  faxgetty  process  reads  its
       configuration  file  only when answering a call or when resetting a modem; this means that
       it will not recognize changes when the modem is idle).

       In addition to the static configuration files, HylaFAX server programs accept commands  on
       their  FIFO special files to alter configuration parameters in the running executable (the
       faxconfig(8) program can be used to dynamically change configuration parameters).   Values
       set  in  this  way however are lost when the process exits or if the configuration file is
       re-read.

NOTES

       Automatic routing of incoming facsimile is desirable.

FILES

       FIFO                  fifo for job submission
       FIFO.<devid>          fifo for communicating with a faxgetty process
       /usr/sbin/faxinfo     command that prints information about received facsimile
       /usr/sbin/faxquit     command to force server to quit
       bin/faxrcvd           faxd command for handling newly received facsimile
       bin/mkcover           faxd command for generating continuation cover pages
       bin/notify            faxd command for doing user notification
       bin/pollrcvd          faxd command for delivering facsimile received by poll
       bin/ps2fax            faxd command for converting POSTSCRIPT to TIFF
       docq/doc*             documents available for transmission
       etc/setup.cache       server setup file created by faxsetup
       etc/cid               caller id access control list
       etc/config.<devid>    configuration data for <devid>
       etc/hosts.hfaxd       hosts that may submit jobs for transmission
       etc/tsi               fax machine receive access control list
       etc/xferfaxlog        log of facsimile sent and received
       info/*                data base of remote fax machine capabilities
       client/*              FIFO special files created by client processes
       config/*              prototype configuration files used by faxaddmodem
       log/*                 session logging records
       recvq/fax*            received facsimile
       sendq/q*              descriptions of jobs queued for transmission
       doneq/q*              descriptions of jobs that are done
       status/*              server status information
       tmp/*                 temporary files created when submitting a job
       archive/*             database of archived jobs

SEE ALSO

       faxsetup(8),  faxq(8),  faxgetty(8),  hfaxd(8),  faxsend(8),   faxrcvd(8),   faxconfig(8),
       faxmodem(8),   faxstate(8),   notify(8),   pollrcvd(8),   recvstats(8),   xferfaxstats(8),
       archive(5), hylafax-config(5), dialrules(5),  doneq(5),  hosts.hfaxd(5),  hylafax-info(5),
       hylafax-log(5), tsi(5), recvq(5), sendq(5), status(5), xferfaxlog(5),

       Extensive  documentation is available in online at http://www.hylafax.org/.  Many of these
       materials are also included in the software distribution.

                                         January 18, 1996                       HYLAFAX-SERVER(5)