This chapter describes how to configure some of the advanced features of HylaFAX. In addition it discusses how many of the modem-specific configuration parameters work together when sending and receiving facsimile. The set of per-modem configuration parameters provides a flexible mechanism for working around many modem and system limitations. This chapter includes the following sections:
LocalIdentifier: "Errno Consulting"Beware that not all Class 2 and Class 2.0 fax modems support arbitrary ASCII local identifier strings. If you encounter problems verify your modem supports this functionality by sending it (if it's a Class 2 modem):
AT+FCLASS=2 OK AT+FLID=? (20)(32-127) OKThe response to the AT+FLID=? command should indicate the range of ASCII characters the modem will accept in a local identifier string.
DialStringRules: etc/dialrulesThe generation of an externalized form for a dial string is done by rules that optionally appear in DIR_LIBDATA/dialrules on client machines (where DIR_LIBDATA is the pathname setup at the time the software is configured for compilation).
Dial string rules are an important part of HylaFAX as they permit local PTT conventions to be handled entirely on the HylaFAX server machine (e.g. the need to dial ``1'' before certain numbers but not others). Client applications are then free to use a canonical format for phone numbers that is location independent. Dial string rules combined with the ModemDialCmd also permit modem-specific idiosyncrasies such as the syntax for doing a ``flash hook'' to be handled transparently. Finally, dial string rules can be used to provide dialing aliases such as mapping ``a-zA-Z'' to the corresponding numeric codes.
Consult dialrules(4F)
for detailed information.
Tagline Support
HylaFAX includes support for ``tag lines''; a line of
text imaged at the top of each outgoing facsimile page.
Tag lines imaging requires the specification of:
A 100 dpi 18point Lucida Typewriter font from
the X Window System is included in the HylaFAX distribution
for use in imaging tag lines.
Experiments indicate this is a reasonable font to use.
You can however use an alternate font of your liking.
On Silicon Graphics systems a tag line font can be installed by converting one of the compressed font files provided with the standard X server; e.g.
% zcat /usr/lib/X11/fonts/lutRS18.pcf.Z > /var/spool/fax/etc/lutRS18.pcf
To enable use of the font and imaging of the tag lines setup the TagLineFont configuration parameter:
TagLineFont: etc/lutRS18.pcfIf font files are stored on your system in an uncompressed format then you can reference the file directly using an absolute pathname. Relative pathnames must be specified with respect to the top of the spooling area. If the TagLineFont parameter references a non-existent file or a file that does not contain a valid PCF font then tag line support will be disabled and a message will be logged through syslog.
The default tag line format string is ``From %%n|%c|Page %%p of %%t'' which prints three fields containing the phone number of the server, the date and time of the outgoing job, and the page number and total pages for the job. Consult the TagLineFormat parameter description in config(4F) for information on configuring a different format string.
The
tagtest(1M)
program may be used to try out different tag
line formats and fonts before they are configured for use by the
server.
Finally, be certain the host bit order is configured to reflect the
order of bits on your machine. The host bit order should be properly
setup at the time the configure script is run.
If the server has the wrong host
bit order then tag lines will be imaged incorrectly.
Adaptive Answer Support
Adaptive answer is the ability for a modem to determine
whether an incoming phone call is for data, fax, or voice use.
If a modem supports a good adaptive-answering facility
then it should be enabled with the ModemSetupAACmd
and HylaFAX will service fax, data, or voice
calls as identified by the modem and specified
in the modem configuration files. For example,
ModemSetupAACmd: AT+FAA=1Beware however that for some modems adaptive-answer support works properly only when the modem is left in Class 2 or Class 2.0; this may be a problem if you want to configure the modem to ``idle in Class 0'' to avoid confusing naive programs that make use of the modem for outbound calls.
The adaptive-answer algorithm used by some modems can confuse
some fax machines and/or data modems.
If you do not intend to service both data and fax calls you may
not want to configure adpative-answer for inbound calls.
If a modem does not support adaptive-answering, then there are several options. If the modem is a Class 1 modem, then HylaFAX provides a simple adaptive-answering strategy whereby incoming calls are first answered as if they are for a fax machine and, if that fails, then answered as if they are for a data modem. This facility is enabled by specifying something like:
AdaptiveAnswer: yes # enable adaptive answer AnswerRotary: "fax data" # answer for fax, then data ModemAnswerCmd: AT+FCLASS=1;A # default is to answer as fax ModemAnswerDataCmd: ATH+FCLASS=0;A # hangup and answer as data Class1RecvIdentTimer: 10000 # timeout fax answer in 10 secsin the configuration file. The above lines cause the fax server to do the following in response to an incoming phone call:
Note also that by reversing the order of the items specified in the AnswerRotary parameter you can get HylaFAX to answer first for data and then for fax. If calls are answered first as data, then you may need to constrain the timeout used to recognize a data call so that time still remains to setup a fax connection. Consult your modem manual and the ModemAnswerResponseTimeout configuration parameter.
A second facility supported by the fax server in lieu of adaptive answering is a "rotary of answering techniques". The general idea is that a list of alternative ways to answer the phone is supplied and the server will rotate through the list on consecutive inbound calls until it finds one that works. For example, one might specify something like:
AnswerRotary: "fax data"which would instruct the server to answer incoming calls as if they were from a fax machine until a call was received from a data modem, in which case it would then answer subsequent calls as a data modem until a non-data call was received (in which case it would go back to fax). The rotary list can have up to three items, with items being selected from one of: fax, data, voice, and any (answer a call of an unknown type). The voice answering request is reserved for future development. Finally, in conjunction with the rotary answer facility there is an AnswerBias parameter that can be used to specify an index into the rotary list to use after successfull calls. In the above example, this parameter can be used, to force calls to always be answered first as data by specifying:
AnswerRotary: "fax data" AnswerBias: 1Note that the adaptive-answer and rotary answer facilities differ only in whether the rotary of answering techniques is applied to a single call or to consecutive calls.
CIDNumber: "CALLER NUMBER: " # pattern string for phone number info CIDName: "CALLER NAME: " # pattern string for identity infoConsult config(4F) for a full description of the caller-ID-related configuration parameters.
HylaFAX supports distinctive ring capabilities through the RingFax, RingData, and RingVoice modem configuration parameters. Modems that support distinctive ring send a different RING status message to the host depending on the ring pattern presented by the phone company. By setting the configuration parameters faxgetty will match the appropriate RING status message and use the information to treat the inbound call as fax, data, or voice before answering the call. For example,
RingFax: RING1 # treat ring pattern 1 as fax RingData: RING2 # treat ring pattern 2 as data
To configure copy quality checking in a Class 2 or Class 2.0 modem, when supported, setup the Class2CQCmd parameter for the modem. For example,
Class2CQCmd: AT+FCQ=1;+FBADMUL=5;+FBADLIN=10This enables copy quality checking for receiving and sets the copy quality parameters so that acceptable page quality requires that no more than 10 consecutive bad rows of data may be present and less than 5% of the rows in a page have errors in them. To disable copy quality checking in the modem use
Class2CQCmd: AT+FCQ=0If a modem indicates that it supports copy quality checking but Class2CQCmd has not been specified then HylaFAX will note this when the modem is prepared for use.
Copy quality checking in the server is controlled by two configuration parameters: PercentGoodLines and MaxConsecutiveBadLines; see config(4F) for more information. These parameters define the criteria by which the server decides if a received page has acceptable copy quality. Pages that are deemed unacceptable are rejected and the sender is told to resend the page.
Beware that many fax machines
are incapable of resending pages that have unacceptable copy quality
because they do not buffer a full page image.
If you encounter problems with the copy quality checking support you can disable it by setting either the PercentGoodLines or MaxConsecutiveBadLines configuration parameters to 0; e.g.
PercentGoodLines: 0 # disable copy quality checkingNote however that doing this means you may receive facsimile that are unreadable.
By default HylaFAX does not enable continuation cover pages.
To enable use of this feature the ContCoverPage configuration
parameter must be set to the pathname of a cover sheet template
file to use in generating continuation cover pages.
This cover page template file is passed to the
mkcover(1M)
script, or to the program specified with the ContCoverCmd
configuration parameter; consult the mkcover(1M) documentation
for a description of this file.
Time-of-Day Usage Scheduling
HylaFAX can be configured so that outbound calls are placed only
during certain hours of the day.
This can optionally be configured on a
per-destination basis, making it easy
to reduce phone costs by processing toll calls only during the
time when off-peak rates are available.
By default outbound calls are permitted at any time. To constrain calls to a particular time or range of times the TimeOfDay parameter can be setup according to the syntax specified in config(4F). This syntax is consistent with the syntax used by the UUCP software. For example, to permit outbound calls only between 9AM and 5PM local time the following might be used:
TimeOfDay: "0900-1700"
Per-destination controls are especially useful for controlling which phone numbers can be called. For example, by specifying an entry of the form:
^911$ RejectNotice = "Calls to emergency numbers are not permitted"any outbound job that would cause HylaFAX to phone 911 would automatically be rejected with the submitter notified by electronic mail using the specified message.
Another useful feature of this facility is the ability to delay toll calls to off-hours so that off-peak phone rates may be used. Entries of the form:
^[+]1415.* TimeOfDay = "Any" ^[+]1510.* TimeOfDay = "Any" .* TimeOfDay = "Wk1700-0830,Sat,Sun"might be used to permit calls to US area codes 415 and 510 at any time of day, but force all other calls to be done only during off hours. Note that the parameters specified in the configuration file serve as the default values to use when scheduling an outbound job. That is, if a parameter value is not obtained from the destination controls file then it is taken from any parameters specified in the configuration file. For example, if the above rules had not included the last line that matched ``.*'', then the time-of-day to use for long-distance calls would have been that specified in the configuration file (by default Any).
For this scheme to work outbound callers must install a UUCP lock file before using a modem. This lock file must be created using the same conventions understood by HylaFAX. In particular the lock file name must be consistent and the file contents must include the process ID of the lock file owner written either as a binary or ascii value according to the system-specific conventions.
HylaFAX supports several schemes found on different systems. The appropriate scheme is normally setup according to the target system at the time that HylaFAX is configured for building. It is possible, however, to override these parameters through the runtime configuration files; consult the config(4F) manual page for information about the UUCPLockType configuration parameter.
In addition to the lock type there are configuration parameters
that control the protection mode of the lock file (UUCPLockMode),
the directory in which lock files are created (UUCPLockDir),
and a timeout parameter used to purge stale lock files.
Consult config(4F) for
a full description of these parameters.
IXO/TAP Support
Experimental support is included for sending messages to alpha-numeric
pager devices using the IXO/TAP protocol.
This protocol is implemented with the
sendpage(1)
client program and the
pagesend(1M)
server program that does the actual delivery.
There are several configuration parameters associated with the IXO/TAP support. The most important parameter is PagerSetupCmds which is a set of commands to send to the modem to configure it for a call to the pager service provider. This command should usually be defined to constrain the modem to connect at 1200 baud using V.22 (and no error correction protocol). Other parameters are related to the IXO protocol implementation and should not need to be changed; consult config(4F) for full details.
Other than the per-modem configuration parameters described above, the only other pager-related information that may need to be setup is information in the info(4F) database to constrain the maximum length of an alpha-numeric pager message and any password string that must be sent to the service provider during the initial login sequence. For example,
&pagerMaxMsgLength: 112 &pagerPassword: "foobar"
Capabilities are returned using a syntax specified in the Class 2/2.0 specification:
(vr),(br),(wd),(ln),(df),(ec),(bf),(st)where,
An example use of this mechanism is found in the prototype configuration file for the AT&T DataPort modem. The rev C01.66.10 firmware for the DataPort returns an invalid string for the AT+FDCC=? query command so the prototype configuration file supplies a valid one instead:
Class2DCCQueryCmd: "!(0,1),(0-5),(0-4),(0-2),(0),(0),(0),(0-7)"Beware of specifying that a modem has capabilities that it does not; HylaFAX is likely to try and make use of them!
In normal operation HylaFAX will first reset a modem and then prepare it for use with a setup procedure appropriate for the modem. Modem reset involves the following steps:
ModemResetCmds any additional reset commands ModemEchoOffCmd disable modem echo of commands ModemVerboseResultsCmd enable verbose result codes ModemResultCodesCmd enable transmission of result codes ModemNoAutoAnswerCmd disable modem from auto-answering calls ModemOnHookCmd place modem ``on hook'' ModemPauseTimeCmd configure delay for "," in dial string ModemWaitTimeCmd configure time to wait for carrier modemflowcontrolcmd establish DTE-DCE flow control scheme ModemSetupDTRCmd force desired modem response to DTR transition ModemSetupDCDCmd force desired modem response to DCD transitionNote that these commands are sent as two separate AT commands, broken between ModemOnHookCmd and ModemPauseTimeCmd; this is done to avoid problems with certain modems.
Class2Cmd force the modem into Class 2/2.0 class2FlowControlCmd establish DTE-DCE flow control scheme Class2TBCCmd select stream modem host-modem communication Class2BORCmd set the bit order for HDLC and page data Class2PHCTOCmd set the timeout during page transfer (Phase C) Class2CQCmd enable copy quality checking Class2NRCmd enable negotiation reporting (Class 2.0 only) Class2PIECmd disable program interrupt handling (Class 2.0 only) Class2BUGCmd enable HDLC frame reporting if requested Class2DCCCmd initialize modem capabilitiesoptionally followed by the following additional commands when the modem is to be configured to (possibly) receive data:
Class2RELCmd enable reception of byte-aligned EOL codes Class2CRCmd enable facsimile reception Class2LIDCmd set local station identifier ModemSetupAACmd enable adaptive-answer support
Class1Cmd force the modem into Class 1 class1FlowControlCmd establish DTE-DCE flow control scheme ModemSetupAACmd enable adaptive-answer support
Class2Cmd: "AT+FCLASS=2<xon>"Note however that this will only work for outbound usage; doing something similar for inbound processing is more complicated because the modem, rather than the host, decides when to switch between Class 0 and Class 1, 2, 2.0. Consequently HylaFAX must react to events rather than initiate them. This work is also complicated by the fact that many modems do not accept commands (or are confused by commands) from the host during certain critical sections of inbound call processing.
To send a facsimile a phone call must be placed. HylaFAX takes the following actions:
Class2Cmd force the modem into Class 2/2.0 class2FlowControlCmd establish DTE-DCE flow control scheme Class2TBCCmd select stream modem host-modem communication Class2BORCmd set the bit order for HDLC and page data Class2PHCTOCmd set the timeout during page transfer (Phase C) Class2CQCmd enable copy quality checking Class2NRCmd enable negotiation reporting (Class 2.0 only) Class2PIECmd disable program interrupt handling (Class 2.0 only) Class2BUGCmd enable HDLC frame reporting if requested Class2DCCCmd initialize modem capabilities Class2LIDCmd set local station identifier Class2SPLCmd request polling status (if a polled receive is to be done) Class2DDISCmd setup initial session parameters (optional) ModemDialCmd place the call
Class1Cmd force the modem into Class 1 class1FlowControlCmd establish DTE-DCE flow control scheme ModemDialCmd place the call
Note that the modem is always switched into the appropriate class and flow control scheme before placing the call. For Class 2 modems that do not properly implement the AT+FDIS command the Class2DDISCmd parameter must be configured so that HylaFAX will setup initial session parameters before placing the phone call.
If the call completes and a facsimile transmit session is started then HylaFAX will send ModemSendBeginCmd to the modem. This parameter can be used to enable servicing that must be done only while Carrier Detect (CD) is asserted to the host. For example, on Sun systems it is not possible to enable RTS/CTS flow control on serial ports implemented with the ZS8530 unless CD is asserted; to workaround this problem for outbound calls one can use:
ModemSendBeginCmd: "<rts>"to force HylaFAX to enable RTS/CTS flow control on the host tty device after carrier is established. Beware however that some modems raise and lower CD during Class 1 operation and this can cause problems for systems with restrictions of this sort.
The next phase in the processing of an outbound job is the selection of station capabilities. The receiver is required to transmit a series of messages that provide its identity and capabilities (e.g. whether it can accept 2D-encoded facsimile data). HylaFAX examines the received capabilities and compares them to the capabilities required for the job. If the receiver is capable of accepting the documents to be sent then HylaFAX proceeds with the transmission. Otherwise HylaFAX will disconnect and, either re-prepare the outbound documents according to the receiver's capabilities or reject the job because it cannot be sent.
Page transfer requires the selection of session capabilities that correspond to the page to be transferred and the actual transfer of the page data to the modem. HylaFAX handles documents with varying page characteristics. In particular this means that documents with a mixture of high res and low res data (e.g. a low res cover page followed by high res image or text) are handled transparently.
For Class 2 modems session parameters are set using the Class2DISCmd (note that this is not the same as Class2DDISCmd). If the negotiated session parameter needs to be changed then this command will be sent to the modem. The Class 2 specification requires that a modem accept this command at any time prior to an AT+FDT command. However because some modems do not properly implement this part of the specification the Class2DDISCmd is provided to workaround modem limitations. Beware however that modems that require Class2DDISCmd may not be capable of renegotiating session parameters at all; this can be an annoying problem.
For Class 2/2.0 modems, page data is transferred using the AT+FDT command. This command instructs the modem that a page of facsimile data will follow. The modem is released to negotiate session parameters (as needed) and HylaFAX then waits for a response that indicates page data may be transferred to the modem. Class 2 modems indicate they are ready for page data by sending CONNECT followed by XON (DC1) to the host. (The ModemWaitForXON configuration parameter controls whether or not HylaFAX should wait for XON because some Class 2 modems do not follow this aspect of the spec.) Class 2.0 modems indicate they are ready for page data by sending a CONNECT response to the host (but no XON). Class 2 modems return OK to the host when they have accepted all the page data. Class 2.0 modems do not return OK.
After a page of data has been transferred to the modem HylaFAX
indicates whether this is the last page to be sent and/or whether
more documents are to come.
A post-page message is then sent and a post-page response
is awaited.
Class 2/2.0 modems handle this exchange entirely within the modem.
For Class 1 modems HylaFAX implements this part of the protocol
on the host: the post-page message may be retransmitted as many
as three times.
A post-page response indicates whether a page was successfully received
and/or whether or not the receiver wants to resynchronize the
line due to a perceived loss in signal quality.
HylaFAX is capable of retransmitting pages that a receiver deems
unacceptable.
HylaFAX will automatically retransmit a page up to three times
if it does not receive a positive acknowledgement from the receiver.
Modem Parameter Usage for Inbound Calls
Inbound call handling is the most complicated part of the HylaFAX
software.
This is because modems vary so widely in the way they process inbound
calls for fax, data, and voice use.
Also, inbound calls typically require that a modem be configured
before a call is received and many modems do not accept
commands from the host until after a call has been recognized,
accepted, and processing initiated.
HylaFAX handles inbound calls in the faxgetty program. The modem is initialized as described above and faxgetty then waits for a ring status message from the modem. On receiving input from the modem the following processing takes place:
Host Modem ---- ----- ATA --> <-- DATA <-- CONNECT
For fax operation faxgetty drops into the facsimile receive protocol.
More to be added.
How to operate a HylaFAX server.
HylaFAX table of contents.