Red Hat Linux rhl59

---

• Installing HylaFAX
  • Where To Get HylaFAX
  • Types of Modems
  • Installation Steps
• Troubleshooting
• Setting Up a Send and Receive Daemon
• Sending a Fax
• Receiving Faxes
• Special Features
  • Cover Pages
  • Polling
  • Receiving Data Calls
  • Checking Status
  • E-Mail Setup
  • Files Used
  • Multiple Modems
• Another Fax Solution
  • The Sticky Copy Issue
  • Troubleshooting the Modems
• Summary

---

59

Using HylaFAX, sendfax, and mgetty

This chapter deals with a fax application for Linux: HylaFAX. Though there are other fax facilities for UNIX systems, such as netfax, in this chapter, I concentrate on HylaFAX because it may be the most comprehensive. You also have access to the C++ source code to make any necessary modifications to the application to adapt it to your PC.

HylaFAX was invented by Sam Leffler. You can send thanks and an "Atta boy" to him via e-mail at sam@sgi.com. HylaFAX is indeed a great piece of work.

HylaFAX is a system for sending and receiving fax documents. Some of the notable features of HylaFAX include the following:

• Queued fax transmission by date and time
  
  
• Asynchronous fax reception via a daemon
  
  
• Most programs are part of a tool kit. You can update portions of the application by updating the executable file.
  
  

Installing HylaFAX

---

The Display PostScript interpreter, Ghostscript, is supplied in binary form for Silicon Graphics machines. There is information on obtaining and setting up Ghostscript (see Chapter 25, "Ghostscript").

---

Where To Get HylaFAX

HylaFAX can be obtained via public FTP on the Internet. It is also available on a number of public domain and shareware-style CD-ROMs. The master distribution site for HylaFAX is the host ftp.sgi.com. (See the /sgi/fax/binary directory at that site.)

---

HylaFax is essentially the same program as FlexFAX, but with a new name and many more features.

---

All the HylaFAX documentation is online on the World Wide Web (WWW). This documentation describes how to unpack and install the source distribution images. The HylaFAX home page at sgi.com is the place to go for all the HylaFAX documentation.

The HylaFAX source code is available for public FTP on ftp.sgi.com as /sgi/fax/source HylaFAX-v3.0.pl0-tar.gz.

You can get more information about HylaFAX from the WWW by accessing the Web page http://www.vix.com/hylaFAX. Check out the FAQs at this site for the most up-to-date information.

Types of Modems

HylaFAX comes with detailed information on specific modems and configuration instructions in a file called MODEMS. Read this file carefully to see whether your modem is listed. If it is, you should have no problems with HylaFAX. If you cannot find your exact modem, choose the one that best fits the description you have. Chances are that a close enough setting will work fine.

Most of the modems on the list are either Class 1 or 2, and both types are supported by HylaFAX. Do not confuse the fax Group I, II, or III standards with Class 1 or 2. The groups discuss how faxes are encoded, and classes explain how you "talk" to a modem.

Installation Steps

First, unzip and untar the source files from the distribution in a local directory. After you get the source file for HylaFAX, the first installation steps are to configure your system and then do a make install command.

The source code is in a compressed tar file. To extract the software

$ mkdir fax

$ cd fax

$ uncompress $(DOWNLOAD_DIR)/v2.3.src.tar.Z

$ tar -xf $(DOWNLOAD_DIR)/v2.3.src.tar

The DOWNLOAD_DIR is the directory you downloaded the tar file to. Because the software is written mostly in C++, you need gnu C++. The versions guaranteed to work with gcc 2.5.8 and libg++ 2.5.3 are the current recommended versions of the GNU tools.

To build and install executables from the sources, look first for any port/target/README file that has target-specific information. In this case, look at port/linux/README.

Then, enter the following commands.

$ su

# configure

# make clean

# make install

I have deliberately not shown output from the configure and make commands because I discuss them in detail in this section. You have to run the make commands as root because they access the /usr/local tree, and you will need write permissions when you write files to that tree.

The output from a sample configure command is shown in Listing 59.1.

Listing 59.1. The output from the configure command.

$ configure

...(Extraneous text deleted here)...

this means that only a crummy built-in font will be available for imaging text.

Warning, /usr/local/bin/gs does not seem to be an executable program;

you'll need to correct this before starting up the fax server.

HylaFAX configuration parameters are:

Directory for applications: /usr/local/bin

Directory for lib data files: /usr/local/lib/fax

Directory for lib executables: /usr/local/lib/fax

Directory for servers: /usr/local/etc

Directory for manual pages: /usr/local/man

Directory for documentation: /usr/local/doc/HylaFAX

Directory for spooling: /usr/spool/fax

Type of uucp lock files: ascii

Directory for uucp lock files: /usr/spool/uucp

Mode for uucp lock files: 0444

Type of PostScript imager: gs

PostScript imager program: /usr/local/bin/gs

Default page size: North American Letter

Default vertical res (lpi): 98

Directory for font metrics: /usr/local/lib/afm

Location of sendmail program: /usr/lib/sendmail

Are these ok [yes]?

It's important to maintain the locations of all the listed files. Changing these locations is not a good idea because they are the default values for other applications. For example, the sendfax command did not work with any other location of the afm tree other than at /usr/local/lib/afm. Changing the location via configure did not help at all.

The make install process takes a while because the make install script has to traverse several directories and build source files in each sub-directory. The files are placed in different parts of your system based on the output of the configure command.

You may have to copy the files mkfifo, chown, and chgrp from the /bin directory to the /usr/local/bin directory. The make files exclusively use these files to set the file permissions. You have to edit the location of the echo command in the make files to reflect the correct location for your echo command. If you see /usr/local/bin/echo not found error messages, either copy echo to /usr/local/bin, or edit the make files to point to the correct location. To get rid of the message Warning, /usr/local/bin/gs does not ... in the previous listing, you create a link to gs from /usr/local/bin/gs.

After the installation is done, check /usr/local/bin/fax for executable files. At a minimum, you should have faxcover, faxd, and sendfax in this directory.

Once you have HylaFAX installed, you can add modems with the faxaddmodem shell script. This script is interactive and steps you through the configuration and installation of a new or existing modem.

---

Even if you have a previous version of this software installed, run the faxaddmodem script to update the configuration information for your modems. Running faxaddmodem twice will not ruin anything.

---

---

If your modem is configured to communicate to the host at a fixed baud rate, use the -s option with faxaddmodem. See the faxaddmodem manual page for details.

---

A sample configuration session for my machine is shown in Listing 59.2. Note that I ran as root while I did this. I pressed the Enter key after each [yes] command to accept the default responses. If you do not like what you see, type n and then press Enter.

Listing 59.2. Sample configuration for HylaFAX.

# faxaddmodem

Verifying your system is set up properly for fax service...

There is no entry for the fax user in the password file.

The fax software needs a name to work properly; add it [yes]?

Added user "fax" to /etc/passwd.

Added fax user to "/etc/passwd.sgi".

There does not appear to be an entry for the fax service in

either the yellow pages database or the /etc/services file;

should an entry be added to /etc/services [yes]?

There is no entry for the fax service in "/usr/etc/inetd.conf";

should one be added [yes]?

Poking inetd so that it rereads the configuration file.

There does not appear to be an entry for the FaxMaster in

either the yellow pages database or the /usr/lib/aliases file;

should an entry be added to /usr/lib/aliases [yes]?

Users to receive fax-related mail [root]?

Rebuilding /usr/lib/aliases database.

41 aliases, longest 81 bytes, 823 bytes total

Done verifying system setup.

Serial port that modem is connected to []? cua1

Ok, time to set up 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.

Phone number of fax modem []? +1.713.265.1539

This is the phone number associated with the modem being configured.

It is passed as an "identity" to peer fax machines 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 +&ltcountry code> &ltarea code> &ltlocal part>.

Any other characters included for readability are automatically

removed if they might cause problems.

Area code []? 713

Country code [1]?

Long distance dialing prefix [1]?

International dialing prefix [011]?

Tracing during normal server operation [1]?

Tracing during send and receive sessions [11]?

Protection mode for received fax [0600]?

Rings to wait before answering [1]?

Modem speaker volume [off]?

The server configuration parameters are

FAXNumber: +1.713.265.1539

AreaCode 713

CountryCode 1

LongDistancePrefix: 1

InternationalPrefix: 011

ServerTracing: 1

SessionTracing: 11

RecvFileMode: 0600

RingsBeforeAnswer: 1

SpeakerVolume: off

Are these ok [yes]? n

Phone number of fax modem [+1.713.265.1539]?

Area code [713]?

Country code [1]?

Long distance dialing prefix [1]?

International dialing prefix [011]?

Tracing during normal server operation [1]?

Tracing during send and receive sessions [11]?

Protection mode for received fax [0600]?

Rings to wait before answering [1]?

Modem speaker volume [off]? low

The server configuration parameters are

FAXNumber: +1.713.265.1539

AreaCode 713

CountryCode 1

LongDistancePrefix: 1

InternationalPrefix: 011

ServerTracing: 1

SessionTracing: 11

RecvFileMode: 0600

RingsBeforeAnswer: 1

SpeakerVolume: low

Are these ok [yes]?

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).

Hmm, this looks like a Class 1 modem.

Product code is "1444".

Modem manufacturer is "USRobotics".

Modem model is "Courier".

Using prototype configuration file config.usr-courier...

The modem configuration parameters are:

ModemRate: 19200

ModemFlowControl: xonxoff

ModemFlowControlCmd: &H2

ModemSetupDTRCmd: S13=1&D2

ModemSetupDCDCmd: &C1

ModemDialCmd: DT%s@

ModemResultCodesCmd X4

Are these ok [yes]?

Startup a fax server for this modem [yes]

/usr/etc/faxd -m /dev/cua1

#

HylaFAX requires that a fax user exist in the password file on the server machine. This user should have the same user ID as uucp so that lock files can be easily shared.

Client applications communicate with the server machine via the faxd.recv program. This program is designed to be started by the inetd program. If the appropriate entry is not present in inetd's configuration file, confirming this prompt causes it to be added. Note that there must also be a fax service already set up for this step to succeed (see above).

A fax server entry must exist so that the inetd program can set up the fax job submission server, faxd.recv, on the appropriate port. If the server machine is running NIS (formerly known as Yellow Pages), it may be necessary to create the entry in the appropriate map. Otherwise the entry is installed in the /etc/services file.

The fax server sends mail notices to a well-known user called the FaxMaster when certain events occur. Some examples are when faxes are received or when modems appear to be on the blink. This step sets up a mail alias for this the FaxMaster. The alias lists those system administrators that handle HylaFAX-specific problems. I chose root because I have a small system and I usually wind up doing all my administrative stuff as root anyway. If you have a large user base, perhaps a specific user could handle all the fax-related problems.

This completes the collection of server-related parameters. The remaining steps identify and configure the modem. Note that if you do not specify a fixed rate for modem communications, faxaddmodem will probe for a good speed. The faxaddmodem command is good at finding what type of modem you have and configuring it. Unless you have a compelling reason to change the responses to settings other than the defaults, leave them.

The fax daemon is now started for you. This is done with /usr/etc/faxd -m /dev/cua1. You may want to put this command in your /etc/rc.d file for subsequent boots so that you don't have to remember to start it yourself.

Troubleshooting

You are bound to run into difficulties while installing HylaFAX. Despite my assertions in the last section about two simple steps to complete the installation, you still have the potential of running into problems. Here is a brief list of problems and their solutions. The list is by no means complete, nor is it guaranteed the examples will apply to you, but at least it will give you an idea of what could be wrong.

• You need the afm-tar.Z file for the Adobe Font Metric (AFM) fonts required by the sendfax program. You can get this file via FTP from sgi.com. Some HylaFAX distributions do not include these Metric files. A subset of these fonts is available via FTP from sgi.com in the file /sgi/fax/afm-tar.Z. If you do not install the AFM files, you get error messages about fonts not found.
  
  
• Add a user called fax to the same group as uucp. The faxaddmodem call may not work and bomb with errors about too many arguments. If this happens, make sure your modem works. If you cannot use cu on your modem, fix that problem first. Check the cables, initialization strings, and so on. For external modems, check to see whether the cable has the relevant signals for doing hardware flow control if necessary and that it passes the DCD and DTR signals appropriately.
  
  
• If you have a Class 1 modem, you cannot use hardware flow control. Class 2 modems do support hardware control. Ensure that you have the correct cables for the type of external modem you plan to connect to.
  
  

Setting Up a Send and Receive Daemon

The faxd daemon is the main processing agent of the HylaFAX package. You need one faxd process and FIFO for each fax modem on your system. faxd listens to its own FIFO for all its command directives. When you start faxd, you can use the following options:

• -m to specify the terminal device the fax modem is attached to. For example, /dev/cua1 is a mandatory argument to faxd.
  
  
• -q to specify a spooling area in which to operate other than /var/spool/HylaFAX.
  
  
• -i to specify the interval in seconds that a job should be held between transmission attempts. By default, this interval is 900 seconds.
  
  
• -g option can be used to indicate that faxd should act like the getty program if it receives a call from a data modem. See the getty man page for details. If this option is not specified and the server is not configured to support incoming data connections, incoming data connections will be rejected.
  
  
• -d stops faxd from detaching itself from the terminal. This is useful for debugging.
  
  
• -1 option causes faxd to generate only 1D-encoded fax when sending.
  
  

---

There is no way to abort an incoming fax. Just sit back and wait until it's over.

---

The faxd.recv daemon is the program that implements the server side of the fax job submission protocol. It also implements extensions to this protocol to support job removal and the return of status information. faxd.recv is normally invoked by inetd with a line in the following form:

fax stream tcp nowait fax /usr/libexec/faxd.recv faxd.recv

The faxd.recv daemon accepts requests for transmitting faxes and creates the appropriate queue and document files in the HylaFAX spooling area. If a job is received properly, a request to process the job is then sent to a fax server by writing to a FIFO special file named FIFO in the spooling directory. The faxd.recv daemon then returns a message to the sender indicating the Job ID (an integer number associated with the job). This Job ID can be used later to remove the job from the queue and to query the job's status.

Diagnostics generated by faxd.recv are logged with the syslog facility. The user is always informed of any problem that affects the status of the queued job. Check the man pages for a list of these error messages.

Sending a Fax

To send a fax, you will use the sendfax program. The syntax for this command from the man page is

sendfax [ -a transmit-time ]

[ -c comments ]

[ -r regarding ]

[ -x to-company ]

[ -y to-location ]

[ -d destination ]

[ -f from ]

[ -h host[:modem] ]

[ -i identifier ]

[ -k kill-time ]

[ -lm ]

[ -n ]

[ -p ]

[ -s pagesize-name ]

[ -t tries ]

[ -v ]

[ -DR ]

[ files... ]

sendfax queues up fax requests to a faxd server. These requests normally are processed immediately, although they may also be queued for later transmission using a syntax identical to the at command. For each job that is queued, Sendfax prints on the standard output a job identifier. This number can be supplied to the faxrm command to remove the job or to the faxalter(1) command to alter some of its parameters.

Fax documents are made from the concatenation of files specified on the command line. If no files are supplied, sendfax reads data from the standard input unless polling is requested. sendfax passes PostScript and TIFF documents directly to the fax server for transmission and attempts to convert other file formats to either PostScript or TIFF. In normal operation, sendfax automatically converts ASCII-text or troff output before transmission.

By default, sendfax will generate a cover page for each fax that is transmitted. This cover page is created by the faxcover program using information determined by sendfax and by information supplied on the command line. The -x option is used to specify the receiver's company; the -y option to specify the receiver's geographical location; the -c option to specify a comments field; and the -r option to specify a Re: subject. If a destination is specified as user@fax-number, the user string is passed to faxcover as the identity of the recipient.

---

The preceding options must precede the -d option on the command line. Note also that multiword names must be enclosed in quote marks (").

---

---

If you don't want a cover page, specify the -n option.

---

Here are a few other things about sending faxes:

• You can use *70, on the -d parameter of sendfax when you want to disable call waiting.
  
  
• By default, a fax is sent at low resolution (98 lines per inch). Medium resolution (196 lines per inch), often called fine mode, is requested with the -m option. Low resolution is requested with the -l option.
  
  
• Faxes are on 8.5´11 pages unless otherwise configured. Other sizes include A3, ISO A4, ISO A5, ISO A6, ISO B4, North American Letter, American Legal, American Ledger, American Executive, Japanese Letter, and Japanese Legal.
  
  
• By default, sendfax uses the FAXSERVER environment variable to identify the fax server to which the job should be directed. This can be overridden with a -h option. The server specified with the -h option, and by the environment variable, is a host name or address and optionally, a modem identifier. The syntax for the latter is either host:modem or modem@host. For example, cua2@no.inhale.edu. If no modem is specified, the job will be submitted to any available modem.
  
  

If the first attempt to send a fax is unsuccessful, HylaFAX periodically tries to resend the fax. By default, HylaFAX tries to transmit the fax for one day from the time of the initial transmission. The -k option is used to specify an alternate time for killing the job. This time is specified using notation compatible with at and as a time relative to the time of the initial transmission attempt.

If an error is encountered while HylaFAX is processing a job, the fax server sends an electronic mail message to the account submitting the job. If the -D option is specified, HylaFAX also notifies the account by mail when the job is completed. In addition, if the -R option is specified, notification also is returned any time the job must be queued for retransmission.

Notification messages identify a job by its job identifier.

An arbitrary identification string can be specified instead with the -i option.

If the -v option is specified, sendfax prints information on the standard output about what sendfax does. If you specify —v -v, even faxd.recv displays its status messages as it works.

See the man pages for more information on the options available with this sendfax command.

Only two types of files are accepted by the fax server for transmission: PostScript files or TIFF Class F (bi-level Group 3-encoded) files. All other types of files must be converted to one of these two formats. The sendfax program applies a set of rules against the contents of each input file to identify the file's type and to figure out how to convert the file to a format that is suitable for transmission. These rules are stored in the /usr/local/lib/HylaFAX/typerules file, an ASCII file similar to /etc/magic. See the man pages on type rules for a detailed look at how these type rules work.

Receiving Faxes

Server processes can be configured to answer incoming phone calls and automatically receive faxes. Received documents are placed in the recvq subdirectory as TIFF Class F files. The server can be configured to make these files publicly accessible, or they can be made private, in which case an administrator must manage their delivery.

When a fax is received, the server process invokes the bin/faxrcvd command. The default command is a shell script that sends a mail message to a well-known user, the FaxMaster, but you might also, for example, automatically spool the document for printing.

Actually the man pages for HylaFAX are well written (for man pages). In the man pages for faxd, you get a lot of detailed information about how received faxes are handled.

Special Features

HylaFAX comes with several features from creating cover pages and receiving incoming data calls to handling polling requests. In each of these cases you can get more information for the man pages for each command discussed in the remainder of this chapter.

Cover Pages

You generate PostScript cover sheets for your outgoing faxes with the faxcover command. The syntax for this command from the man page is

$ faxcover [ -t to-name ]

[ -l to-location ]

[ -x to-company ]

[ -v to-voice-number ]

[ -c comments ]

[ -r regarding ]

[ -p page-count ]

[ -s pagesize-name ]

[ -C template-file ]

-f from-name -n fax-number

To generate the cover page for each outgoing fax, faxcover is invoked by the sendfax program. Faxcover generates a PostScript cover-page document on the standard output. The cover page fills the entire area of the default page and is created according to the information supplied on the command line and a cover sheet template file. The default template file is named faxcover.ps. You can override the default cover sheet with the -C option by specifying a file in the FAXCOVER environment variable.

If the cover sheet's filename is not an absolute path, faxcover looks first for this file in the sender's home directory. If no such file is present, faxcover looks in the library directory where the HylaFAX client application data is installed. If no template file is located, faxcover terminates without generating a cover page.

Polling

HylaFAX supports the polled retrieval of fax documents. Documents received because of a poll request are stored in the recvq subdirectory and also delivered directly to the requester using the bin/pollrcvd command. This script typically encodes the binary fax data and returns it to the recipient via e-mail.

Receiving Data Calls

Most fax modems also support non-fax communications. HylaFAX uses the locking mechanism employed by uucp and cu. Therefore, HylaFAX transparently relinquishes the serial port when an application uses the modem for an outgoing call. In addition, HylaFAX attempts to deduce whether an incoming call is for fax or data use. If an incoming call comes from a data modem and the -g argument is specified in the configuration file (or on the command line when the fax server process is started), HylaFAX invokes the getty program so that the caller may log in to the system.

Checking Status

HylaFAX maintains status information in several forms. General status information for each server process can be displayed by the faxstat(1) program. The server processes may also be configured to log various kinds of debugging and tracing information. For more information about configuration, see the section entitled "Installation Steps" in this chapter. The faxstat utility provides information such as the remote status of jobs queued for transmission, jobs received, and the general status of server processes. See Listing 59.3.

Listing 59.3. Output of the faxstat command.

# faxstat

Server on localhost:cua1 for C: Running and idle.

Job Modem Destination Time-To-Send Sender Status

2 any 5551212 root Queued and waiting

1 any 5551212 kamran Being processed

Server on localhost:cua1 for C: Sending job 1 to 5796555.

Any problems encountered during fax transmission are reported to the user by e-mail. A user may also request notification by mail when a job is requeued. The server process uses the /bin/notify command to inform the user via e-mail.

The file etc/xferlog contains status information about all faxes sent and received. This file is in a simple ASCII format that is easy to manipulate with programs such as vi or emacs.

To get more accounting information, use the following commands.

• xferlog—A log file of all transmitted files
  
  
• xferstats—Accounting information about all faxes sent or received
  
  

E-Mail Setup

It is easy to set up a simple mail-to-fax gateway facility with HylaFAX. If your system uses sendmail to deliver mail, follow the instructions in the faxmail/mailfax.sh-sendmail document. If your system uses smail (Linux users), follow the instructions in faxmail/mailfax.sh-smail. Restart your mail software.

Now, mail to user@dest.fax will be formatted and submitted as a facsimile job to user at the specified destination. By writing a more involved mailfax script, you can add options and display parameters such as different resolutions by parsing the user string. See the faxgateway documentation on www.vix.com in HylaFAX/faxgateway.asp or the /sgi/fax/contrib/dirks-faxmailer/README on sgi.com for more information.

Files Used

HylaFAX stores its data, configuration, and faxes in several places on the file system in Linux. Here is a list of the important files and directories:

• HylaFAX uses a spool area on the disk for sending and receiving faxes. The spooling area is located under the directory /var/spool/HylaFAX.
  
  
• The /usr/local/bin directory has the commands used by the HylaFAX package. The commands are fax2ps, faxaddmodem, faxalter, faxanswer, faxcover, faxmail, faxquit, faxrm, faxstat, and sendfax.
  
  
• The ./etc directory stores all the configuration, access control, and accounting information.
  
  
• The ./sendq directory has all the outgoing fax jobs.
  
  
• The ./recvq directory contains a copy of all received faxes.
  
  
• The ./docq and ./temp subdirectories are used in fax transmission also.
  
  
• The info subdirectory contains files that describe the capabilities of fax machines called by HylaFAX. This information is used in preparing documents for transmission.
  
  
• The cinfo subdirectory contains files with per-machine control parameters to use when sending faxes.
  
  
• The status subdirectory contains files to which server processes write their current status.
  
  
• The log subdirectory contains logging information about send and receive sessions.
  
  

Multiple Modems

HylaFAX supports multiple fax modems on a single host. Associated with each modem is a server process that handles transmission and asynchronous reception. Server processes operate independently of each other and use file-locking to avoid conflicts when handling jobs submitted for transmission. All modems are treated equally at the same priority. A HylaFAX server process accepts messages and commands through FIFOs. A FIFO is basically a communications data channel where the first data in (FI) is the first data out (FO).

Another Fax Solution

The mgetty+sendfax+vgetty package is a set of programs to send and receive faxes in a UNIX environment. The package only supports Class 2 modems. The filename is called mgetty+sendfax-0.98.tar.gz, and you can get it from tsx-11.mit.edu in the /pub/linux/sources/sbin directory. There are three parts to this package: sendfax, vgetty, and mgetty. The program mgetty is for receiving faxes and handling external logins without killing any outgoing calls. sendfax is a program that sends fax files. vgetty is an extended version of mgetty that can answer the telephone like an answering machine and record voice-mail messages in addition to mgetty's fax or data call handling capabilities. The entire package lets you manage faxes and voice messages.

So what's the difference between mgetty and the regular versions of getty? Unlike traditional versions of getty or uugetty, which will put a modem into auto-answer mode, mgetty does not. When a call comes in, mgetty tells the modem to answer and tell mgetty what kind of call is being received. If it is fax, mgetty will receive the fax itself. If the modem is getting data, mgetty prompts for a user ID, and then hands the open line off to login for a normal data login.

It's the modem's job to distinguish a fax call from a data call. Not all fax modems can do this, so if yours does not do this, there is no way for mgetty to do this for you. mgetty can be used with modems that cannot distinguish a fax call from a data call, but you must tell it ahead of time what type of call to expect. You can configure mgetty to allow for uucp and other connections.

---

Note that mgetty also supports caller ID and can be programmed to deny connections based on originating telephone number.

---

If you have a voice-capable modem, then you can use vgetty. The vgetty program is an extension to mgetty that provides additional call-handling capabilities. When the modem reports an incoming call, vgetty has the modem pick up the line and play a greeting. Then, as with mgetty, the modem reports the type of call. If it hears "human voices" (stuff it can't identify), the modem reports a voice connection and vgetty records the noise as an incoming voice message. If the modem reports that it identifies a fax tone, vgetty acts like mgetty and receives a fax or answers a poll. If instead, the modem hears nothing following the greeting (a certain level of silence that continues for a certain number of seconds), the modem assumes the caller is a data modem and attempts a data connection.

---

Do not use vgetty if you expect a large number of voice calls and very few data calls on the phone line you hook up. Most modems will hang up during the incoming message.

---

Basically the sendfax portion does the following:

• Send faxes directly or using shell scripts.
  
  
• Do fax polling. The polling means that you can call another fax machine and request data from it.
  
  
• Create a fax queue: outgoing faxes get sent automatically, and the user is informed by mail about the result.
  
  

You will need the Portable Bitmap Toolkit (pbmplus) for converting from the standard G3 fax format to printable images. The reason is that mgetty itself can only send or receive G3 (raster) format. However, the distribution includes tools to convert raw G3 files to or from the format used by pbmplus. The pbmplus toolkit is available from tsx-11 or sunsite archives. You will have to use the pbmtog3 and g3topbm utilities in mgetty to convert between PBM and G3. Also, the Ghostscript interpreter can convert PostScript to G3, but not vice versa.

To compile the package, copy the policy.h-dist over to the policy.h file. Then run make all to make all the packages.

To enable logins with fax capability, replace the getty with mgetty (or vgetty if your modem can handle voice) for the /dev/tty device you have configured for incoming calls. To send faxes, you have to use sendfax. The syntax for the command is:

sendfax [-p] [-xdebuglevel] [-v] [-lmodemlines]

 [-minitstring]] [-dpolldirectory] [-Cmodemclass] [-S]

 [-n] phone-number [g3file]

The options for this command are as follows:

-p	Tells sendfax to try fax polling, that is, get any documents queued in the remote fax machine for you.
-x	Uses the given level of verbosity for logging—0 means no logging, 5 is really noisy.
-v	Gives some progress report on stdout.
-l	Uses the given modem lines. Multiple lines can be separated by a colon. Example: sendfax -l tty1a:tty2a
-m	Sends an additional init string. This string is sent right after initializing the modem and setting it into Class 2 mode. You can use this to set the speaker value, some special registers, and so on. The modem must return "OK." If it returns "ERROR," sendfax prints an error message and aborts. You do not have to prepend the "AT" prefix, but it won't do any harm either.
-d	Specifies the directory where polled fax files should go to. Defaults to the directory from which the program was invoked for the current directory. Unused if not polling a fax.
-C	The values for class are the type of modem: "auto" (the default), or "cls2."
-S	Assumes modem connection on stdin, do not try to lock or initialize anything. To take over existing connections use with a dial string of T1. The T1 command sends out a short beep and no phone number at all. Such a behavior would confuse many modems. In the case of a pulse dialed number, this action may confuse the telco switch. You may also use the -m ATX1 option with the -S option if you do not wait for dial tone.
-n	Tells sendfax to send the fax pages in "normal" (204´98 dpi) mode. Default is "fine" mode (204´196 dpi).

Now that we have discussed all these options, you may be happy to know that none of these options are required to send a fax. So the following command by itself will send out a fax:

$ sendfax 5551212 sample.g3

will send the G3 encoded file fax to the number 5551212. For sending graphic images in the popular PBM format, you can also pipe the output of the pbm2g3 command to sendfax:

$ pbm2g3 sample.pbm | sendfax 555-1212

The Sticky Copy Issue

From the FAQ, the note about the Copy is as follows:

"The mgetty+sendfax package is Copy " 1993 Gert Doering. You are permitted to do anything you want with this program—redistribute it, use parts of the code in your own programs, _, but you have to give me credit—do not remove my name.

"If the program works for you, and you want to honour my efforts, you are invited to donate as much as you want.

"If you make money with mgetty, I want a share. What I mean by that is: it's perfectly OK with me to get paid for mgetty installation or support, but if you want to actually sell mgetty, or pack mgetty with a modem and sell it as "UNIX FAX package," contact me first."

---

This package is still BETA software. Use it at your own risk, there is NO warranty. If it erases all the data on your hard disk, damages your hardware, or kills your dog, that is entirely your problem. Anyway, the program works for me and quite a lot of other people.
For more info on the Copy issue, please contact Mr. Doering directly.

---

Troubleshooting the Modems

The FAQ has some interesting questions and answers to the commonly found bugs, "features," and fixes. In most cases, if your modem is not supported, twiddling with a few files here or there will not do the trick. I tried four different types of known name-brand modems before a cheap clone modem worked. I have no idea why this modem, which by the way has no visible markings, worked whereas the others did not. You may have better luck than I did.

In short, trying to fax out of Linux may not be as easy as you think. It's possible, but will take time and effort on your part.

Summary

This is a brief introduction to HylaFAX, a complete fax-handling package for UNIX and Linux. I covered the following items in this chapter.

• How to get HylaFAX for your machine.
  
  
• HylaFAX installation involves untarring the source files in a local directory. Then it's a matter of running configure to customize the program for your machine and running make install. You have to be root to install HylaFAX.
  
  
• How to check the MODEMS file to see whether your modem is supported.
  
  
• HylaFAX requires a background daemon faxd to handle incoming and outgoing faxes. You have to start the daemon with the -m option to specify where your modem exists. You need a FIFO and daemon for each modem on your system.
  
  
• The sendfax program requires the Adobe Font Metric files (in /usr/local/lib/afm) for converting from text to fax.
  
  
• Install Ghostscript before you install the HylaFAX package. This saves you a lot of time and gets rid of most installation problems.
  
  
• How to check the status of received or sent faxes with the faxstat program.
  
  
• The fax daemon, faxd, can be configured to answer either data or fax transmissions if faxd is invoked with the -g argument.
  
  
• HylaFAX supports polling via fax machines.
  
  
• How to get more information about HylaFAX via the WWW by accessing the Web page http://www.vix.com/hylafax.
  
  

The source code for HylaFAX is available for public FTP on ftp.sgi.com as /sgi/fax/source/ hylaFAX-v3.0.pl0-tar.gz.

I have also introduced you to sendfax, mgetty, and vgetty. These three programs enable you to send faxes, receive faxes, and even set up voice mail on your Linux box, provided your modem is supported.