| HFAXD(8) | System Manager's Manual | HFAXD(8) |
hfaxd - HylaFAX client-server protocol server
/usr/sbin/hfaxd [ -d ] [ -q dir ] [ -o port ] [ -O ] [ -l bindaddress ] [ -i port ] [ -I ] [ -s port ] [ -S ]
hfaxd is the HylaFAX program that implements the server portion of:
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.
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 ¹ 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) 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.
Request Description 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.
Request Description 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.
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.
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.
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).
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:
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)
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
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)
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)
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
Diagnostics generated by hfaxd are logged using syslog(3).
/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
To be filled in.
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 |