1faxrunqd(1) mgetty+sendfax manual faxrunqd(1)
2
6 faxrunqd - daemon to send fax jobs queued by faxspool(1)
7
9 faxrunqd [-v] [-d] [-l <ttys>] [-u <user>] [-V]
10
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 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 The advantages of faxrunqd are:
21 - 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 - quicker response to new faxes in queue
26 - can sensibly handle more than one modem
28 - can handle prioritized fax jobs
30 - can do 'policy routing' of faxes depending on the fax number
32 The disadvantages are:
34 - needs more system ressources if you have only little fax traffic
36 - requires Perl 5.004
38 - more tricky to set up and to debug
40
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 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 faxrunqd [-v] [-d] [-l <ttys>] [-u <user>] [-V]
59
61 -v Tells faxrunqd to write progress information to the log file.
62 -d Tells faxrunqd to write debugging information to stdout and the
64 log file (usually used together with -v)
65 -l <ttyS>
67 Specifies the list of modem devices to use. Multiple devices
68 are separated with ':', e.g. '-l ttyS0:ttyS1'.
69 -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 -V print version number and exit
80
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 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 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 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 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 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 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 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 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 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 The options that are specific to faxrunqd are:
147 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 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 policy-config [filename]
163 Specifies a file containing rules for "policy routing", see
164 below. Default is "no file".
165 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 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 sendfax-tty-map capi0 /usr/sbin/sendfax.capi
184 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 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 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 delay-rule [errcode] [delay1] [delay2] [...]
212 fine-tune how long faxrunqd waits before re-sending a failed job
213 after sendfax returned with error code "errcode". "delay1" is
214 used after the first try, "delay2" after the second try, and so
215 on. If faxrunqd needs more tries than delay values are speci‐
216 fied, the last one will be re-used. The values given are inter‐
217 preted as seconds, unless postfixed with 'm' (e.g. "60m"), in
218 which case they are interpreted as minutes.
219
222 faxrunqd can do some things differently, depending on the phone number
223 where the fax is supposed to be sent to. For example, this might be
224 useful to:
225 - send in-house faxes over a specific modem connected to a PABX (to
227 avoid paying telco charges)
228 - send long-distance faxes to the US over a special LD provider, that
230 is, use a specific dial-prefix for those
231 - use extra high debugging when sending to a known-to-be problematic
233 receipient
234 etc.
236 This feature is controlled by a file, containing match / substitute
238 rules. The name of the file is specified with the "policy-config"
239 option in faxrunq.config.
240 The file is read from top to bottom. Each line starting with a "#"
242 sign is a comment, and is skipped. In every other line, the first
243 field of the line is interpreted as a "match" clause, and compared to
244 the telefone number of an to-be-sent fax job. Regular expressions can
245 be used (see perlre(1)).
246 If the telefone number is matched, the second field is used to substi‐
248 tute parts of the telefone number, for example, cut off a local prefix,
249 or change a digit, or whatever. If you do not want any substitutions,
250 put a "-" in that field.
251 The third field specifies the tty lines to use for faxes matched by
253 this line (for example, you might have one modem connected to a long-
254 distance provider, and others for local use or so). Put a "-" in this
255 field if you want to use the default fax modems.
256 The remaining part of the line are appended to the sendfax command
258 line. With those, you can set a different dial-string ("-D ATD"), or a
259 higher debug level ("-x 9"), or whatever else you can imagine. Do NOT
260 set a tty to use here ("-l ttyS1"), because that would confuse the
261 internal tty handling of faxrunqd, leading to weird effects processing
262 the fax queue!!
263 Examples:
265 # 12345-nnn is sent to "nnn" over a local PABX, modem on tty2
267 ^12345 s/12345// tty2
269 # fax to 56789 (exact match) is sent with higher debugging
271 ^56789$ - - -x 8
273
277 /var/spool/fax/outgoing/stop
278 if this file exists, faxrunqd will stop whatever it's doing at
279 the moment, wait for all outstanding jobs, and then fall asleep
280 until the file is removed. You can use this to stop queue pro‐
281 cessing while testing something, or if you know that the
282 modem(s) are unavailable and do not want to run into any error
283 messages, etc.
284 /var/spool/fax/outgoing/faxqueue_done
287 Every time faxrunqd runs the fax queue, a time stamp is written
288 into that file. It is used by faxspool to display a warning if
289 the queue hasn't been run recently (so faxes may get stuck).
290
293 To control faxrunqd's behaviour, you can send it the following signals:
294 SIGINT
297 SIGTERM
299 remove lock file, remove pid file, terminate immediately.
300 SIGHUP finish all fax jobs that are currently being sent, then termi‐
303 nate (this is used to signal faxrunqd "I want you to terminate"
304 without disturbing the normal flow of operation - SIGINT/TERM
305 etc. can lead to some faxes being sent twice).
306 SIGUSR1
309 close, roll, and re-open log file.
310 SIGUSR2
313 dump current modem success/failure statistics to log file.
314
317 faxrunqd does not report if a modem goes bad - instead it will just
318 stop using it (which is good for reliable faxing, but bad for error
319 recovery).
320
323 faxspool(1), sendfax(8), faxq(1), faxrunq(1), faxqueue(5)
324
326 faxrunqd is Copyright (C) 1997-2004 by Gert Doering, <gert@gree‐
327 nie.muc.de>. It was inspired by Bodo Bauer's initial faxrunqd, but
328 completely rewritten.
329greenie 23 Nov 02 faxrunqd(1)