faxqueue(5)

💖 faxqueue — okay bestie, let's talk about the fax spool queue 💖

So like. This is the faxqueue(5) manual page from the mgetty+sendfax manual set, and it's all about these lil control files that tell your machine which faxes to send and when. Pull up a chair 🫶

---

✨ NAME ✨

faxqueue — the sendfax fax spool queue control files, aka the receipts that keep your outgoing faxes organized 💅

---

🎀 SYNOPSIS 🎀

/var/spool/fax/outgoing/F*/JOB

---

🌸 DESCRIPTION 🌸

The JOB files live in the subdirectories of the outgoing fax spool directory, /var/spool/fax/outgoing, and together they build up a whole queue of faxes that are waiting to be sent by faxrunq(1). It's giving ✨organized chaos✨.

These little guys are created by faxspool(1), you can peek at them with faxq(1), and you can yeet them with faxrm(1). Periodt.

---

🦋 FORMAT 🦋

Okay so here's the tea on how a JOB file is structured:

Every line is a leading keyword plus whatever data goes with it (and that data is just, like, the rest of the line). Some of these are required, some are optional. Here's every keyword that's currently implemented, no gatekeeping:

• phone <number> — the telephone number you're sending the fax to. Required, no skips.
• user <user> — the name of the user who originated this (on the local machine, bestie). If there's no mail field hanging around, this is the user who gets the status mail about the fax. Required.
• mail <email> — if this field is here, faxrunq(1) sends its status mail to the address you put right there. If it's not here, faxrunq(1) falls back to the user field instead. Optional 💫
• input <file(s)> — the file names that got passed to faxspool(1). Optional, and honestly only faxq(1) even looks at it.
• pages <file(s)> — the file names that are gonna be sent with sendfax(8), listed relative to the directory where the JOB file itself is chillin'. These files have to actually exist, and they have to be readable by whoever runs faxrunq(1). Required — unless you're using poll, in which case it's optional.
• priority <0-9> — sets the priority for this job in the fax queue (higher-priority jobs get sent before all the low-pri ones, obviously 💅). Fair warning: so far only faxrunqd uses this field, faxrunq does NOT. 9 is the highest, 0 is the lowest, and 5 is the default.
• Status <message> — this one gets automatically appended by faxrunq(1) after every run, and it tells the reader all about the successful and unsuccessful tries to send this job. Heads up: if more than five "FATAL" errors get listed, the fax job is removed from the queue. 💀
• verbose_to <blurb> — a plain-text description of whoever's receiving the fax. If it's present, it gets returned in the mail messages as "your fax to <blurb>". Optional.
• time <hhmm> — if this is present, faxrunq won't send the job before the given time. The format has to be exactly "hhmm", in 24-hr format, otherwise faxrunq just won't understand it. Optional. (Notice: this implies "stop trying after midnight, until hh:mm next day" — iykyk.)
• time <hhmm>-<hhmm> — this format specifies a time window when sending this fax is permitted, like "time 2300-0500" for example. Lowkey important: this format only works if you use faxrunqd, because support for it hasn't been implemented for faxrunq yet. 😭
• poll — flag token. If it's present, faxrunq will try to poll the given phone number for documents (see "sendfax -p").
• normal_res — flag token. If it's present, faxrunq will transmit all pages using normal resolution (see "sendfax -n").
• acct_handle <arbitrary string> — this is a pure comment field, but sendfax(8) will log it into its transaction log file. So you can use it as a customer handle, a job number, whatever you need to get the phone bills charged to the right customer (the programs won't actually look at it, they just pass it through). Optional. Kinda iconic honestly.
• subject <arbitrary string> — also a pure comment field, used only for informational purposes. faxrunq will return it in the success/failure mail. And if you use faxspool -s <subj>, it'll put this string on the cover page and in the JOB file too. 💌

---

🔒 PERMISSIONS 🔒

Starting with mgetty 1.1.29, the fax spool directory /var/spool/fax/outgoing is no longer world-writeable. It should be owned by the user 'uucp' and be mode 755. And the faxrunq(1) and faxrunqd(1) programs should also be run under that user ID if possible. Bestie, this matters.

If the fax spool directory is world- or group-writeable, there are a number of denial of service or file overwrite / file access attacks possible that it's very hard to guard against. So don't do this! 🙈

If the fax spool directory has the proper permissions, there are currently no known attacks against faxrunq/faxrunqd, even if they run as "root" — but it's always more safe to run as an untrusted user. No cap.

---

⚙️ PROCESSING ⚙️

While a given JOB file is being processed by faxrunq(1), it gets locked against being sent multiple times by temporarily renaming it to JOB.locked — so yeah, it can happen that a faxq(1) command doesn't show you this job. (faxrunqd(8) is a bit smarter and does the locking by creating a hard link instead. main character energy ✨)

When a job is successfully sent, it's not deleted — instead the JOB file gets renamed to JOB.done. Because of this, you can still see old jobs with "faxq -o". You should regularly clean up the outgoing fax directory, removing old faxes. And if you don't want this behaviour, go edit the faxrunq(1) config file and enable the option:

delete-sent-jobs yes

When a job can't be sent after several tries (and we're not counting normal difficulties like the called number being busy or the modem being in use), the JOB file gets renamed to JOB.suspended. To re-queue this job, call faxq -r — that renames the JOB file right back. 🫶

---

👑 SEE ALSO 👑

faxrunq(1), faxspool(1), faxrm(1), faxq(1), faxrunqd(8)

---

Okay that's the whole thing, bestie! This page came from the mgetty+sendfax manual, written by greenie, dated 23 Nov 02. Slay, go send some faxes 💖🎀🦋