Provided by: hylafax-server_4.4.3-1_i386 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  (though  support for PCL documents is not
       currently  implemented).   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).

       There  are a number of controls on outbound calls that can be specified
       using the etc/destcontrols file (or whatever file  is  specified  in  a
       DestControls  configuration  parameter in the faxq configuration file).
       This file,  described  in  destctrls(5),  allows  an  administrator  to
       restrict  calls  by  phone  number  and to control the time of day that
       calls may be placed.  In addition, operational parameters such  as  the
       maximum  number of pages in a facsimile transmission can be constrained
       on a per-destination basis.

       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)