NAME
hfaxd - HylaFAX client-server protocol server
SYNOPSIS
/usr/sbin/hfaxd [ -d ] [ -q dir ] [ -o port ] [ -O ] [ -l bindaddress ]
[ -i port ] [ -I ] [ -s port ] [ -S ]
DESCRIPTION
hfaxd is the HylaFAX program that implements the server portion of:
o the client-server protocol and
o 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 (in which case the -i, -o, or -s
option must be used), or as a subservient process to the inetd(8)
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
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. (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.)
The hfaxd server currently recognizes the following protocol requests;
case is not distinguished. Entries marked with a 1 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)
ANSWER1 request that call be answered
APPE append to a file
CDUP change to parent of current working directory
CHMOD change mode of a file
CHOWN1 change owner of a file
CWD change working directory
DELE delete a file
DISABLE1 disable outbound use of modem
ENABLE1 enable outbound use of modem
HELP give help information
FILEFMT specify/query format for returning file status
FILESORTFMT specify/query format for sorting file status listing
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
JOBSORTFMT specify/query format for sorting job status listing
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
MDMSORTFMT specify/query format for sorting modem status listing
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
RCVSORTFMT specify/query format for sorting received facsimile status listing
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
ADDMODEM1 add/configure new modem for use
ADDUSER1 add client access control entry
CONFIG1 send configuration parameter setting to server
DELMODEM1 deconfigure/remove modem
DELUSER1 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.
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).
The hfaxd server currently recognizes the SNPP protocol requests listed
below. Requests marked with a 1 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
ABOR1 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)
SITE1 site-specific commands (see next section)
STAT1 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
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(5) 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).
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; /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.
SERVER ACCESS CONTROL
The file /var/spool/hylafax/etc/shutdown, when present, specifies when
to restrict access to a server machine. When this file is present and
contains valid information hfaxd will permit only users with
administrative privileges to access the server. Any other users that
request service will be denied access and negative server responses
will include any shutdown message specified in the shutdown file.
Consult hylafax-shutdown(5) for information on the format and content
of this file.
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
hfaxd reads configuration information from the file
/etc/hylafax/hfaxd.conf each time a new server process is started (i.e.
for each new client). This file uses the same conventions used by
other HylaFAX configuration files; as described in hylafax-config(5).
The following configuration parameters are recognized; items marked
``(SNPP)'' are used only by the SNPP support.
Tag Type Default Description
AllowSortFormat boolean true Allow client to request sorting formats
FaxContact string see below contact address to show in help text
FileFmt string see below format string for file status results
FileSortFmt string - format string for sorting file status listing
IdleTimeout integer 900 client idle timeout in seconds
JobFmt string see below format string for job status results
JobSortFmt string - format string for sorting job status listing
JobProtection octal 0444 permissions for job qfiles in sendq/doneq
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
ModemSortFmt string - format string for sorting modem status listing
PagerIDMapFile string /var/spool/hylafax/etc/pagermap name of file for mapping pager IDs (SNPP)
PriorityMap string see below mapping from service level to job priority (SNPP)
PublicJobQ boolean true Allow public listing access to the sendq/doneq
PublicRecvQ boolean true Allow public listing access to the recvq
RcvFmt string see below format string for received facsimile status results
RcvSortFmt string - format string for sorting received facsimile status results listing
RetryTimeMap string see below mapping from service level to job retry time (SNPP)
ServerTracing integer 1 server tracing control vector
ShutdownFile string /var/spool/hylafax/etc/shutdown name of shutdown control file
UserAccessFile string /var/spool/hylafax/etc/hosts.hfaxd name of access control file
XferLogFile string /var/spool/hylafax/etc/clientlog name of file for logging client data transfers
The configuration parameters are explained below:
AllowSortFormat
This controls whether the server accept the *SORTFMT commands
which the client issues to change the server sort the
listings.
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.
FileSortFmt
The format string to use when sorting the listing for
directories using the LIST command. Follows the FileFmt
formatting rules.
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)
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.
JobSortFmt
The format string to use when sorting the listing for jobs in
the sendq and doneq directories. Follows the JobFmt
formatting rules.
JobProtection
The file mode setting for job qfiles in the HylaFAX queues
(sendq and doneq). The default setting of ``0644'' allows
all users to view all job parameters in the send/done queues.
If PublicJobQ is set to false, then this file 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.
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
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.
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(8) process is running; otherwise `` '' (space)
The default format string is ``Modem %m (%n): %s''.
ModemSortFmt
The format string to use when sorting the listsin for modem
status information in the status directory.
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(5) 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.
PublicJobQ
By default, HylaFAX has always made the listings of the
sendq/doneq include all jobs to any client connected to
hfaxd. By setting this to false, hfaxd will also enforce
it's normal access restrictions on the listing of jobs in the
sendq/doneq. These access restrictions are based on the file
mode (see JobProtection ) and the logged in uid (see
hosts.hfaxd )
PublicRecvQ
By default, HylaFAX has always made the listings of the recvq
include all faxes to any client connected to hfaxd. By
setting this to false, hfaxd will also enforce it's normal
access restrictions on the listing of faxes in the recvq.
These access restrictions are based on the file mode faxgetty
(and it's related FaxDispatch ) set for the fax, and the
logged in uid (see hosts.hfaxd )
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.
RcvSortFmt
The format string to use when sorting the listing for
received facsimile in the recvq directory. Follows
the RcvFmt formatting rules.
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(8)
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(8) 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(5) 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(5) 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(8) 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 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.
Each time this flag is specified, it will listen on
the specified port, bound to the last -l bindaddress
specified. If no -l bindaddress was specified, it
will bind to the system configured default wildcard
address, which could be any of IPv6, or IPv4, or both.
-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(8).
-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(8).
DIAGNOSTICS
Diagnostics generated by hfaxd are logged using syslog(3).
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/docq/seqf for assigning document identifiers
/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.
SEE ALSO
sendfax(1), sendpage(1), faxalter(1), faxrm(1), faxstat(1),
faxq(8), syslog(3) hylafax-server(5), hosts.hfaxd(5), status(5),
hylafax-shutdown(5),
July 12, 1996