Provided by: mgetty-fax_1.1.36-1.4_i386 bug

NAME

       faxrunqd - daemon to send fax jobs queued by faxspool(1)

SYNOPSIS

       faxrunqd  [-v]  [-d] [-D] [-l <ttys>] [-u <user or uid>] [ -g <group or
       gid> ] [-V]

DESCRIPTION

       Runs in the background, and regularily checks the fax queue set  up  by
       faxspool(1).   Sends  all jobs that are due, records results, and takes
       appropriate action (notify mails etc).

       faxrunqd basically does the same as faxrunq(1), just more  so.   Please
       read  the  faxrunq(1)  man page if you’re not already familiar with the
       concept.

       The advantages of faxrunqd are:

       - runs all the time, so you don’t have to set up a cron  job  (but  you
       have to set up an entry in /etc/inittab or start it from /etc/rc*)

       - quicker response to new faxes in queue

       - can sensibly handle more than one modem

       - can handle prioritized fax jobs

       - can do ’policy routing’ of faxes depending on the fax number

       The disadvantages are:

       - needs more system ressources if you have only little fax traffic

       - requires Perl 5.004

       - more tricky to set up and to debug

SETUP

       faxrunqd   is   started   at   system  boot  from  /etc/rc.*,  or  from
       /etc/inittab.  You can also start it from the command line. It does not
       put  itself  in the background, so you have to start it with an "&", or
       from a ":respawn:" line in /etc/inittab.   Using /etc/inittab  has  the
       advantage  that  faxrunqd  is restarted automatically if something goes
       wrong and faxrunqd is stopped.

       faxrunqd will first read a global configuration file (see below),  then
       (optionally)  the  faxrunqd policy file (see further below).  From then
       on, it will sit in a loop. It will check the fax queue every 60 seconds
       for  new jobs, and will then distribute them over all available modems.
       If the job is sent, or fails, it will  do  the  same  thing  faxrunq(1)
       would  do  (send  a  mail,  delete  the  JOB directory, execute a named
       program, etc.).  Both programs are fully compatible in this respect.

       faxrunqd [-v] [-d] [-D] [-l <ttys>] [-u <user or uid>] [ -g  <group  or
       gid> ] [-V]

OPTIONS

       -v     Tells faxrunqd to write progress information to the log file.

       -D     Tells faxrunqd to run in the background, as a daemon.

       -d     Tells  faxrunqd to write debugging information to stdout and the
              log file (usually used together with -v).

       -l <ttyS>
              Specifies the list of modem devices to  use.   Multiple  devices
              are separated with ’:’, e.g. ’-l ttyS0:ttyS1’.

       -u <user or uid>
              faxrunqd  can  now  (since 1.1.29) run as unprivileged user.  If
              you start it as root  from  /etc/inittab  or  from  one  of  the
              /etc/rc* scripts, it’s strongly recommended to use ’-u uucp’ (to
              be precise: the user that  is  owning  the  outgoing  fax  spool
              directory).   This will make faxrunqd drop all its privileges at
              startup, and run as the specified  user.   Running  faxrunqd  as
              root  user  might  lead to security problems - don’t do it. This
              parameter takes either a uid or a username as argument.

       -g <group or gid>
              Same effect as above but for the group id. Indicates  the  group
              which  should  own  the fax files. This parameter takes either a
              gid or a groupname as argument.

       -V     print version number and exit

CONFIGURATION FILE

       Some aspects of the behaviour  of  faxrunqd  can  be  controlled  by  a
       configuration  file,  usually named /etc/mgetty/faxrunq.config (this is
       the same file that faxrunq(1) uses, but there  are  additional  options
       for faxrunqd). In this file, you can use the following options:

       success-send-mail [y/n]
              A  boolean  parameter  that controls whether a mail will be sent
              after successful completition of the fax job.

       failure-send-mail [y/n]
              A boolean parameter that controls whether a mail  will  be  sent
              after  the  fax  job  has failed more than the maximum number of
              times.

       success-call-program <name>
              Here, you can specify a program that will be run  when  the  fax
              has  been  successfully sent. It will be passed two command line
              parameters. The first is the full path to the fax JOB file  (see
              faxq(5)),  the  second  is  the last exit code from sendfax (for
              success-call-program, this is always "0").

       failure-call-program <name>
              Similar to the "success-call-program", this program will be  run
              when  the  fax  has been failed too often and faxrunqd gives up.
              This script could, for example, print out the fax on  a  printer
              so that it can be sent manually on a paper fax machine.

       update-call-program <name>
              This  is,  again, similar to "success-call-program".  It will be
              called for interim status  updates  ("we’ve  tried  and  it  was
              BUSY"),  so that frontend programs can display this information.
              "update-call-program" will only be called for jobs that will  be
              kept in the fax queue for at least one more try.

       maxfail-costly <n>
              This  specifies  the  number  of  times  that  a  fax  may  fail
              "fatally", that is, causing telephone costs  (explained  above).
              The default value is 5.

       maxfail-total <m>
              This  is the absolute maximum number of times that faxrunqd will
              try to send any given fax. The default value is 10.

       delete-sent-jobs [y/n]
              Determines whether faxrunqd should delete jobs after sending, or
              leave  them  in  the  fax  queue (while moving the "JOB" file to
              "JOB.done") so that they can  be  seen  at  by  "faxq  -o".  The
              default value is "do not delete sent faxes".

       acct-log <path>
              Specifies  where faxrunqd should protocol success and failure of
              each  try  to  send  a  fax  job.   The  default   location   is
              /var/spool/fax/outgoing/acct.log.

       The options that are specific to faxrunqd are:

       fax-devices [tty(s)]
              Specifies  which ttys should be used for sending jobs.  faxrunqd
              will always explicitely tell sendfax which modem to use, so  the
              settings  in  sendfax.config  are  ignored.   If  you use policy
              routing (see below), this applies only to fax jobs that  do  not
              have a tty set by faxrunqd.policy.

       faxrunqd-log [filename]
              Specifies where logging information is written to.  This is only
              used if faxrunqd is called with the -v or -d option.

       policy-config [filename]
              Specifies a file containing  rules  for  "policy  routing",  see
              below.  Default is "no file".

       faxrunqd-max-pages [n]
              If  this is set to something greater 1 (default is 10), faxrunqd
              will combine multiple jobs  to  the  same  receipient  telephone
              number  into  one  telephone  call.  The maximum number of pages
              that the resulting job may have is specified here.   Usually  it
              makes  no  sense  to  increase this, but in some surroundings it
              might make sense to turn off this feature by setting it to 1.

       sendfax-tty-map [tty] [program path] [args]
              Some special cases might require running a  non-default  sendfax
              binary  for  specific  ttys (like "testing new version" or "some
              other  call-compatible  sendfax  applications  for   non-class-2
              modems").   If you want mappings for more than one "special" tty
              devices, just use the option multiple times.  Example:

              sendfax-tty-map capi0 /usr/sbin/sendfax.capi

       queue-length-high [number] [program path] [args]
              run the specified command when the number of  jobs  in  the  fax
              queue  exceeds  number (this could be used to send out a warning
              by syslog or e-mail when too many modems fail on a busy  system,
              and  faxes get stuck).  The script will be run only once, unless
              the queue length falls below the ‘‘low  water  mark’’  threshold
              and rises again later on.

       queue-length-low [number] [program path] [args]
              run  the  specified  command when the queue length has been over
              the ‘‘high water’’ threshold, and is  back  below  this  number.
              This  can  be  used  to send ‘‘everything is back to normal’’ e-
              mails, or just to reset the alarm threshold.

       modem-error-threshold [number] [program path] [args]
              this script is called whenever  a  given  modem  has  more  than
              number  consecutive  errors.  Every successfully sent fax always
              resets the counter for a given modem to 0.  This can be used  to
              notify  the  sysadmin  when a modem breaks (by default, faxrunqd
              just phases out a problematic modem, but  will  not  report  the
              problem).

POLICY ROUTING

       faxrunqd  can do some things differently, depending on the phone number
       where the fax is supposed to be sent to.  For example,  this  might  be
       useful to:

       -  send  in-house  faxes  over a specific modem connected to a PABX (to
       avoid paying telco charges)

       - send long-distance faxes to the US over a special LD  provider,  that
       is, use a specific dial-prefix for those

       -  use  extra  high debugging when sending to a known-to-be problematic
       receipient

       etc.

       This feature is controlled by a file,  containing  match  /  substitute
       rules.   The  name  of  the  file is specified with the "policy-config"
       option in faxrunq.config.

       The file is read from top to bottom.  Each line  starting  with  a  "#"
       sign  is  a  comment,  and  is skipped.  In every other line, the first
       field of the line is interpreted as a "match" clause, and  compared  to
       the  telefone number of an to-be-sent fax job.  Regular expressions can
       be used (see perlre(1)).

       If the telefone  number  is  matched,  the  second  field  is  used  to
       substitute  parts  of the telefone number, for example, cut off a local
       prefix, or change a digit,  or  whatever.   If  you  do  not  want  any
       substitutions, put a "-" in that field.

       The  third  field  specifies  the tty lines to use for faxes matched by
       this line (for example, you might have one modem connected to  a  long-
       distance  provider, and others for local use or so).  Put a "-" in this
       field if you want to use the default fax modems.

       The remaining part of the line are  appended  to  the  sendfax  command
       line.  With those, you can set a different dial-string ("-D ATD"), or a
       higher debug level ("-x 9"), or whatever else you can imagine.  Do  NOT
       set  a  tty  to  use  here ("-l ttyS1"), because that would confuse the
       internal tty handling of faxrunqd, leading to weird effects  processing
       the fax queue!!

       Examples:

       # 12345-nnn is sent to "nnn" over a local PABX, modem on tty2

       ^12345         s/12345// tty2

       # fax to 56789 (exact match) is sent with higher debugging

       ^56789$        -         -    -x 8

FILES

       /var/spool/fax/outgoing/stop
              if  this  file exists, faxrunqd will stop whatever it’s doing at
              the moment, wait for all outstanding jobs, and then fall  asleep
              until  the  file  is  removed.   You  can use this to stop queue
              processing while testing something, or  if  you  know  that  the
              modem(s)  are  unavailable and do not want to run into any error
              messages, etc.

       /var/spool/fax/outgoing/faxqueue_done
              Every time faxrunqd runs the fax queue, a time stamp is  written
              into  that file.  It is used by faxspool to display a warning if
              the queue hasn’t been run recently (so faxes may get stuck).

SIGNALS

       To control faxrunqds behaviour, you can send it the following signals:

       SIGINT

       SIGTERM
              remove lock file, remove pid file, terminate immediately.

       SIGHUP finish  all  fax  jobs  that  are  currently  being  sent,  then
              terminate  (this is used to  signal  faxrunqd  "I  want  you  to
              terminate"  without  disturbing  the  normal flow of operation -
              SIGINT/TERM etc. can lead to some faxes being sent twice).

       SIGUSR1
              close, roll, and re-open log file.

       SIGUSR2
              dump current modem success/failure statistics to log file.

BUGS

       faxrunqd does not report if a modem goes bad -  instead  it  will  just
       stop  using  it  (which  is good for reliable faxing, but bad for error
       recovery).

SEE ALSO

       faxspool(1), sendfax(8), faxq(1), faxrunq(1), faxqueue(5)

AUTHOR

       faxrunqd   is   Copyright    (C)    1997-2004    by    Gert    Doering,
       <gert@greenie.muc.de>.    It  was  inspired  by  Bodo  Bauer’s  initial
       faxrunqd, but completely rewritten.