MT1432BA Hylafax

User Manual: MT1432BA

Open the PDF directly: View PDF PDF.
Page Count: 52

DownloadMT1432BA Hylafax
Open PDF In BrowserView PDF
HylaFAX
Hyla - Any of a genus of frogs, especially the tree frog.

12March2003

1

Copyright
© 2003 Adam Tauno Williams (awilliam@whitemice.org)
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation
License, Version 1.1 or any later version published by the
Free Software Foundation with no Invariant Sections, no
Front-Cover Texts, and no Back-Cover Texts. You may
obtain a copy of the GNU Free Documentation License from
the Free Software Foundation by visiting their Web site or
by writing to: Free Software Foundation, Inc., 59 Temple
Place - Suite 330, Boston, MA 02111-1307, USA.
If you find this document useful or further it's distribution we
would appreciate you letting us know.

2

Whitemice Consulting
The master copy of this document is hosted by the Whitemice
Consulting at the following URL:
http://www.whitemiceconsulting.com/node/154
This document is updated periodically with additional information. If
you have a topic you think this presentation should include please
contact the maintainer: awilliam@whitemice.org
Whitemice Consulting's home page can be found at:
http://www.whitemiceconsulting.com
See the Presentations section for great presentations on a wide range of
Open Source related topics.

3

What is HylaFAX
HylaFAX is the premiere open source (GPL'd) fax management systems.
HylaFAX was originally developed by
Sam Leffler a developer at SGI. HylaFAX
(originally FlexFAX) is not and was never
an SGI product, however, the name
HylaFAX is trademaked by SGI.

Platforms supported:
AIX v3.x, v4.x, v5.x
BSD/386 & FreeBSD
HP-UX 9.x, 10.x
IRIX,
ISC4.0,
Linux 2.2.x & 2,4.x
OSF/1 V1.3 & V3.0,
SCO
3.2v4 with TCP/IP
SCO ODT 3
SCO 5.0

From the HylaFAX FAQ:

>Can I run HylaFax on my NT 4.0 Server?
NO. (NT is not the answer, it's the question
and the answer is NO :-))

Solaris 2.x & SunOS 4.1.x,
SVR4.x
Intel x86 and MIPS
UnixWare, Onsite, SINIX, ...
Ultrix 4.4.

4

Features
Facsimile transmission
Automatic document type conversion
Scheduled transmission
Facsimile to electronic mail gateway
Automatic cover page generation
Sent documents can be any size
Facsimile recieving
Scripted document management
Polling for remote documents
Send pager messages
Rule based call control
Block calls to 911, etc...
Extensive logging

Client applications
communicate with the server
via a simple FTP like protocol,
and you can actually control
the server using any telnet
client (not that would actually
ever want to do that). The
HylaFAX server listens on
TCP port 4559.

5

Prerequisites
Ghostscript, the most recent version possible.
Ghostscript is used to convert documents (usually postscript) to the
TIFF G3 format used by fax machines as well as converting recieved
faxes to postscript or possibly PDF format.
To build you should use gcc 2.6.3 or greater with libg++ 2.6.2 or greater.
RedHat 8.0 ships with gcc 3.2.7 and libg++ 2.7.2.8
Working serial connectivity between the host and the modem.

Make sure your modem is available before attempting to configure
HylaFAX. Use a program like minicom to verify communications
with the modem and the presence of dial tone.

6

Modems

Modem Classes
Modems with fax capability support a specific “class” or version of the
standard fax command set and operational standard. Class 1 modems may only
support software
flowcontrol when in fax
very mode.
low latency as the

Class 1
These tend to be very compatible but require
protocol is timing sensitive. Latency, such as caused high system
load or a busy IDE device will cause communication failures.
Class 2
These are the most common type of fax modem available, but “2”
represents a standard implemented before final adoption so
compatibility varies. Class 2 modems also vary greatly in quality.
Class 2.0
This indicates the latest ratified standard, they are less common than
“2” modem but usually offer fewer compatibility problems.

8

Modem Recomendations
Many modems available are simply
The fax software community tends to
manufactured from off the shelf parts.
be very fond of Multitech modems.
Hylafax can usually probe for and
http://www.multitech.com/
support modems based on the
Modems are one device where you typically get what
following “chipsets”:
you pay for, buy nothing that costs less than $50.00
Rockwell
RC96AC
RC144AC
RC144DP
RC32ACL
RC224A
RC288DPI
Exar
Cirrus Logic

The Hylafax documentation contains a list of recommended modems:
Class 1

Digicom Scout+

Class 2

AT&T Paradyne DataPort 14.4
Telebit T3000 WorldBlazer (Class 2)
Multitech
MT1432BA, MT1432BA/A, MT1432MK, MT1432PCS, MT1432BG,
MT1932ZDX, MT2834ZDX

Class 2.0

Mutlitech MT5600ZDX (Class 2.0)
Zylex U1496, U1496e+

9

Architecture

Components
Clients
HylaFAX has many parts.
sendfax - Local job submission.
Troubleshooting and
faxstat - Display the status of the server.
managing a server requires
faxrm - Cancel a pending transmission.
understanding which parts
The server
are responsible for each task.
hfaxd - Job and status management
Single process, runs constantly
faxgetty - Manages fax devices.
One process per device, spawned by initd.
faxq - Job schedular
Single process, runs constantly.
faxsend & pagesend - Handle outbound jobs.
Maintenance
faxqclean - Spool are cleaner
Controlled via crond

11

Processes
faxgetty

Fax Logs,
Archives,
Spools, &
FIFOs.

Modem
State

faxsend
Outboun
d
Job

faxq

Outbound
Jobs

hfaxd

TCP/IP 4559

Outbound Job

faxgetty

Modem State

Queue Status
& Archived
Jobs

12

Directories
/var/spool/hylafax
archive - Old documents and logs, see the bin/archive script.
bin - HylaFAX script files; faxrecvd, mkcover, ps2fax, etc...
client - FIFO files used by faxd live here.
config -Modem specific files for modem type recognition, etc...
dev - ?
docq - Jobs scheduled for transmission.
doneq - Descriptions of transmitted jobs.
etc - HylaFAX configureation files: hosts.hfaxd, dialrules, etc...
info - Cache of information about fax devices HylaFAX has communicated with.
log - Hmm, log files perhaps?
pollq - Documents available to remote fax services/devices via polling.
recvq - Documents recieved by Hylafax, each is a Class F TIFF file.
sendq - Description files corresponding to jobs in docq.
status - Text status files maintained by the various daemons.
tmp - Scratch directory for the daemon processes.

13

Receiving

faxgetty
initd
faxanswer
faxgetty

FIFO
kill

SIGTERM
SIGINT

Data Call

Fax Call

etc/config.deviceID

faxabort

getty

faxgetty is usually run from the initd
process so that a process is always ready
on each fax modem.
faxgetty listens on a command
FIFO so thats its behaviour can
be controlled via utilities such
as faxanswer and faxabort.

recvq
bin/faxrcvd

15

faxgetty
Listens for ...

Incoming calls on device
Commands written to FIFO.{device}
Typically from the faxanswer or faxabort utilities.
SIGTERM & SIGHUP signals

Notifies hfaxd and faxq about changes in modem state
Reads its configuration from etc/config.{device}
Automatically raises its process priority when spawned.
This can be disabled with the -p option in /etc/inittab.
Implements access control based upon TSI or CID information.
Highly configurable
RecvFileMode - Permissions of newly recieved documents.
RingsBeforeAnswer - Number of rings before pickup.
MaxRecvPages - Maximum length of a fax document.
PercentGoodLines & MaxConsecutiveBadLines - Tolerance of errors.

16

faxrcvd
faxrcvd is a shell script invoked by Hylafax whenever a fax has been
recieved. It is the last step in fax reception.
faxrcvd {file} {devID} {commID} {error-msg} {cidnumber} {cidname}
{file} - File name of recieved document
{devID} - The device name (ttyS0, etc...) on which document was recieved.
{commID} - The communication identifier of the inbound call.
{error-msg} - An error message if reciept failed in any way.
{cidnumber} & {cidname} - Caller ID information if supported by both the
modem and the inbound line.
The default script simply sends a notification e-mail to
FaxMaster; you will almost certainly want to hack this part of
your installation.

17

Adaptive Answer
faxgetty support adaptive answer which permits a single device to handle
fax, data, and possibly even voice calls. HylaFAX implements adaptive
answer in the server and does not depend upon adaptive answer in the
modem itself.
Adaptive answer is disabled by default.
Adaptive answer is enabled using the AdaptiveAnswer directive in the
device's configuration file (etc/config.deviceID).
If adaptive answer is enabled the order by which the call type is
tested is determined by the AnswerRotory directive.
AnswerRotary fax data attempts to first answer the call as a fax and
they as a data call.
If data calls are to be answered a GettyArgs directive is required to
inform Hylafax how to properly spawn the getty process
GettyArgs: "-h %l dx_%s" where %l is replaced with the device
name and %s with the speed for matching a gettydefs line.

18

Sending

The Sending Process
Is this client allowed to send?

etc/hosts.hfaxd

etc/hfaxd.conf

hfaxd
hfaxd coverts
document to the
appropriate TIFF
format if possible.

etc/config

docq
sendq

etc/config.device

FIFO
Document
Job Description
“Yo! New Job.”

faxq
Exit
Status

faxsend

20

hfaxd
Runs chroot'd to the top of HylaFAX's directory structure.
Usually /var/spool/hylafax
Be careful about specifying filenames that lie above this root as
hfaxd will not be able to access them.
If the file etc/shutdown is present hfaxd will deny all access to users
who are not administrators.
Primary configuration file is etc/hfaxd.conf
Default TCP port is 4559
This can be modified with the -i {port#} command line switch, you
may specify multiple port numbers by repeating the switch.
hfaxd can also be run from xinetd/inetd rather than as a stand alone
daemon.
Specify the -I command line switch to enable superserver
compatibility.

21

A sendq description file
tts:1047171046
killtime:1047181786
retrytime:0
state:6
npages:0
totpages:4
ntries:0
ndials:0
totdials:0
maxdials:12
tottries:0
maxtries:3
pagewidth:209
resolution:196
pagelength:296
priority:127
schedpri:127
minsp:0
desiredbr:13
desiredst:0

desiredec:1
desireddf:3
desiredtl:0
useccover:1
external:3611124
number:3611124
mailaddr:adam@morrison-ind.com
sender:adam
jobid:6
jobtag:
pagehandling:61S61S61S61P
modem:any
receiver:
company:
location:
cover:
client:localhost.localdomain
owner:root
groupid:6

signalrate:
dataformat:
jobtype:facsimile
tagline:
subaddr:
passwd:
doneop:default
commid:
status:
notify:none
pagechop:default
chopthreshold:3
!postscript:0::docq/doc6.cover
fax:0::docq/doc6.cover;41
!postscript:0::docq/doc7.ps.6
fax:0::docq/doc7.ps;41

Once a fax has been trasmitted, or
failed to be transmitted, this file
moves to the doneq directory.

22

Document Conversion
In order to be sent as a fax any document must first be converted to a
multi-page TIFF format often referred to as TIFF/F.
hfaxd uses a small collection of helper applications in order to manage
document type conversion if submitted documents are not TIFF/F.
PCL2FaxCmd - Command to convert PCL documents to TIFF/F.
PS2FaxCmd - Command to conver PS documents to TIFF/F.
Usually ps2fax, a Ghostscript wrapper script.
ps2fax is provided in most HylaFAX packages.
TIFF2FaxCmd - Command to convert TIFF documents to TIFF/F
Usually tiff2fax, a wrapper arround the tiffcp utility.
tiff2fax is provided in most HylaFAX packages.
On RedHat tiffcp is provided by the libtiff package.
It is optimal to convert the document prior to submission in order to
have the optimal output as you avoid any issues such as font
substitution.

23

Destination Controls
Destination controls are rules defined in the destctrls file.
These rules are globally applied to all outgoing calls.
The first column of the destctrls file is a regular expression that
matches the destination phone number
The second column is a list of parameter=value constructs, you may
list more than one construct.
MaxConcurrentJobs, jobdPages, MaxTries, TimeOfDay, etc...

faxq scans this file and returns the first match, so order is important.
^911$ RejectNotice = "Calls to emergency numbers are not permitted"
The above rule will black all calls to 911, the sender will recieve an electronic
mail message with the specified message.

24

faxq
faxq is in charge of scheduling outbound jobs.
Recieves information from hfaxd about new jobs via a FIFO
The faxquit utility also communicates via the FIFO
Running faxquit is the proper way to terminate faxq
While a job is actively being processed the description file in sendq is
locked via flock(2).
hfaxd can check file locks in sendq to determine if a job is currently
active.
faxq usually spawns a faxsend to process each job.
The process actually used to send the job may be changed via the
FaxSendCmd configuration directive.
faxsend communicates a transmissions success or failure back to
faxq via its exit code.
0=Retry, 1=Failed, 2=Success, 4=Reformat

25

Maintenance

faxcron
Most the the routine maintencance regarding the HylaFAX spool area is
managed by a Bourne Again Shell script: /usr/sbin/faxcron.
This script is meant to be executed by crond once a day
(via /etc/cron.daily on a RedHat system).
By default this script Removes information from log and info that is more than 30 days old.
These values can be adjusted via the -log {days} and -info {days}
command line switches.
This job also resets the file permissions of session log files.
Remove files from tmp older than one day.
This can be adjusted with the -tmp {days} command line switch.
Remove documents received more than seven days ago.
This can be adjusted with the -rcv {days} command line switch.

27

faxqclean
/usr/sbin/faxqclean is a binary excutable that should be executed via
crond roughly once an hour (via /etc/cron.hourly on a RedHat system).
Remove documents from the doneq directory based upon age and the
doneop flag in the corresponding job description file in sendq.
doneop is either a value that indicates archive or purge.
By default files remain in doneq for 900 seconds (15 minutes)
Adjustable via the -j {seconds} command switch
Remove unreferenced files from the doneq directory.
Default is to allow unreferenced files to exist for up to 3600
seconds (1 hour).
Adjustable via the -d {seconds} command switch.
Archiving of jobs is managed by calling the bin/archive shell script
whose parameter is the job id. This script can be hacked to achieve any
custom archival method.

28

Clients

faxstat
The faxstat command is used the interrogate the Hylafax server processes
as to the status of the various components as well as progess on the job
queues.
-a Display archive directory contents
-d Display the status of all jobs completed
-f Display status of all documents in the docq direcotry
-g Display times and dates in GMT
This is the default behaviour, changed via the -l option.
-h {hostname} Query the status of a specific host
-i Display additions status information
-l Display times and dates in local time zone
-r Display the receive queue status
-s Display the status of jobs in the send queue
-v Trace protocol exchanges

30

sendfax
sendfax -d 1-810-351-4816 /etc/termcap
The HylaFAX package includes the sendfax client, a very powerful
command line fax job submission utility.
Destinations are indicated with the -d option.
The -d option may occur multiple times to specify multiple
destinations.
Almost all of the HylaFAX configuration paramters can be overridden
via switches from the sendfax command.
The manual page is eight pages.

Jobs can be scheduled for transmission up to one year in advance.
Documents types of text, PDF, and SGI image will be converted to
either Postscript or TIFF/F prior to submission.
Jobs can be submitted to remote hosts.
sendfax supports passing parameters for cover page generation.

31

w2hfax
http://w2hfax.sourceforge.net/
w2hfax is a Win32 Hylafax client
written in Visual Basic that also
includes an Active X component
written in Python.
The Active X component permits
sending faxes from within M$Excel and M$-Word macros.

w2hfax provides all the functionality you'd expect from a fax
application including viewing, cancelling jobs, viewing job detail, etc...

32

KSendFax
http://ksendfax.sourceforge.net/
KSendFax is a Qt toolkit based fax
client for Linux.
KSendFax supports not only HylaFAX
but efax and mgetty+sendfax as well.
Integrates with xsane for faxing
scanned documents.

33

Byteforge.Networking.Hylafax
http://byteforge.ath.cx/hylafaxclient/
ByteForge has a freely available HylaFAX .Net component.

34

fax4CUPS
http://gongolo.usr.dsi.unimi.it/~vigna/fax4CUPS/
fax4CUPS is a backend module, including PPD file, that integreates a
CUPS queue with either efax or HylaFAX.
Job status may be viewed using standard CUPS utilities, including the
CUPS web interface. Pending jobs may be cancelled via the same.
The phone number may be passed to backend using lpr's -J {jobid}
parameter.

35

gfax
http://www.cowlug.org/gfax/
gfax is a GNOME 1.x fax
client that supports both
HylaFAX and mgetty
+sendfax.
gfax integrates with
gnome-print, provides a
pop-up window, and
reads GnomeCard phone
books.
gfax is written in Python
and relies on libglade.

36

pyla
http://digilander.libero.it/aser76/docs/pyla.html

Pyla is a cross-platform HylaFAX client
written entirely in Python. Pyla attempts
to mimic WHFC.

37

smbfax
http://inconnu.isu.edu/~ink/new/projects/smbfax/
smbfax is a script that is used as the “print command” of a Samba
print queue to enable CIFS clients to submit jobs to HylaFAX
without any client side software.
Jobs appear as regular print entries in the Win32 print manager and
can be cancelled there.
Once a job is submitted the user recieves and E-Mail containing a
link. At that link the user can enter information about delivering
the fax such as phone number and other details.

38

whfc
http://www.uli-eckhardt.de/whfc/
whfc is yet another Win32
HylaFAX client. It provides
all the functionality you
would expect from a fax
client, as well as...
Use of ODBC sources for
address book information.
Offline mode
OLE support enables use
from M$-Office macros.
Adjustable kill time.

39

Cypheus
http://www.cypheus.de/
Cypheus is a
commercial
Win32 HylaFAX
client that
requires
registration for
commercial use.
Cypheus is
similair in
functionality to
WHFC but is
more complete
and current.

40

Cypheus
Organize cover pages and add one to any fax.
Drag&Drop Support
Use any address book.
Support for G3-2D TIFFs
Set transmission time.
Job Suspend/Release
Send mail merge faxes with MS Word™
Fax Polling
Save columns' width & position and sort order of list
Watched Folder
items
Replied/forwarded icon
You can assign any installed modem to each fax
Automatic addition of documents
Login on different HylaFAX servers by a simple click
Comments are shown in tooltips
New address book & MySQL table in main window
Forward any incoming fax by eMail as TIFF
Import wizard
attachment
Outlook integration
Preview of all outgoing faxes
CDO access on Outlook and
Merge a number of PS documents to a single fax
Exchange folders.
View faxes with the built in viewer, before sending
Security features: You can assign restrictions for
Annotate documents
Save documents to the local disk. reading/sending a fax to each user
Export all faxes to HTML/JPEG including index page
Send fax out of MS Word for
Add sub-folders to organize received/sent faxes
Windows™ without typing a fax
Cover Page/Text Editor
number again.

41

StarOffice/OpenOffice
Star Office / Open Office are not
fax clients in the strict sense, but
via spadmin a queue can be setup
that prompts for a fax number and
calls up a fax client.
In this case the HylaFAX sendfax
utility.

42

Setup

faxsetup
HylaFAX needs this to work properly, add it [yes]?
Added user "fax" to /etc/passwd.
...
No scheduler config file exists, creating one from scratch.
Country code [1]?
Area code []? 616
Long distance dialing prefix [1]?
International dialing prefix [011]?
Dial string rules file (relative to /var/spool/hylafax) ["etc/dialrules"]?
Tracing during normal server operation [1]?
Default tracing during send and receive sessions [0xffffffff]?
Continuation cover page (relative to /var/spool/hylafax) []?
Timeout when converting PostScript documents (secs) [180]?
Maximum number of concurrent jobs to a destination [1]?
Define a group of modems []?
Time of day restrictions for outbound jobs ["Any"]?
Pathname of destination controls file (relative to /var/spool/hylafax) []?
Timeout before purging a stale UUCP lock file (secs) [30]?
Max number of pages to permit in an outbound job [0xffffffff]?
Syslog facility name for ServerTracing messages [daemon]?

44

faxaddmodem
/usr/sbin/faxaddmodem -s {speed} {tty device}
The faxaddmodem command is used to
configure the fax devices and is run once for
each fax device.
faxaddmodem uses the information
in /var/spool/hylafax/config to identify various
types of modems.
faxaddmodem is a Bourne Again shell
script, and has problems with bash versions
prior to 1.14.3.
faxaddmodem generates a modem
configuration file in etc.
Modem configuration files are in the form
of config.{deviceID}

CountryCode:
1
AreaCode:
616
FAXNumber:
+1.616.447.8121
LongDistancePrefix: 1
InternationalPrefix: 011
DialStringRules:
etc/dialrules
ServerTracing:
1
SessionTracing:
11
RecvFileMode:
0600
LogFileMode:
0600
DeviceMode:
0600
RingsBeforeAnswer:
1
SpeakerVolume:
off
GettyArgs:
"-h %l dx_%s"
LocalIdentifier:
MorrisonIndustries
TagLineFont:
etc/lutRS18.pcf
TagLineFormat:
"From %%l|%c|Page
MaxRecvPages:
25

45

faxconfig
/usr/sbin/faxconfig −m { modem } {parameter value... }
faxconfig can be used to change configuration parameters on the fly
without restarting the server.
The available configuration directives are listed in the hylafax-config
manual page.
Most configuration directives can be applied either globally
(without a -m modem paramter) or to a specific device.
faxconfig communicates with faxgetty processes, and the central faxq
schedular via the FIFOs.
Configuration changes made with faxconfig are not durable, they are
lost when the server is restarted. To make durable changes you must
modify the configuration files.

46

Device Priority
Each fax modem device has a priority, for systems with multiple modems
this determines the preference for sending outbound jobs.
Priority ranges from 0 to 255
A lower priority indicates a greater preference.
Priorities can be adjusted dynamically
faxconfig -m ttyf2 ModemPriority 32
By default all configured modems have an equal priority.
The ModemPriority directive in a device's configuration file
(etc/config.deviceID) determines the devices default priority.

47

Cover Pages

faxcover
/usr/bin/faxcover is used by HylaFAX to generate fax cover pages.
By default a simple cover page is used.
The default cover page is /etc/hylafax/faxcover.ps
The fax cover page is parametized postscript, certain strings are
replaced with the corresponding information.
to, to-company, to-location, to-voice-number, to-fax-number
comments1 .. comments20, regarding
The comment? parameters related to lines of commentary broken by
newline (“\n”) characters.
from, from-company, from-location, from-voice-number
page-count, todays-date, pageWidth, pageLength

49

Generating FAX Cover Sheets
Generate an acceptable cover page with any application capable of
outputing to a Postscript or EPS file.
You can use M$-Word on Win32 by creating a printer queue using
the Apple LaserWriter driver and printing to a file.
Use easy to find text for the fields, such as “XXXX-to-company”
Edit the output document with a text editor changing your stand in
text to the tags faxcover looks for.
So “(XXXX-to-company)” becomes to-company.
Further Information
http://www.hylafax.org/HylaFAQ/Q202.html
http://www.hylafax.org/archive/2000-12/msg00090.html
http://www.hylafax.org/howto/tweaking.html

50

Misc...

Important
It is a requirement of United States law that a tagline including the
transmitter's phone number appear on EVERY page of facsimile.
The tagline is typically found on the top of each page, often seperated
from the document itself by a thin horizontal line.
HylaFAX's default TagLineFormat is
“From %%l|%c|Page %%P of %%T”
and satisfies these requirements. But you should verify the
compliance of your installation before commencing operation.

52



Source Exif Data:
File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : No
Page Count                      : 52
Page Layout                     : SinglePage
Page Mode                       : UseOutlines
Creator                         : Impress
Producer                        : OpenOffice.org 2.3
Create Date                     : 2008:05:13 06:59:13-04:00
EXIF Metadata provided by EXIF.tools

Navigation menu