HYLAFAX-CONFIG

config − Hyla FAX configuration database

Hyla FAX uses a configuration file for the central queueing agent and for each facsimile modem attached to a machine. These files contain information about the modems and about how the Hyla FAX server processes that service these modem should operate. Configuration files are located in the etc subdirectory. The configuration file for the faxq(1m) program is named config. The per-modem configuration files used by the faxgetty(1m), faxsend(1m), and pagesend(1m) programs have names of the form config.devid, where devid is an identifier derived from the name of the modem’s device file; for example ttym2 for /dev/ttym2, term_10 for /dev/term/10.

Configuration files have a simple format and are entirely ASCII. A configuration parameter is of the form

tag: value

where a tag identifies a parameter and a value is either a string, number, or boolean value. Comments are introduced by the ‘‘#’’ character and extend to the end of the line. String values start at the first non-blank character after the ‘‘:’’ and continue to the first non-whitespace character or, if whitespace is to be included, may be enclosed in quote marks (‘‘"’’). String values enclosed in quote marks may also use the standard C programming conventions for specifying escape codes; e.g. ‘‘\n’’ for a newline character and ‘‘\xxx’’ for an octal value. Numeric values are specified according to the C programming conventions (leading ‘‘0x’’ for hex, leading ‘‘0’’ for octal, otherwise decimal), except for a few parameters, such as RecvFileMode, whose value is interpreted strictly as an octal number and PageChopThreshold whose value is interpreted strictly as a floating point number. Boolean values are case insensitive. For a true value, either ‘‘Yes’’ or ‘‘On’’ should be used. For a false value, use ‘‘No’’ or ‘‘Off’’.

The following table itemizes the tags and the expected type of their value. The first part lists items specific to the operation of each server, while the second part has items related to the servicing of the modem. Parameters marked with a ¹ are used only by the Hyla FAX scheduler process and should appear only in the file named config. Parameters marked with a ² are used by both the scheduler and the per-device applications and so should appear in all appropriate configuration files (i.e. config and any per-device files that make sense). Parameters not otherwise marked should appear only in per-device configuration files. More detailed information about each item is given following the table.

AdaptiveAnswer

boolean

No

enable adaptive answer of inbound calls

AdminGroup

string

faxadmin

System user group for administration (if PAM enabled)

AnswerRotary

string

Any

alternatives for answering calls

AnswerBias

integer

−

bias to apply to successful rotary answer

AreaCode²

string

−

local area code

AuditHook¹

string − command to run for faxq event auditing

BadPageHandlingMethod

string

RTN-SAVE

bad page received handling method

BatchLogs¹

boolean

Yes

keep all session logs of a batch in a single log

CallIDAnswerLength

integer

−

answer call when CallIDPattern received

CallIDPattern

strint

−

call identification pattern string

CIDName

string

−

equivalent to CallIDPattern (2)

CIDNameAnswerLength

integer

0

equivalent to CallIDAnswerLength (2)

CIDNumber

string

−

equivalent to CallIDPattern (1)

CIDNumberAnswerLength

integer

0

equivalent to CallIDAnswerLength (1)

ClocalAsRoot

boolean

No

set CLOCAL using root UID

ContCoverCmd¹

string

bin/mkcover

continuation cover page generation script

ContCoverPage¹

string

−

continuation cover page template filename

CountryCode²

string

−

local country code

DestControls¹

obsolete

−

Obsoleted by JobControl

DeviceMode

octal

0600

protection mode to use for modem device

DialStringRules²

string

−

dial string rules file

DistinctiveRings

string

−

configuration for distinctive ring cadences

DRingOff

string

−

distinctive ring ‘‘off’’ cadence indicator

DRingOn

string

−

distinctive ring ‘‘on’’ cadence indicator

DynamicConfig

string

−

script for dynamic receive configuration

EGettyArgs

string

−

arguments passed to external getty program

FAXNumber

string

−

facsimile modem phone number

FaxRcvdCmd

string

bin/faxrcvd

notification script for received facsimile

GettyArgs

string

−

arguments passed to getty program

Include²

string

−

include another file

InternationalPrefix²

string

−

dialing prefix for international calls

JobControlCmd¹

string

−

job control command

JobReqBusy

integer

180

requeue interval for BUSY dial result

JobReqDataConn

integer

300

requeue interval for data connection dial result

JobReqNoAnswer

integer

300

requeue interval for NO ANSWER dial result

JobReqNoCarrier

integer

300

requeue interval for NO CARRIER dial result

JobReqNoFCon

integer

300

requeue interval for carrier without +FCON dial result

JobReqOther²

integer

300

requeue interval for ‘‘other’’ problems

JobReqProto

integer

60

requeue interval after fax protocol error

JobRetryBusy

integer

−

number of retries for BUSY dial result

JobRetryDataConn

integer

−

number of retries for data connection dial result

JobRetryNoAnswer

integer

−

number of retries for NO ANSWER dial result

JobRetryNoCarrier

integer

1

number of retries for NO CARRIER dial result

JobRetryOther

integer

−

number of retries for ‘‘other’’ problems

LockDataCalls

boolean

Yes

lock modem for the duration of an inbound data call

LockVoiceCalls

boolean

Yes

lock modem for the duration of an inbound voice call

LogCalls

boolean

Yes

Log all incoming calls as CALL records in xferfaxlog

LogFacility²

string

daemon

syslog facility name for ServerTracing messages

LogFileMode

octal

0600

protection mode to use for session log files

LocalIdentifier

string

−

local station identification string

LongDistancePrefix

string

−

dialing prefix for long distance calls

MaxBatchJobs¹

integer

64

max jobs in a batch

MaxConcurrentCalls¹

integer

1

max concurrent jobs to process for a destination

MaxConsecutiveBadLines

integer

5

max consecutive bad rows for OK page quality

MaxDials¹

integer

12

max phone calls to make to transmit a job

MaxRecvPages

integer

unlimited

max pages to permit in a receive

MaxSendPages¹

integer

unlimited

max pages to permit in a send

MaxSetupAttempts

integer

2

max attempts to initialize a modem

MaxTries¹

integer

3

max attempts to transmit a job

ModemGroup¹

string

−

define a name for a set of modems

ModemPriority

integer

255

scheduling priority for outbound jobs

ModemReadyState

string

R

‘‘ready state’’ sent by faxgetty

ModemRingResponse

string

−

command to respond after hearing RING

ModemRingsBeforeResponse

integer

0

the number of rings before ModemRingResponse

NoAnswerVoice

boolean

false

disable the answering of voice-indicated calls

NoCarrierRetrys

integer

−

Deprecated - See JobRetryNoCarrier

NotifyCmd²

string

bin/notify

user notification command script

PageChop¹

string

last

control automatic truncation of trailing whitespace

PageChopThreshold¹

float

3.0

whitespace truncation threshold (inches)

PCL2FaxCmd¹

string

bin/pcl2fax

PCL RIP command script

PercentGoodLines

integer

95

percentage of good rows for OK page quality

PollLockWait²

integer

30

polling interval for lockfile presence/removal (secs)

PollModemWait

integer

30

polling interval when in ‘‘modem wait’’ state (secs)

PollRcvdCmd

string

bin/pollrcvd

delivery script for facsimile received by polling

PostScriptTimeout¹

integer

300

timeout on P OST S CRIPT interpreter runs (secs)

PriorityScheduling

boolean

see below

use available priority job scheduling mechanism

PS2FaxCmd¹

string

bin/ps2fax

P OST S CRIPT RIP command script

QualifyCID

obsolete

−

See DynamicConfig and RejectCall for rejecting calls

QualifyPWD

string

−

file of PWD patterns for qualifying senders

QualifyTSI

string

−

file of TSI patterns for qualifying senders

RecvDataFormat

string

adaptive

format for received facsimile data

RecvFileMode

octal

0600

protection mode to use for received facsimile files

RejectCall

boolean

false

Reject the current call

RingData

string

−

distinctive ring data call identifier

RingExtended

string

−

extended ring message identifier

RingFax

string

−

distinctive ring fax call identifier

RingsBeforeAnswer

integer

0

rings to wait before answering phone

RingTimeout

integer

6000

timeout in ms after RING before reset

RingVoice

string

−

distinctive ring voice call identifier

RTNHandlingMethod

string

Retransmit-Ignore RTN signal handling method

SaveUnconfirmedPages

boolean

true

save or delete unconfirmed pages

SendFaxCmd¹

string

bin/faxsend

fax transmit command script

SendPageCmd¹

string

bin/pagesend

pager transmit command script

SendUUCPCmd¹

string

bin/uucpsend

UUCP transmit command script

ServerTracing²

integer

1

non-session server tracing

SessionTracing²

integer

1

send and receive session tracing

SpeakerVolume

string

Quiet

volume level for modem speaker

TagLineFont

string

−

tag line font filename

TagLineFormat

string

see below

tag line format string

TIFF2FaxCmd¹

string

bin/tiff2fax

TIFF converter command script

TimeOfDay¹

string

Any

default time-of-day restrictions

Use2D¹

boolean

Yes

restrict/permit use of 2D-encoded fax data

UseJobTSI

boolean

No

use job-specified TSI instead of LocalIdentifier

UseJobTagLine

boolean

Yes

Allow use of job-specified Tagline instead of TagLineFormat

UUCPLockMode²

octal

0600

protection mode for UUCP lock files

UUCPLockDir²

string

see below

UUCP lockfile directory

UUCPLockTimeout²

integer

30

time before removing stale UUCP lockfile

UUCPLockType²

string

see below

UUCP lockfile type

VGettyArgs

string

−

arguments passed to voice getty program

WedgedCmd¹

string

bin/wedged

command to run when modem is wedged

ModemAnswerCmd

string

ATA

command for answering phone

ModemAnswerDataBeginCmd

string

−

command for start of answered data call

ModemAnswerDataCmd

string

ATA

command for answering data call

ModemAnswerDialCmd

string

ATA

command for answering data call

ModemAnswerFaxBeginCmd

string

−

command for start of answered fax call

ModemAnswerFaxCmd

string

ATA

command for answering fax call

ModemAnswerResponseTimeout

integer

180000

answer command timeout (ms)

ModemAnswerVoiceBeginCmd

string

−

command for start of answered voice call

ModemAnswerVoiceCmd

string

ATA

command for answering voice call

ModemATCmdDelay

integer

0

delay before sending modem an AT cmd (ms)

ModemBaudRateDelay

integer

10

delay (ms) after setting baud rate

ModemClassQueryCmd

string

AT+FCLASS=?

command for querying modem services

ModemCommaPauseTimeCmd

string

ATS8=2

command for setting time to pause for ‘‘,’’ in dialing string

ModemDialCmd

string

ATDT%s

command for dialing (%s for number to dial)

ModemDialResponseTimeout

integer

180000

dialing command timeout (ms)

ModemDTRDropDelay

integer

75

delay (ms) between DTR OFF and DTR ON

ModemEchoOffCmd

string

ATE0

command for disabling command echo

ModemFlowControl

string

XONXOFF

DTE-DCE flow control scheme

ModemFrameFillOrder

string

LSB2MSB

bit order for HDLC frames

ModemHardFlowCmd

string

−

command for setting hardware flow control between DTE and DCE

ModemMinSpeed

string

2400

minimum acceptable transmit speed

ModemMfrQueryCmd

string

−

command for querying modem manufacturer

ModemModelQueryCmd

string

−

command for querying modem model

ModemNoAutoAnswerCmd

string

ATS0=0

command for disabling auto-answer

ModemNoFlowCmd

string

−

command for disabling hardware flow control between DTE and DCE

ModemOnHookCmd

string

ATH0

command for placing phone ‘‘on hook’’

ModemPageDoneTimeout

integer

180000

page send/receive timeout (ms)

ModemPageStartTimeout

integer

180000

page send/receive timeout (ms)

ModemRate

integer

19200

baud rate to use for DCE-DTE communication

ModemReadyCmds

string

−

additional final commands when resetting modem

ModemRecvFillOrder

string

see below

bit order for received facsimile data

ModemRecvSuccessCmd

string

−

command to send after a successful reception

ModemResetCmds

string

−

additional commands when resetting modem

ModemResetDelay

integer

2600

delay (ms) after placing DTR ON

ModemResultCodesCmd

string

ATQ0

command for enabling result codes

ModemRevQueryCmd

string

see below

command for querying modem firmware revision

ModemSendBeginCmd

string

−

command to send on establishing carrier

ModemSendFillOrder

string

LSB2MSB

bit order for sending facsimile data

ModemSetVolumeCmd

string

see below

commands for setting modem speaker volume level

ModemSetupAACmd

string

−

command for setting up adaptive answer

ModemSetupDCDCmd

string

−

command for setting up DCD handling

ModemSetupDTRCmd

string

−

command for setting up DTR handling

ModemSoftFlowCmd

string

−

command for setting software flow control between DTE and DCE

ModemSoftResetCmd

string

ATZ

command for doing a soft reset

ModemSoftResetCmdDelay

integer

3000

time, in ms, to pause after a soft reset

ModemSoftRTFCC

boolean

Yes

enable software-driven real-time fax compression conversion

ModemType

string

see below

modem type

ModemVerboseResultsCmd

string

ATV1

command for enabling verbose result codes

ModemWaitForConnect

boolean

No

force server to wait for ‘‘ CONNECT ’’ response on answer

ModemWaitTimeCmd

string

ATS7=60

command for setting time to wait for carrier when dialing

FaxT1Timer

integer

35000

CCITT T.30 T1 timer (ms)

FaxT2Timer

integer

7000

CCITT T.30 T2 timer (ms)

FaxT4Timer

integer

3100

CCITT T.30 T4 timer (ms)

Class0Cmd

string

AT+FCLASS=0

Class 0: command to enter class 0

Class1Cmd

string

AT+FCLASS=1

Class 1: command to enter class 1

Class1Cmd

string

AT+FCLASS=1.0

Class 1.0: command to enter class 1

Class1AdaptRecvCmd

string

−

Class 1/1.0: command for adaptive reception support

Class1ColorJPEGSupport

boolean

No

Class 1/1.0: to enable color JPEG fax support

Class1EnableV34Cmd

string

−

Class 1/1.0: command to enable V.34-fax support

Class1ECMSupport

boolean

Yes

Class 1/1.0: enable T.30-A ECM support

Class1PersistentECM

boolean

Yes

Class 1/1.0: to continue to correct while in ECM

Class1ECMFrameSize

integer

256

Class 1/1.0: image frame size in ECM protocol

Class1ExtendedRes

boolean

−

Class 1/1.0: enable extended resolution support

Class1HasRHConnectBug

boolean

No

Class 1/1.0: modem can report CONNECT incorrectly

Class1HFLOCmd

string

−

Class 1/1.0: command to set hardware flow control

Class1FrameOverhead

integer

4

Class 1/1.0: extra bytes in a received HDLC frame

Class1GreyJPEGSupport

boolean

No

Class 1/1.0: to enable grey JPEG fax support

Class1JBIGSupport

string

see below

Class 1/1.0: to enable monochrome JBIG fax support

Class1MRSupport

boolean

Yes

Class 1/1.0: enable 2-D MR support

Class1MMRSupport

boolean

Yes

Class 1/1.0: enable 2-D MMR support

Class1NFLOCmd

string

−

Class 1/1.0: command to set no flow control

Class1PageLengthSupport

integer

7

Class 1/1.0: coded value for modem page length support

Class1PageWidthSupport

integer

7

Class 1/1.0: coded value for modem page width support

Class1RecvAbortOK

integer

200

Class 1/1.0: max wait (ms) for ‘‘ OK ’’ after recv abort

Class1RecvIdentTimer

integer

40000

Class 1/1.0: max wait (ms) for initial ident frame

Class1RMPersistence

integer

2

Class 1/1.0: times to attempt high-speed carrier recv

Class1SFLOCmd

string

−

Class 1/1.0: command to set software flow control

Class1PPMWaitCmd

string

AT+FTS=7

Class 1/1.0: command to stop and wait before PPM

Class1ResponseWaitCmd

string

−

Class 1/1.0: command to wait before TCF response

Class1Resolutions

integer

0x7F

Class 1/1.0: bitmap of supported resolutions

Class1RMQueryCmd

string

AT+FRM=?

Class 1/1.0: command to query modem data reception rates

Class1TCFWaitCmd

string

AT+FTS=7

Class 1/1.0: command to stop and wait before TCF

Class1TMQueryCmd

string

AT+FTM=?

Class 1/1.0: command to query modem data transmission rates

Class1EOPWaitCmd

string

AT+FTS=9

Class 1/1.0: command to stop and wait before EOP

Class1ModemHasDLEBug

boolean

No

Class 1/1.0: modem fails to double DLE in V.21

Class1MsgRecvHackCmd

string

""

Class 1/1.0: command to avoid +FCERROR before image data

Class1TCFRecvHackCmd

string

""

Class 1/1.0: command to avoid +FCERROR before TCF

Class1TCFMaxNonZero

integer

10

Class 1/1.0: max% of non-zero data in good TCF

Class1TCFMinRun

integer

1000

Class 1/1.0: minimum zero run in good TCF

Class1TCFRecvTimeout

integer

4500

Class 1/1.0: max wait (ms) for TCF

Class1TMConnectDelay

integer

0

Class 1/1.0: delay between +FTM CONNECT and data transmission

Class1SwitchingCmd

string

AT+FRS=7

Class 1/1.0: command to ensure silence after HDLC reception

Class1ValidateV21Frames

boolean

No

Class 1/1.0: check FCS against received frames

Class2Cmd

string

AT+FCLASS=2

Class 2: command to enter class 2/2.0

Class2AbortCmd

string

AT+FK

Class 2: command to abort active session

Class2APCmd

string

AT+FAP

Class 2: enable support for sending and receiving SUB, SEP, and PWD frames

Class2APQueryCmd

string

AT+FAP=?

Class 2: query capabilities for sending and receiving SUB, SEP, and PWD frames

Class2BORCmd

string

AT+FBOR=0

Class 2: command to setup bit order

Class2BUGCmd

string

AT+FBUG=1

Class 2: command to enable HDLC frame tracing

Class2CIGCmd

string

AT+FCIG

Class 2: command to set polling identifier

Class2CRCmd

string

AT+FCR=1

Class 2: command to enable receive capability

Class2CQCmd

string

−

Class 2: command to setup copy quality parameters

Class2CQQueryCmd

string

AT+FCQ=?

Class 2: command to query modem copy quality capabilities

Class2DCCCmd

string

AT+FDCC

Class 2: command to set modem capabilities

Class2DCCQueryCmd

string

AT+FDCC=?

Class 2: command to query modem capabilities

Class2DisableV17Cmd

string −

Class 2: command to disable V.17 support

Class2DISCmd

string

AT+FDIS

Class 2: command to set session parameters

Class2DDISCmd

string

−

Class 2: command to set session parameters before dialing

Class2ECMType

string

‘‘2’’

Class 2: ECM specification type to follow

Class2HexNSF

boolean

Yes

Class 2: parse NSF strings as hex values

Class2HFLOCmd

string

−

Class 2: command to set hardware flow control

Class2JPEGSupport

boolean

No

Class 2: use modem JPEG support

Class2LIDCmd

string

AT+FLID

Class 2: command to set local identifier string

Class2MINSPCmd

string

AT+FMINSP

Class 2: command to set minimum transmit speed

Class2NFLOCmd

string

−

Class 2: command to set no flow control

Class2PACmd

string

AT+FPA

Class 2: set polling address string

Class2PHCTOCmd

string

AT+FPHCTO=30

Class 2: command to set Phase C timeout parameter

Class2PTSCmd

string

AT+FPTS

Class 2: command to set received page status

Class2PWCmd

string

AT+FPW

Class 2: set password string

Class2RecvDataTrigger

string

‘‘\21’’

Class 2: character to send to trigger recv

Class2RELCmd

string

−

Class 2: command to enable byte-aligned EOL codes

Class2SACmd

string

AT+FSA

Class 2: set destination subaddress string

Class2SendRTC

boolean

No

Class 2: append RTC to page data on transmit

Class2SFLOCmd

string

−

Class 2: command to set software flow control

Class2SPLCmd

string

AT+FSPL

Class 2: command to set polling request

Class2TBCCmd

string

AT+FTBC=0

Class 2: command to enable stream mode

Class2UseLineCount

boolean

No

Class 2: use the line count from the firmware decoder

Class2UseHex

boolean

No

Class 2: parse capabilities strings as hex values

Class2XmitWaitForXON

boolean

Yes

Class 2: wait for XON before sending facsimile data

Class2Cmd

string

AT+FCLASS=2.0

Class 2.0: command to enter class 2/2.0

Class2AbortCmd

string

AT+FKS

Class 2.0: command to abort active session

Class2APCmd

string

AT+FAP

Class 2.0: enable support for sending and receiving SUB, SEP, and PWD frames

Class2APQueryCmd

string

AT+FAP=?

Class 2.0: query capabilities for sending and receiving SUB, SEP, and PWD frames

Class2BORCmd

string

AT+FBO=0

Class 2.0: command to setup bit order

Class2BUGCmd

string

AT+FBU=1

Class 2.0: command to enable HDLC frame tracing

Class2CIGCmd

string

AT+FPI

Class 2.0: command to set polling identifier

Class2CRCmd

string

AT+FCR=1

Class 2.0: command to enable receive capability

Class2CQCmd

string

−

Class 2.0: command to setup copy quality parameters

Class2CQQueryCmd

string

AT+FCQ=?

Class 2.0: command to query modem copy quality capabilities

Class2DCCCmd

string

AT+FCC

Class 2.0: command to set modem capabilities

Class2DCCQueryCmd

string

AT+FCC=?

Class 2.0: command to query modem capabilities

Class2DisableV17Cmd

string −

Class 2.0: command to disable V.17 support

Class2DISCmd

string

AT+FIS

Class 2.0: command to set session parameters

Class2ECMType

string

‘‘2.0’’

Class 2.0: ECM specification type to follow

Class2HexNSF

boolean

Yes

Class 2.0: parse NSF strings as hex values

Class2HFLOCmd

string

AT+FLO=2

Class 2.0: command to set hardware flow control

Class2JPEGSupport

boolean

No

Class 2.0: use modem JPEG support

Class2LIDCmd

string

AT+FLI

Class 2.0: command to set local identifier string

Class2MINSPCmd

string

AT+FMS

Class 2.0: command to set minimum transmit speed

Class2NFLOCmd

string

AT+FLO=0

Class 2.0: command to set no flow control

Class2NRCmd

string

AT+FNR=1,1,1,1

Class 2.0: command to set negotiation message reporting

Class2PACmd string

AT+FPA

Class 2.0: set polling address string

Class2PHCTOCmd

string

AT+FCT=30

Class 2.0: command to set Phase C timeout parameter

Class2PIECmd

string

AT+FIE=0

Class 2.0: command to set procedure interrupt handling

Class2PWCmd string

AT+FPW

Class 2.0: set password string

Class2PTSCmd

string

AT+FPS

Class 2.0: command to set received page status

Class2PTSQueryCmd

string

AT+FPS?

Class 2.0: command to query received page status

Class2RecvDataTrigger

string

‘‘\22’’

Class 2.0: character to send to trigger recv

Class2RELCmd

string

−

Class 2.0: command to enable byte-aligned EOL codes

Class2RTFCC

boolean

No

Class 2.0: enable real-time fax compression conversion

Class2SACmd string

AT+FSA

Class 2.0: set destination subaddress string

Class2SendRTC

boolean

No

Class 2.0: append RTC to page data on transmit

Class2SFLOCmd

string

AT+FLO=1

Class 2.0: command to set software flow control

Class2SPLCmd

string

AT+FSP

Class 2.0: command to set polling request

Class2TBCCmd

string

AT+FPP=0

Class 2.0: command to enable stream mode

Class2UseLineCount

boolean

No

Class 2.0: use the line count from the firmware decoder

Class2UseHex

boolean

No

Class 2.0: parse capabilities strings as hex values

PagerSetupCmds

string

−

commands for setting up modem for a pager call

PagerMaxMsgLength

integer

128

max length of a text message

IXOService

string

‘‘PG’’

IXO: service identification string

IXODeviceID

string

‘‘1’’

IXO: device identification string

IXOMaxUnknown

integer

3

IXO and UCP: max unknown responses before abort

IXOIDProbe

integer

2

IXO: time between sending \r during ID sequence (secs)

IXOIDTimeout

integer

20

IXO: max time to wait for ID= response (secs)

IXOLoginRetries

integer

3

IXO: max attempts to login

IXOLoginTimeout

integer

15

IXO: max time to complete login (secs)

IXOGATimeout

integer

30

IXO: max time to wait for Go-Ahead response (secs)

IXOXmitRetries

integer

3

IXO and UCP: max retries to send text msg block

IXOXmitTimeout

integer

15

IXO and UCP: max time to transmit text msg block

IXOAckTimeout

integer

30

IXO: max time to wait for msg block ack (secs)

These configuration parameters affect the general operation of the fax server.

AdaptiveAnswer

Control whether or not an adaptive answering strategy is used whereby an incoming call is answered in multiple ways according to the list specified in the AnswerRotary parameter. For example, if adaptive answering is enabled and AnswerRotary specifies ‘‘fax data’’, then an incoming call will first be answered as fax using ModemAnswerFaxCmd and then, if that fails, as data using ModemAnswerDataCmd. If the adaptive answer strategy is not enabled, then calls are answered using the appropriate ModemAnswer*Cmd parameter (normally ModemAnswerCmd for unattended operation). Note that the adaptive answer strategy depends on many factors that limit its usefulness. When calls are answered first as fax, it typically only works with a Class 1 modem because it is important that the sequence of operations related to answering as fax be completed in a short enough time that a subsequent answer for data be done before the caller times out and hangs up the telephone (for this reason Class1RecvIdentTimer should be set to a value that is shorter than FaxT1Timer.) Also, note that it is sometimes necessary to arrange that the phone be placed on-hook between successive answers; this can typically be done by inserting the appropriate command at the start of the second and subsequent ModemAnswer*Cmds.

AdminGroup

Tells PAM what user group is allowed to administer the fax server. Only useful if the server is compiled with PAM enabled.

AnswerRotary

The sequence of answering techniques the server should ‘‘rotate through’’ when answer incoming calls. Answering techniques are:

Name

Description

fax

answer a fax call

data

answer a data call

voice

answer a voice call

extern

use the vgetty application to answer a call

any

answer a call of any/unknown type

When a call is not answered successfully, the server advances the rotary to the next specified answering technique. If AdaptiveAnswer is enabled, the server will try all the answering techniques for each incoming call. Otherwise, the rotary is advanced between unsuccessful phone calls. For example, if AdaptiveAnswer is disabled and AnswerRotary is ‘‘fax data’’, then the calls will initially be answered as fax until the first call is received that does not appear to be from a fax machine; after that calls will be answered as if they were from a data modem until the next unsuccessful call; after which they will one again be answered as fax. Only the first three techniques listed are used; any additional ones are (silently) ignored. See also AnswerBias.

AnswerBias

The index into the AnswerRotary list that the server should rotate the list to after each successful incoming phone call. List indices are numbered starting at zero. For example, if AnswerRotary is ‘‘fax data’’ and AnswerBias is 1, then after each successful inbound call, the next call will be answered as data.

AreaCode²

The local area code in which the facsimile modem resides. This value is passed to the dial string rules that are used, for example, to formulate canonical phone numbers for dialing (see DialStringRules below.)

AuditHook¹

Specifies a program command and an interest specification indicating which events as described in faxwatch(1m) should trigger the execution of the program. For example, this configuration:

    AuditHook: "bin/hook: J*S*M*R*"

would cause bin/hook to be executed upon every event. The arguments passed to the hook program are respectively <class>, <mask>, <id>, and optionally [info] where...

    <class> = JOB | SEND | MODEM | RECV
    <mask>  = the specific event
    <id>    = id of the job/modem with which the event is associated
    [info]  = additional information

BadPageHandlingMethod

(Class 1/1.0 only) Specifies how to react to a bad page received from the remote sender: one of ‘‘ RTN ’’, ‘‘ DCN ’’, or ‘‘ RTN-SAVE ’’.

If a page is received in non-ECM mode with unacceptable quality according to PercentGoodLines or MaxConseutiveBadLines then it can be somewhat difficult to inform the sender of the problem. Historically, Hyla FAX has assumed that signalling RTN to the sender will accomplish this. However, some senders are incapable of retransmitting pages, and to reduce burden they treat an RTN signal as a receipt confirmation and proceed to the next page without notifying the sending user of the potential problem in readability on the receive-end. (The assumption there being that the receiving user will notify the sending user if there actually is a readability problem.)

A setting of ‘‘ RTN ’’ is the historic behavior and assumes that an RTN signal will be enough to get the sender to retransmit or be otherwise informed of a potential readability problem on the receive-end. The previously-received page data is marked to be overwritten by the next page data received from the sender.

A setting of ‘‘ DCN ’’ tells Hyla FAX to transmit a DCN signal in response to the post-page message and should trigger a call abortion by the sender. This should clearly indicate a problem in page readability to the sender, although the receipt of any following pages in a later call cannot be guaranteed.

A setting of ‘‘ RTN-SAVE ’’ more closely approximates the behavior of other fax receivers (especially fax machines). It causes Hyla FAX to send the RTN signal but it saves the previously received page data and places the next transmitted page data in another page. This is the default setting. However, this could result in multiple copies of the same page image being saved in the same file - if the sender does indeed retransmit the unacceptable pages during the same call.

BatchLogs¹

When sending or receiving multiple documents (denoted by EOM), this value determines if the session logs span the entire batch or, if set to no, only contain a single document.

CallIDPattern

A string that identifies the caller’s identity in any call identification messages provided by the modem (such as Caller*ID or DNIS/DID). The specified string is compared against any unrecognized status messages received from the modem before ModemAnswerCmd is sent to the modem. If there is a match, then the remainder of the message is returned as CallIDn where n corresponds to the n’th instance that this CallIDPattern is from the top in the modem configuration file. For example, for the ZyXEL U-1496 this parameter would be set to

CallIDPattern: ‘‘CALLER NAME: ’’ (note the trailing space).

If more than one message matches between instances of "RING" messages, then the message remainders are concatenated.

The special CallID value of "SHIELDED_DTMF" is used in conjunction with ModemRingResponse and CallIDAnswerLength. After executing ModemRingResponse, HylaFAX will expect DTMF data (usually DLE-shielded) for CallIDn until CallIDAnswerLength is reached. Note that if the modem is in voice mode to hear these DTMF digits, then it must be returned to fax mode in the ModemAnswerCmd. In order to prevent this feature from losing incoming fax calls, if fax sender CNG is detected while waiting for DTMF or if ten seconds elapse without sufficient DTMF then the remaining expected digits will be populated by whitespace, triggering fax answering.

For example, the following settings will cause HylaFAX to enter voice mode and go off-hook when a RING is detected. It will then expect four DTMF digits (presumably for routing), and then it will pause for 100 ms before returning to fax mode and answering the call.

  ModemRingResponse:     AT+FCLASS=8;H1
  CallIDPattern:         SHIELDED_DTMF
  CallIDAnswerLength:    4
  ModemAnswerCmd:        <delay:100>AT+FCLASS=1;A

Multiple entries of CallIDPattern are used together in one modem configuration file in order to capture multiple CallID responses. For example, the following settings would capture "NDID" responses from the modem as CallID1, "NMBR" responses from the modem as CallID2, "NAME" responses as CallID3, and it would trigger ModemAnswerCmd whenever CallID1 or CallID2 were longer than 7 or 10 characters, respectively.

  CallIDPattern:         "NDID="
  CallIDAnswerLength:    7
  CallIDPattern:         "NMBR="
  CallIDAnswerLength:    10
  CallIDPattern:         "NAME="

Note that this example is only given as an example, and probably would cause unexpected results. Because pattern-matching ends when ModemAnswerCmd is sent to the modem, if "NDID", "NMBR", and "NAME" responses came from the modem in that order, and the "NDID" response was at least 7 characters long, then ModemAnswerCmd would be sent to the modem immediately following the "NDID" response, and the "NMBR" and "NAME" responses would be ignored. Generally only one CallIDAnswerLength item should be in a modem configuration file.

CallIDAnswerLength

An integer indicating the minimum number of characters in a CallID matching the previous CallIDPattern to be received when ModemAnswerCmd is sent to the modem irrespective of any RingsBeforeAnswer value greater than zero. This allows the answering of calls which deliver CID/DID data but not RINGs. For example,

CallIDAnswerLength: ‘‘7’’

would cause the call to be answered when CallID2 reached a length of seven digits. A value of zero for CallIDAnswerLength disables this feature.

ClocalAsRoot

Control whether operations that set the CLOCAL bit on the modem device special file are done with the effective user-ID set to the super-user or the ‘‘fax’’ user. By default such operations are done as the fax user, except under IRIX where they are done as the super-user (because IRIX disallows manipulation of CLOCAL by anyone but the super-user).

ContCoverCmd¹

The command to invoke to generate a continuation cover page; see ContCoverPage and mkcover(1m).

ContCoverPage¹

A template file to use in creating continuation cover pages. If this parameter is non-null, then the server will pass the filename to the command specified by ContCoverCmd to generate cover pages for outbound jobs that are continued after protocol errors. These cover pages identify the receiver and indicate that the document is a continued transmission. If this parameter is not specified or is null, then the server will not generate continuation cover pages. The specified pathname must be relative to the top of the fax server’s spooling area.

CountryCode²

The local country code in which the facsimile modem resides. As for AreaCode, this value is passed to the dial string rules for use in formulating canonical phone numbers for dialing (among other things.)

DeviceMode

The file protection mode that the server should set for the modem device file. Note that this value is given in octal. The default value of 0600 implies that only the facsimile user (usually uucp) can access the modem. See also chmod(2).

DialStringRules²

The pathname of the file that holds the rules for processing user-specified dial strings; c.f. dialrules(4f). The specified pathname must be relative to the top of the fax server’s spooling area; e.g. etc/dialrules.

DistinctiveRings

Modern distinctive ring support on most modems indicates the ring cadence rather than the older style of ‘‘RING1’’, ‘‘RING2’’, etc. To indicate the ring cadence, DRingOn and DRingOff values are presented by the modem to the faxgetty process. The modem indicates the entire cadence between ‘‘RING’’ indications Like this:

  RING
  DROF=40
  DRON=8
  DROF=4
  DRON=8
  RING

The corresponding DistinctiveRings parameter for this ring cadence would be:

  DistinctiveRings:  F-8-4-8

where ‘‘F’’ tells the faxgetty process that the ring cadence is for a facsimile (‘‘V’’ for voice and ‘‘D’’ for data), and the other values describe the ring cadence with leading and ending DRingOff values ignored. Multiple ring cadences are indicated by delimiting them with commas in this fashion:

  DistinctiveRings:  V-20,F-8-4-8,D-4-2-4-8

DRingOff

A string that identifies the ‘‘off’’ value in any distinctive ring cadence, for example ‘‘ DROF= ’’. See also DRingOn and DistinctiveRings.

DRingOn

A string that identifies the ‘‘on’’ value in any distinctive ring cadence, for example ‘‘ DRON= ’’. See also DRingOff and DistinctiveRings.

DynamicConfig

The pathname of the optional program, e.g. ‘‘etc/localid’’, that makes dynamic configuration changes, i.e., to LocalIdentifier, based on device ID and call identification. The program is passed those values as the parameters ($1 = device id, $2 = CallID1, $3 = CallID2, $4 = CallID3, ...), when answering an incoming call. The program can then perform local processing as desired to send on standard output the configuration items to change in a ‘‘parameter:value’’ format, i.e. ‘‘LocalIdentifier: +1.800.555.1212’’. If there are multiple parameters to be changed, then each item must be on its own line. This is commonly used to dynamically alter the local identification of systems which use DID/DNIS, but it can also be used to allow different modem configurations for different senders. This program can also set the RejectCall options to cause the current call to be rejected instead of answered. Note that this file must be marked as executable by the faxgetty process.

EGettyArgs

A string that indicates whether or not the server should use an an external getty application to deduce and possibly handle an incoming call. If the string value is not null, then it is interpreted as a set of arguments to pass to the getty program. Before supplying the arguments, the string is first scanned for ‘‘%’’-escape sequences: any appearance of ‘‘%l’’ is replaced with the tty name and any appearance of ‘‘%s’’ is replaced with the serial port speed (in decimal). Any appearance of escaped numbers 1 through 9 (‘‘%1’’ through ‘‘%9’’) are replaced by the match to the corresponding CallIDPattern, if present. The ‘‘%’’ character can be specified with ‘‘%%’’. If the EGettyArgs parameter is not specified in the configuration file or if the string value is null, then ‘‘extern’’ connections will be rejected. Note that in addition to the specified command line arguments, the external getty program is invoked with its standard input, output, and error descriptors directed to the controlling tty device.

When the external getty application completes, its exit status is evaluated and is interpreted to indicate what, if anything, should be done with the call. An exit status of ‘‘0’’ indicates an unknown call type and that the call should be handled as if the external getty program had not been used. An exit status of ‘‘1’’ indicates a data connection and that the getty(1m) program should be used to handle the call (see GettyArgs) after being answered with ModemAnswerDataBeginCmd . An exit status of ‘‘2’’ indicates a fax connection that should be handled after being answered with ModemAnswerFaxBeginCmd. An exit status of ‘‘3’’ indicates a voice call and that the vgetty program should be used to handle the call (see VGettyArgs) after being answered with BR ModemAnswerVoiceBeginCmd . An exit status of ‘‘4’’ is considered to be an error condition. The session will be terminated. An exit status of ‘‘5’’ is used to indicate that the external getty program handled the call entirely, is not an error condition, and that the session is to be considered terminated.

FAXNumber

The phone number associated with the facsimile modem. This string is used to generate the Transmitter Subscriber Identification ( TSI ) and Caller Subscriber Identification ( CSI ) information passed to remote machines—unless the LocalIdentifier parameter is explicitly set. The FAXNumber is also used to name the session log file where information for incoming phone calls is recorded; see hylafax-log(4f). If this phone number is not a fully qualified number the values of AreaCode and CountryCode are used to generate the transmitted CSI and TSI.

Include²

Include the specified file and parse it as a config file

InternationalPrefix²

The string to use to place an international phone call. In the United States, this is ‘‘011’’. This string is passed to the dial string rules.

JobControlCmd¹

The command to invoke to which provides Job Control information for a job. See JobControl(1m).

JobReqBusy

The delay in seconds to wait before retrying a job whose dialing attempt failed with a ‘‘ BUSY ’’ status result.

JobReqDataConn

The delay in seconds to wait before retrying a facsimile job whose dialing attempt failed because a data modem answered the phone.

JobReqNoAnswer

The delay in seconds to wait before retrying a job whose dialing attempt failed with a ‘‘ NO ANSWER ’’ status result.

JobReqNoCarrier

The delay in seconds to wait before retrying a job whose dialing attempt failed with a ‘‘ NO CARRIER ’’ status result.

JobReqNoFCon

The delay in seconds to wait before retrying a facsimile job whose dialing attempt failed because the initial facsimile protocol handshake failed (i.e. no ‘‘ +FCON: ’’ result was received from a Class 2/2.0 modem).

JobReqOther²

The delay in seconds to wait before retrying a job that failed for a reason not already covered by one of the JobReq* parameters.

JobReqProto

The delay in seconds to wait before retrying a facsimile job that failed because of a fax protocol error.

JobRetryBusy

The number of times to redial a phone number after receiving a ‘‘ BUSY ’’ result code when the number has not been successfully dialed before.

JobRetryDataConn

The number of times to redial a phone number after the dialing attempt failed because a data modem answered the phone when the number has not been successfully dialed before.

JobRetryNoAnswer

The number of times to redial a phone number after the dialing attempt failed because of NO ANSWER when the number has not been successfully dialed before.

JobRetryNoCarrier

The number of times to redial a phone number after the dialing attempt failed because of NO CARRIER when the number has not been successfully dialed before. In normal operation the fax server will treat this result code to mean that a facsimile modem/machine did not answer the phone and reject the transmit job. This is done to avoid repeatedly dialing wrong phone numbers and depends on the modem distinguishing between no carrier and no answer. However, some modems are not capable of reliably distinguishing between no carrier and no answer, or when instructed to do so do not identify a busy signal correctly. For these modems one may find it necessary to increase the value of this parameter to compensate. It is strongly recommended, however, that this value not be set to a large number.

JobRetryOther

The number of times to redial a phone number after the dialing attempt failed for a reason not already covered by one of the other JobRetry* parameters when the number has not been successfully dialed before.

GettyArgs

A string that indicates whether or not the server should invoke the getty(1m) program in response to an incoming call from a data modem. If the string value is not null, then it is interpreted as a set of arguments to pass to the getty program. Before supplying the arguments, the string is first scanned for ‘‘%’’-escape sequences: any appearance of ‘‘%l’’ is replaced with the tty name and any appearance of ‘‘%s’’ is replaced with the serial port speed (in decimal). Any appearance of escaped numbers 1 through 9 (‘‘%1’’ through ‘‘%9’’) are replaced by the match to the corresponding CallIDPattern, if present. The ‘‘%’’ character can be specified with ‘‘%%’’. If the GettyArgs parameter is not specified in the configuration file or if the string value is null, then data connections will be rejected. Note that in addition to the specified command line arguments, the getty program is invoked with its standard input, output, and error descriptors directed to the controlling tty device.

LocalIdentifier

The local station identification string to use when transmitting TSI and CSI strings (see FAXNumber above). NB: while this string may contain any printable ASCII characters; beware that CCITT T.30 specifies a restricted character set and some fax modems and machines may reject or not display non-conforming strings. If the local identifier is not specified, a canonical form of the FAXNumber is used instead.

LockDataCalls

Hold the UUCP lockfile during the time an inbound data call is processed by the external getty program. If this is disabled then the lockfile will be removed just before the getty program is invoked. Note however that doing this introduces a race condition whereby an outbound program may sneak in and take control of the modem after the inbound call has been accepted, but before the getty program has started up and installed it’s own lockfile.

LockVoiceCalls

Hold the UUCP lockfile during the time an inbound data call is processed by the external voice getty program. If this is disabled then the lockfile will be removed just before the voice getty program is invoked. Note however that doing this introduces a race condition whereby an outbound program may sneak in and take control of the modem after the inbound call has been accepted, but before the voice getty program has started up and installed it’s own lockfile.

LogFacility²

The symbolic name for the syslog(3) facility to use when logging error messages and informational/debugging messages requested through the ServerTracing parameter. The list of facility names is standardized; it can be found in the system include file <syslog.h>; comparisons are case-insensitive.

LogCalls

Log all incoming calls into xferfaxlog as CALL records. This allows a quick check of all incoming calls, regardless of fax completion or not in a unified manner with other fax logs.

LogFileMode

The file protection mode that should be used when creating files to hold session logs. Note that this value is given in octal. The default value of 0600 implies that the log files are not generally accessible, which is important if sensitive information such as calling card access codes are logged. If log files are to be publicly accessible, this value may be set, for example, to 0644. See also chmod(2).

LongDistancePrefix²

The string to use to place a long distance phone call. In the United States, this is ‘‘1’’.

MaxConcurrentCalls¹

The default value to use for the maximum number of jobs for the same destination that are processed concurrently. Thus this parameter defines the maximum number of concurrent phone calls to the same destination. Unless all of your fax destinations have multiple fax lines using the same fax number per destination then MaxConcurrentCalls is probably best left as the default of 1 and exceptions should be accommodated by the JobControl mechanism.

MaxBatchJobs¹

The maximum number of jobs to batch together in a single call.

MaxConsecutiveBadLines

The maximum number of consecutive erroneous rows of image data that the server will receive before it deems a page to have unacceptable copy quality. Setting this parameter to zero causes the server to not check the quality of received facsimile. Facsimile received with error-correction do not have copy quality checking performed. See also PercentGoodLines.

MaxDials¹

The default value for the maximum number of times the server will place a c