FAXWATCH(8C)

💖 FAXWATCH 💖 (section 8C of the manual, bestie)

okay so welcome to the faxwatch page, and yes it's a section 8C joint, we love a legacy sysadmin moment 💅

---

✨ NAME ✨

faxwatch — monitor low-level HylaFAX server actions 👀

---

🎀 SYNOPSIS 🎀

/usr/bin/faxwatch [ -g ] [ -l ] [ -h host ] trigger-expression

---

🌸 DESCRIPTION 🌸

so basically faxwatch signs you up for one or more events on a HylaFAX server, and then it just keeps printing the event messages that come after to standard output. it's giving surveillance but make it polite. the main character purpose here? testing the event distribution mechanism that the HylaFAX servers use. no cap, that's the job. 🫶

the trigger-expression gets handed over as an argument to a SITE TRIGGER command that's passed to hfaxd(8C). the syntax for that expression is:

[<class>['<'id'>'][<mask>|'*']]*

where <class> says which class of events you're talking about, and it's one of these:

• J — for job-related events 💼
• S — for fax send-related events 📤
• R — for fax receive-related events 📥
• M — for modem-related events 📡

a <mask> is a 4-hex-digit mask of trigger events (peep the table further down ⬇️). and if you write * then literally every event in that class matches. all of them. the whole vibe.

an <id> is how you narrow the matches down to one specific job or modem. (eventually this is gonna need to be generalized for job groups — noted, not my problem today 🙈)

so for example, a spec that would catch any event for the modem on ttyf2 would be M<ttyf2>*. and to get pinged when job 1932 is requeued or completes, you'd use J<1932>4c60. iconic.

the output from faxwatch is ASCII text that describes each event. faxwatch runs until you interrupt it. it will simply keep going. it has no quit in it bestie 😭

---

✨ OPTIONS ✨

• -g — display times and dates in Greenwich Mean Time (GMT). NB: this is the default. so yeah, you're already here 🕰️
• -h host — report the status of the server on a specific host. the host can be either a symbolic name or a network address. IPv6 addresses are given in [xx:xx::x]:port format. if you don't pass a -h option, faxwatch uses the FAXSERVER environment variable to figure out which HylaFAX server to contact. if that variable isn't set, then faxwatch checks for a setting in the configuration files (first in the per-user file and then in the system-wide file). and if all of the above fails, then faxwatch just tries to contact a server on the machine where it's being run. persistence!! 🐝
• -l — display times and dates in the local timezone of the server 🌍
• -v — trace the protocol exchanges between faxwatch and the hfaxd processes on standard output. for when you want to see the receipts 🔍

---

🌈 EVENTS 🌈

here's the current set of events you can monitor. heads up though: this info is subject to change — consult the source code for reference, fr fr.

• JOB_CREATE — class J, mask 0x0001 — job created
• JOB_SUSPEND — class J, mask 0x0002 — job suspended
• JOB_READY — class J, mask 0x0004 — job ready to send
• JOB_SLEEP — class J, mask 0x0008 — job sleeping awaiting time-to-send
• JOB_DEAD — class J, mask 0x0010 — job marked dead
• JOB_PROCESS — class J, mask 0x0020 — job processed by scheduler
• JOB_REAP — class J, mask 0x0040 — job corpus reaped
• JOB_ACTIVE — class J, mask 0x0080 — job activated
• JOB_REJECT — class J, mask 0x0100 — job rejected
• JOB_KILL — class J, mask 0x0200 — job killed
• JOB_BLOCKED — class J, mask 0x0400 — job blocked by other job
• JOB_DELAYED — class J, mask 0x0800 — job delayed by tod restriction or similar
• JOB_ALTERED¹ — class J, mask 0x1000 — job parameters altered
• JOB_TIMEDOUT — class J, mask 0x2000 — job kill timer expired
• JOB_PREP_BEGIN — class J, mask 0x4000 — job preparation started
• JOB_PREP_END — class J, mask 0x8000 — job preparation finished
• SEND_BEGIN — class S, mask 0x0001 — fax, send attempt started
• SEND_CALL — class S, mask 0x0002 — fax, call placed
• SEND_CONNECTED — class S, mask 0x0004 — fax, call answered by fax
• SEND_PAGE — class S, mask 0x0008 — fax, page transmit done
• SEND_DOC — class S, mask 0x0010 — fax, document transmit done
• SEND_POLLRCVD — class S, mask 0x0020 — fax, document retrieved by poll operation
• SEND_POLLDONE — class S, mask 0x0040 — fax, poll operation completed
• SEND_END — class S, mask 0x0080 — fax, send attempt finished
• SEND_REFORMAT — class S, mask 0x0100 — fax, job being reformatted
• SEND_REQUEUE — class S, mask 0x0200 — fax, job requeued
• SEND_DONE — class S, mask 0x0400 — fax, send job done
• RECV_BEGIN — class R, mask 0x0001 — fax, inbound call started
• RECV_START — class R, mask 0x0002 — fax, session started
• RECV_PAGE — class R, mask 0x0004 — fax, page receive done
• RECV_DOC — class R, mask 0x0008 — fax, document receive done
• RECV_END — class R, mask 0x0010 — fax, inbound call finished
• MODEM_ASSIGN — class M, mask 0x0001 — modem assigned to job
• MODEM_RELEASE — class M, mask 0x0002 — modem released by job
• MODEM_DOWN — class M, mask 0x0004 — modem marked down
• MODEM_READY — class M, mask 0x0008 — modem marked ready
• MODEM_BUSY — class M, mask 0x0010 — modem marked busy
• MODEM_WEDGED — class M, mask 0x0020 — modem considered wedged
• MODEM_INUSE — class M, mask 0x0040 — modem in use for outbound work
• MODEM_DATA_BEGIN — class M, mask 0x0080 — inbound data call begun
• MODEM_DATA_END — class M, mask 0x0100 — inbound data call finished
• MODEM_VOICE_BEGIN — class M, mask 0x0200 — inbound voice call begun
• MODEM_VOICE_END — class M, mask 0x0400 — inbound voice call finished
• MODEM_CID — class M, mask 0x0800 — inbound caller-ID information

¹ that one, JOB_ALTERED, is event to be removed soon. don't get attached 💀

---

🦋 SEE ALSO 🦋

hylafax-server(5F), hfaxd(8C).

---

and that's the whole page bestie!! this one was dated January 18, 1996, and it's the FAXWATCH(8C) page from the HylaFAX world — old enough to be vintage, still out here monitoring low-level server actions like a queen 👑 thanks for reading, mwah 💖✨