faxspool(1) mgetty+sendfax manual faxspool(1)
faxspool - queue and convert files for faxing with sendfax(8)
faxspool [options] phone-number files...
Queue the named files for later transmission with sendfax(8). The input files are con-
verted 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 format of this line is configurable via
the file /etc/mgetty+sendfax/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 substi-
tuted by the output of the `date` command, and @ID@ stands for the sender's fax number
If "phone-number" contains non-numeric characters, faxspool interprets it as an alias and
tries to look it up in the files /etc/mgetty+sendfax/faxaliases and $HOME/.faxnrs. These
files have a very simple format: 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+send-
fax/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 /etc/mgetty+sendfax/make.coverpg exists and is executable, it is run
with all relevant source/destination data on the command line, and its output is sent as
the first page of the resulting fax. See coverpg(1) for details.
-n Tells faxspool to use normal resolution (as opposed to the default, fine resolu-
tion) both when converting files to G3 format and when transmitting (no effect on
-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 ..., spooling 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 speci-
fied. 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".
Verbose form of the fax's destination. Used only for informational 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.
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>.
Sets the priority of the fax in the queue. 9 is highest (meaning: faxes get sent
out first), 1 is lowest. If nothing is specified, 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) man-
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 /usr/lib/mgetty+sendfax/make.coverpg.
-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.
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 success-
fully before midnight, it won't be sent on the next day until <hh:mm>!
Only send the fax in the time range between those two times. This is only imple-
mented in faxrunqd. If the second time specified is 'earlier' than the first time,
it is interpreted as a time range crossing midnight.
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 private/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
-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).
fax spool directory
global fax alias file
private fax alias file
list of allowed users
list of denied users
default fax page header
program to create fax cover page (see coverpg(1)).
program to control which file extentions are recognized (.txt, .ps, ...) and how
those file formats should be converted to G3.
this a small C helper program that facilitates access to the fax spool queue (which
is since mgetty 1.1.29 no longer world-writeable)
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.
g3cat(1), pbm2g3(1), sendfax(8), faxrunq(1), faxrunqd(8), faxq(1), faxqueue(5), coverpg(1)
faxspool is Copyright (C) 1993-2002 by Gert Doering, <email@example.com>. Access con-
trol and alias handling suggested by Caz Yokoyama, <firstname.lastname@example.org>.
greenie 23 Nov 02 faxspool(1)