bionic (5) hylafax-server.5.gz

Provided by: hylafax-server_6.0.6-8.1~ubuntu0.18.04.1_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)