Installing HYLAFAX v4.0pl1 on SunOS 4.1.4

1. System Dependencies and Suggested Tools
2. Getting the binary distribution package
3. Installing the binary distribution
4. Configuration of HylaFAX
5. Changes for SunOS 4.1.4 systems
6. Providing Login and PPP service
7. How to start up the fax daemons
8. Online HTML documentation
9. Quickly test your installation

SYSTEM DEPENDENCIES AND SUGGESTED TOOLS

The binary distribution package of HylaFAX v4.0pl1 is available in gzipped tar format and was compiled under SunOS 4.1.4 with GNU gcc version 2.7.2.1 and libg++ 2.7.2. The package contains a complete set of server and clients together with some goodies to ensure a complete and ready to use system.

Previous versions of Hylafax worked on the following SunOS systems and HylaFAX v4.0 should work on them as well:

• SunOS 4.1.2
• SunOS 4.1.3
• SunOS 4.1.3_U1
• SunOS 4.1.4

If you are using a SunOS earlier than SunOS 4.1.4, you will also need the jumbo tty patch to provide hardware flow control and prevent certain problems with the serial lines getting so wedged that the machine must be rebooted to clear them. These patches do require recompiling your kernel: if they are not installed and you are not comfortable doing this, you should definitely rethink whether you have the expertise to run a fax server. They are easy to install and are known to improve serial line performance.

The jumbo tty patch is available at:

• ftp://sunsolve1.sun.com/pub/patches/100513-05.tar.Z for SunOS 4.1.[123]
• ftp://sunsolve1.sun.com/pub/patches/101621-04.tar.Z for SunOS 4.1.3_U1

Fortunately, SunOS 4.1.4 does not require any of these patches. If you are not already running this latest operating system, you should strongly consider it for security reasons and improvements like hardware flow control.

To install and run HylaFAX v4.0pl1 you will also need the following resources on your system:

• 7 MBytes or so of free diskspace on the /usr filesystem where the software is installed;
• 10 MBytes or so of temporary free diskspace on the /tmp or /usr/tmp filesystem while running obtaining and unpacking the binary distribution;
• root access to do any kernel patches, install the software package and run the configuration scripts;

There is also some free, publicly available software necessary to run HylaFAX under SunOS. I strongly recommend installing the most recent version of these programs. They are:

• gawk: instead of nawk for SunOS
  version 3.0.0 or better
• ghostscript: changes Postscript to fax formats or display it on an X screen
  version 2.6.1 or better
• tiff: transforms TIFF fax formats to Postscript
  version 3.4 or better

• sfax: create and send faxes from a template at a terminal window
• faxtool: create, send, or receive faxes from an X-windows server
• macflex: create, send, or receive faxes from a Macintosh client
• winflex: create, send, or receive faxes with a Windows client
• ghostview: view Postscript files directly on an X-server
• viewfax: view TIFF files directly on an X-server, without converting to Postscript first
• fax covers: user-created faxcovers to replace the SGI default included with Hylafax
• dialrules: sets of dialing rules for different national or local telephone systems
• ftp://ftp.sgi.com/sgi/fax/contrib/: other contributed configuration tools and configurations setups for Hylafax

Ghostscript Notes

If you compile ghostscript under SunOS, it is important to modify the Makefiles to use /usr/openwin/include for the XINCLUDE option, and /usr/openwin/lib for the XLIBDIRS option. This will access the right Openwindows X11 files and libraries for compilation and when any Postscript files get turned to tiffg3 with ghostscript by the Hylafax software using (ps2fax). This is necessary because SunOS ignores the LD_LIBRARY_PATH environment variable for suid scripts as a security precaution. You may also want to add a "-s" option to the INSTALL_PROGRAM flags to install the software stripped, to save space.

If this is unclear, simply add the following lines to cc-unix.mak and gcc-unix.mak, run tar_cat to collate it into the new makefiles, and use one of the resulting makefiles to compile the software:

• INSTALL_PROGRAMS= $(INSTALL) -s -m 755 # at line 38

• XINCLUDE= -I/usr/openwin/include # at line 178

• XLIBDIRS= -L/usr/openwin/lib # at line 190

There is also a known optimizer bug with gcc-2.7.2 that is tripped when compiling ghostscript-4.0[x]. There are several solutions to this:

• Use the the full ghostscript binary and fonts in gzipped tar format from, ftp://sgi.com/sgi/fax/binary/gs-sunos414-gs4.03-tar.gz. This is the fastest solution.
• Install and use gcc-2.7.2.1.
• Turn off optimization when compiling ghostscript.
• Use the Sun "/bin/cc" C compiler.
• Install the gcc-2.7.2 patch discussed in the ghostscript-4.03 documentation

GETTING THE DISTRIBUTION PACKAGE

The distribution package is available for free from ftp://sgi.com/sgi/fax/binary/hylafax-sunos4.1.4-v4.0pl1-tar.gz, where Sam Leffler, the creator of Hylafax, has graciously agreed to keep some binaries compiled by others.

These binaries are installed suid, and some of them are owned by root. You should therefore check the sum or the md5sum value of the package to protect yourself from Trojan Horse programs and other security problems. The correct values are:

• sum: 25754 2281 hylafax-sunos4.1.4-v4.0pl1-tar.gz
• md5sum: ce797108a5188e3a3cb5033ed8e10b37 hylafax-sunos4.1.4-v4.0pl1-tar.gz

INSTALLING THE DISTRIBUTION

If you have already installed an older binary distribution of FlexFAX or HylaFAX on your system backup your old software (e.g. with tar) and simply delete the entire old distribution.

Please note that the SunOS binaries do not use the default Hylafax software and spooling directories. Because SunOS typically has a rather small /var partition, Hylafax can easily overflow it with large numbers of outgoing faxes or received, undeleted faxes. Instead, the software is installed in the /usr/local/hylafax and /usr/local/spool/hylafax directories and there are symbolic links to those directories in /var/spool and in /usr/local/bin.

To install the binary SunOS distribution of Hylafax perform the following steps as root:

   prompt# gzcat hylafax-sunos4.1.4-v4.0pl1-tar.gz | tar xvpf - -C  /

If you also need to install ghostscript, use this:

   prompt# gzcat gs-sunos4.1.4-4.03-tar.gz | tar xvpf - -C /

This HylaFAX distribution was compiled with the following configuration parameters (from the configure script):

HylaFAX configuration parameters are:

[ 1] Directory for applications:
                   /usr/local/hylafax/bin
[ 2] Directory for lib data files:      
                   /usr/local/hylafax/lib
[ 3] Directory for lib executables:     
                   /usr/local/hylafax/lib
[ 4] Directory for system apps:         
                   /usr/local/spool/hylafax/bin
[ 5] Directory for manual pages:        
                   /usr/local/hylafax/man
[ 6] Directory for HTML documentation:  
                   /usr/local/httpd/htdocs/hylafax
[ 7] Directory for spooling:            
                   /usr/local/spool/hylafax
[ 8] Directory for font metrics:        
                   /usr/openwin/lib/fonts/afm
[ 9] Directory for uucp lock files:     
                   /var/spool/locks
[10] Uucp lock file scheme:             
                   ascii
[11] PostScript imager package:         
                   gs
[12] PostScript imager program:         
                   /usr/local/bin/gs
[13] Manual page installation scheme:   
                   bsd-source-cat-strip
[14] Default page size:                 
                   North American letter
[15] Default vertical res (lpi):        
                   196
[16] Location of getty program:         
                   /usr/etc/getty
[17] Location of voice getty program:   
                   /bin/vgetty
[18] Location of sendmail program:      
                   /usr/lib/sendmail
[19] Location of TIFF tools:            
                   /usr/local/bin

Several of the above pathnames are compiled into applications included in this binary distribution. If any of these pathnames are unacceptable, your best options are to create a symbolic link to the installed directory hierarchies or to retrieve the HylaFAX source distribution and recompile from scratch. Fortunately, compilation is very easy with this software. You will need a good ANSI C++ compiler like gcc-2.7.2.1 and libg++-2.7.2, available from the Free Software Foundation ftp site ftp://aeneas.mit.edu/pub/gnu

If you decide to recompile Hylafax, there is a file in the source distribution called hylafax-v4.0/config.site that can be edited directly. It is better to copy it to hylafax-v4.0/config.local and edit that file to store these changes separately. Options include the compiler to use, various compilation flags, whether and where to install local html pages, etc. In general, there is little reason to modify them. The configuration scripts are very good at detecting and using appropriate settings without interference.

Some of the above parameters can also be changed after installation by editing various configuration files, see also config.

CONFIGURATION OF HYLAFAX

If you have access to the World Wide Web, go to the HylaFAX Home Page at http://www.vix.com/hylafax/ and read the documentation. In particular, read the information that describes how to setup a fax server.

Online documentation is also available through the manual pages; consult the pages hylafax(1M) and hylafax(4F) for introductory information on the client applications and the server setup, respectively.

In order to run HylaFAX you must have a modem with fax support (Class 1, Class 2, or Class 2.0). This modem must be connected to your system on an RS232 serial port and you have to know to which port (e.g. ttya) it is connected. (Many users have reported good success with terminal servers on different operating systems as well, although I have not tried it myself). For the modem-configuration part of the installation you should know a little bit about your modem and the AT commands to control various settings in the modem. If you are in doubt ask a modem guru or consult the documentation that comes with your modem (never buy a modem without documentation.)

If you don't have either documentation or a guru handy you are on your own; try configuring the modem and if you have a problem consult the WWW documentation or ask for help on the HylaFAX mailing list (read the URL above to subscribe) . There is also a new Modems for Dummies book available from out: look for it in your local bookstore.

You should consult the FAQ of HylaFAX before asking questions already answered.

It is a good idea to first check out your serial port with a terminal emulation program (such as kermit or cu) to test the modem and the connection to your serial ports. Remember that you should use the same tty names for ALL modem programs. This is in direct contradiction to the "split device" trick recommended by Sun. (See Changes for SunOS 4.1.4 systems.)

After the modem is properly connected to your computer and your Hylafax software installed, login as root and run faxsetup:

prompt# sh /usr/local/spool/hylafax/bin/faxsetup

When you run faxsetup, use the defaults wherever possible. The only option that you really need to answer is the area code: the defaults for the others work quite well. For safety's sake, you may want to set a maximum fax number of pages for outgoing faxes as well. Do not worry when it complains about not having vgetty and egetty: these are optional programs with the mgetty package, which have not been tested under SunOS.

When faxsetup is finished, use faxaddmodem to set up your individual modem lines. Carefully read the manual page for config to set any special parameters for your site. You can always run faxaddmodem later to revise these settings.

Warning note for SunOS installation: If the faxaddmodem script seems to hang when started, suspend it and use ps to look for fuser processes that have hung. Sometimes fuser simply hangs on serial lines under SunOS. Kill off the fuser processes, resume your faxaddmodem job, and ignore the complaints about missing fuser commands.

CHANGES FOR SUNOS 4.1.4

For SunOS 4.1.4 and other SunOS versions, there are a number of configuration changes and patches you will want.

SunOS recommends something called the split-device trick for sharing modems for dial-in and dial-out. This absolutely does not work with Hylafax, nor does it work with Sbus serial expanders or a plethora of other increasingly popular setups. Hylafax will itself handle providing getty and sharing the modem with kermit, uucp, tip, etc.: simply edit the /etc/uucp/Devices file to use your /dev/tty* modem lines instead of the associated /dev/cu* devices and delete those /dev/cu* devices altogether to prevent confusion.

PROVIDING LOGIN AND PPP

The fax daemon process is capable of distinguishing between fax- and data-calls. If you want to provide "Login:" capability on data-calls you need to do the following steps:

• Create entries for any new and different baudrates in gettytab. All the standard baud rates are already present there. To add a new one, simply duplicate a standard one, assign it a new name, and add it to the file. For example, to create some entries that use 8N1 instead of the standard SunOS 7E1 byte length, parity, and stop bits, use these:

  ppp.1200|1200-ppp:\ :p8:sp#1200: ppp.2400|2400-ppp:\ :p8:sp#2400: ppp.4800|4800-ppp:\ :p8:sp#4800: ppp.19200|19200-ppp:\ :p8:sp#19200: ppp.38400|38400-ppp:\ :p8:sp#38400: ppp.57600|57600-ppp:\ :p8:sp#57600:

• To automatically have any new modem lines added to your system use these more standard 8N1 dialup settings, especially for Win95 Dial-Up Networking clients, change GettyArgs in your skel file to read this way:

  GettyArgs: "ppp.%s -"

• Then doublecheck the GettyArgs: value in each modem's config.ttyxxx file. This file was created by faxaddmodem and its default data is set by the skel configuration file. It should read the same way as the skel file. If it's different, use faxaddmodem to change the GettyArgs entry for that modem.

• Next, modify the entries for any modem lines in the /etc/ttytab file, as follows.

  ttya "/usr/local/hylafax/lib/faxgetty" dialup on #dialup modem line

  You can use whatever terminal type you wish to support for the terminal setting: I suggest dialup to permit users to detect that they are on a modem line and set up their environment differently in their configuration files.

• To actually use PPP under SunOS with Hylafax, you should install the latest freeware ppp-2.3b3 and use these settings for the /etc/ppp/options file.

  nodefaultroute # don'tt use defaultroute for dial-in lines (required) lock # lock the modem from other users (required) proxyarp # pass connections to other hosts <required) lcp-echo-interval 60 # interval in seconds between touches (recommended) lcp-echo-failure 5 # failed attempts before link shutdown (recommended) -ipcp-accept-remote # force PPP client to use dynamically assigned IP address (recommended) mtu 296 # maximum transfer unit (recommended) crtscts # use hardware flow control (recommended) debug # leave debugging on (optional) -pap # do not use pap passwords (optional) -chap # do not use chap passwords (optional)

• Then add /etc/ppp/options.ttyxxx files matching your /dev/ttyxxx modem lines with entries like:

  :dialupttyxxx # dynamically assigned IP address for PPP client

  The IP addresses of those dialupttyxxx entries should be in your system /etc/hostsfile or your NIS hosts information, and registered with the InterNIC to prevent IP conflicts. (Dealing with InterNIC is a bit beyond the scope of this INSTALL file). Your local network administrator absolutely must know about these IP addresses to prevent security or configuration problems, such as IP conflicts or IP spoofing (which is also a bit beyond the scope of this INSTALL file). This information also permits them to add permissions as needed for local services like Usenet, Web access to the local server, NFS mounting permissions, etc.

• If you cannot get clearance to install a true PPP server, you can also use a pseudo-server called SLIRP

HOW TO START UP THE FAX DAEMONS

There are several other important system related files to examine. A useful script called hylafax is provided with the binary distribution to begin the fax services. This script is not installed by the default software configuration, but is in the hylafax-v4.0pl1/etc directory of the source code. This script can be used to start or stop the server daemons if you decide to do so by hand rather than configuring it in the inetd.conf file. If you wish to use this script, you should delete any old hylafax, fax, and snpp entries from the inetd.conf file and edit rc.local file to start the hylafax script at boot time.

To start the daemons by hand, simply do this as root:

prompt# sh /usr/local/spool/hylafax/etc/hylafax start

To kill off the fax daemons by hand, simply do this as root:

prompt# sh /usr/local/spool/hylafax/etc/hylafax stop

ONLINE HTML DOCUMENTATION

The best online documentation is the HylaFAX Home Page at http://www.vix.com/hylafax/. The HTML material from the source distribution is provided with the SunOS binary distribution, but it is bulky and depends somewhat on the configuration of the local http daemon. It resides in /usr/local/httpd/htdocs/hylafax and /usr/local/httpd/cgi-bin after installation, and the /usr/local/httpd/htdocs/hylafax can easily be deleted to save space.

If you decide to compile from source you may edit the hylafax-v4.0pl1/config.local file at compilation time to install them locally.

QUICKLY TEST YOUR INSTALLATION

To test your installation once you've configured your fax server and modem, startup the fax server as shown above, log out as root, and log in again as a "normal" user.

First run faxstat to make sure the server is running:

prompt> /usr/local/hylafax/bin/faxstat

The hfaxd daemon should respond with something like:

prompt> faxstat HylaFAX scheduler on hostname: Running Modem ttya (+x.xxx.xxxx): Running and idle Modem ttyb (+x.xxx.xxxx): Running and idle prompt>

If it doesn't respond correctly, double check that the faxq and hfaxd daemons are running, and that the contents of your Hylafax hosts file, which is in /usr/local/spool/hylafax/etc/hosts, are correct.

Then send a short fax (use the phone number of a local fax machine instead of +1.999.555.1212):

prompt> sendfax -n -d +1.999.555.1212 <<EOF Hello world. I like the binary distribution of HylaFAX v4.0pl1 EOF

You should now see the job in the queue being processed. If it is not there or fails, try running "faxstat -v", check the logs in /usr/local/spool/hylafax/logs, and re-read the documentation. If you have problems that are not answered by the documentation included with the distribution, check the Web for information, especially the HylaFAQ. A mailing list for users of this software also exists; see FAQ Question 12 to learn how to subscribe to the list.

If you have comments or suggestions for this installation, or even need some help with SunOS installations, feel free to contact me:

Nico Garcia / raoul@cirl.harvard.edu.
Last updated $Date: Fri Nov 22 16:17:20 EST 1996 $.