The basic steps required to setup a HylaFAX server machine are:
hyla# make install # NB: must be done by the super-userfrom the top-level of the build tree.
If you are working from a binary distribution the above step is also
common, though different distribution formats may require different
techniques for installing the software. For Silicon Graphics users
the installation technique is discussed in
Binary Distributions for IRIX.
Selecting a Facsimile Modem
Selecting a modem usually means purchasing a modem that is capable
of sending and receiving facsimile.
Most any fax-capable modem can be used with HylaFAX but not all are equal.
HylaFAX has drivers for Class 1, Class 2, and Class 2.0 facsimile
modems, but there are caveats on the use of
Class 1 modems.
Class 2 modems are the most common, but due to the non-standard
nature of the specification that they are implemented against
compatibility can be a problem.
Note also that the quality of Class 2 modems varies significantly.
Class 2.0 modems follow the latest standard, a ratified version of
the specification used in implementing Class 2 modems.
There are significantly fewer Class 2.0 modems available, though
the quality of these modems also varies significantly.
There is a list of modems
that have been tried with HylaFAX and
this list includes several modems that have been found to be
reliable for use in sending and receiving facsimile.
Checking Your Modem
Once you have a modem to use with HylaFAX first make sure that the modem works for data use. One can not say this enough. If you can not use cu, tip, kermit, or whatever with your modem, do not try to configure it for use with HylaFAX. This means in particular that you should verify that you have a working cable between your host and modem and that this cable is suitable for use. That is, that the cable has the relevant signals for doing hardware flow control if that is necessary and that it passes the DCD and DTR signals appropriately.
Verify that the modem you are using is a fax modem. This can be done by communicating directly with the modem or by using the probemodem shell script that comes with HylaFAX.
To verify the modem can be used with HylaFAX use a communication program such as cu to talk to the modem directly, for example:
hyla% cu -l ttyf2 Connected at+fclass=? 0,1,2 OK ~[hyla]. DisconnectedThe at+fclass=? command asks the modem to report which classes it is capable of supporting. Class 0 is for data use. Class 1, Class 2, and Class 2.0 are for facsimile use. Other classes may be reported, for example, for modems that provide digitized voice support. HylaFAX can be used with any modem that supports Class 1, Class 2, or Class 2.0.
The probemodem script can be used to obtain information about which facsimile capabilities a modem implements. It works by sending commands to the modem to query known capabilities and reporting the results of the queries. probemodem is normally located in the same location as the faxaddmodem script and is run in a similar manner:
hyla% su # NB: probemodem must be run by the super-user hyla# /var/spool/fax/bin/probemodem ttym2 Now we are going to probe the tty port. This takes a few seconds, so be patient. Note that if you do not have the modem cabled to the port, or the modem is turned off, this may hang (just go and cable up the modem or turn it on, or whatever). Probing for best speed to talk to modem: 38400 OK. This looks like a Class 1+2 modem. ATI0 RESULT = "OK" RESPONSE = "144" ATI1 RESULT = "OK" RESPONSE = "176" ATI2 RESULT = "OK" RESPONSE = "OK" ATI3 RESULT = "OK" RESPONSE = "03134479" Class 1 stuff... AT+FCLASS=? RESULT = "OK" RESPONSE = "0,1,2" AT+FCLASS? RESULT = "OK" RESPONSE = "2" AT+FCLASS=0 RESULT = "OK" RESPONSE = "OK" ...stuff deleted...For the purpose of verifying that a modem is capable of use with HylaFAX, the most important information to check in the output of probemodem is the response to the AT+FCLASS=? command.
If a prototype configuration file for your modem is included in the
HylaFAX distribution then the appropriate flow control scheme should
already be setup.
Choosing a TTY Device
There are two things to beware of in selecting a tty device file to
use with your modem: flow control usage and port locking mechanisms.
On many systems different devices are used to select different flow control schemes and/or whether or not the system will monitor the DCD signal. For example, IRIX systems use different device names to identify devices that monitor DCD and/or support RTS/CTS flow control. Likewise the FAS driver for SCO uses a different names as does the standard HP-UX terminal driver.
On some systems inbound and outbound port use is interlocked by
using a pair of devices, one for inbound use and another for
outbound use. Typically this scheme works by stopping programs that
use the inbound device until an inbound call is received (and DCD
is raised by the modem).
Outbound usage is also interlocked against applications waiting
for the inbound device.
HylaFAX provides no direct support for this because this scheme
requires that a modem
auto-answer incoming calls (something that does not work with virtually
any multi-mode, i.e. fax and data, modem).
When faced with a system that uses this you have several alternatives.
Most people elect to avoid the inbound device and run both incoming and
outgoing traffic on the outbound device, using the builtin interlocking
mechanism provided by HylaFAX.
In this case the appropriate device to use is typically named /dev/cu*.
Systems that have this style of device usage include BSDI and SunOS.
Configuring Outbound Use
Modems are configured for use with HylaFAX using the
faxaddmodem script.
This is an interactive script that walks you through the
configuration and installation of a new or existing modem. Note that
even if you have a previous version of this software installed you
should run faxaddmodem to update the configuration
information for your modems.
faxaddmodem actually does a lot of work other than configuring
a modem for use by HylaFAX. Specifically, before faxaddmodem
even begins setting up a modem it:
The remainder of this section shows a sample configuration session and describes the work done. The session is shown indented in a fixed width font with user-supplied input in a bold font. Comments are shown in a normal or italic font. faxaddmodem displays the current/default setting for a configuration parameter enclosed in ``[]''; to accept the current value type a carriage-return.
This session was collected on a Silicon Graphics Indigo running IRIX 5.3 and communicating with an AT&T DataPort modem.
Note that if your modem is configured to communicate to the host at fixed baud rate, then you should use the -s option to lock the host-modem line rate; consult the faxaddmodem manual page for details.
hyla# faxaddmodem # NB: must be run as the super-user Verifying that your system is setup properly for fax service... Done verifying system setup. Serial port that modem is connected to []? ttym2 Ok, time to setup a configuration file for the modem. The manual page config(4F) may be useful during this process. Also be aware that at any time you can safely interrupt this procedure. No existing configuration, let's do this from scratch.If you run faxaddmodem and a configuration file already exists, the server-specific parameters will be carried over to the new configuration file, but the modem-specific parameters will not. This is because faxaddmodem is not intelligent enough to recognize when the old modem and the new modem are the same type. In this situation you may prefer to edit the configuration file using your favorite text editor instead of using faxaddmodem.
Country code [1]? Area code [415]? 510The area code may be set to a null string or omitted from the configuration file in countries where the notion of an area code does not exist.
Phone number of fax modem [+1.415.965.7824]? +1 510 526-8781This is the phone number associated with the modem being configured. By default it is passed as an ``identity'' to peer fax machines (see below) and it may also appear on tag lines created by the fax server. The phone number should be a complete international dialing specification in the form +<country code> <area code> <local part>. Any other characters that are included for readability are automatically removed if they might cause problems.
Local identification string (for TSI/CIG) [+14159657824]? +1 510 526-8781The local identification string is passed to peer fax machines during communication. If it is not specified, or set to a null string, then the canonical phone number for the fax modem is used instead. Beware that the CCITT T.30 protocol for facsimile communication specifies that this string should contain only numbers, blank, and the + symbol. In practice however, most facsimile machines will accept any ASCII string.
Long distance dialing prefix [1]? International dialing prefix [011]? Dial string rules file (relative to /var/spool/fax) [etc/dialrules]? etc/dialrules.sf-baThe dial string rules file holds rules used to convert user-supplied dialing strings (i.e. phone numbers) to a canonical format and to prepare strings for delivery to a modem. The default rules do very little. Specific dialing rules may be useful for your site or locale based on how your modems are connected to the PTT. Consult the section in the Advanced Server Configuration chapter for more information.
Tracing during normal server operation [1]? Tracing during send and receive sessions [11]?These parameters control the tracing/logging done by the server process. It is important that tracing during send and receive sessions include sufficient information to diagnose problems. For Class 1 modems this parameter is usually set to 0x4f so that HDLC frames are included in the logs. For Class 2 and Class 2.0 modems the default setting of 11 is typically ok. Consult the description of the ServerTracing and SessionTracing configuration parameters in the config(4F) manual page for detailed information about these parameters.
Protection mode for received facsimile [0600]?The default parameter selected here makes all received facsimile accessible only to the fax user. It may be desirable to set this parameter to 0644 so that anyone can look at received facsimile.
Protection mode for session logs [0600]?Note that if sensitive information such as credit card access codes are supplied by users that they will appear in the session logs kept by the HylaFAX servers. For this reason the default protection mode for session logs makes them accessible only to the fax user. For ease of debugging however it may be preferrable to select a different mode for the session logs.
Protection mode for ttym2 [0600]? Rings to wait before answering [1]?This parameter is used during inbound call handling. It specifies the number of rings to wait before answering the phone. See the section on inbound call handling for a discussion of the different schemes that HylaFAX supports for handling inbound calls.
Modem speaker volume [off]? Command line arguments to getty program ["-h %l dx_%s"]?This parameter is also related to inbound call handling. It controls whether or not to enable support for inbound data calls and should not be set without first understanding how to setup your system for incoming data usage.
Pathname of TSI access control list file (relative to /var/spool/fax) [""]?The TSI access control list file can be used to restrict inbound facsimile usage. The default parameter does not setup a file so any inbound facsimile will be accepted. This parameter is discussed more below.
Tag line font file (relative to /var/spool/fax) [etc/lutRS18.pcf]? Tag line format string ["From %%l|%c|Page %%p of %%t"]?Tag lines are an optional feature supported by HylaFAX whereby each page of an outbound facsimile is marked with a line of text that identifies the sender and possibly more. A proper description of the tag line support is provided in the Tagline Configuration chapter. Note that in the United States some form of identification of the sender of a facsimile is required by law; properly configured tag lines are an acceptable form of identification. Also note that if you specify a tag line font file that does not exist or that is not a proper font file nothing bad will happen; you just won't get tag lines on outbound facsimile. It is ok to initially accept the default parameters and then customize the setup of tag lines at a later time.
Time before purging a stale UUCP lock file (secs) [10800]? 30This parameter controls the time that a HylaFAX server process will wait before usurping a UUCP lock file whose owner appears to be gone. The default parameter forces these stale lock files to be left around for 5 minutes; a shorter, more aggressive, time can be used on systems where applications that use UUCP lock files are known to be well behaved.
Percent good lines to accept during copy quality checking [95]? Max consecutive bad lines to accept during copy quality checking [5]? Max number of pages to accept in a received facsimile [25]? Syslog facility name for ServerTracing messages [""]? local5More parameters associated with inbound facsimile jobs; consult the section below. The syslog facility controls where HylaFAX directs server tracing-related messages. The facility name identifies the syslog facility to direct the messages to. By setting this parameter to a non-standard value HylaFAX messages can easily be recorded in a file separate from the normal system messages. Consult the Troubleshooting chapter, config(4F) and syslogd(1M) manual pages for more information.
Set UID to 0 to manipulate CLOCAL [""]?This parameter should only need to be set on Silicon Graphics systems. Consult the section on IRIX-specific guidance for a description of why this parameter might be used.
The non-default server configuration parameters are: CountryCode: 1 AreaCode: 510 FAXNumber: +1 510 526-8781 LongDistancePrefix: 1 InternationalPrefix: 011 DialStringRules: etc/dialrules.sf-ba SessionTracing: 11 RingsBeforeAnswer: 1 SpeakerVolume: off GettyArgs: "-h %l dx_%s" LocalIdentifier: +1 510 526-8781 TagLineFont: etc/lutRS18.pcf TagLineFormat: "From %%l|%c|Page %%p of %%t" QualifyTSI: etc/tsi MaxRecvPages: 25 UUCPLockTimeout: 30 LogFacility: local5 Are these ok [yes]?This completes the collection of server-related parameters; the remaining steps identify and configure the modem for use. If the displayed parameters are unacceptable, typing something other than yes or a carriage return will cause faxaddmodem to prompt for new/changed parameter settings.
Now we are going to probe the tty port to figure out the type of modem that is attached. This takes a few seconds, so be patient. Note that if you do not have the modem cabled to the port, or the modem is turned off, this may hang (just go and cable up the modem or turn it on, or whatever). Probing for best speed to talk to modem: 38400 OK. This modem looks to have support for both Class 1 and 2; how should it be configured [2]?Modems that support multiple classes can be configured to use any supported class. By default faxaddmodem prefers Class 2.0 over Class 2 over Class 1.
Hmm, this looks like a Class 2 modem. Modem manufacturer is "AT&T Paradyne EDC". Modem model is "3710-A1-201". DTE-DCE flow control scheme [xonxoff]?The flow control scheme requested is either xonxoff for software flow control or rtscts for hardware flow control. Beware of using an improper flow control scheme for the selected tty device. On systems where faxaddmodem understands how tty device names reflect flow control characteristics, selecting a flow control scheme not supported by the device will cause the script to prompt for confirmation and/or to change the device name or the flow control scheme.
Using prototype configuration file att-dataport-2... The modem configuration parameters are: ModemFlowControl: xonxoff ModemHardFlowCmd: AT&R0\D1\Q3 ModemSoftFlowCmd: AT&R1\D0\Q1 ModemRate: 38400 ModemRecvFillOrder: MSB2LSB ModemSendFillOrder: LSB2MSB ModemSetupAACmd: AT+FAA=1 ModemSetupDCDCmd: AT&C1 ModemSetupDTRCmd: AT&D2 Class2CQCmd: AT+FCQ=1;+FBADMUL=20;+FBADLIN=10 Class2DCCQueryCmd: "!(0,1),(0-5),(0-4),(0-2),(0),(0),(0),(0-7)" Are these ok [yes]?The modem-specific configuration parameters are obtained from prototype configuration files that reside in the config subdirectory of the HylaFAX spooling area. These parameters have been taken from working systems and should provide a functioning configuration based on the modem type and the selected flow control scheme. If no prototype configuration file exists for a modem then faxaddmodem will prompt for parameters. There are generic prototype configuration files for Class 1, Class 2, and Class 2.0 modems. Because there are many configuration parameters for modems it may be preferrable to use a normal text editor instead of faxaddmodem when constructing a configuration file for an unsupported modem, To do this, simply accept the default parameters and then edit the generated configuration file before starting up a server for the modem. Once a working configuration file is created it is simple to create a prototype file from it; consult the faxaddmodem(1M) or config(4F) manual pages for information on doing this.
Creating new configuration file "/var/spool/fax/etc/config.ttym2". Creating "/var/spool/fax/FIFO.ttym2" in the spooling directory. Done setting up the modem configuration.At this point faxaddmodem compares the parameters setup for the modem against the parameters setup for the HylaFAX scheduler process. If any parameters have changed it prompts to see if they should be used to create a new configuration file for the scheduler. If no parameters have changed this procedure will not take place.
No existing scheduler configuration, let's do this from scratch. The non-default scheduler parameters are: CountryCode: 1 AreaCode: 510 LongDistancePrefix: 1 InternationalPrefix: 011 DialStringRules: etc/dialrules.sf-ba SessionTracing: 11 UUCPLockTimeout: 30 Are these ok [yes]? Creating new configuration file "/var/spool/fax/etc/config". Don't forget to restart faxq with "-m ttym2" or configure init to run faxgetty on ttym2 (if faxq is already running).That's all there is to setting up a basic configuration; or at least all there should be to it! Once a configuration file is setup HylaFAX must be notified that a new modem is to be used. Otherwise, if the modem was previously in use nothing needs to be done; the HylaFAX server processes will notice the new configuration files and automatically use their contents.
Specifying modems on the command line is useful when HylaFAX is to be used in a send-only configuration. Doing this however limits the functionality of the scheduler because it will not know the capabilities of the modems it is scheduling. Instead faxq will assume that each modem is capable of anything it is requested to do (e.g. send 2D-encoded facsimile). When the faxq program is able to identify modem capabilities it can do a more effective job of assigning modems to jobs based on the capabilities required by the job.
Modems are specified on the faxq command line using the -m option. A modem is identified by the tty device it is attached to. Thus, to start the scheduler up to use two modems, the following might be used:
hyla# /usr/etc/faxq -m tty01 -m /dev/tty02Note that devices may be specified with or without a leading /dev/ prefix. Note also that faxq must be started by the super-user and that it will automatically detach itself from the controlling tty. The latter can be defeated for debugging purposes with the -D option.
When faxq is used in conjunction with faxgetty no modems need to be specified on the command line. If modems are specified however it does not matter; faxq will just treat the modems as capable of all tasks until it receives information from the faxgetty processes identifying the true capabilities of the modems.
If faxq is being used in a send-only mode and a new modem is
added to the system, then faxq must be restarted with new parameters.
The faxquit program is best used to stop a running faxq process;
it works by sending faxq a ``quit'' message.
Note that if faxq is busy processing
a job that it will not process the quit request until it is no longer
busy with its current tasks. Using faxquit is preferrable to
killing faxq with a signal because it insures that faxq will terminate
in an orderly fashion. Consult the
faxq(1M)
manual page for more details on its operation.
Setting up Inbound Service
To setup HylaFAX to provide inbound facsimile or data service a
modem configuration file must be setup and
a faxgetty program must be started to listen for input on the tty device.
The configuration file setup is usually done at the same time
that the outbound server is configured; i.e. when faxaddmodem is run.
The faxgetty server for the modem should be setup to be run by the
init(1M)
process according to local system conventions.
For System V-based systems this is done by editing the
/etc/inittab file to spawn faxgetty on the appropriate port.
For example, if a modem is to be started on /dev/ttyf2 the
following line might be appropriate:
t2:23:respawn:/usr/etc/faxgetty ttyf2 # port 2For systems that use a BSD-style setup the following line might be appropriate for the /etc/ttyab file.
cua0 "/usr/etc/faxgetty /dev/cua0" dialup onNote that faxgetty may be run on a modem port whether or not it is to provide inbound service. By setting the ``rings before answer'' parameter to zero, a faxgetty will not answer an incoming phone call unless it is explicitly commanded to by the faxanswer(1M) program. This may be desirable if a phone line is used for other than fax and data.
In general it is desirable to run faxgetty whenever possible because faxgetty informs the central HylaFAX scheduler process whenever modems are in use and also identifies the modems' capabilities. Since faxgetty also does a reliable job of reseting and configuring recalcitrant modems it may even be desirable to run faxgetty on non-fax modems.
The following sections discuss HylaFAX features associated
with servicing inbound calls.
Facsimile Service
In normal operation HylaFAX will automatically answer inbound phone
calls and receive facsimile.
Facsimile reception is done by the faxgetty server process.
Inbound facsimile are written to the recvq directory
in the spooling area on the server machine.
Facsimile data is stored as a TIFF Class F (TIFF/F) file and
protected according to the RecvFileMode configuration parameter
specified in the modem configuration file.
The maximum number of pages that will be received in a single
call can also be controlled with the MaxRecvPages
configuration parameter.
Finally, HylaFAX provides an access control list mechanism for
restricting recived facsimile according to the TSI
string passed as part of the facsimile protocol;
consult the QualityTSI configuration parameter in the
config(4F)
manual page for details.
Data Service
By default HylaFAX does not enable support for inbound data calls.
Data service is not enabled so that naive users do not accidentally
setup inbound access to their system before proper password controls
are in place.
To enable inbound data service the modem configuration file must
be setup to accept data calls and to invoke the normal system
getty program to process the incoming call.
Normally this involves enabling the use of
adaptive-answer functionality
and the setup of the GettyArgs parameter
in the configuration file.
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 the faxgetty process will automatically service fax, data, or voice calls as identified by the modem. Most Class 2 and Class 2.0 modems provide adaptive-answer support and the prototype configuration files that come with HylaFAX automatically enable it if it is provided by the modem. Most Class 1 modems do not provide adaptive-answer support, but HylaFAX provides adaptive-answer support in the server. Consult the adaptive answer section in the Advanced Server Configuration chapter for more information on configuring adaptive-answer support.
Setting up the GettyArgs parameter requires an understanding of how to invoke the system getty program. HylaFAX will invoke the getty program when a data call is recognized and set up the standard input, output, and error descriptors to point to the appropriate tty device. The getty program should not reopen or reinitialize the modem before doing its work. Some getty programs are incapable of this and are unsuitable for use with HylaFAX. The parameters passed to the getty program must also identify the speed to use to communicate with the local modem. Some getty programs want to automatically detect this rate based on the CONNECT message that a modem sends to the host when a connection is established; these programs are unsuitable for use with HylaFAX. A getty program used with HylaFAX must be able to handle a fixed speed for host-modem communication (i.e. the port rate is locked); a speed that is specified on the command line.
For System V-style getty programs the appropriate parameters are typically of the form:
GettyArgs: "-h %l dx_%s"where the -h parameter instructs getty to not hangup the device first, the %l parameter is translated to the device name (``the tty line''), and the dx_%s parameter identifies the /etc/gettydefs entry to use (%s is translated by HylaFAX to the speed used to communicate with the modem). Note that the exact parameters to supply depend on the getty program used; consult local documentation to understand what options should be used.
For BSD-style systems, GettyArgs is usually of the form:
GettyArgs: "std.%s -"where std.%s refers to an entry in the /etc/gettytab file for a fixed speed port; e.g.
g|std.19200|19200-baud:sp#19200: h|std.38400|38400-baud:sp#38400:(Note that as before, the ``%s'' is replaced by the speed for host-modem communication.)
AT+FCLASS=0DT<phone number>How things work depends entirely on the contents of the modem configuration file. It is usually a good idea to setup the configuration parameters so that the modem is left idling in Class 0 (for data use) when HylaFAX is not actively using a modem.
Note that when HylaFAX places an outband facsimile call it
automatically forces the modem into Class 1, 2, or 2.0
before issuing ModemDialCmd.
Thus the old FlexFAX trick of changing the class in the
ModemDialCmd parameter should not be used.
BSDI Guidance
Beware that the standard BSDI FlexFAX distribution places certain
server applications such as faxaddmodem in non-standard locations.
This can cause confusion when HylaFAX is installed because the
old faxaddmodem may be accidentally run and generate incorrect
modem configuration files.
IRIX Guidance
On Silicon Graphics Indigo and Indy machines
you can not use a Macintosh modem cable to connect your modem
to the DIN-8 connector on the back of your host.
A Macintosh cable uses a special wiring pattern to pass
the RTS and CTS signals between the host and modem.
This wiring is not compatible with the wiring used on SGI machines.
While it may appear that the the modem and cable work,
hardware flow control will not function properly and
data will eventually be lost. Consult the
serial(7)
manual page for an explanation of how to wire up modem cables.
The tty device that is used must reflect whether hardware or software flow control is to be used. Under IRIX, modem devices (i.e. those that monitor DCD) come in two flavors: ttyf* devices support RTS/CTS flow control while ttym* devices support XON/XOFF flow control. If you want to use hardware flow control to communicate with your modem you should use a ttyf* device, otherwise use a ttym* device. If you fail to use the correct device you may still get the correct flow control (because later versions of IRIX actually permit flow control to be switched irrespective of the device used), but you are likely to collide with other modem users such as cu, uucp, ppp, and slip that still use the old-style device names (so UUCP lock files may be created for a different name than the one HylaFAX is using).
IRIX 5.2 and 5.3 have a bug in the device driver for the on-board
serial ports on IP20 and IP22 systems that causes RTS/CTS flow control
to be turned off as a
side effect of setting CLOCAL.
If hardware flow control is to be used, set the ClocalAsRoot
modem configuration parameter to No; see
config(4F).
Note however that this may cause problems with modems that are quick
to drop DCD when carrier is lost because the final status message
to the host may not be received before IRIX closes the file
descriptor on the server process.
SCO Guidance
The standard SCO serial I/O driver (SIO) does nothing with modem control
lines if CLOCAL is set on the tty device.
The usual workaround is to use the FAS driver instead.
More to be added.
Solaris Guidance
Do not use RTS/CTS flow control with serial ports
built around the Zilog ZS8530 chip unless you have
patched your system to support hardware flow control when DCD
is not asserted to the host
(consult the FAQ for an explanation).
Solaris 2.3, and some other SVR4-derived systems, silently
truncate or discard syslog messages longer than about 120 characters.
SunOS Guidance
Do not use RTS/CTS flow control with serial ports
built around the Zilog ZS8530 chip unless you have
patched your system to support hardware flow control when DCD
is not asserted to the host
(consult the FAQ for an explanation).
Ultrix Guidance
[Ed: this information comes from Tom Lislegaard
Serial ports are conventionally called tty00, tty01, etc; see MAKEDEV(8) if you need to create devices.
Advanced server configuration.
HylaFAX table of contents.