faxspool(1)

🎀 NAME 🎀

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

(yes bestie, this is from the mgetty+sendfax manual, and it's about to be your new fave)

---

✨ SYNOPSIS ✨

faxspool [options] phone-number files...

---

🦋 DESCRIPTION 🦋

Okay so here's the vibe: faxspool queues up the files you name so they can get sent later by sendfax(8). It takes your input files, converts them into G3 fax files, spools them to /var/spool/fax/outgoing/<dir>/f*.g3, and queues them for transmission to the fax address "phone-number". Slay. 💅

On top of every single page, faxspool drops a header line telling the other side the number of pages, your fax id, ..., literally whatever you want. The format of that line is configurable through the file /etc/mgetty/faxheader, and per-user through $HOME/.faxheader. (You can also pick a different one with the "-h" option — like one for your business faxes and one for the private stuff. Iconic, honestly.) 🎀

That file should contain a few lines of text — normally just one line, but more than one line is permitted. The text can use these tokens:

• @T@ — the remote telephone number
• @U@ — the sending user name
• @N@ — their full name (fifth field of /etc/passwd, if not given with "-F")
• @P@ — the page number
• @M@ — the total number of pages
• @D@ — gets replaced by the string specified with the "-D" option (see below)
• @DATE@ — substituted by the output of the date command
• @ID@ — stands for the sender's fax number (FAX_STATION_ID)
• @S@ — substituted by the JOB ID (Fxxxxxx)

If "phone-number" contains non-numeric characters, faxspool reads it as an alias and tries to look it up in /etc/mgetty/faxaliases and $HOME/.faxnrs. Those files have a very simple format: one line per alias, alias name first, whitespace (tab or blank), phone number. Optionally you can put a short description of the receiver after the phone number — that gets used as if you'd passed it with "-D" (but an explicit "-D" flag overrides it, no cap).

Example:

gert 0893244814 Gert Doering

Access control works kinda like "crontab" does it, bestie:

• If a file /etc/mgetty/fax.allow exists, only the users listed in it (one name per line) may use the fax service.
• If it does not exist, but /etc/mgetty/fax.deny exists, then all users but the ones listed in that file may use faxspool(1).
• 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. Setting it up is genuinely so easy: if a file /etc/mgetty/make.coverpg exists and is executable, it's run with all the relevant source/destination data on the command line, and its output gets sent as the first page of the resulting fax. If $HOME/.make.coverpg exists, that file is used instead. See coverpg(1) for the details. 🫶

---

👑 OPTIONS 👑

• -n — tells faxspool to use normal resolution (as opposed to the default, fine resolution) both when converting files to G3 format 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/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 specified instead. Since this can lead to an 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, 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 (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) 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 a cover page. 🧚

The default cover page program used is $HOME/.make.coverpg; if this file doesn't exist, /etc/mgetty/make.coverpg is used. (However, if $HOME/.make.coverpg exists, but is not executable, 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 specified is 'earlier' than the first time, it's 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 private/corporate, to tag faxes with the customer ID to use for billing, or something along those 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 (not implemented yet). 📞
• -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" (not implemented yet).
• -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/faxaliases — global fax alias file
• $HOME/.faxnrs — private fax alias file
• /etc/mgetty/fax.allow — list of allowed users
• /etc/mgetty/fax.deny — list of denied users
• /etc/mgetty/faxheader — default fax page header
• /etc/mgetty/make.coverpg — program to create fax cover page (see coverpg(1))
• /etc/mgetty/faxspool.rules — program to control which file extensions are recognized (.txt, .ps, ...) and how those file formats should be converted to G3
• /usr/lib/mgetty-fax/faxq-helper — this is a small C helper program that facilitates access to the fax spool queue (which is, since mgetty 1.1.29, no longer world-writeable)

---

💀 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@greenie.muc.de>. Access control and alias handling suggested by Caz Yokoyama, <caz@shoki.osk.psq.mei.co.jp>. 🫶

---

and that's the whole page, bestie — written by greenie, dated 23 Nov 02, and it's literally the faxspool(1) manual. periodt. 💅✨