faxspool



faxspool(1)                  mgetty+sendfax manual                 faxspool(1)




NAME

       faxspool - queue and convert files for faxing with sendfax(8)


SYNOPSIS

       faxspool [options] phone-number files...


DESCRIPTION

       Queue  the  named  files  for  later transmission with sendfax(8).  The
       input   files   are   converted   to   G3   fax   files,   spooled   to
       /var/spool/fax/outgoing/<dir>/f*.g3, and queued for transmsssion to the
       fax address "phone-number".

       On top of each page, faxspool puts a header  line,  telling  the  other
       side the number of pages, your fax id, ..., whatever you like. The for-
       mat of this line is configurable via the file  /etc/mgetty+sendfax/fax-
       header  and  per-user  via  the file $HOME/.faxheader.  (you can select
       another one with the "-h" option, for example, one  for  your  business
       faxes and one for the private stuff).

       This  file  should contain a few lines of text, normally only one line,
       but more than one line is permitted. The text may use  the  tokens  @T@
       for the remote telephone number, @U@ for the sending user name, @N@ for
       his full name (fifth field of /etc/passwd, if not given with "-F"), @P@
       for  the page number and @M@ for the total number of pages. @D@ will be
       replaced by the string specified with  the  "-D"  option  (see  below),
       @DATE@  will  be  substituted  by the output of the ‘date‘ command, and
       @ID@ stands for the sender’s fax number (FAX_STATION_ID).

       If "phone-number" contains non-numeric characters, faxspool  interprets
       it  as  an alias and tries to look it up in the files /etc/mgetty+send-
       fax/faxaliases and $HOME/.faxnrs.  These files have a very simple  for-
       mat:  one  line per alias, alias name first, whitespace (tab or blank),
       phone number. Optionally, you can place  a  short  description  of  the
       receiver  after  the  phone number, this will be used as if it had been
       specified with "-D" (an explicit "-D" flag overrides this).

       Example: gert 0893244814 Gert Doering


       Access control is handled similar to the way "crontab" does  it:  if  a
       file  /etc/mgetty+sendfax/fax.allow  exists, only those users listed in
       that file (one name per line) may use the fax service. If it  does  not
       exist,  but  a  file /etc/mgetty+sendfax/fax.deny exists, all users but
       those listed in that file may use  faxspool(1),  and  if  neither  file
       exists,  only  root  may  send  faxes.  (Note:  if the user name in the
       fax.allow file is followed by  a  blank,  the  rest  of  that  line  is
       ignored. Some other fax spooling software uses this to store additional
       information about the user sending the request).


       Optionally, faxspool can generate user-customizable fax cover pages. It
       is quite easy to set up: if a file /usr/lib/mgetty+sendfax/make.coverpg
       exists and is executable, it is run with all  relevant  source/destina-
       tion data on the command line, and its output is sent as the first page
       of the resulting fax. If $HOME/.make.coverpg exists, this file is  used
       instead. See coverpg(1) for details.



OPTIONS

       -n     Tells  faxspool  to  use  normal  resolution  (as opposed to the
              default, fine resolution) both when converting files to G3  for-
              mat and when transmitting (no effect on pbm files)

       -h <text file>
              Use  <text file> for the FAX header line(s).  The default format
              file for faxspool is  /etc/mgetty+sendfax/faxheader.  -  means
              no header line.

       -q     do  not output progress messages (file ... is format ..., spool-
              ing to ...).  Error messages will be seen anyway.

       -f <mail address>
              Use the address given for the status mail that faxrunq(1)  sends
              after completing / dequeueing the request. If no mail address is
              specified, the requesting user (on the local machine)  gets  the
              mail.

       -u <user name>
              Do  not  use the current user ID for authentication purposes but
              the user name specified. Since this can lead to easy  breach  of
              security,  only  "trusted"  users  may use this flag. Currently,
              those users are "root", "lp" and "daemon"  (hardwired  into  the
              code).  Note:  the status mail will still go to the user running
              faxspool(1) unless changed with "-f".

       -D <destination>
              Verbose form of the fax’s destination. Used  only  for  informa-
              tional  purposes, that is, faxq(1) will show it, faxrunq(1) will
              put it into the return mail ("Subject: your fax to ..."), and  a
              @D@ in the page header will be replaced by it.

       -F <description>
              Full  name  or  similar  description of the sending user (if not
              specified, the full name field from /etc/passwd will  be  used).
              Used  only for informational purposes, that is, faxspool(1) will
              substitute a @N@ in the page header file with it, and it will be
              passed to the cover page program (if used) as <sender-NAME>.

       -P <priority>
              Sets  the  priority of the fax in the queue. 9 is highest (mean-
              ing: faxes get sent out first), 1 is lowest. If nothing is spec-
              ified,  a  default  value of 5 is used. Right now, only faxrunqd
              understands priority, faxrunq will silently ignore it.

       -C <cover page program>
              Specify that the named program is to be used to generate a cover
              page for the fax that is being queued. How the program is called
              is described in the coverpg(1) manpage.

              The special program name "-" is used to specify "no coverpage at
              all".

              No  message  is  issued if the program isn’t found, or cannot be
              executed, faxspool will simply queue the fax without cover page.

              The  default  cover page program used is $HOME/.make.coverpg; if
              this file doesn’t exist /usr/lib/mgetty+sendfax/make.coverpg  is
              used.  (However,  if $HOME/.make.coverpg exists, but is not exe-
              cutable, no coverpage is used at all.)

       -p     Spool a request that will try polling (see  "sendfax  -p").  The
              implementation isn’t too smart yet, the polled files will simply
              go into the job’s spool directory.

       -t <hh:mm>
              Don’t send the fax before the time given. It  may  not  be  sent
              exactly  at  <hh:mm>, but the first time faxrunq runs after that
              time. If the fax cannot be sent successfully before midnight, it
              won’t be sent on the next day until <hh:mm>!

       -t <hh:mm>-<hh:mm>
              Only  send  the  fax  in the time range between those two times.
              This is only implemented in faxrunqd.  If the second time speci-
              fied  is  ’earlier’  than the first time, it is interpreted as a
              time range crossing midnight.

       -A <data>
              pass faxspool a chunk of data that is ignored (so  you  can  put
              anything  you  want  here),  but  written  to  all the log files
              (acct.log, sendfax.log).  This can be used to tag faxes as  pri-
              vate/corporate,  to  tag  faxes  with the customer ID to use for
              billing, or something along that lines.

       -m <phone1> <phone2> <phone3> ... --
              Multicasting - send the specified files to all phone numbers  in
              the  list  given  after  "-m". The list is terminated with "--".
              "-m" has to be the last option on the command line.

       -M <file name>
              Multicasting - read a list of telephone numbers to send the  fax
              to from the given file. Do not use in conjunction with "-m".

       -c     Copy source files to a sub directory ".source-files/" in the fax
              queue directory (most likely, you  won’t  ever  need  this  -  I
              needed  it  for  one project, so it’s here and documented. Don’t
              ask what it’s good for).


FILES

       /var/spool/fax/outgoing/*
              fax spool directory

       /etc/mgetty+sendfax/faxaliases
              global fax alias file

       $HOME/.faxnrs
              private fax alias file

       /etc/mgetty+sendfax/fax.allow
              list of allowed users

       /etc/mgetty+sendfax/fax.deny
              list of denied users

       /etc/mgetty+sendfax/faxheader
              default fax page header

       /usr/lib/mgetty+sendfax/make.coverpg
              program to create fax cover page (see coverpg(1)).

       /etc/mgetty+sendfax/faxspool.rules
              program to control which file extentions are  recognized  (.txt,
              .ps, ...)  and how those file formats should be converted to G3.

       /usr/lib/mgetty+sendfax/faxq-helper
              this a small C helper program that facilitates access to the fax
              spool queue (which is since mgetty 1.1.29 no longer world-write-
              able)



BUGS

       faxspool is not too smart about recognizing file types

       Use of faxspool -n with bitmap files may give wrong results,  depending
       on the aspect ratio of the input files.

       Multicasting with the -m and -M options is not implemented yet.



SEE ALSO

       g3cat(1),  pbm2g3(1),  sendfax(8),  faxrunq(1),  faxrunqd(8),  faxq(1),
       faxqueue(5), coverpg(1)


AUTHOR

       faxspool is  Copyright  (C)  1993-2002  by  Gert  Doering,  <gert@gree-
       nie.muc.de>.   Access  control  and  alias  handling  suggested  by Caz
       Yokoyama, <caz@shoki.osk.psq.mei.co.jp>.



greenie                            23 Nov 02                       faxspool(1)

Man(1) output converted with man2html