faxrunqd



faxrunqd(1)                  mgetty+sendfax manual                 faxrunqd(1)




NAME

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


SYNOPSIS

       faxrunqd [-v] [-d] [-l <ttys>] [-u <user>] [-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/init-
       tab.   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 advan-
       tage 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  pro-
       gram, etc.).  Both programs are fully compatible in this respect.

       faxrunqd [-v] [-d] [-l <ttys>] [-u <user>] [-V]


OPTIONS

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

       -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>
              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 fax’ (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.

       -V     print version number and exit



CONFIGURATION FILE

       Some  aspects  of the behaviour of faxrunqd can be controlled by a con-
       figuration file, usually named /etc/mgetty+sendfax/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 rout-
              ing  (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 num-
              ber 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  substi-
       tute 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 pro-
              cessing 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 termi-
              nate  (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@gree-
       nie.muc.de>.   It  was  inspired  by Bodo Bauer’s initial faxrunqd, but
       completely rewritten.



greenie                            23 Nov 02                       faxrunqd(1)

Man(1) output converted with man2html