1HFAXD(8C)                                                            HFAXD(8C)
2
3
4

NAME

6       hfaxd - HylaFAX client-server protocol server
7

SYNOPSIS

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

DESCRIPTION

14       hfaxd is the HylaFAX program that implements the server portion of:
15
16       ·  the client-server protocol and
17
18       ·  the  Simple  Network  Paging  Protocol (SNPP) used to submit message
19          pager jobs to the IXO/TAP and UCP support.
20
21       Additional client-server protocols are planned and hfaxd is intended to
22       be the ``carrier'' through which they are supported.
23
24       hfaxd  is  typically  used  in one of two ways; either as a stand-alone
25       process that is started at system boot time to listen for  client  con‐
26       nections  on  one or more ports (in which case the -i, -o, or -s option
27       must be used), or as a subservient process to  the  inetd(8C)  program.
28       The  two  forms of use may however be combined so long as the same ser‐
29       vice is not provided both by the stand-alone hfaxd and through inetd.
30

HYLAFAX CLIENT-SERVER PROTOCOL SUPPORT

32       If hfaxd is started with the -i option it will  service  clients  using
33       the  HylaFAX client-server protocol.  This protocol is strongly related
34       to the Internet File Transfer Protocol (FTP); so much so in  fact  that
35       FTP client programs that include support for ``quoted commands'' may be
36       used to communicate with hfaxd using the new protocol.  (It should also
37       be possible to use FTP-aware World Wide Web browsers such as Mosaic and
38       Netscape Navigator to access HylaFAX servers through the new  protocol;
39       but  the  current format for information returned in directory listings
40       confuses them.)
41
42       The hfaxd server currently recognizes the following protocol  requests;
43       case  is  not  distinguished.  Entries marked with a ¹ can be used only
44       when the client has established administrative privileges with ADMIN.
45
46       Request         Description
47       ABOR            abort previous command
48       ACCT            specify account (ignored)
49       ADMIN           specify password for administrative privileges
50       ALLO            allocate storage (vacuously)
51       ANSWER¹         request that call be answered
52       APPE            append to a file
53       CDUP            change to parent of current working directory
54       CHMOD           change mode of a file
55       CHOWN¹          change owner of a file
56       CWD             change working directory
57       DELE            delete a file
58       DISABLE¹        disable outbound use of modem
59       ENABLE¹         enable outbound use of modem
60       HELP            give help information
61       FILEFMT         specify/query format for returning file status
62       FORM            specify data transfer format
63       IDLE            set idle-timer (in seconds)
64       JDELE           delete done or suspended job
65       JINTR           interrupt job
66       JKILL           kill job
67       JNEW            create new job
68       JOB             set/query current job
69       JOBFMT          specify/query format for returning job status
70       JPARM           specify/query job state parameter
71       JREST           reset current job state
72       JSUBM           submit job to scheduler
73       JSUSP           suspend job from scheduling
74       JWAIT           wait for job to complete
75       JGDELE          delete group of jobs
76       JGKILL          kill group of jobs
77       JGINTR          interrupt group of jobs
78       JGNEW           place current job in a new job group
79       JGPARM          set state parameter in a group of jobs
80       JGREST          reset current state for a group of jobs
81       JGRP            set/query current job group
82       JGSUBM          submit group of jobs to scheduler
83       JGSUSP          suspend group of jobs from scheduling
84       JGWAIT          wait for group of jobs to complete
85       LIST            list files in a directory
86       MDTM            show last modification time of file
87       MODE            specify data transfer mode
88       MDMFMT          specify/query format for returning modem status
89       NLST            give name list of files in directory
90       NOOP            do nothing
91       PASS            specify password
92       PASV            prepare for server-to-server transfer
93       PORT            specify data connection port
94       PWD             print the current working directory
95       QUIT            terminate session
96       RCVFMT          specify/query format for returning received facsimile status
97       REIN            reinitiate server state
98       REST            restart incomplete transfer
99       RETP            retrieve the next page in a file
100       RETR            retrieve a file
101       SHUT            schedule server shutdown
102       SITE            non-standard commands (see next section)
103       SIZE            return size of file
104       STAT            return status of server or file
105       STOR            store a file
106       STOT            store a temporary file with a unique name
107       STOU            store a file with a unique name
108       STRU            specify data transfer structure
109       SYST            show operating system type of server system
110       TYPE            specify data transfer type
111       TZONE           specify timezone handling for dates and times
112       USER            specify user name
113       VRFY            verify dialstring handling and/or least-cost routing
114
115       The following  non-standard  or  experimental  commands  are  supported
116       through the SITE request.
117
118       Request          Description
119       ADDMODEM¹        add/configure new modem for use
120       ADDUSER¹         add client access control entry
121       CONFIG¹          send configuration parameter setting to server
122       DELMODEM¹        deconfigure/remove modem
123       DELUSER¹         remove client access control entry
124       TRIGGER          register real-time event trigger
125       HELP             give help information, e.g., SITE HELP
126
127       In addition FTP requests that are specified in Internet RFC 959 but not
128       listed here are recognized, but not implemented.
129
130       The hfaxd server will abort an active data transfer only when the  ABOR
131       command  is  preceded by a Telnet "Interrupt Process" (IP) signal and a
132       Telnet "Synch" signal in the command Telnet  stream,  as  described  in
133       Internet  RFC  959.  If a STAT command is received during a data trans‐
134       fer, preceded by a  Telnet  IP  and  Synch,  transfer  status  will  be
135       returned.
136

SIMPLE NETWORK PAGING PROTOCOL (SNPP) SUPPORT

138       If  hfaxd  is  started with the -s option it will service clients using
139       the Simple Network Pager Protocol  (SNPP)  as  specified  in  RFC  1861
140       (which obsoletes RFC 1645).
141
142       The hfaxd server currently recognizes the SNPP protocol requests listed
143       below.  Requests marked with a ¹ are  non-standard  extensions  to  RFC
144       1861  that  may be added to SNPP at some future time.  Case is not dis‐
145       tinguished and only the first four characters of requests are  used  in
146       identifying commands.
147
148       Request      Description
149       2WAY         preface a 2-way transaction
150       ABOR¹        abort previous command
151       ACKR         set read acknowledgement handling for subsequent requests
152       ALER         set the alter-level for subsequent requests
153       CALL         set the caller-ID for subsequent requests
154       COVE         set the alternate coverage area for subsequent requests
155       DATA         specify a multi-line message
156       EXPT         set the expiration time for subsequent requests
157       HELP         give help information
158       HOLD         set the time at which subsequent requests are to be delivered
159       KTAG         kill a previously submitted request
160       LEVE         set the service level for subsequent requests
161       LOGI         login to server
162       MCRE         specify multiple response text and code
163       MESS         specify a single-line message
164       MSTA         return the status of a previously submitted request
165       NOQU         disable message queueing
166       PAGE         specify the destination pager
167       PING         locate/validate a pager
168       QUIT         terminate session
169       RESE         reset server state
170       RTYP         set the reply type code for subsequent requests
171       SEND         send message(s)
172       SITE¹        site-specific commands (see next section)
173       STAT¹        return server status
174       SUBJ         set the message text for subsequent requests
175
176       The  hfaxd server will abort an active SEND operation when an ABOR com‐
177       mand is preceded by a Telnet "Interrupt Process" (IP) signal and a Tel‐
178       net "Synch" signal in the command Telnet stream.
179
180       The  following non-standard or experimental commands are also supported
181       through the SITE request.
182
183       Request        Description
184       FROMUSER       specify the sender's identity
185       IDLE           set idle-timer (in seconds)
186       JPARM          query job parameter status
187       JQUEUE         control whether or not job is queued
188       LASTTIME       set the time to terminate an unfinished job
189       MAILADDR       set the e-mail address to use for notification
190       MAXDIALS       set the maximum number of times to dial the phone
191       MAXTRIES       set the maximum number of times to try sending the page
192       MODEM          set the modem or class of modems to use
193       NOTIFY         set the e-mail notification
194       RETRYTIME      set the time to delay between job retries
195       SCHEDPRI       set the scheduling priority for the job
196       HELP           give help information, e.g., SITE HELP
197
198       Note that hfaxd requires that SNPP clients login first  with  the  LOGI
199       directive while RFC 1861 permits clients to submit pages anonymously.
200

CLIENT ACCESS CONTROL

202       hfaxd  controls  client access according to the information in the file
203       /var/spool/hylafax/etc/hosts.hfaxd.  This file defines the set of users
204       and machines that may receive service and, optionally, defines password
205       challenges to use in authenticating clients.  Clients may be  permitted
206       access  to  services  with or without a password challenge.  Access may
207       also be restricted based on the host machine that a request for service
208       originates from.  Consult hosts.hfaxd(5F) for information on the format
209       and content of this file.  The SITE ADDUSER protocol  request  is  pro‐
210       vided  for adding new users to a server (available only to clients with
211       administrative privileges).
212
213       Server resources are controlled based on clients' identities.  Jobs and
214       documents,  both  received  and submitted, are protected by the server.
215       Typically clients are permitted access to anything they own or that  is
216       publicly  accessible.   There  are  also administrative privileges that
217       clients may acquire and which permit them wide access to  objects  that
218       reside on the server.
219
220       A complete client-server protocol specification is still outstanding.
221
222       hfaxd  operates  with  its root directory set to the top of the HylaFAX
223       spooling area; /var/spool/hylafax.  This is done so that clients see  a
224       virtual  file hierarchy that is completely contained within the HylaFAX
225       operating environment on the server  machine.   Administrators  however
226       must be aware of this action when specifying files in the hfaxd config‐
227       uration file: absolute pathnames relative to the root of  the  spooling
228       should be used to specify filenames.
229

SERVER ACCESS CONTROL

231       The  file /var/spool/hylafax/etc/shutdown, when present, specifies when
232       to restrict access to a server machine.  When this file is present  and
233       contains  valid  information hfaxd will permit only users with adminis‐
234       trative privileges to access the server.  Any other users that  request
235       service  will  be  denied  access  and  negative  server responses will
236       include any shutdown message specified in the shutdown  file.   Consult
237       hylafax-shutdown(5F)  for information on the format and content of this
238       file.
239
240       The SHUT protocol request can be used to schedule a server shutdown; it
241       is available only to clients with administrative privileges.  To make a
242       shutdown server available again the shutdown file can be  deleted  with
243       the  DELE  protocol  request (this is to be replaced with an ``unshut''
244       protocol request so that implementation details are  not  part  of  the
245       protocol).
246

CONFIGURATION FILES

248       hfaxd     reads     configuration    information    from    the    file
249       /etc/hylafax/hfaxd.conf each time a new server process is started (i.e.
250       for  each  new  client).   This  file uses the same conventions used by
251       other HylaFAX configuration files; as described in  hylafax-config(5F).
252       The  following  configuration  parameters  are recognized; items marked
253       ``(SNPP)'' are used only by the SNPP support.
254       Tag                      Type       Default                             Description
255       FaxContact               string     see below                           contact address to show in help text
256       FileFmt                  string     see below                           format string for file status results
257       IdleTimeout              integer    900                                 client idle timeout in seconds
258       JobFmt                   string     see below                           format string for job status results
259       JobHostID                string                                         identification information for job hosts
260       JobProtection            octal      0644                                permissions for job qfiles in sendq/doneq
261       KillTimeMap              string     see below                           mapping from service level to job kill time (SNPP)
262       LDAPServerURI            string                                         URI of the ldap server including port number
263       LDAPBaseDN               string                                         LDAP context where user objects can be found
264       LDAPBindQuery            string                                         format for the LDAP bind query
265       LDAPGroupAttribute       string     groupMembership                     LDAP group attribute label
266       LDAPReqGroup             string                                         LDAP context of the users group
267       LDAPSearchDN             string                                         format for the UserDN in LDAP search
268       LDAPSearchQuery          string     uid=%s                              format for the LDAP search query
269       LDAPVersion              integer    3                                   LDAP protocol version to use
270       LogFacility              string     daemon                              syslog facility name for tracing messages
271       MaxAdminAttempts         integer    5                                   maximum admin attempts before disconnecting
272       MaxConsecutiveBadCmds    integer    10                                  maximum invalid commands before disconnecting
273       MaxIdleTimeout           integer    7200                                maximum client idle timeout permitted
274       MaxLoginAttempts         integer    5                                   maximum login attempts before disconnecting
275       MaxMsgLength             integer    128                                 maximum pager message length (SNPP)
276       ModemFmt                 string     see below                           format string for modem status results
277       PagerIDMapFile           string     /var/spool/hylafax/etc/pagermap     name of file for mapping pager IDs (SNPP)
278       PriorityMap              string     see below                           mapping from service level to job priority (SNPP)
279       RcvFmt                   string     see below                           format string for received facsimile status results
280       RecvqProtection          octal      0444                                permissions for client access to recvq
281       RetryTimeMap             string     see below                           mapping from service level to job retry time (SNPP)
282       ServerTracing            integer    1                                   server tracing control vector
283       ShutdownFile             string     /var/spool/hylafax/etc/shutdown     name of shutdown control file
284       UserAccessFile           string     /var/spool/hylafax/etc/hosts.hfaxd  name of access control file
285       XferLogFile              string     /var/spool/hylafax/etc/clientlog    name of file for logging client data transfers
286
287       The configuration parameters are explained below:
288
289       FaxContact
290                 The e-mail address to display as a point of  contact  in  the
291                 help  text  returned  to  a client in response to the HELP or
292                 SITE HELP commands.  By  default  this  is  ``FaxMaster@host‐
293                 name'',  where  hostname  is the fully qualified name for the
294                 machine where the server is running.
295
296       FileFmt   The format string to use when returning file status  informa‐
297                 tion  with the LIST and STAT commands.  Formats are specified
298                 using printf(3S) style conventions but using the field  iden‐
299                 tifiers  listed  below.   Each  item can include field width,
300                 precision, left-justification, 0-filling, etc.  just  as  for
301                 printf;  e.g.  %-8p  for an 8-character wide, left-justified,
302                 blank-padded field containing the file protection flags.
303
304                 Format    Description
305                 a         Last access time
306                 c         Creation time
307                 d         Device number (octal)
308                 f         Filename
309                 g         Group identifier (decimal)
310                 i         Inode number (decimal)
311                 l         Link count (decimal)
312                 m         Last modification time
313                 o         Owner (based on file GID)
314                 p         Fax-style protection flags (no group bits)
315                 q         UNIX-style protection flags
316                 r         Root device number (octal)
317                 s         File size in bytes (decimal)
318                 u         User identifier (decimal)
319
320                 The default format string is  ``%-7p  %3l  %8o  %8s  %-12.12m
321                 %.48f''.   It  is  recommended that all items include a field
322                 width so that client applications that construct headers from
323                 the  format  string  can  constrain the width of column title
324                 strings.
325
326       IdleTimeout
327                 The  initial/default  timeout  to  use  in  timing  out  idle
328                 clients.   This  value defines the maximum amount of time (in
329                 seconds) that hfaxd will wait for a  command  from  a  client
330                 before  terminating the connection.  Unprivileged clients may
331                 alter the idle timeout up to  the  value  of  MaxIdleTimeout;
332                 privileged clients may set the timeout to any value.
333
334       JobFmt    The  format  string to use when returning job status informa‐
335                 tion for jobs in the sendq and  doneq  directories.   Formats
336                 are  specified  using  printf(3S) style conventions but using
337                 the field identifiers listed below.  Each  item  can  include
338                 field  width,  precision, left-justification, 0-filling, etc.
339                 just as for printf; e.g. %-3j for a 3-character  wide,  left-
340                 justified, blank-padded field containing the job state.
341
342                 Format    Description
343                 A         Destination SubAddress
344                 B         Destination Password
345                 C         Destination company name
346                 D         Total # dials/maximum # dials
347                 E         Desired signalling rate
348                 F         Client-specific tagline format string
349                 G         Desired min-scanline time
350                 H         Desired data format
351                 I         Client-specified scheduling priority
352                 J         Client-specified job tag string
353                 K         Desired use of ECM
354                 L         Destination geographic location
355                 M         Notification e-mail address
356                 N         Desired use of private tagline (one-character symbol)
357                 O         Whether to use continuation cover page (one-character symbol)
358                 P         # pages transmitted/total # pages to transmit
359                 Q         Client-specified minimum acceptable signalling rate
360                 R         Destination person (receiver)
361                 S         Sender's identity
362                 T         Total # tries/maximum # tries
363                 U         Page chopping threshold (inches)
364                 V         Job done operation
365                 W         Communication identifier
366                 X         Job type (one-character symbol)
367                 Y         Scheduled date and time
368                 Z         Scheduled time in seconds since the UNIX epoch
369                 a         Job state (one-character symbol)
370                 b         # consecutive failed tries
371                 c         Client machine name
372                 d         Total # dials
373                 e         Public (external) format of dialstring
374                 f         # consecutive failed dials
375                 g         Group identifier
376                 h         Page chop handling (one-character symbol)
377                 i         Current scheduling priority
378                 j         Job identifier
379                 k         Job kill time
380                 l         Page length in mm
381                 m         Assigned modem
382                 n         E-mail notification handling (one-character symbol)
383                 o         Job owner
384                 p         # pages transmitted
385                 q         Job retry time (MM::SS)
386                 r         Document resolution in lines/inch
387                 s         Job status information from last failure
388                 t         Total # tries attempted
389                 u         Maximum # tries
390                 v         Client-specified dialstring
391                 w         Page width in mm
392                 x         Maximum # dials
393                 y         Total # pages to transmit
394                 z         Time to send job
395
396                 The  default  format  string is ``%-4j %3i %1a %6.6o %-12.12e
397                 %5P %5D %7z %.25s''.  This string constrains each status line
398                 to  be  less  than 80 characters.  It is recommended that all
399                 items include a field width so that client applications, such
400                 as  faxstat(1)  that construct headers from the format string
401                 can constrain the width of column title strings.
402
403       JobHostID A  formatted  string  of  the  format  ``<id>[:<host>[:<user‐
404                 name>:<password>:<adminwd>]]''  that  identifies  a job host.
405                 Multiple instances of JobHostID are used in the configuration
406                 file  to  identify multiple job hosts.  ``<id>'' is a numeric
407                 identification for the host which is prepended onto  job  ids
408                 created  by  that  host.  This is used by a client to distin‐
409                 guish between jobs created on different hosts when it may not
410                 initially know to which server it connected. ``<id>'' must be
411                 the same number of digits for all configured job hosts.   For
412                 compatibility with all clients ``<id>'' must be numeric only.
413                 If the instance of JobHostID only includes ``<id>''  then  it
414                 is  understood  to  refer  to the local host and not a remote
415                 host.   It  is  this  configuration  entry  that  causes  the
416                 prepending  of  the  ``<id>''  number  onto the job ids.  The
417                 other values for the formatted  string  refer  to  connection
418                 details  for  user-level and admin-level login at the identi‐
419                 fied remote host.  If only ``<host>'' is  provided  then  the
420                 current  user's  login  credentials  are used for the chained
421                 connection.  This configuration will cause hfaxd  to  connect
422                 as  a  client  to the specified remote host for the requested
423                 action when the job id provided by its client refers to  that
424                 remote  host  (the provided job id matches the ``<id>'' value
425                 in the host's JobHostID configuration).  To do this the hfaxd
426                 client  connection to the remote host requires administrative
427                 privileges or synchonized user accounts on  both  hosts.   Be
428                 aware that when providing ``<username>'', ``<password>'', and
429                 especially ``<adminwd>'' in the configuration that  this  may
430                 compromise  job  security on the remote host since users from
431                 this host will be connecting to the remote host as a  differ‐
432                 ent user (and possibly with administrative privileges).  As a
433                 null value for ``<adminwd>'' is  permissible,  administrative
434                 privileges  may  be omitted by using ``*'' for ``<adminwd>''.
435                 Because of the chroot under  which  the  client  instance  of
436                 hfaxd  operates  it will be necessary to copy numerous system
437                 files to the HylaFAX spool directory structure  so  that  the
438                 chained client connection can be made to the remote job host.
439                 This copy should be repeated after any upgrades or changes to
440                 the system files.  To identify which files must be copied one
441                 may examine strace output for  faxstat  and  look  for  which
442                 files it opens in the operation.
443
444       JobProtection
445                 The  default setting of ``0644'' allows all users to view all
446                 job parameters in the send and done queues.   The mode deter‐
447                 mines the permissions of the clients to see the jobs, follow‐
448                 ing the HylaFAX permission model of the group  bits  control‐
449                 ling  uid  permissions  and  the other bits controlling other
450                 permissions.  A setting of ``0640'' allows only the job owner
451                 and  the  administrator to view jobs.  If a user doesn't have
452                 permissions on the job, the job will not be visible  to  them
453                 when viewing the queues.
454
455       KillTimeMap
456                 The  mapping from SNPP service level (0-11) to job expiration
457                 time (kill time).  A mapping is  specified  as  a  string  of
458                 space-separate numbers where each value is the number of min‐
459                 utes to permit a job to run.  The default mapping is ``5 5  5
460                 15  60 240 720 1440 1440 1440 1440 1440'' which expires a job
461                 in 5 minutes for service levels 0-2,  15  minutes  for  level
462                 three, 60 minutes for level four, etc.
463
464       LDAPServerURI
465                 The  full  address  of the ldap server including port number,
466                 i.e.:  ldaps://1.2.3.4:636  (for   secure   connections)   or
467                 ldap://1.2.3.4:389 (for insecure connections)
468
469       LDAPBaseDN
470                 The  full LDAP context where user objects can be found, i.e.:
471                 ou=users,dc=example,dc=com  for  Active   Directory/LDAP   or
472                 ou=users,o=organization for Novell eDirectory
473
474       LDAPBindQuery
475                 The  format  for the LDAP bind query (ldap_sasl_bind_s) where
476                 ``%s'' is replaced with the username.   If  LDAPBindQuery  is
477                 not  configured,  then  the  bind  query  will use the format
478                 ``cn=%s,<BaseDN>''  where  ``%s''  is   the   username,   and
479                 ``<BaseDN>'' is the configured LDAPBaseDN string.
480
481       LDAPGroupAttribute
482                 The  label  for the group membership data.  On older OpenLDAP
483                 servers this  should  probably  be  ``groupMembership''.   On
484                 ActiveDirectory this should probably be ``memberOf''.
485
486       LDAPReqGroup
487                 The  full LDAP context of the group users have to be a member
488                 of to gain HylaFAX access for sending faxes.  If this is  not
489                 set then no group membership is required.
490
491       LDAPSearchDN
492                 The    format   for   the   UserDN   in   the   LDAP   search
493                 (ldap_search_ext_s) where ``%s'' is replaced with  the  user‐
494                 name.  By default this is the same as LDAPBindQuery .
495
496       LDAPSearchQuery
497                 The  format  for  the  LDAP  search query (ldap_search_ext_s)
498                 where ``%s'' is replaced with the username.  By default  this
499                 is  ``uid=%s''.   On  ActiveDirectory this should probably be
500                 set to ``cn=%s''.
501
502       LDAPVersion
503                 Version number of the LDAP Protocol to use (default is '3')
504
505       LogFacility
506                 The symbolic name for the syslog(3) facility to use when log‐
507                 ging  error  messages  and  informational/debugging  messages
508                 requested through the ServerTracing parameter.  The  list  of
509                 facility  names  is  found  in  the system include file <sys‐
510                 log.h>; comparisons are case-insensitive.
511
512       MaxAdminAttempts
513                 The maximum number of unsuccessful attempts gain  administra‐
514                 tive privileges with the ADMIN command that hfaxd will permit
515                 a client before terminating the connection.   Note  that  the
516                 count  of  attempts  is reset if/when the client successfully
517                 gains administrative privileges.
518
519       MaxConsecutiveBadCmds
520                 The maximum  number  of  consecutive  unrecognized,  unimple‐
521                 mented,  syntactically  incorrect,  or otherwise unacceptable
522                 commands to permit a client before  terminating  the  connec‐
523                 tion.   This  control  has  two  purposes: to handle naive or
524                 malicious clients from sending long streams of nonsense  com‐
525                 mands  to  a  server, and to ensure that clients are forcibly
526                 terminated when a server is marked shutdown.
527
528       MaxIdleTimeout
529                 The maximum value that a client may set the idle timeout  to.
530                 This  value  is not enforced if the client has administrative
531                 privileges.
532
533       MaxLoginAttempts
534                 The maximum number of unsuccessful attempts to login with the
535                 USER and PASS commands that hfaxd will permit a client before
536                 terminating the connection.
537
538       MaxMsgLength
539                 The maximum number of characters to accept in a pager message
540                 specified  with  the  DATA or MESS commands.  Messages longer
541                 than this value are rejected.
542
543       ModemFmt  The format string to use when returning modem status informa‐
544                 tion  for modems listed in the status directory.  Formats are
545                 specified using printf(3S) style conventions  but  using  the
546                 field  identifiers listed below.  Each item can include field
547                 width, precision, left-justification, 0-filling, etc. just as
548                 for  printf;  e.g.  %-8h for an 8-character wide, left-justi‐
549                 fied, blank-padded field containing the name of the host  the
550                 server is running on.
551
552                 Format    Description
553                 h         Server hostname
554                 l         Local identifier string
555                 m         Canonical modem name
556                 n         FAX phone number
557                 r         Maximum pages that can be received in a single call
558                 s         Status information string
559                 t         Server and session tracing levels (xxxxx:yyyyy)
560                 v         Modem speaker volume as one-character symbol
561                 z         A ``*'' if a faxgetty(8C) process is running; otherwise `` '' (space)
562
563                 The default format string is ``Modem %m (%n): %s''.
564
565       PagerIDMapFile
566                 The  absolute  pathname  of the file that contains directions
567                 for mapping pager  identifiers  to  IXO/TAP  or  UCP  service
568                 providers  (and  optionally  a  pager identification number).
569                 Consult pagermap(5F) for information on the format  and  con‐
570                 tent  of  this file.  (Note that absolute pathnames are rela‐
571                 tive to the root of the spooling area).
572
573       PriorityMap
574                 The mapping from SNPP service level (0-11) to job  scheduling
575                 priority.   A mapping is specified as a string of space-sepa‐
576                 rate numbers where each value is the priority to assign to  a
577                 job.  The default mapping is ``63 127 127 127 127 127 127 127
578                 127 127 127 127'' which assigns a high  priority  to  service
579                 level zero and normal (default) priority to all other service
580                 levels.
581
582       RcvFmt    The format string to use when  returning  status  information
583                 for  received  facsimile in the recvq directory.  Formats are
584                 specified using printf(3S) style conventions  but  using  the
585                 field  identifiers listed below.  Each item can include field
586                 width, precision, left-justification, 0-filling, etc. just as
587                 for printf; e.g. %-3b for a 3-character wide, left-justified,
588                 blank-padded field containing the signalling rate.
589
590                 Format    Description
591                 X         Reception indicator (1=yes, 0=no)
592                 Y         Received date and time
593                 Z         Received time in seconds since the UNIX epoch
594                 a         SubAddress received from sender (if any)
595                 b         Signalling rate used during receive
596                 d         Data format used during receive
597                 e         Error description if an error occurred during receive
598                 f         Document filename (relative to the recvq directory)
599                 h         Time spent receiving document (HH:MM:SS)
600                 l         Page length in mm
601                 m         Fax-style protection mode string (``-rwxrwx'')
602                 n         File size (number of bytes)
603                 o         File owner
604                 p         Number of pages in document
605                 q         UNIX-style protection flags
606                 r         Resolution of received data
607                 s         Sender identity (TSI)
608                 t         Compact representation of the time when the receive happened
609                 w         Page width in mm
610                 z         A ``*'' if receive is going on; otherwise `` '' (space)
611
612                 The default format string is ``%-7m %4p%1z %-8.8o %14.14s %7t
613                 %f''.   This  string  constrains  each status line to be less
614                 than 80 characters.  It is recommended that all items include
615                 a field width so that client applications, such as faxstat(1)
616                 that construct headers from the format string  can  constrain
617                 the width of column title strings.
618
619       RecvqProtection
620                 The  permissions setting for administrator, owners, and users
621                 for viewing files in the HylaFAX receive queue.  The  default
622                 setting of ``0444'' allows all users to view all files in the
623                 queues.  A setting of ``0440'' allows only the job owner  and
624                 the  administrator  to  view  files.   A  setting of ``0040''
625                 allows only the administrator to view the files.  If  a  user
626                 doesn't  have  permissions  on the file, the file will not be
627                 visible to them when viewing the queue.
628
629       RetryTimeMap
630                 The mapping from SNPP service level (0-11) to job retry time.
631                 A  mapping is specified as a string of space-separate numbers
632                 where each value is the number of seconds  to  delay  between
633                 delivery  attempts.   A  value  of  zero causes retries to be
634                 scheduled using the default algorithm used by the HylaFAX job
635                 scheduler.  The default mapping is ``30 60 60 180 0 0 0 0 0 0
636                 0 0'' which retries a level 0 job after a  30  second  delay,
637                 levels 1 and 2 after 60 seconds, level 3 after 3 minutes, and
638                 other jobs are retried  according  to  the  usual  scheduling
639                 algorithm.
640
641       ServerTracing
642                 A  number that controls the generation of tracing information
643                 by a server.  areas that  are  individually  controlled.   To
644                 enable tracing of multiple areas of operation, the flag asso‐
645                 ciated with each area should be bit-or'd to  form  the  value
646                 for this tag.
647                 Flag             Description
648                 1 (0x00001)      General server operation
649                 2 (0x00002)      Client-server protocol requests and responses
650                 4 (0x00004)      File transfers from client to server
651                 8 (0x00008)      File transfers from server to client
652                 16 (0x00010)     Client logins
653                 32 (0x00020)     All network connections
654                 64 (0x00040)     FIFO messages to and from faxq(8C)
655                 128 (0x00080)    TIFF Library errors and warnings
656                 256 (0x00100)    Configuration file processing
657
658                 Tracing messages are directed to syslog(3) using the facility
659                 specified with the LogFacility configuration parameter.  Note
660                 that syslogd(8C) must be configured to capture facility.info,
661                 facility.debug, facility.warning, and facility.err messages.
662
663       ShutdownFile
664                 The absolute  pathname  of  the  server  shutdown  file;  see
665                 hylafax-shutdown(5F)  for  information on the format and con‐
666                 tent of this file.  (Note that absolute pathnames  are  rela‐
667                 tive to the root of the spooling area).
668
669       UserAccessFile
670                 The  absolute  pathname  of the user access control file; see
671                 hosts.hfaxd(5F) for information on the format and content  of
672                 this file.  (Note that absolute pathnames are relative to the
673                 root of the spooling area).
674
675       XferLogFile
676                 The absolute pathname of the file to use for logging  client-
677                 server file transfers (when enabled through the ServerTracing
678                 parameter).  (Note that absolute pathnames  are  relative  to
679                 the root of the spooling area).
680

OPTIONS

682       -q dir    The specified directory is treated as the spooling area.  The
683                 default spooling area, /var/spool/hylafax, is defined at  the
684                 time the software is built.
685
686       -d        Stop  hfaxd from detaching itself from the controlling termi‐
687                 nal.  This option is normally used only  when  running  hfaxd
688                 under  a  debugger  or  when  hfaxd  is  started  up from the
689                 inetd(8C) process.
690
691       -D secs   Sleep for the specified number  of  seconds  before  actually
692                 processing the client to allow a debugger to attach.
693
694       -f bindaddressfamily
695                 Bind to the specified bindaddressfamily tcp port. Options are
696                 ``IPv4'', ``IPv6'', or ``all''.  Please note that this  argu‐
697                 ment  needs  to  be  specified before -i otherwise it will be
698                 ignored.
699
700       -l bindaddress
701                 Bind to the specified bindaddress tcp port. Please note  that
702                 this  argument  needs  to be specified before -i otherwise it
703                 will be ignored. A better approach to improve security  would
704                 be  to run hfaxd from xinetd, binding its service to the spe‐
705                 cific port. This will also make  hylafax  benefits  from  tcp
706                 wrappers and other options provided by xinetd.
707
708       -p port:port
709                 Restrict  the range of TCP ports used when binding the socket
710                 for PASV/EPSV mode data transfers.  Without this option, bind
711                 will be called with a port of 0, allowing the kernel to allo‐
712                 cate an ephemeral port.  To be useful, -p MUST  be  specified
713                 BEFORE -i due to the way command line arguments are parsed.
714
715       -i port   Listen on the specified port for service requests and respond
716                 with the client-server protocol.  The port may  be  specified
717                 either  symbolically,  e.g. ``hylafax'' or numerically.  This
718                 flag may be specified multiple times to  request  service  on
719                 multiple different ports.
720
721       -s port   Listen on the specified port for service requests and respond
722                 with the Simple Network Paging (SNPP) protocol.  The port may
723                 be  specified  either  symbolically, e.g. ``snpp'' or numeri‐
724                 cally.  This flag may be specified multiple times to  request
725                 service on multiple different ports.
726
727       -I        Service  the  client-server protocol using the standard input
728                 and output.  This option is useful when hfaxd is  started  up
729                 by inetd(8C).
730
731       -S        Service  the  Simple Network Paging (SNPP) protocol using the
732                 standard input and output.  This option is useful when  hfaxd
733                 is started up by inetd(8C).
734

DIAGNOSTICS

736       Diagnostics generated by hfaxd are logged using syslog(3).
737
738       -c config Treat  config as a configuration parameter specification that
739                 is interpreted after reading  the  configuration  file.   For
740                 example,  ``-c servertracing:0x4f'' would set the ServerTrac‐
741                 ing configuration parameter to ``0x4f'', overriding any  set‐
742                 ting in the configuration file.
743

FILES

745       /etc/hylafax/hfaxd.conf             server configuration file
746       /var/spool/hylafax                  spooling area
747       /var/spool/hylafax/FIFO             for submitting the job
748       /var/spool/hylafax/sendq            where job description is placed
749       /var/spool/hylafax/sendq/seqf       for assigning job identifiers
750       /var/spool/hylafax/sendq/seqf.incrementincrement value for sendq seqf
751       /var/spool/hylafax/docq/seqf        for assigning document identifiers
752       /var/spool/hylafax/docq/seqf.incrementincrement value for docq seqf
753       /var/spool/hylafax/tmp              temporary location of job-related files
754       /var/spool/hylafax/docq             where document files are placed
755       /var/spool/hylafax/recvq            where received facsimile are found
756       /var/spool/hylafax/archive          where archived jobs are placed
757       /var/spool/hylafax/log              for server log files
758       /var/spool/hylafax/client           for FIFO files used in communicating with faxq
759       /var/spool/hylafax/status           for server status information
760       /var/spool/hylafax/config.device    for returning server status
761       /var/spool/hylafax/etc/hosts.hfaxd  host access control list
762       /var/spool/hylafax/etc/shutdown     server shutdown control
763       /var/spool/hylafax/etc/pagermap     SNPP pager ID mapping file
764

BUGS

766       To be filled in.
767

SEE ALSO

769       sendfax(1),  sendpage(1),  faxalter(1), faxrm(1), faxstat(1), faxq(8C),
770       syslog(3)  hylafax-server(5F),  hosts.hfaxd(5F),  status(5F),  hylafax-
771       shutdown(5F),
772
773
774
775                                 July 12, 1996                       HFAXD(8C)
Impressum