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.

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.

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.

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.

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.
  

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.
  

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:

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.

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

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.

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.

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.

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

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.

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.

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
  

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.

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.
  

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.

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.

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:

The options for this command are as follows:

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:

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

"The mgetty+sendfax package is Copyright " 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."

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.

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://<a name=/ftp.sgi.com">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.