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 may be necessary to copy or link at least
437                 some system files to the HylaFAX spool directory structure so
438                 that  the chained client connection can be made to the remote
439                 job host.  This operation may  need  to  be  revisited  after
440                 upgrades or changes to those system files.  To identify which
441                 files may need to be included one may examine  strace  output
442                 for  faxstat  and look for which files it opens in the opera‐
443                 tion.
444
445       JobProtection
446                 The default setting of ``0644'' allows all users to view  all
447                 job parameters in the send and done queues.   The mode deter‐
448                 mines the permissions of the clients to see the jobs, follow‐
449                 ing  the  HylaFAX permission model of the group bits control‐
450                 ling uid permissions and the  other  bits  controlling  other
451                 permissions.  A setting of ``0640'' allows only the job owner
452                 and the administrator to view jobs.  If a user  doesn't  have
453                 permissions  on  the job, the job will not be visible to them
454                 when viewing the queues.
455
456       KillTimeMap
457                 The mapping from SNPP service level (0-11) to job  expiration
458                 time  (kill  time).   A  mapping  is specified as a string of
459                 space-separate numbers where each value is the number of min‐
460                 utes  to permit a job to run.  The default mapping is ``5 5 5
461                 15 60 240 720 1440 1440 1440 1440 1440'' which expires a  job
462                 in  5  minutes  for  service levels 0-2, 15 minutes for level
463                 three, 60 minutes for level four, etc.
464
465       LDAPServerURI
466                 The full address of the ldap server  including  port  number,
467                 i.e.:   ldaps://1.2.3.4:636   (for   secure  connections)  or
468                 ldap://1.2.3.4:389 (for insecure connections)
469
470       LDAPBaseDN
471                 The full LDAP context where user objects can be found,  i.e.:
472                 ou=users,dc=example,dc=com   for   Active  Directory/LDAP  or
473                 ou=users,o=organization for Novell eDirectory
474
475       LDAPBindQuery
476                 The format for the LDAP bind query  (ldap_sasl_bind_s)  where
477                 ``%s''  is  replaced  with the username.  If LDAPBindQuery is
478                 not configured, then the  bind  query  will  use  the  format
479                 ``cn=%s,<BaseDN>''   where   ``%s''   is  the  username,  and
480                 ``<BaseDN>'' is the configured LDAPBaseDN string.
481
482       LDAPGroupAttribute
483                 The label for the group membership data.  On  older  OpenLDAP
484                 servers  this  should  probably  be  ``groupMembership''.  On
485                 ActiveDirectory this should probably be ``memberOf''.
486
487       LDAPReqGroup
488                 The full LDAP context of the group users have to be a  member
489                 of  to gain HylaFAX access for sending faxes.  If this is not
490                 set then no group membership is required.
491
492       LDAPSearchDN
493                 The   format   for   the   UserDN   in   the   LDAP    search
494                 (ldap_search_ext_s)  where  ``%s'' is replaced with the user‐
495                 name.  By default this is the same as LDAPBindQuery .
496
497       LDAPSearchQuery
498                 The format for  the  LDAP  search  query  (ldap_search_ext_s)
499                 where  ``%s'' is replaced with the username.  By default this
500                 is ``uid=%s''.  On ActiveDirectory this  should  probably  be
501                 set to ``cn=%s''.
502
503       LDAPVersion
504                 Version number of the LDAP Protocol to use (default is '3')
505
506       LogFacility
507                 The symbolic name for the syslog(3) facility to use when log‐
508                 ging  error  messages  and  informational/debugging  messages
509                 requested  through  the ServerTracing parameter.  The list of
510                 facility names is found in  the  system  include  file  <sys‐
511                 log.h>; comparisons are case-insensitive.
512
513       MaxAdminAttempts
514                 The  maximum number of unsuccessful attempts gain administra‐
515                 tive privileges with the ADMIN command that hfaxd will permit
516                 a  client  before  terminating the connection.  Note that the
517                 count of attempts is reset if/when  the  client  successfully
518                 gains administrative privileges.
519
520       MaxConsecutiveBadCmds
521                 The  maximum  number  of  consecutive  unrecognized, unimple‐
522                 mented, syntactically incorrect,  or  otherwise  unacceptable
523                 commands  to  permit  a client before terminating the connec‐
524                 tion.  This control has two  purposes:  to  handle  naive  or
525                 malicious  clients from sending long streams of nonsense com‐
526                 mands to a server, and to ensure that  clients  are  forcibly
527                 terminated when a server is marked shutdown.
528
529       MaxIdleTimeout
530                 The  maximum value that a client may set the idle timeout to.
531                 This value is not enforced if the client  has  administrative
532                 privileges.
533
534       MaxLoginAttempts
535                 The maximum number of unsuccessful attempts to login with the
536                 USER and PASS commands that hfaxd will permit a client before
537                 terminating the connection.
538
539       MaxMsgLength
540                 The maximum number of characters to accept in a pager message
541                 specified with the DATA or MESS  commands.   Messages  longer
542                 than this value are rejected.
543
544       ModemFmt  The format string to use when returning modem status informa‐
545                 tion for modems listed in the status directory.  Formats  are
546                 specified  using  printf(3S)  style conventions but using the
547                 field identifiers listed below.  Each item can include  field
548                 width, precision, left-justification, 0-filling, etc. just as
549                 for printf; e.g. %-8h for an  8-character  wide,  left-justi‐
550                 fied,  blank-padded field containing the name of the host the
551                 server is running on.
552
553                 Format    Description
554                 h         Server hostname
555                 l         Local identifier string
556                 m         Canonical modem name
557                 n         FAX phone number
558                 r         Maximum pages that can be received in a single call
559                 s         Status information string
560                 t         Server and session tracing levels (xxxxx:yyyyy)
561                 v         Modem speaker volume as one-character symbol
562                 z         A ``*'' if a faxgetty(8C) process is running; otherwise `` '' (space)
563
564                 The default format string is ``Modem %m (%n): %s''.
565
566       PagerIDMapFile
567                 The absolute pathname of the file  that  contains  directions
568                 for  mapping  pager  identifiers  to  IXO/TAP  or UCP service
569                 providers (and optionally  a  pager  identification  number).
570                 Consult  pagermap(5F)  for information on the format and con‐
571                 tent of this file.  (Note that absolute pathnames  are  rela‐
572                 tive to the root of the spooling area).
573
574       PriorityMap
575                 The  mapping from SNPP service level (0-11) to job scheduling
576                 priority.  A mapping is specified as a string of  space-sepa‐
577                 rate  numbers where each value is the priority to assign to a
578                 job.  The default mapping is ``63 127 127 127 127 127 127 127
579                 127  127  127  127'' which assigns a high priority to service
580                 level zero and normal (default) priority to all other service
581                 levels.
582
583       RcvFmt    The  format  string  to use when returning status information
584                 for received facsimile in the recvq directory.   Formats  are
585                 specified  using  printf(3S)  style conventions but using the
586                 field identifiers listed below.  Each item can include  field
587                 width, precision, left-justification, 0-filling, etc. just as
588                 for printf; e.g. %-3b for a 3-character wide, left-justified,
589                 blank-padded field containing the signalling rate.
590
591                 Format    Description
592                 X         Reception indicator (1=yes, 0=no)
593                 Y         Received date and time
594                 Z         Received time in seconds since the UNIX epoch
595                 a         SubAddress received from sender (if any)
596                 b         Signalling rate used during receive
597                 d         Data format used during receive
598                 e         Error description if an error occurred during receive
599                 f         Document filename (relative to the recvq directory)
600                 h         Time spent receiving document (HH:MM:SS)
601                 l         Page length in mm
602                 m         Fax-style protection mode string (``-rwxrwx'')
603                 n         File size (number of bytes)
604                 o         File owner
605                 p         Number of pages in document
606                 q         UNIX-style protection flags
607                 r         Resolution of received data
608                 s         Sender identity (TSI)
609                 t         Compact representation of the time when the receive happened
610                 w         Page width in mm
611                 z         A ``*'' if receive is going on; otherwise `` '' (space)
612
613                 The default format string is ``%-7m %4p%1z %-8.8o %14.14s %7t
614                 %f''.  This string constrains each status  line  to  be  less
615                 than 80 characters.  It is recommended that all items include
616                 a field width so that client applications, such as faxstat(1)
617                 that  construct  headers from the format string can constrain
618                 the width of column title strings.
619
620       RecvqProtection
621                 The permissions setting for administrator, owners, and  users
622                 for  viewing files in the HylaFAX receive queue.  The default
623                 setting of ``0444'' allows all users to view all files in the
624                 queues.   A setting of ``0440'' allows only the job owner and
625                 the administrator to  view  files.   A  setting  of  ``0040''
626                 allows  only  the administrator to view the files.  If a user
627                 doesn't have permissions on the file, the file  will  not  be
628                 visible to them when viewing the queue.
629
630       RetryTimeMap
631                 The mapping from SNPP service level (0-11) to job retry time.
632                 A mapping is specified as a string of space-separate  numbers
633                 where  each  value  is the number of seconds to delay between
634                 delivery attempts.  A value of  zero  causes  retries  to  be
635                 scheduled using the default algorithm used by the HylaFAX job
636                 scheduler.  The default mapping is ``30 60 60 180 0 0 0 0 0 0
637                 0  0''  which  retries a level 0 job after a 30 second delay,
638                 levels 1 and 2 after 60 seconds, level 3 after 3 minutes, and
639                 other  jobs  are  retried  according  to the usual scheduling
640                 algorithm.
641
642       ServerTracing
643                 A number that controls the generation of tracing  information
644                 by  a  server.   areas  that are individually controlled.  To
645                 enable tracing of multiple areas of operation, the flag asso‐
646                 ciated  with  each  area should be bit-or'd to form the value
647                 for this tag.
648                 Flag             Description
649                 1 (0x00001)      General server operation
650                 2 (0x00002)      Client-server protocol requests and responses
651                 4 (0x00004)      File transfers from client to server
652                 8 (0x00008)      File transfers from server to client
653                 16 (0x00010)     Client logins
654                 32 (0x00020)     All network connections
655                 64 (0x00040)     FIFO messages to and from faxq(8C)
656                 128 (0x00080)    TIFF Library errors and warnings
657                 256 (0x00100)    Configuration file processing
658
659                 Tracing messages are directed to syslog(3) using the facility
660                 specified with the LogFacility configuration parameter.  Note
661                 that syslogd(8C) must be configured to capture facility.info,
662                 facility.debug, facility.warning, and facility.err messages.
663
664       ShutdownFile
665                 The  absolute  pathname  of  the  server  shutdown  file; see
666                 hylafax-shutdown(5F) for information on the format  and  con‐
667                 tent  of  this file.  (Note that absolute pathnames are rela‐
668                 tive to the root of the spooling area).
669
670       UserAccessFile
671                 The absolute pathname of the user access  control  file;  see
672                 hosts.hfaxd(5F)  for information on the format and content of
673                 this file.  (Note that absolute pathnames are relative to the
674                 root of the spooling area).
675
676       XferLogFile
677                 The  absolute pathname of the file to use for logging client-
678                 server file transfers (when enabled through the ServerTracing
679                 parameter).   (Note  that  absolute pathnames are relative to
680                 the root of the spooling area).
681

OPTIONS

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

DIAGNOSTICS

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

FILES

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

BUGS

767       To be filled in.
768

SEE ALSO

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