faxspool(1) / faxqueue(5): please comment
Gert Doering (gert@greenie.muc.de)
Thu, 3 Mar 1994 12:59:19 +0100
Hi,
I've just finished reworking much of faxspool and heavily extending the
format of the fax queue "JOB" file. I've written two manpages for that,
but want to make sure that they are easily understandable and that I did
not miss some important case.
So, please read the following man pages and send me your comments.
gert
::::::::::::::
faxspool.man
::::::::::::::
faxspool(1) mgetty+sendfax manual faxspool(1)
NAME
faxspool - queue and convert files for faxing with send-
fax(8)
SYNOPSIS
faxspool [options] phone-number file
DESCRIPTION
Queue the named files for later transmission with send-
fax(8). The input files are converted to G3 fax files,
spooled to /usr/spool/fax/outgoing/<dir>/f*.g3, and queued
for transmssion to the fax address "phone-number".
On top of each page, faxspool puts a header line, telling
the other side the number of pages, the sending fax id,
and whatever you like. The format of this line is
(finally) configurable via the file
/usr/local/lib/mgetty+sendfax/faxheader . This file
should contain a few lines text, at best, only one line.
This text may contain some tokes, that is, @T@ for the
remote telephone number, @U@ for the sending user name,
@P@ for the page number and @M@ for the total number of
pages.
If "phone-number" contains non-numeric characters,
faxspool interprets it as an alias and tries to look it up
in /usr/local/lib/mgetty+sendfax/aliases and $HOME/.faxnrs
. These files have a very simple format: one line per
alias, alias name first, blank, phone number.
Access control is handled similar to the way "crontab"
does it: if a file /usr/local/lib/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 /usr/local/lib/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 infor-
mations about the user sending the request).
OPTIONS
-n Tells faxspool to use normal resolution (as opposed
to the default, high resolution)
-q do not output progress messages (file ... is format
..., spooling to ...). Error messages will be seen
anyway.
-f <mail address>
Use the adress given for the status mail that
faxrunq(1) sends after comleting / dequeueing the
request. If no mail address is specified, the
greenie 27 Oct 93 1
faxspool(1) mgetty+sendfax manual faxspool(1)
requesting user (on the local machine) gets the
mail.
-u <user name>
Do not use the current user ID for authentification
purpose 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 informational purposes, that is, faxq(1) will
show it, and faxrunq(1) will put it into the return
mail ("Subject: your mail from ..."). Later, it
will also be put into the fax's page headers.
-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.
-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".
FILES
/usr/spool/fax/outgoing/*
fax spool directory
/usr/local/lib/mgetty+sendfax/aliases
global fax alias file
$HOME/.faxnrs
private fax alias file
/usr/local/lib/mgetty+sendfax/fax.allow
list of allowed users
/usr/local/lib/mgetty+sendfax/fax.deny
list of denied users
/usr/local/lib/mgetty+sendfax/faxheader
fax page header
greenie 27 Oct 93 2
faxspool(1) mgetty+sendfax manual faxspool(1)
BUGS
faxspool is not too smart about recognizing file types
faxspool does only do limited access control - if a user
can write to the fax spool directory, he can bypass the
"access control"
faxspool doesn't honour the "-n" flag
faxspool cannot do time scheduling
Multicasting with the -m and -M options are not imple-
mented yet.
SEE ALSO
g3cat(1), pbmtog3(1), sendfax(8), faxrunq(1), faxq(1),
faxqueue(5)
AUTHOR
faxspool is Copyright (C) 1993 by Gert Doering,
<gert@greenie.muc.de>. Access control and alias handling
suggested by Caz Yokoyama, <caz@shoki.osk.psq.mei.co.jp>.
greenie 27 Oct 93 3
::::::::::::::
faxqueue.man
::::::::::::::
faxqueue(5) mgetty+sendfax manual faxqueue(5)
NAME
faxqueue - sendfax fax spool queue control files
SYNOPSIS
/usr/spool/fax/outgoing/F*/JOB
DESCRIPTION
The JOB files in the subdirectories of the outgoing fax
spool directory, /usr/spool/fax/outgoing, build up a queue
of faxes to be sent by faxrunq(1). They are created by
faxspool(1), can be viewed with faxq(1), and be deleted by
faxrm(1).
FORMAT
The format of the JOB file is as follows:
Each line consists of a leading keyword and associated
data (rest of the line). Some are required, some others
are optional. The currently implemented keywords are:
phone <number>
The telephone number to send the fax to. Required.
user <user>
The originating user name (on the local machine).
If no "mail" field is present, this user will get
the status mails about the fax. Required.
mail <email>
If this field is present, faxrunq(1) will send its
status mails to the address given here. If not,
faxrunq(1) will use the "user" field. Optional.
input <file(s)>
The file names passed to faxspool(1). Optional,
used only by faxq(1).
pages <file(s)>
The file names, relative to the directory where the
JOB file is found, that are to be sent with send-
fax(1). The files have to exist, and be readable by
the user that runs faxrunq(1). Required.
Status <message>
Automatically appended by faxrunq(1) after each
run, tells the reader about successful and unsuc-
cessful tries to send this job. If more than five
"FATAL" errors are listed, the fax job is removed
from the queue.
verbose_to <blurb>
A plain-text description of the receiver of the
fax. Is returned, if present, in the mail messages
greenie 2 Feb 94 1
faxqueue(5) mgetty+sendfax manual faxqueue(5)
"your fax to <blurb>". Optional.
poll flag token. If present, faxrunq will try to poll
the given phone number for documents (see "sendfax
-p").
PROCESSING
While a given JOB file is processed by faxrunq(1), it's
locked against sending it multiple times by temorarily
renaming it to JOB.locked, thus it may happen that a
faxq(1) command doesn't show this job.
When a job is successfully sent, it's not deleted but the
JOB file is renamed to JOB.done. Because of this, you can
still see old jobs with "faxq -o". You should regularily
clean up the outgoing fax directory, removing old faxes.
If you don't want this behaviour, look into the faxrunq
shell script, and remove the comment signs before the code
to delete the job files.
When a job cannot be sent in five tries, the JOB file is
renamed to JOB.suspended. To re-queue this job, rename
the JOB file back and remove all the "Status" lines in it.
SEE ALSO
faxrunq(1), faxspool(1), faxrm(1), faxq(1)
greenie 2 Feb 94 2
--
It can hardly be a coincidence that no language on Earth has ever
produced the expression `as pretty as an airport'. -- D.Adams