1faxrunqd(1)                  mgetty+sendfax manual                 faxrunqd(1)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

12       Runs  in  the background, and regularily checks the fax queue set up by
13       faxspool(1).  Sends all jobs that are due, records results,  and  takes
14       appropriate action (notify mails etc).
15
16       faxrunqd  basically  does the same as faxrunq(1), just more so.  Please
17       read the faxrunq(1) man page if you're not already  familiar  with  the
18       concept.
19
20       The advantages of faxrunqd are:
21
22       -  runs  all  the time, so you don't have to set up a cron job (but you
23       have to set up an entry in /etc/inittab or start it from /etc/rc*)
24
25       - quicker response to new faxes in queue
26
27       - can sensibly handle more than one modem
28
29       - can handle prioritized fax jobs
30
31       - can do 'policy routing' of faxes depending on the fax number
32
33       The disadvantages are:
34
35       - needs more system ressources if you have only little fax traffic
36
37       - requires Perl 5.004
38
39       - more tricky to set up and to debug
40
41

SETUP

43       faxrunqd is started at system boot from /etc/rc.*, or  from  /etc/init‐
44       tab.   You  can  also  start  it from the command line. It does not put
45       itself in the background, so you have to start it with an "&", or  from
46       a ":respawn:" line in /etc/inittab.   Using /etc/inittab has the advan‐
47       tage that faxrunqd is restarted automatically if something  goes  wrong
48       and faxrunqd is stopped.
49
50       faxrunqd  will first read a global configuration file (see below), then
51       (optionally) the faxrunqd policy file (see further below).   From  then
52       on, it will sit in a loop. It will check the fax queue every 60 seconds
53       for new jobs, and will then distribute them over all available  modems.
54       If  the  job  is  sent,  or fails, it will do the same thing faxrunq(1)
55       would do (send a mail, delete the JOB directory, execute a  named  pro‐
56       gram, etc.).  Both programs are fully compatible in this respect.
57
58       faxrunqd [-v] [-d] [-l <ttys>] [-u <user>] [-V]
59

OPTIONS

61       -v     Tells faxrunqd to write progress information to the log file.
62
63       -d     Tells  faxrunqd to write debugging information to stdout and the
64              log file (usually used together with -v)
65
66       -l <ttyS>
67              Specifies the list of modem devices to  use.   Multiple  devices
68              are separated with ':', e.g. '-l ttyS0:ttyS1'.
69
70       -u <user>
71              faxrunqd  can  now  (since 1.1.29) run as unprivileged user.  If
72              you start it as root  from  /etc/inittab  or  from  one  of  the
73              /etc/rc*  scripts, it's strongly recommended to use '-u fax' (to
74              be precise: the user that  is  owning  the  outgoing  fax  spool
75              directory).   This will make faxrunqd drop all its privileges at
76              startup, and run as the specified  user.   Running  faxrunqd  as
77              root user might lead to security problems - don't do it.
78
79       -V     print version number and exit
80
81

CONFIGURATION FILE

83       Some  aspects  of the behaviour of faxrunqd can be controlled by a con‐
84       figuration file, usually named /etc/mgetty+sendfax/faxrunq.config (this
85       is the same file that faxrunq(1) uses, but there are additional options
86       for faxrunqd). In this file, you can use the following options:
87
88       success-send-mail [y/n]
89              A boolean parameter that controls whether a mail  will  be  sent
90              after successful completition of the fax job.
91
92
93       failure-send-mail [y/n]
94              A  boolean  parameter  that controls whether a mail will be sent
95              after the fax job has failed more than  the  maximum  number  of
96              times.
97
98
99       success-call-program <name>
100              Here,  you  can  specify a program that will be run when the fax
101              has been successfully sent. It will be passed two  command  line
102              parameters.  The first is the full path to the fax JOB file (see
103              faxq(5)), the second is the last exit  code  from  sendfax  (for
104              success-call-program, this is always "0").
105
106
107       failure-call-program <name>
108              Similar  to the "success-call-program", this program will be run
109              when the fax has been failed too often and  faxrunqd  gives  up.
110              This  script  could, for example, print out the fax on a printer
111              so that it can be sent manually on a paper fax machine.
112
113
114       update-call-program <name>
115              This is, again, similar to "success-call-program".  It  will  be
116              called  for  interim  status  updates  ("we've  tried and it was
117              BUSY"), so that frontend programs can display this  information.
118              "update-call-program"  will only be called for jobs that will be
119              kept in the fax queue for at least one more try.
120
121
122       maxfail-costly <n>
123              This  specifies  the  number  of  times  that  a  fax  may  fail
124              "fatally",  that  is, causing telephone costs (explained above).
125              The default value is 5.
126
127
128       maxfail-total <m>
129              This is the absolute maximum number of times that faxrunqd  will
130              try to send any given fax. The default value is 10.
131
132
133       delete-sent-jobs [y/n]
134              Determines whether faxrunqd should delete jobs after sending, or
135              leave them in the fax queue (while  moving  the  "JOB"  file  to
136              "JOB.done")  so  that  they  can  be  seen  at by "faxq -o". The
137              default value is "do not delete sent faxes".
138
139
140       acct-log <path>
141              Specifies where faxrunqd should protocol success and failure  of
142              each   try   to  send  a  fax  job.   The  default  location  is
143              /var/spool/fax/outgoing/acct.log.
144
145
146       The options that are specific to faxrunqd are:
147
148
149       fax-devices [tty(s)]
150              Specifies which ttys should be used for sending jobs.   faxrunqd
151              will  always explicitely tell sendfax which modem to use, so the
152              settings in sendfax.config are ignored.  If you use policy rout‐
153              ing  (see below), this applies only to fax jobs that do not have
154              a tty set by faxrunqd.policy.
155
156
157       faxrunqd-log [filename]
158              Specifies where logging information is written to.  This is only
159              used if faxrunqd is called with the -v or -d option.
160
161
162       policy-config [filename]
163              Specifies  a  file  containing  rules  for "policy routing", see
164              below.  Default is "no file".
165
166
167       faxrunqd-max-pages [n]
168              If this is set to something greater 1 (default is 10),  faxrunqd
169              will combine multiple jobs to the same receipient telephone num‐
170              ber into one telephone call.  The maximum number of  pages  that
171              the  resulting job may have is specified here.  Usually it makes
172              no sense to increase this, but in  some  surroundings  it  might
173              make sense to turn off this feature by setting it to 1.
174
175
176       sendfax-tty-map [tty] [program path] [args]
177              Some  special  cases might require running a non-default sendfax
178              binary for specific ttys (like "testing new  version"  or  "some
179              other   call-compatible  sendfax  applications  for  non-class-2
180              modems").  If you want mappings for more than one "special"  tty
181              devices, just use the option multiple times.  Example:
182
183              sendfax-tty-map capi0 /usr/sbin/sendfax.capi
184
185
186       queue-length-high [number] [program path] [args]
187              run  the  specified  command  when the number of jobs in the fax
188              queue exceeds number (this could be used to send out  a  warning
189              by  syslog or e-mail when too many modems fail on a busy system,
190              and faxes get stuck).  The script will be run only once,  unless
191              the  queue  length  falls below the ``low water mark'' threshold
192              and rises again later on.
193
194
195       queue-length-low [number] [program path] [args]
196              run the specified command when the queue length  has  been  over
197              the  ``high  water''  threshold,  and is back below this number.
198              This can be used to send ``everything is  back  to  normal''  e-
199              mails, or just to reset the alarm threshold.
200
201
202       modem-error-threshold [number] [program path] [args]
203              this  script is called whenever a given modem has more than num‐
204              ber consecutive errors.   Every  successfully  sent  fax  always
205              resets  the counter for a given modem to 0.  This can be used to
206              notify the sysadmin when a modem breaks  (by  default,  faxrunqd
207              just  phases  out  a  problematic modem, but will not report the
208              problem).
209
210
211

POLICY ROUTING

213       faxrunqd can do some things differently, depending on the phone  number
214       where  the  fax  is supposed to be sent to.  For example, this might be
215       useful to:
216
217       - send in-house faxes over a specific modem connected  to  a  PABX  (to
218       avoid paying telco charges)
219
220       -  send  long-distance faxes to the US over a special LD provider, that
221       is, use a specific dial-prefix for those
222
223       - use extra high debugging when sending to  a  known-to-be  problematic
224       receipient
225
226       etc.
227
228       This  feature  is  controlled  by a file, containing match / substitute
229       rules.  The name of the file  is  specified  with  the  "policy-config"
230       option in faxrunq.config.
231
232       The  file  is  read  from top to bottom.  Each line starting with a "#"
233       sign is a comment, and is skipped.  In  every  other  line,  the  first
234       field  of  the line is interpreted as a "match" clause, and compared to
235       the telefone number of an to-be-sent fax job.  Regular expressions  can
236       be used (see perlre(1)).
237
238       If  the telefone number is matched, the second field is used to substi‐
239       tute parts of the telefone number, for example, cut off a local prefix,
240       or  change a digit, or whatever.  If you do not want any substitutions,
241       put a "-" in that field.
242
243       The third field specifies the tty lines to use  for  faxes  matched  by
244       this  line  (for example, you might have one modem connected to a long-
245       distance provider, and others for local use or so).  Put a "-" in  this
246       field if you want to use the default fax modems.
247
248       The  remaining  part  of  the  line are appended to the sendfax command
249       line.  With those, you can set a different dial-string ("-D ATD"), or a
250       higher  debug  level ("-x 9"), or whatever else you can imagine. Do NOT
251       set a tty to use here ("-l ttyS1"),  because  that  would  confuse  the
252       internal  tty handling of faxrunqd, leading to weird effects processing
253       the fax queue!!
254
255       Examples:
256
257       # 12345-nnn is sent to "nnn" over a local PABX, modem on tty2
258
259       ^12345         s/12345// tty2
260
261       # fax to 56789 (exact match) is sent with higher debugging
262
263       ^56789$        -         -    -x 8
264
265
266

FILES

268       /var/spool/fax/outgoing/stop
269              if this file exists, faxrunqd will stop whatever it's  doing  at
270              the  moment, wait for all outstanding jobs, and then fall asleep
271              until the file is removed.  You can use this to stop queue  pro‐
272              cessing  while  testing  something,  or  if  you  know  that the
273              modem(s) are unavailable and do not want to run into  any  error
274              messages, etc.
275
276
277       /var/spool/fax/outgoing/faxqueue_done
278              Every  time faxrunqd runs the fax queue, a time stamp is written
279              into that file.  It is used by faxspool to display a warning  if
280              the queue hasn't been run recently (so faxes may get stuck).
281
282

SIGNALS

284       To control faxrunqd's behaviour, you can send it the following signals:
285
286
287       SIGINT
288
289       SIGTERM
290              remove lock file, remove pid file, terminate immediately.
291
292
293       SIGHUP finish  all  fax jobs that are currently being sent, then termi‐
294              nate  (this is used to signal faxrunqd "I want you to terminate"
295              without  disturbing  the  normal flow of operation - SIGINT/TERM
296              etc. can lead to some faxes being sent twice).
297
298
299       SIGUSR1
300              close, roll, and re-open log file.
301
302
303       SIGUSR2
304              dump current modem success/failure statistics to log file.
305
306

BUGS

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

SEE ALSO

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

AUTHOR

317       faxrunqd is  Copyright  (C)  1997-2004  by  Gert  Doering,  <gert@gree‐
318       nie.muc.de>.   It  was  inspired  by Bodo Bauer's initial faxrunqd, but
319       completely rewritten.
320
321
322
323greenie                            23 Nov 02                       faxrunqd(1)
Impressum