faxrunqd man page on OpenSuSE

Man page or keyword search:  
man Server   25941 pages
apropos Keyword Search (all sections)
Output format
OpenSuSE logo
[printable version]

faxrunqd(1)		     mgetty+sendfax manual		   faxrunqd(1)

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

SYNOPSIS
       faxrunqd [-v] [-d] [-l <ttys>] [-u <user>] [-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/init‐
       tab.   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 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]

OPTIONS
       -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 fax' (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.

       -V     print version number and exit

CONFIGURATION FILE
       Some  aspects  of the behaviour of faxrunqd can be controlled by a con‐
       figuration file, usually named /etc/mgetty+sendfax/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 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
	      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 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
	      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).

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 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
       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  pro‐
	      cessing  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 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).

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

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

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

greenie				   23 Nov 02			   faxrunqd(1)
[top]

List of man pages available for OpenSuSE

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net