HFAXD(8C)

📦
version 7.0.11 · 5 versions
, in fedora 43, fedora 44

💖 HFAXD — the hfaxd(8C) page, bestie edition 💖

okay so. sit down. hydrate. we're talking about hfaxd, and she is the server, no cap. 🫶

✨ NAME ✨

hfaxd — the HylaFAX client-server protocol server 👑

✨ SYNOPSIS ✨

/usr/bin/hfaxd [ -d ] [ -D secs ] [ -q dir ] [ -c config ] [ -o port ] [
-O ] [ -f bindaddressfamily ] [ -l bindaddress ] [ -p
pasv_min_port:pasv_max_port ] [ -i port ] [ -I ] [ -s port ] [ -S ]

like. look at her. so many flags. main character energy fr fr 💅

✨ DESCRIPTION ✨

So hfaxd is the HylaFAX program that implements the server portion of two things:

  • the client-server protocol and
  • the Simple Network Paging Protocol (SNPP) — which is what you use to submit message pager jobs to the IXO/TAP and UCP support 📟

And more client-server protocols are planned, bestie — hfaxd is literally intended to be the ``carrier'' through which they get supported. she's the vessel. the icon. the moment. 🦋

hfaxd is typically used in one of two ways:

  • as a stand-alone process that's started at system boot time to listen for client connections on one or more ports — and in this case the -i, -o, or -s option must be used, okay? not optional, not a vibe, a requirement.
  • as a subservient process to the inetd(8C) program

and the two forms of use may be combined — so long as the same service is not provided both by the stand-alone hfaxd and through inetd. don't do double duty on the same service, it's giving chaos 😭

🌈 HYLAFAX CLIENT-SERVER PROTOCOL SUPPORT 🌈

If hfaxd is started with the -i option it will service clients using the HylaFAX client-server protocol. This protocol is strongly related to the Internet File Transfer Protocol (FTP) — so much so, in fact, that FTP client programs that include support for ``quoted commands'' may be used to communicate with hfaxd using the new protocol. iconic behaviour, honestly. ✨

(it should also be possible to use FTP-aware World Wide Web browsers such as Mosaic and Netscape Navigator to access HylaFAX servers through the new protocol — but the current format for information returned in directory listings confuses them. they're doing their best, they're just confused 🥺)

The hfaxd server currently recognizes the following protocol requests; case is not distinguished. Entries marked with a ¹ can be used only when the client has established administrative privileges with ADMIN. so like, know your power level 💅

  • ABOR — abort previous command
  • ACCT — specify account (ignored) 🙈
  • ADMIN — specify password for administrative privileges
  • ALL... ok no, moving on:
  • ALLO — allocate storage (vacuously)
  • ANSWER¹ — request that call be answered
  • APPE — append to a file
  • CDUP — change to parent of current working directory
  • CHMOD — change mode of a file
  • CHOWN¹ — change owner of a file
  • CWD — change working directory
  • DELE — delete a file
  • DISABLE¹ — disable outbound use of modem
  • ENABLE¹ — enable outbound use of modem
  • HELP — give help information
  • FILEFMT — specify/query format for returning file status
  • FORM — specify data transfer format
  • IDLE — set idle-timer (in seconds)
  • JDELE — delete done or suspended job
  • JINTR — interrupt job
  • JKILL — kill job
  • JNEW — create new job
  • JOB — set/query current job
  • JOBFMT — specify/query format for returning job status
  • JPARM — specify/query job state parameter
  • JREST — reset current job state
  • JSUBM — submit job to scheduler
  • JSUSP — suspend job from scheduling
  • JWAIT — wait for job to complete
  • JGDELE — delete group of jobs
  • JGKILL — kill group of jobs
  • JGINTR — interrupt group of jobs
  • JGNEW — place current job in a new job group
  • JGPARM — set state parameter in a group of jobs
  • JGREST — reset current state for a group of jobs
  • JGRP — set/query current job group
  • JGSUBM — submit group of jobs to scheduler
  • JGSUSP — suspend group of jobs from scheduling
  • JGWAIT — wait for group of jobs to complete
  • LIST — list files in a directory
  • MDTM — show last modification time of file
  • MODE — specify data transfer mode
  • MDMFMT — specify/query format for returning modem status
  • NLST — give name list of files in directory
  • NOOP — do nothing
  • PASS — specify password
  • PASV — prepare for server-to-server transfer
  • PORT — specify data connection port
  • PWD — print the current working directory
  • QUIT — terminate session
  • RCVFMT — specify/query format for returning received facsimile status
  • REIN — reinitiate server state
  • REST — restart incomplete transfer
  • RETP — retrieve the next page in a file
  • RETR — retrieve a file
  • SHUT — schedule server shutdown
  • SITE — non-standard commands (see next section) 👀
  • SIZE — return size of file
  • STAT — return status of server or file
  • STOR — store a file
  • STOT — store a temporary file with a unique name
  • STOU — store a file with a unique name
  • STRU — specify data transfer structure
  • SYST — show operating system type of server system
  • TYPE — specify data transfer type
  • TZONE — specify timezone handling for dates and times
  • USER — specify user name
  • VRFY — verify dialstring handling and/or least-cost routing

The following non-standard or experimental commands are supported through the SITE request. yes queen, secret menu 💅

  • ADDMODEM¹ — add/configure new modem for use
  • ADDUSER¹ — add client access control entry
  • CONFIG¹ — send configuration parameter setting to server
  • DELMODEM¹ — deconfigure/remove modem
  • DELUSER¹ — remove client access control entry
  • TRIGGER — register real-time event trigger
  • HELP — give help information, e.g., SITE HELP

In addition, FTP requests that are specified in Internet RFC 959 but not listed here are recognized, but not implemented. recognized ≠ functional, bestie. it's giving "I know her but we don't talk" 💀

🚨 hfaxd will abort an active data transfer only when the ABOR command is preceded by a Telnet "Interrupt Process" (IP) signal and a Telnet "Synch" signal in the command Telnet stream, as described in Internet RFC 959. And if a STAT command is received during a data transfer, preceded by a Telnet IP and Synch, transfer status will be returned. both signals or nothing, that's the rule 📜

🎀 SIMPLE NETWORK PAGING PROTOCOL (SNPP) SUPPORT 🎀

If hfaxd is started with the -s option it will service clients using the Simple Network Pager Protocol (SNPP) as specified in RFC 1861 (which obsoletes RFC 1645). out with the old, in with the new ✨

The hfaxd server currently recognizes the SNPP protocol requests listed below. Requests marked with a ¹ are non-standard extensions to RFC 1861 that may be added to SNPP at some future time. Case is not distinguished, and only the first four characters of requests are used in identifying commands. four chars and she knows what you mean. efficient queen 👑

  • 2WAY — preface a 2-way transaction
  • ABOR¹ — abort previous command
  • ACKR — set read acknowledgement handling for subsequent requests
  • ALER — set the alter-level for subsequent requests
  • CALL — set the caller-ID for subsequent requests
  • COVE — set the alternate coverage area for subsequent requests
  • DATA — specify a multi-line message
  • EXPT — set the expiration time for subsequent requests
  • HELP — give help information
  • HOLD — set the time at which subsequent requests are to be delivered
  • KTAG — kill a previously submitted request
  • LEVE — set the service level for subsequent requests
  • LOGI — login to server
  • MCRE — specify multiple response text and code
  • MESS — specify a single-line message
  • MSTA — return the status of a previously submitted request
  • NOQU — disable message queueing
  • PAGE — specify the destination pager
  • PING — locate/validate a pager
  • QUIT — terminate session
  • RESE — reset server state
  • RTYP — set the reply type code for subsequent requests
  • SEND — send message(s)
  • SITE¹ — site-specific commands (see next section)
  • STAT¹ — return server status
  • SUBJ — set the message text for subsequent requests
🚨 hfaxd will abort an active SEND operation when an ABOR command is preceded by a Telnet "Interrupt Process" (IP) signal and a Telnet "Synch" signal in the command Telnet stream. same energy as the FTP side, iconic consistency 💖

The following non-standard or experimental commands are also supported through the SITE request:

  • FROMUSER — specify the sender's identity
  • IDLE — set idle-timer (in seconds)
  • JPARM — query job parameter status
  • JQUEUE — control whether or not job is queued
  • LASTTIME — set the time to terminate an unfinished job
  • MAILADDR — set the e-mail address to use for notification
  • MAXDIALS — set the maximum number of times to dial the phone
  • MAXTRIES — set the maximum number of times to try sending the page
  • MODEM — set the modem or class of modems to use
  • NOTIFY — set the e-mail notification
  • RETRYTIME — set the time to delay between job retries
  • SCHEDPRI — set the scheduling priority for the job [0-255]
  • HELP — give help information, e.g., SITE HELP
👀 Note that hfaxd requires that SNPP clients login first with the LOGI directive, while RFC 1861 permits clients to submit pages anonymously. so if you're out here expecting anonymous pages: not on this server, bestie. no anonymous vibes here 🙅‍♀️

🔥 CLIENT ACCESS CONTROL 🔥

hfaxd controls client access according to the information in the file

/var/spool/hylafax/etc/hosts.hfaxd

This file defines the set of users and machines that may receive service and, optionally, defines password challenges to use in authenticating clients. Clients may be permitted access to services with or without a password challenge. Access may also be restricted based on the host machine that a request for service originates from. Consult hosts.hfaxd(5F) for information on the format and content of this file. 📄

The SITE ADDUSER protocol request is provided for adding new users to a server — available only to clients with administrative privileges. sorry babe, admin only, that's the door policy 🚪

Server resources are controlled based on clients' identities. Jobs and documents, both received and submitted, are protected by the server. Typically clients are permitted access to anything they own or that is publicly accessible. There are also administrative privileges that clients may acquire, and which permit them wide access to objects that reside on the server. with great power etc etc 💅

🌸 A complete client-server protocol specification is still outstanding. (yes really. it's coming. eventually. we promise.)

hfaxd operates with its root directory set to the top of the HylaFAX spooling area:

/var/spool/hylafax

This is done so that clients see a virtual file hierarchy that is completely contained within the HylaFAX operating environment on the server machine. ✨

⚠️ Administrators, however, must be aware of this action when specifying files in the hfaxd configuration file: absolute pathnames relative to the root of the spooling should be used to specify filenames. this one bites people, bestie, don't let it be you 😭

part 1 of 4, keep scrolling, we're not done yet 🦋

🌸 SERVER ACCESS CONTROL 🌸

okay bestie, listen up, this is the part where the server gets picky about who's allowed in 💅

The file /var/spool/hylafax/etc/shutdown, when it exists, tells everyone when to lock the server down. The moment that file is present and contains valid info, hfaxd will let only users with administrative privileges touch the server. Everybody else who rolls up asking for service gets denied — and their negative server responses will include whatever shutdown message is written in the shutdown file. Go read hylafax-shutdown(5F) for the tea on the format and content of that file. 🫶

The SHUT protocol request can schedule a server shutdown; it's only available to clients with administrative privileges. And to bring a shut-down server back to life, you can just delete the shutdown file with the DELE protocol request. (Heads up though: this is meant to be replaced with an ``unshut'' protocol request so that implementation details stay out of the protocol. So like, it's giving temporary.)

⚙️ CONFIGURATION FILES ⚙️

hfaxd reads its configuration info from /etc/hylafax/hfaxd.conf every single time a new server process starts up (so basically, once per new client). That file plays by the same rules as all the other HylaFAX configuration files, which are described over in hylafax-config(5F). ✨

Here's every parameter it knows about — and the ones marked ``(SNPP)'' are only used by the SNPP support, iykyk:

  • FaxContact — string, default: see below — contact address to show in help text
  • FileFmt — string, default: see below — format string for file status results
  • IdleTimeout — integer, default 900 — client idle timeout in seconds
  • JobFmt — string, default: see below — format string for job status results
  • JobHostID — string, default: (none) — identification information for job hosts
  • JobProtection — octal, default 0644 — permissions for job qfiles in sendq/doneq
  • KillTimeMap — string, default: see below — mapping from service level to job kill time (SNPP)
  • LDAPServerURI — string, default: (none) — URI of the ldap server including port number
  • LDAPBaseDN — string, default: (none) — LDAP context where user objects can be found
  • LDAPBindQuery — string, default: (none) — format for the LDAP bind query
  • LDAPGroupAttribute — string, default groupMembership — LDAP group attribute label
  • LDAPReqGroup — string, default: (none) — LDAP context of the users group
  • LDAPSearchDN — string, default: (none) — format for the UserDN in LDAP search
  • LDAPSearchQuery — string, default uid=%s — format for the LDAP search query
  • LDAPVersion — integer, default 3 — LDAP protocol version to use
  • LogFacility — string, default daemon — syslog facility name for tracing messages
  • MaxAdminAttempts — integer, default 5 — maximum admin attempts before disconnecting
  • MaxConsecutiveBadCmds — integer, default 10 — maximum invalid commands before disconnecting
  • MaxIdleTimeout — integer, default 7200 — maximum client idle timeout permitted
  • MaxLoginAttempts — integer, default 5 — maximum login attempts before disconnecting
  • MaxMsgLength — integer, default 128 — maximum pager message length (SNPP)
  • ModemFmt — string, default: see below — format string for modem status results
  • PagerIDMapFile — string, default /var/spool/hylafax/etc/pagermap — name of file for mapping pager IDs (SNPP)
  • PriorityMap — string, default: see below — mapping from service level to job priority (SNPP)
  • RcvFmt — string, default: see below — format string for received facsimile status results
  • RecvqProtection — octal, default 0444 — permissions for client access to recvq
  • RetryTimeMap — string, default: see below — mapping from service level to job retry time (SNPP)
  • ServerTracing — integer, default 1 — server tracing control vector
  • ShutdownFile — string, default /var/spool/hylafax/etc/shutdown — name of shutdown control file
  • UserAccessFile — string, default /var/spool/hylafax/etc/hosts.hfaxd — name of access control file
  • XferLogFile — string, default /var/spool/hylafax/etc/clientlog — name of file for logging client data transfers

The configuration parameters are explained below, one by one, no skips no skimming 🎀

🌸 FaxContact

The e-mail address to display as a point of contact in the help text that gets returned to a client in response to the HELP or SITE HELP commands. By default this is ``FaxMaster@hostname'', where hostname is the fully qualified name for the machine where the server is running. 💌

🌸 FileFmt

The format string to use when returning file status information with the LIST and STAT commands. Formats are specified using printf(3S) style conventions, but using the field identifiers listed below. Each item can include field width, precision, left-justification, 0-filling, etc. — just exactly like printf; e.g. %-8p for an 8-character wide, left-justified, blank-padded field containing the file protection flags. 💅

  • a — Last access time
  • c — Creation time
  • d — Device number (octal)
  • f — Filename
  • g — Group identifier (decimal)
  • i — Inode number (decimal)
  • l — Link count (decimal)
  • m — Last modification time
  • o — Owner (based on file GID)
  • p — Fax-style protection flags (no group bits)
  • q — UNIX-style protection flags
  • r — Root device number (octal)
  • s — File size in bytes (decimal)
  • u — User identifier (decimal)

The default format string is:

%-7p %3l %8o %8s %-12.12m %.48f

It is recommended that all items include a field width so that client applications that construct headers from the format string can constrain the width of column title strings. (fr fr, do this. your future self will thank you. 🫶)

🌸 IdleTimeout

The initial/default timeout to use when timing out idle clients. This value defines the maximum amount of time (in seconds) that hfaxd will wait for a command from a client before terminating the connection. Unprivileged clients may alter the idle timeout up to the value of MaxIdleTimeout; privileged clients may set the timeout to any value. ✨

🌸 JobFmt

The format string to use when returning job status information for jobs in the sendq and doneq directories. Formats are specified using printf(3S) style conventions, but using the field identifiers listed below. Each item can include field width, precision, left-justification, 0-filling, etc. — just like printf; e.g. %-3j for a 3-character wide, left-justified, blank-padded field containing the job state. 🔥

  • A — Destination SubAddress
  • B — Destination Password
  • C — Destination company name
  • D — Total # dials/maximum # dials
  • E — Desired signalling rate
  • F — Client-specific tagline format string
  • G — Desired min-scanline time
  • H — Desired data format
  • I — Client-specified scheduling priority
  • J — Client-specified job tag string
  • K — Desired use of ECM
  • L — Destination geographic location
  • M — Notification e-mail address
  • N — Desired use of private tagline (one-character symbol)
  • O — Whether to use continuation cover page (one-character symbol)
  • P — # pages transmitted/total # pages to transmit
  • Q — Client-specified minimum acceptable signalling rate
  • R — Destination person (receiver)
  • S — Sender's identity
  • T — Total # tries/maximum # tries
  • U — Page chopping threshold (inches)
  • V — Job done operation
  • W — Communication identifier
  • X — Job type (one-character symbol)
  • Y — Scheduled date and time
  • Z — Scheduled time in seconds since the UNIX epoch
  • a — Job state (one-character symbol)
  • b — # consecutive failed tries
  • c — Client machine name
  • d — Total # dials
  • e — Public (external) format of dialstring
  • f — # consecutive failed dials
  • g — Group identifier
  • h — Page chop handling (one-character symbol)
  • i — Current scheduling priority
  • j — Job identifier
  • k — Job kill time
  • l — Page length in mm
  • m — Assigned modem
  • n — E-mail notification handling (one-character symbol)
  • o — Job owner
  • p — # pages transmitted
  • q — Job retry time (MM::SS)
  • r — Document resolution in lines/inch
  • s — Job status information from last failure
  • t — Total # tries attempted
  • u — Maximum # tries
  • v — Client-specified dialstring
  • w — Page width in mm
  • x — Maximum # dials
  • y — Total # pages to transmit
  • z — Time to send job

The default format string is:

%-4j %3i %1a %6.6o %-12.12e %5P %5D %7z %.25s

This string constrains each status line to be less than 80 characters. It is recommended that all items include a field width so that client applications, such as faxstat(1), that construct headers from the format string can constrain the width of column title strings. 🌈

JobHostID

okay so this one is a whole formatted string, and the format is literally:

<id>[:<host>[:<username>:<password>:<adminwd>]]

and it identifies a job host. You can drop multiple instances of JobHostID in the config file to identify multiple job hosts, bestie, go off.

  • <id> is a numeric identification for the host that gets prepended onto job ids created by that host. It's how a client tells apart jobs created on different hosts when it might not initially know which server it connected to.
  • <id> must be the same number of digits for all configured job hosts.
  • For compatibility with all clients, <id> must be numeric only. No letters, no vibes, just digits.
  • If your JobHostID instance only includes <id>, then it's understood to refer to the local host and not a remote host. Local queen behavior 💅
  • It is this configuration entry that causes the prepending of the <id> number onto the job ids. Yes, this one specifically.
  • The other values in the formatted string are the connection details for user-level and admin-level login at the identified remote host.
  • If only <host> is provided, then the current user's login credentials are used for the chained connection.

This config will cause hfaxd to connect as a client to the specified remote host for the requested action when the job id provided by its client refers to that remote host — meaning the provided job id matches the <id> value in that host's JobHostID configuration. To do this, the hfaxd client connection to the remote host requires administrative privileges or synchronized user accounts on both hosts. No cap.

🚨 Be aware that when you provide <username>, <password>, and especially <adminwd> in the configuration, this may compromise job security on the remote host, since users from this host will be connecting to the remote host as a different user (and possibly with administrative privileges). That's not a vibe, that's a warning.

Since a null value for <adminwd> is permissible, administrative privileges may be omitted by using * for <adminwd>.

Because of the chroot under which the client instance of hfaxd operates, it may be necessary to copy or link at least some system files to the HylaFAX spool directory structure so that the chained client connection can be made to the remote job host. This operation may need to be revisited after upgrades or changes to those system files. To identify which files may need to be included, one may examine strace output for faxstat and look for which files it opens in the operation. Sherlock Holmes era 🔍✨

JobProtection

The default setting of 0644 allows all users to view all job parameters in the send and done queues. The mode determines the permissions of the clients to see the jobs, following the HylaFAX permission model of the group bits controlling uid permissions and the other bits controlling other permissions.

A setting of 0640 allows only the job owner and the administrator to view jobs. If a user doesn't have permissions on the job, the job will simply not be visible to them when viewing the queues. Poof, gone, invisible 🙈

KillTimeMap

The mapping from SNPP service level (0-11) to job expiration time (aka kill time, ominous). A mapping is specified as a string of space-separate numbers where each value is the number of minutes to permit a job to run.

The default mapping is:

5 5 5 15 60 240 720 1440 1440 1440 1440 1440

which expires a job in 5 minutes for service levels 0-2, 15 minutes for level three, 60 minutes for level four, etc. ✨

LDAPServerURI

The full address of the ldap server including port number, i.e.: ldaps://1.2.3.4:636 (for secure connections) or ldap://1.2.3.4:389 (for insecure connections). Secure is giving main character energy, insecure is giving 💀

LDAPBaseDN

The full LDAP context where user objects can be found, i.e.: ou=users,dc=example,dc=com for Active Directory/LDAP or ou=users,o=organization for Novell eDirectory.

LDAPBindQuery

The format for the LDAP bind query (ldap_sasl_bind_s) where %s is replaced with the username. If LDAPBindQuery is not configured, then the bind query will use the format cn=%s,<BaseDN> where %s is the username, and <BaseDN> is the configured LDAPBaseDN string.

LDAPGroupAttribute

The label for the group membership data. On older OpenLDAP servers this should probably be groupMembership. On ActiveDirectory this should probably be memberOf. Pick your fighter 🥊

LDAPReqGroup

The full LDAP context of the group users have to be a member of to gain HylaFAX access for sending faxes. If this is not set, then no group membership is required. Everybody's in, no velvet rope 🌈

LDAPSearchDN

The format for the UserDN in the LDAP search (ldap_search_ext_s) where %s is replaced with the username. By default this is the same as LDAPBindQuery .

LDAPSearchQuery

The format for the LDAP search query (ldap_search_ext_s) where %s is replaced with the username. By default this is uid=%s. On ActiveDirectory this should probably be set to cn=%s.

LDAPVersion

Version number of the LDAP Protocol to use (default is 3).

LogFacility

The symbolic name for the syslog(3) facility to use when logging error messages and informational/debugging messages requested through the ServerTracing parameter. The list of facility names is found in the system include file <syslog.h>; comparisons are case-insensitive. lowercase besties, we don't judge 💖

MaxAdminAttempts

The maximum number of unsuccessful attempts to gain administrative privileges with the ADMIN command that hfaxd will permit a client before terminating the connection. Note that the count of attempts is reset if/when the client successfully gains administrative privileges. Forgiven and forgotten, slay ✨

MaxConsecutiveBadCmds

The maximum number of consecutive unrecognized, unimplemented, syntactically incorrect, or otherwise unacceptable commands to permit a client before terminating the connection. This control has two purposes:

  1. to handle naive or malicious clients from sending long streams of nonsense commands to a server, and
  2. to ensure that clients are forcibly terminated when a server is marked shutdown.

MaxIdleTimeout

The maximum value that a client may set the idle timeout to. This value is not enforced if the client has administrative privileges. Admin privileges = skipping the line, apparently 👑

MaxLoginAttempts

The maximum number of unsuccessful attempts to login with the USER and PASS commands that hfaxd will permit a client before terminating the connection.

MaxMsgLength

The maximum number of characters to accept in a pager message specified with the DATA or MESS commands. Messages longer than this value are rejected. Keep it short, bestie ✂️

ModemFmt

The format string to use when returning modem status information for modems listed in the status directory. Formats are specified using printf(3S) style conventions but using the field identifiers listed below. Each item can include field width, precision, left-justification, 0-filling, etc. just as for printf; e.g. %-8h for an 8-character wide, left-justified, blank-padded field containing the name of the host the server is running on. Cute.

  • h — Server hostname
  • l — Local identifier string
  • m — Canonical modem name
  • n — FAX phone number
  • r — Maximum pages that can be received in a single call
  • s — Status information string
  • t — Server and session tracing levels (xxxxx:yyyyy)
  • v — Modem speaker volume as one-character symbol
  • z — A * if a faxgetty(8C) process is running; otherwise (space)

The default format string is Modem %m (%n): %s.

PagerIDMapFile

The absolute pathname of the file that contains directions for mapping pager identifiers to IXO/TAP or UCP service providers (and optionally a pager identification number). Consult pagermap(5F) for information on the format and content of this file.

(Note that absolute pathnames are relative to the root of the spooling area). yeah, sneaky, read it twice 🫶

PriorityMap

The mapping from SNPP service level (0-11) to job scheduling priority. A mapping is specified as a string of space-separate numbers where each value is the priority to assign to a job.

The default mapping is:

63 127 127 127 127 127 127 127 127 127 127 127

which assigns a high priority to service level zero and normal (default) priority to all other service levels. Level zero really said "I'm the moment" 🔥

RcvFmt

The format string to use when returning status information for received facsimile in the recvq directory. Formats are specified using printf(3S) style conventions but using the field identifiers listed below. Each item can include field width, precision, left-justification, 0-filling, etc. just as for printf; e.g. %-3b for a 3-character wide, left-justified, blank-padded field containing the signalling rate.

  • X — Reception indicator (1=yes, 0=no)
  • Y — Received date and time
  • Z — Received time in seconds since the UNIX epoch
  • a — SubAddress received from sender (if any)
  • b — Signalling rate used during receive
  • d — Data format used during receive
  • e — Error description if an error occurred during receive
  • f — Document filename (relative to the recvq directory)
  • h — Time spent receiving document (HH:MM:SS)
  • l — Page length in mm
  • m — Fax-style protection mode string (-rwxrwx)
  • n — File size (number of bytes)
  • o — File owner
  • p — Number of pages in document
  • q — UNIX-style protection flags
  • r — Resolution of received data
  • s — Sender identity (TSI)
  • t — Compact representation of the time when the receive happened
  • w — Page width in mm
  • z — A *'' if receive is going on; otherwise '' (space)

The default format string is %-7m %4p%1z %-8.8o %14.14s %7t %f. This string constrains each status line to be less than 80 characters. It is recommended that all items include a field width so that client applications, such as faxstat(1) that construct headers from the format string can constrain the width of column title strings.

RecvqProtection 🔐

The permissions setting for administrator, owners, and users for viewing files in the HylaFAX receive queue. The default setting of 0444'' lets <rainbow>literally everyone</rainbow> view all files in the queues. A setting of 0440'' allows only the job owner and the administrator to view files. A setting of ``0040'' allows only the administrator to view the files. If a user doesn't have permissions on the file, the file will not be visible to them when viewing the queue. (so yeah, if a file is ghosting them, that's why 💀)

RetryTimeMap ⏰

The mapping from SNPP service level (0-11) to job retry time. A mapping is specified as a string of space-separate numbers where each value is the number of seconds to delay between delivery attempts. A value of zero causes retries to be scheduled using the default algorithm used by the HylaFAX job scheduler. The default mapping is ``30 60 60 180 0 0 0 0 0 0 0 0'' which retries a level 0 job after a 30 second delay, levels 1 and 2 after 60 seconds, level 3 after 3 minutes, and other jobs are retried according to the usual scheduling algorithm.

ServerTracing 🕵️

A number that controls the generation of tracing information by a server. areas that are individually controlled. To enable tracing of multiple areas of operation, the flag associated with each area should be bit-or'd to form the value for this tag. (yes bestie, we're doing bit math, it's giving computer science 💅)

  • 1 (0x00001) — General server operation
  • 2 (0x00002) — Client-server protocol requests and responses
  • 4 (0x00004) — File transfers from client to server
  • 8 (0x00008) — File transfers from server to client
  • 16 (0x00010) — Client logins
  • 32 (0x00020) — All network connections
  • 64 (0x00040) — FIFO messages to and from faxq(8C)
  • 128 (0x00080) — TIFF Library errors and warnings
  • 256 (0x00100) — Configuration file processing

Tracing messages are directed to syslog(3) using the facility specified with the LogFacility configuration parameter. Note that syslogd(8C) must be configured to capture facility.info, facility.debug, facility.warning, and facility.err messages.

ShutdownFile 🛑

The absolute pathname of the server shutdown file; see hylafax-shutdown(5F) for information on the format and content of this file. (Note that absolute pathnames are relative to the root of the spooling area).

UserAccessFile 🚪

The absolute pathname of the user access control file; see hosts.hfaxd(5F) for information on the format and content of this file. (Note that absolute pathnames are relative to the root of the spooling area).

XferLogFile 📝

The absolute pathname of the file to use for logging client-server file transfers (when enabled through the ServerTracing parameter). (Note that absolute pathnames are relative to the root of the spooling area).

✨ OPTIONS ✨

  • -q dir — The specified directory is treated as the spooling area. The default spooling area, /var/spool/hylafax, is defined at the time the software is built. 🏠
  • -d — Stop hfaxd from detaching itself from the controlling terminal. This option is normally used only when running hfaxd under a debugger or when hfaxd is started up from the inetd(8C) process. 🐞
  • -D secs — Sleep for the specified number of seconds before actually processing the client to allow a debugger to attach. 😴
  • -f bindaddressfamily — Bind to the specified bindaddressfamily tcp port. Options are IPv4'', IPv6'', or ``all''. Please note that this argument needs to be specified before -i otherwise it will be ignored. ⚠️
  • -l bindaddress — Bind to the specified bindaddress tcp port. Please note that this argument needs to be specified before -i otherwise it will be ignored. A better approach to improve security would be to run hfaxd from xinetd, binding its service to the specific port. This will also make hylafax benefits from tcp wrappers and other options provided by xinetd. 🛡️
  • -p port:port — Restrict the range of TCP ports used when binding the socket for PASV/EPSV mode data transfers. Without this option, bind will be called with a port of 0, allowing the kernel to allocate an ephemeral port. To be useful, -p MUST be specified BEFORE -i due to the way command line arguments are parsed. 🌀
  • -i port — Listen on the specified port for service requests and respond with the client-server protocol. The port may be specified either symbolically, e.g. ``hylafax'' or numerically. This flag may be specified multiple times to request service on multiple different ports. 👂
  • -s port — Listen on the specified port for service requests and respond with the Simple Network Paging (SNPP) protocol. The port may be specified either symbolically, e.g. ``snpp'' or numerically. This flag may be specified multiple times to request service on multiple different ports. 📟
  • -I — Service the client-server protocol using the standard input and output. This option is useful when hfaxd is started up by inetd(8C). 🔌
  • -S — Service the Simple Network Paging (SNPP) protocol using the standard input and output. This option is useful when hfaxd is started up by inetd(8C). 🔌

🩺 DIAGNOSTICS 🩺

Diagnostics generated by hfaxd are logged using syslog(3). 🗒️

  • -c config — Treat config as a configuration parameter specification that is interpreted after reading the configuration file. For example, -c servertracing:0x4f'' would set the `ServerTracing` configuration parameter to 0x4f'', overriding any setting in the configuration file. (sneaky little override, we love her 🙈)

📁 FILES 📁

  • /etc/hylafax/hfaxd.conf — server configuration file
  • /var/spool/hylafax — spooling area
  • /var/spool/hylafax/FIFO — for submitting the job
  • /var/spool/hylafax/sendq — where job description is placed
  • /var/spool/hylafax/sendq/seqf — for assigning job identifiers
  • /var/spool/hylafax/sendq/seqf.increment — increment value for sendq seqf
  • /var/spool/hylafax/docq/seqf — for assigning document identifiers
  • /var/spool/hylafax/docq/seqf.increment — increment value for docq seqf
  • /var/spool/hylafax/tmp — temporary location of job-related files
  • /var/spool/hylafax/docq — where document files are placed
  • /var/spool/hylafax/recvq — where received facsimile are found
  • /var/spool/hylafax/archive — where archived jobs are placed
  • /var/spool/hylafax/log — for server log files
  • /var/spool/hylafax/client — for FIFO files used in communicating with faxq
  • /var/spool/hylafax/status — for server status information
  • /var/spool/hylafax/config.device — for returning server status
  • /var/spool/hylafax/etc/hosts.hfaxd — host access control list
  • /var/spool/hylafax/etc/shutdown — server shutdown control
  • /var/spool/hylafax/etc/pagermap — SNPP pager ID mapping file

🐛 BUGS 🐛

To be filled in. (bestie the bug section is literally a blank page. iconic honestly. no notes. 💀✨)

👀 SEE ALSO 👀

sendfax(1), sendpage(1), faxalter(1), faxrm(1), faxstat(1), faxq(8C), syslog(3) hylafax-server(5F), hosts.hfaxd(5F), status(5F), hylafax-shutdown(5F),

okay that's the whole page bestie, you made it, I'm so proud of you 🫶 This absolute icon of a manpage is from July 12, 1996 and it's filed under HFAXD(8C) — go forth and fax responsibly, mwah 💅💖

📦 where this page comes from