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
188 faxrunqd can do some things differently, depending on the phone number
189 where the fax is supposed to be sent to. For example, this might be
190 useful to:
191 - send in-house faxes over a specific modem connected to a PABX (to
193 avoid paying telco charges)
194 - send long-distance faxes to the US over a special LD provider, that
196 is, use a specific dial-prefix for those
197 - use extra high debugging when sending to a known-to-be problematic
199 receipient
200 etc.
202 This feature is controlled by a file, containing match / substitute
204 rules. The name of the file is specified with the "policy-config"
205 option in faxrunq.config.
206 The file is read from top to bottom. Each line starting with a "#"
208 sign is a comment, and is skipped. In every other line, the first
209 field of the line is interpreted as a "match" clause, and compared to
210 the telefone number of an to-be-sent fax job. Regular expressions can
211 be used (see perlre(1)).
212 If the telefone number is matched, the second field is used to substi‐
214 tute parts of the telefone number, for example, cut off a local prefix,
215 or change a digit, or whatever. If you do not want any substitutions,
216 put a "-" in that field.
217 The third field specifies the tty lines to use for faxes matched by
219 this line (for example, you might have one modem connected to a long-
220 distance provider, and others for local use or so). Put a "-" in this
221 field if you want to use the default fax modems.
222 The remaining part of the line are appended to the sendfax command
224 line. With those, you can set a different dial-string ("-D ATD"), or a
225 higher debug level ("-x 9"), or whatever else you can imagine. Do NOT
226 set a tty to use here ("-l ttyS1"), because that would confuse the
227 internal tty handling of faxrunqd, leading to weird effects processing
228 the fax queue!!
229 Examples:
231 # 12345-nnn is sent to "nnn" over a local PABX, modem on tty2
233 ^12345 s/12345// tty2
235 # fax to 56789 (exact match) is sent with higher debugging
237 ^56789$ - - -x 8
239
243 /var/spool/fax/outgoing/stop
244 if this file exists, faxrunqd will stop whatever it's doing at
245 the moment, wait for all outstanding jobs, and then fall asleep
246 until the file is removed. You can use this to stop queue pro‐
247 cessing while testing something, or if you know that the
248 modem(s) are unavailable and do not want to run into any error
249 messages, etc.
250 /var/spool/fax/outgoing/faxqueue_done
253 Every time faxrunqd runs the fax queue, a time stamp is written
254 into that file. It is used by faxspool to display a warning if
255 the queue hasn't been run recently (so faxes may get stuck).
256
259 To control faxrunqd's behaviour, you can send it the following signals:
260 SIGINT
263 SIGTERM
265 remove lock file, remove pid file, terminate immediately.
266 SIGHUP finish all fax jobs that are currently being sent, then termi‐
269 nate (this is used to signal faxrunqd "I want you to terminate"
270 without disturbing the normal flow of operation - SIGINT/TERM
271 etc. can lead to some faxes being sent twice).
272 SIGUSR1
275 close, roll, and re-open log file.
276 SIGUSR2
279 dump current modem success/failure statistics to log file.
280
283 faxrunqd does not report if a modem goes bad - instead it will just
284 stop using it (which is good for reliable faxing, but bad for error
285 recovery).
286
289 faxspool(1), sendfax(8), faxq(1), faxrunq(1), faxqueue(5)
290
292 faxrunqd is Copyright (C) 1997-2004 by Gert Doering, <gert@gree‐
293 nie.muc.de>. It was inspired by Bodo Bauer's initial faxrunqd, but
294 completely rewritten.
295greenie 23 Nov 02 faxrunqd(1)