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

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).

delay-rule [errcode] [delay1] [delay2] [...]
fine-tune how long faxrunqd waits before re-sending a failed job after sendfax returned with error
code "errcode". "delay1" is used after the first try, "delay2" after the second try, and so on.
If faxrunqd needs more tries than delay values are specified, the last one will be re-used. The
values given are interpreted as seconds, unless postfixed with 'm' (e.g. "60m"), in which case
they are interpreted as minutes.

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 faxrunqd's 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).

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.