Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
faxrunqd(1)		     mgetty+sendfax manual		   faxrunqd(1)

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

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

       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

       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

       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 it-
       self 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]

       -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 root' (to
	      be precise: the user that	is owning the outgoing fax  spool  di-
	      rectory).	  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

       Some  aspects  of the behaviour of faxrunqd can be controlled by	a con-
       figuration    file,    usually	 named	   /usr/local/etc/mgetty+send-
       fax/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

       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 "fa-
	      tally", 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  de-
	      fault 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

       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  be-
	      low.  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

       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  num-
	      ber  consecutive errors.	Every successfully sent	fax always re-
	      sets 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

       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	speci-
	      fied, the	last one will be re-used.  The values given are	inter-
	      preted as	seconds, unless	postfixed with 'm'  (e.g.  "60m"),  in
	      which case they are interpreted as minutes.

       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


       This feature is controlled by a file,  containing  match	 /  substitute
       rules.	The name of the	file is	specified with the "policy-config" op-
       tion 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 in-
       ternal tty handling of faxrunqd,	leading	to  weird  effects  processing
       the fax queue!!


       # 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

	      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  mo-
	      dem(s)  are  unavailable	and  do	not want to run	into any error
	      messages,	etc.

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

       To control faxrunqd's behaviour,	you can	send it	the following signals:


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

	      close, roll, and re-open log file.

	      dump current modem success/failure statistics to log file.

       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 re-

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

       faxrunqd	 is  Copyright	(C)  1997-2004	by  Gert  Doering, <gert@gree->.  It	was inspired by	Bodo  Bauer's  initial	faxrunqd,  but
       completely rewritten.

greenie				   23 Nov 02			   faxrunqd(1)


Want to link to this manual page? Use this URL:

home | help