HFAXD

hfaxd − Hyla FAX client-server protocol server

${LIBEXEC}/hfaxd [ −d ] [ −q dir ] [ −o port ] [ −O ] [ −l bindaddress ] [ −i port ] [ −I ] [ −s port ] [ −S ]

hfaxd is the Hyla FAX program that implements the server portion of:

•

the client-server protocol 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 (in which case the -i, -o, or -s option must be used), 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.

If hfaxd is started with the −i option it will service clients using the Hyla FAX 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 Hyla FAX 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 ¹ can be used only when the client has established administrative privileges with ADMIN .

ABOR

abort previous command

ACCT

specify account (ignored)

ADMIN

specify password for administrative privileges

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

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.

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

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 ¹ 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.

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

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.

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.

hfaxd controls client access according to the information in the file ${SPOOL}/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(4f) 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 Hyla FAX spooling area; ${SPOOL}. This is done so that clients see a virtual file hierarchy that is completely contained within the Hyla FAX 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.

The file ${SPOOL}/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(4f) 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).

hfaxd reads configuration information from the file ${LIBDATA}/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 Hyla FAX configuration files; as described in hylafax-config(4f). The following configuration parameters are recognized; items marked ‘‘( SNPP )’’ are used only by the SNPP support.

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

${SPOOL}/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

${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:

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.

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.

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 Hyla FAX 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 Hyla FAX 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.

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’’.

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(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.

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 )

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.

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 Hyla FAX 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).

−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 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(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 generated by hfaxd are logged using syslog(3).

${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

To be filled in.

sendfax(1), sendpage(1), faxalter(1), faxrm(1), faxstat(1), faxq(1m), syslog(3) hylafax-server(4f), hosts.hfaxd(4f), status(4f), hylafax-shutdown(4f),