HFAXD

NAME

SYNOPSIS

DESCRIPTION

*

the (new) client-server protocol,

*

the old client-server protocol previously implemented by the faxd.recv program, and

*

the Simple Network Paging Protocol (SNPP) used to submit message pager jobs to the IXO/TAP and UCP support.

Additional client-server protocols are planned and hfaxd is intended to be the ``carrier'' through which they are supported.

hfaxd is typically used in one of two ways; either as a standalone process that is started at system boot time to listen for client connections on one or more ports, or as a subservient process to the inetd(1m) program. The two forms of use may however be combined so long as the same service is not provided both by the standalone hfaxd and through inetd.  

HYLAFAX (NEW) CLIENT-SERVER PROTOCOL SUPPORT

The hfaxd server currently recognizes the following protocol requests; case is not distinguished. Entries marked with a S1 can be used only when the client has established administrative privileges with ADMIN.

Request         Description
ABOR            abort previous command
ACCT            specify account (ignored)
ADMIN           specify password for administrative privileges
ALLO            allocate storage (vacuously)
ANSWERS1        request that call be answered
APPE            append to a file
CDUP            change to parent of current working directory
CHMOD           change mode of a file
CHOWNS1         change owner of a file
CWD             change working directory
DELE            delete a file
DISABLES1       disable outbound use of modem
ENABLES1        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 returing 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.

Request          Description
ADDMODEMS1       add/configure new modem for use
ADDUSERS1        add client access control entry
CONFIGS1         send configuration parameter setting to server
DELMODEMS1       deconfigure/remove modem
DELUSERS1        remove client access control entry
TRIGGER          register realtime 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.

The hfaxd server 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. If a STAT command is received during a data transfer, preceded by a Telnet IP and Synch, transfer status will be returned.  

OLD CLIENT-SERVER PROTOCOL SUPPORT

Emulation of the old protocol is important for supporting non-UNIX clients such as the WinFlex client for Windows systems and the MacFlex client for Macintosh systems. It is strongly recommended however that unless you need to support these old-style clients that you not enable support for the old protocol because of the inherent misdesign of this protocol.  

SIMPLE NETWORK PAGING PROTOCOL (SNPP) SUPPORT

The hfaxd server currently recognizes the SNPP protocol requests listed below. Requests marked with a S1 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.

Request      Description
2WAY         preface a 2-way transaction
ABORS1       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         diable 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)
SITES1       site-specific commands (see next section)
STATS1       return server status
SUBJ         set the message text for subsequent requests

The hfaxd server 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.

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

Request        Description
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
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.  

CLIENT ACCESS CONTROL

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.

A complete client-server protocol specification is still outstanding.

hfaxd operates with its root directory set to the top of the HylaFAX spooling area; ${SPOOL}. 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.  

SERVER ACCESS CONTROL

The SHUT protocol request can be used to schedule a server shutdown; it is available only to clients with administrative privileges. To make a shutdown server available again the shutdown file can be deleted with the DELE protocol request (this is to be replaced with an ``unshut'' protocol request so that implementation details are not part of the protocol).  

CONFIGURATION FILES

Tag                      Type       Default                     Description
FaxContact               string     see below                   contact address to show in help text
FileFmt                  string     see below                   format string for file status results
IdleTimeout              integer    900                         client idle timeout in seconds
JobFmt                   string     see below                   format string for job status results
KillTimeMap              string     see below                   mapping from service level to job kill time (SNPP)
LogFacility              string     daemon                      syslog facility name for tracing messages
MaxAdminAttempts         integer    5                           maximum admin attempts before disconnecting
MaxConsecutiveBadCmds    integer    10                          maximum invalid commands before disconnecting
MaxIdleTimeout           integer    7200                        maximum client idle timeout permitted
MaxLoginAttempts         integer    5                           maximum login attempts before disconnecting
MaxMsgLength             integer    128                         maximum pager message length (SNPP)
ModemFmt                 string     see below                   format string for modem status results
PagerIDMapFile           string     ${SPOOL}/etc/pagermap       name of file for mapping pager IDs (SNPP)
PriorityMap              string     see below                   mapping from service level to job priority (SNPP)
RcvFmt                   string     see below                   format string for received facsimile status results
RetryTimeMap             string     see below                   mapping from service level to job retry time (SNPP)
ServerTracing            integer    1                           server tracing control vector
ShutdownFile             string     ${SPOOL}/etc/shutdown       name of shutdown control file
UserAccessFile           string     ${SPOOL}/etc/hosts.hfaxd    name of access control file
XferLogFile              string     ${SPOOL}/etc/clientlog      name of file for logging client data transfers

The configuration parameters are explained below:

FaxContact

The e-mail address to display as a point of contact in the help text 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 as for printf; e.g. %-8p for an 8-character wide, left-justified, blank-padded field containing the file protection flags.

Format    Description
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.

IdleTimeout

The initial/default timeout to use in 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 as for printf; e.g. %-3j for a 3-character wide, left-justified, blank-padded field containing the job state.

Format    Description
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)
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.

KillTimeMap

The mapping from SNPP service level (0-11) to job expiration time (kill time). 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.

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.

MaxAdminAttempts

The maximum number of unsuccessful attempts gain adminstrative 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.

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: to handle naive or malicious clients from sending long streams of nonsense commands to a server, and to insure 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.

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.

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.

Format    Description
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(1m) 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(4f) for information on the format and content of this file. (Note that absolute pathnames are relative to the root of the spooling area).

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.

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.

Format    Description
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.

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.

Flag               Description
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(1m)
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(1m) 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(4f) 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(4f) 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, ${SPOOL}, 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(1m) process.

-l bindaddress

Bind to the specified bindaddress the tcp port. Please note that this argument need to be specified before the -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.

-i port

Listen on the specified port for service requests and respond with the (new) 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.

-o port

Listen on the specified port for service requests and respond with the old client-server protocol. The port may be specified either symbolically, e.g. ``fax'' 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 (new) client-server protocol using the standard input and output. This option is useful when hfaxd is started up by inetd(1m).

-O

Service the old client-server protocol using the standard input and output. This option is useful when hfaxd is started up by inetd(1m).

-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(1m).

DIAGNOSTICS

FILES

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

BUGS

SEE ALSO

Index

NAME

SYNOPSIS

DESCRIPTION

HYLAFAX (NEW) CLIENT-SERVER PROTOCOL SUPPORT

OLD CLIENT-SERVER PROTOCOL SUPPORT

SIMPLE NETWORK PAGING PROTOCOL (SNPP) SUPPORT

CLIENT ACCESS CONTROL

SERVER ACCESS CONTROL

CONFIGURATION FILES

OPTIONS

DIAGNOSTICS

FILES

BUGS

SEE ALSO