Provided by: mgetty-fax_1.1.33-3ubuntu2_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

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.