IN THIS CHAPTER
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@engr.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:
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.
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-v4.0pl1-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 to get the most up-to-date information.
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.
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, use the following commands:
$ 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 64.1.
$ 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.
A sample configuration session for my machine is shown in Listing 64.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.
# 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 +<country code> <area code> <local 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 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.
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.
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:
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.
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 a job identifier on the standard output. 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:
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.
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.
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.
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.
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.
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.
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 titled "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 64.3.)
# 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.
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.html or the /sgi/fax/contrib/dirks-faxmailer/README on sgi.com for more information.
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 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).
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 a fax call, 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, 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:
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. This is the syntax for the command:
sendfax [-p] [-xdebuglevel] [-v] [-lmodemlines]
[-minitstring]] [-dpolldirectory] [-Cmodemclass] [-S]
[-n] phone-number [g3file]
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 commmand by itself will send out a fax:
$ sendfax 5551212 sample.g3The command 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 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."
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.
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.