HOW TO INSTALL HylaFAX v4.0 ON SCO UNIX ver4.2 1. Overview 2. System Dependencies 3. Getting the distribution package 4. Installing/Updating the distribution 5. Configuration of HylaFAX 6. Make Symbolic links 7. How to startup the fax daemons 8. Getty related changes 9. Online HTML documentation 10. Syslog changes 11. Testing OVERVIEW [This document augments the normal materials provided with the HylaFAX v4.0 source distribution. All HylaFAX v4.0 documentation is available on-line on the World Wide Web (WWW) at the HylaFAX Home Page http://www.vix.com/hylafax/] HylaFAX is a facsimile system for UNIX systems. It supports: - sending facsimile (sendfax(1)); - receiving facsimile; - polled retrieval of facsimile (sendfax(1)); - sending messages to pager through SNPP (sendpage(1)); - transparent shared data use of the modem (faxgetty(1M)); Facsimile can be any size (e.g. A4, B4), either 98 or 196 lpi, and transmitted/received as either 1D-encoded or 2D-encoded facsimile data (2D-encoded data is frequently more compact and hence takes a shorter time to communicate). Outgoing documents can be any format; the sendfax program uses a rule-based definition file similar to the System V /etc/magic file to deduce document types and to decide how to convert each document to a form suitable for transmission (either PostScript or TIFF/F). Automatic cover page generation (faxcover(1)) is supported and users can easily tailor cover pages to their environment. A simple text-based phonebook database is supported by sendfax. Information is also provided on how to easy setup an email to fax gateway service. Incoming facsimile are stored in a receiving area as TIFF/F files and may be automatically delivered by mail and/or printed; see faxrcvd(1M). A fax server status program, faxstat(1), can be used to monitor the send and receive queues, as well as the state of facsimile servers. Fax modems may be shared with outgoing data communication applications that honor the "uucp locking protocol". These applications typically include: cu, tip, kermit, uucp, slip, and ppp. The system can also be configured to enable incoming data calls to cause the system to invoke the standard system getty program. The software is structured around a client-server architecture. One facsimile server process (faxgetty(1M)) exists for each fax modem on a network and one server process ( faxq(1M)) for each fax-queue on a computer on a network. Clients may send facsimile from any machine that can communicate with the machine(s) on which the server(s) reside. The server side of the protocol is handled by the daemon (hfaxd(1M)) the protocol itself is implemted in form of the standard FTP protocol. Client software is designed to be lightweight and easy to port; imaging can be offloaded to the server or done on the client. (Imaging is, however, typically done on the server because it simplifies administration.) Multiple modems may be located on a single machine. An access control mechanism is included to control which users on which machines may submit documents for transmission. The system supports a wide variety of fax modems. Any Class 1, Class 2, Class 2.0 modem should work with the system. There is also support for pager devices. Please report all problems & bugs regarding this binary distribution to me, Tim Rice Disclaimer: THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. In addition for the binary distribution: IN NO EVENT SHALL TIM RICE OR MULTITALENTS BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. SYSTEM DEPENDENCIES The binary distribution package of HylaFAX v4.0 is available in cpio(C) format and was compiled under Altos/SCO UNIX Version 4.2aC0 with GNU gcc version 2.7.2.1 and libg++ 2.7.2. Actually the package contains a complete set of server and clients together with some goodies to ensure a complete and ready to use system. The installation and execution of version (HylaFAX v4.0pl2) was tested on the following x86-based systems. - Clone i486DX33 running Altos/SCO Open Server Enterprise Ver. 3.0aC0 To install and run HylaFAX v4.0 you need the following ressources on your system: - You MUST have TCP/IP installed. - a minimum free diskspace of 10 MB on the /usr filesystem + room for faxes use df(1) to check this out; - a minimum free diskspace of 10 MB on the /tmp filesystem while running ftp and unpacking the distribution; - the ability to become root to install the package; In addition there is some public available software necessary to run HylaFAX on your computer. You need a ghostscript binary with a tiffg3 driver and the ghostscript fonts. A binary for gs5.10 is available from ftp://ftp.sgi.com/sgi/fax/binary/INSTALL-gs510-sco3.2v4.2 ftp://ftp.sgi.com/sgi/fax/binary/gs5.10-sco3.2v4.2-tar.gz Fonts are available from ftp.cs.wisc.edu. ftp://ftp.cs.wisc.edu/ghost/aladdin/gs510/ghostscript-fonts-std-5.10.tar.gz ftp://ftp.cs.wisc.edu/ghost/aladdin/gs510/ghostscript-fonts-other-5.10.tar.gz You need a binary of gzcat. If you don't have it, get a copy from ftp://ftp.sco.com/Skunk1/CD-ROM/bin/gzcat gzcat is under the GNU Public License. The source for it could be retrieved by ftp from prep.ai.mit.edu. Ghostscript 5.10 source can be retrieved by ftp from ftp://ftp.cs.wisc.edu/ghost/aladdin/gs510/ghostscript-5.10.tar.gz GETTING THE DISTRIBUTION PACKAGE The package is available for free from ftp://ftp.sgi.com/sgi/fax/binary/hylafax-sco3.2v4.2-v4.0pl2.cpio.gz If you retrieve the package from any ftp-server you should check the sum(C) or the MD5 value of the package: The correct values are: sum(C): 54652 7625 hylafax-sco3.2v4.2-v4.0pl2.cpio.gz MD5 (hylafax-sco3.2v4.2-v4.0pl2.cpio.gz) = 70265d6dafac904961abaed5d1584798 INSTALLING/UPDATING THE DISTRIBUTION To install the image hylafax-sco3.2v4.2-v4.0pl2.cpio.gz do the following steps as root: IMPORTANT: If upgrading from a previous binary do the following 6 things FIRST. 1. Disable any tty that has faxgetty running on it. 2. Stop Hylafax ( # sh /etc/init.d/hylafax stop ) 3> Remove the symbololic links. ( # cd /usr/local/HylaFAX-v4.0 ; sh remove.links ) 4. If you have made modifications to lib/faxcover.ps save a copy. 5. If you have made modifications to spool/etc/hosts save a copy. 6. Run the following 2 commands # cd /usr/local/HylaFAX-v4.0/spool # find docq doneq log pollq recvq sendq status -user 0 -exec chown fax {} \; IMPORTANT: If upgrading from the v4.0pl0 binary do the following Remove all files in /usr/local/HylaFAX-v4.0/man/cat.LOCAL (# rm -fr /usr/local/HylaFAX-v4.0/man/cat.LOCAL) OK, now you are ready. # cp hylafax-sco3.2v4.2-v4.0pl2.cpio.gz /tmp # cd / # gzcat /tmp/hylafax-sco3.2v4.2-v4.0pl2.cpio.gz | cpio -idvaum # rm /tmp/hylafax-sco3.2v4.2-v4.0pl2.cpio.gz This will install the sco3.2v4.2 binary distribution of HylaFAX under: /etc/init.d/hylafax /etc/rc2.d/S80fax /etc/rc0.d/K80fax /usr/local/HylaFAX-v4.0/... /usr/local/share/ghostscript/fonts/... No other parts of your system will be touched during this step of installation This HylaFAX distribution was compiled with the following configuration parameters: [ 1] Directory for applications: /usr/local/HylaFAX-v4.0/bin [ 2] Directory for lib data files: /usr/local/HylaFAX-v4.0/lib [ 3] Directory for lib executables: /usr/local/HylaFAX-v4.0/slib [ 4] Directory for system apps: /usr/local/HylaFAX-v4.0/sbin [ 5] Directory for manual pages: /usr/local/HylaFAX-v4.0/man [ 6] Directory for HTML documentation: /usr/local/HylaFAX-v4.0/html [ 7] Directory for spooling: /usr/local/HylaFAX-v4.0/spool [ 8] Directory for font metrics: /usr/local/share/ghostscript/fonts [ 9] Directory for uucp lock files: /usr/spool/uucp [10] Uucp lock file scheme: -ascii [11] PostScript imager package: gs [12] PostScript imager program: /usr/local/bin/gs [13] Manual page installation scheme: sysv-source-cat [14] Default page size: North American Letter [15] Default vertical res (lpi): 98 [16] Location of getty program: /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/HylaFAX-v4.0/tiffbin Several of the above pathnames are compiled into applications included in this binary distribution. If any of these pathnames are unacceptable, your only options are to create a symbolic link to the installed directory hierarchies or retrieve the HylaFAX source distribution and recompile from scratch. Some of the above parameters can however be changed by editing various configuration files, see also config(4F). 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 hylafax(1) and hylafax(4F) for introductory information on the client applications and the server setup, respectively. In order to run HylaFAX you need 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 or must be an internal modem card and you have to know, to which port (e.g. tty011) it is connected. For the modem-configuration part of the installtion you must 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 guru or consult the documentation that comes with your modem (don't buy a modem without documentation.) If you don't have any of these (documentation or 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 (see below). You should consult the FAQ of HylaFAX before asking questions already answered. The system must be configured to NOT run a getty or something other on the tty port where the fax software is configured. It is a good idea to first checkout your port with a terminal emulation program (e.g. kermit or cu) to test the modem and the name of the tty. If the modem is properly connected to your computer login as root and run faxsetup(1M): # sh /usr/local/HylaFAX-v4.0/sbin/faxsetup Here is the log of the messages, questions and answers during faxsetup and faxaddmodem. At any time you might safely interrupt faxsetup or faxaddmodem without causing any problems. Users upgrading from pl0 or pl1 will see fewer messages from faxsetup. Users upgrading from pl0 or pl1 do not need to run faxaddmodem. Setup program for HylaFAX (tm) v4.0. Created for i486-unknown-sco3.2v4.2 on Mon Feb 23 19:44:59 PST 1998 Checking system for proper client configuration. Checking system for proper server configuration. Warning: /bin/vgetty does not exist or is not an executable program! The file: /bin/vgetty does not exist or this file is not an executable program. The HylaFAX software optionally uses this program and the fact that it does not exist on the system is not a fatal error. If the program resides in a different location and you do not want to install a symbolic link for /bin/vgetty that points to your program then you must reconfigure and rebuild HylaFAX from source code. Warning: /bin/egetty does not exist or is not an executable program! The file: /bin/egetty does not exist or this file is not an executable program. The HylaFAX software optionally uses this program and the fact that it does not exist on the system is not a fatal error. If the program resides in a different location and you do not want to install a symbolic link for /bin/egetty that points to your program then you must reconfigure and rebuild HylaFAX from source code. You do not appear to have a "fax" user in the password file. HylaFAX needs this to work properly, add it [yes]? Warning: No hylafax service entry found! No entry was found for the hylafax service in the YP/NIS database or in the /etc/services file. The software should work properly without one (except if you want to start hfaxd from inetd), but you will see warning messages whenever you run a HylaFAX client application. If you want to manually add an entry the following information should be used: hylafax 4559/tcp # HylaFAX client-server protocol Should a hylafax entry be added to /etc/services [yes]? yes Warning: No snpp service entry found! No entry was found for the Simple Network Paging Protocol (SNPP) service in the YP/NIS database or in the /etc/services file. The software should work properly without one (except if you want to start hfaxd from inetd), but you will see warning messages whenever you run the HylaFAX sendpage program. If you want to manually add an entry the following information should be used: snpp 444/tcp # Simple Network Paging Protocol Should an snpp entry be added to /etc/services [yes]? yes There is no entry for the hylafax service in /etc/inetd.conf. The HylaFAX client-server protocol process can be setup to run standalone or started by the inetd program. A standalone setup is preferred for performance reasons, especially if hfaxd is to support multiple protocols (e.g. SNPP); however it may require manual setup if your operating system does not have a System-V style init program. Should an entry be added to /etc/inetd.conf [no]? no There does not appear to be an entry for the FaxMaster either in the YP/NIS database or in the /usr/mmdf/table/alias.user file. The FaxMaster is the primary point of contact for HylaFAX problems. The HylaFAX client-server protocol server identifies this alias as the place to register complaints and HylaFAX directs automatic mail messages to this user when problems are identified on a server machine or when the routine server maintainence scripts are run (e.g. faxcron). Should an entry be added for the FaxMaster to /usr/mmdf/table/alias.user [yes]? yes Modem support functions written to /usr/local/HylaFAX-v4.0/spool/etc/setup.modem. Configuration parameters written to /usr/local/HylaFAX-v4.0/spool/etc/setup.cache. No scheduler config file exists, creating one from scratch. Country code [1]? Area code []? Your Area Code Long distance dialing prefix [1]? International dialing prefix [011]? Dial string rules file (relative to /usr/local/HylaFAX-v4.0/spool) ["etc/dialrules"]? Tracing during normal server operation [1]? 11 Default tracing during send and receive sessions [0xffffffff]? 11 Continuation cover page (relative to /usr/local/HylaFAX-v4.0/spool) []? Timeout when converting PostScript documents (secs) [180]? Maximum number of concurrent jobs to a destination [1]? Define a class of modems []? Time of day restrictions for outbound jobs ["Any"]? Pathname of destination controls file (relative to /usr/local/HylaFAX-v4.0/spool) []? Timeout before purging a stale UUCP lock file (secs) [30]? Max number of pages to permit in an outbound job [0xffffffff]? 25 Syslog facility name for ServerTracing messages [daemon]? local0 The non-default scheduler parameters are: LogFacility: local0 CountryCode: 1 AreaCode: xxx LongDistancePrefix: 1 InternationalPrefix: 011 ServerTracing: 11 MaxSendPages: 25 SessionTracing: 11 Are these ok [yes]? Creating new configuration file /usr/local/HylaFAX-v4.0/spool/etc/config... Restarting HylaFAX server processes. Should I restart the HylaFAX server processes [yes]? yes You do not appear to have any modems configured for use. Modems are configured for use with HylaFAX with the faxaddmodem(1M) command. Do you want to run faxaddmodem to configure a modem [yes]? yes Serial port that modem is connected to []? ttyy1H Ok, time to setup 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. Reading scheduler config file /usr/local/HylaFAX-v4.0/spool/etc/config. No existing configuration, let's do this from scratch. <... modem specific part deleted ...> Creating new configuration file /usr/local/HylaFAX-v4.0/spool/etc/config.ttyy1H Creating fifo /usr/local/HylaFAX-v4.0/spool/FIFO.ttyy1H for faxgetty... done. Done setting up the modem configuration. Checking /usr/local/HylaFAX-v4.0/spool/etc/config for consistency... ...everything looks ok; leaving existing file unchanged. Don't forget to run faxmodem(1M) (if you have a send-only environment) or configure init to run faxgetty on ttyFN01. Do you want to run faxaddmodem to configure another modem [yes]? no You do not appear to be using faxgetty to notify the HylaFAX scheduler about new modems and/or their status. This means that you must use the faxmodem program to inform the new faxq process about the modems you want to have scheduled by HylaFAX. Should I run faxmodem for each configured modem [yes]? no Done verifying system setup. Additionnally you may reconfigure any other type of modem later with faxaddmodem(1M). Note: If the faxaddmodem(1M) script seems to hang, interrupt it and restart it with -s option: # sh /usr/local/HylaFAX-v4.0/sbin/faxaddmodem -s 38400 MAKE SYMBOLIC LINKS Go into /usr/local/HylaFAX-v4.0 and run make.links. This will make links to the user programs and the man pages. # cd /usr/local/HylaFAX-v4.0 # sh make.links HOW TO STARTUP THE FAX DAEMONS The faxq and hfaxd daemons are started at boot by /etc/rc2.d/S80fax To start the daemons without rebooting the system simply do as root: # sh /etc/rc2.d/S80fax start (this was done by faxsetup) GETTY RELATED CHANGES (if upgrading from pl0 or pl1 you can skip this) The fax daemon process is capable of distinguishing between fax and data-calls. If you want to provide "Login:" on data-calls you need to do the following steps: Change the GettyArgs: value in your modem config file. This file was created by faxaddmodem and the name is something like +++++++++++++++++++++++++++++++++++++++++++ /usr/local/HylaFAX-v4.0/spool/etc/config. GettyArgs: "-t 60 -h %l dx_%s" Add the gettydefs entries from /usr/local/HylaFAX-v4.0/gettydefs to the end of /etc/gettydefs. # cat /usr/local/HylaFAX-v4.0/gettydefs >>/etc/gettydefs. Change the entry in /etc/inittab for the tty you use. Example: I use ttyy1H so the line in /etc/inittab looks like this. y1H:234:respawn:/usr/local/HylaFAX-v4.0/slib/faxgetty ttyy1H You may want to also edit your /etc/conf/init.d/??? file so the changes will remain the next time you rebuild the kernel. ONLINE HTML DOCUMENTATION You can allways contact the HylaFAX Home Page at http://www.vix.com/hylafax/ if you want access to the online documents. All HTML material is also provided with the binary distribution. If you're running a http-daemon on your system you may configure your daemon to use the installed html documents. Add the following alias-definitions to your httpd-config files: Alias /hylafax/ /usr/local/HylaFAX-v4.0/html/ ScriptAlias /hylafax-cgi-bin/ /usr/local/HylaFAX-v4.0/cgi-bin/ SYSLOG CHANGES I made some changes to my /etc/syslog.conf so I could have the fax stuff in a seperate files. First I created the directory /usr/adm/log Then I modified /etc/syslog.conf to look like this. ----------- # @(#)syslog.conf local0.emerg /usr/adm/log/local0.emergency local0.alert /usr/adm/log/local0.alert local0.crit /usr/adm/log/local0.critical local0.err /usr/adm/log/local0.err local0.warning /usr/adm/log/local0.warning local0.notice /usr/adm/log/local0.notice local0.info /usr/adm/log/local0.info local0.debug /usr/adm/log/local0.debug *.notice;mail.info /usr/adm/log/notice *.crit /usr/adm/log/critical kern,mark.debug /usr/adm/log/kern kern.err /usr/adm/log/kern.err *.info,*.debug /usr/adm/syslog *.emerg * *.alert;auth.warning /usr/adm/log/auth ----------- Then I restarted my syslogd. TESTING To test your installation once you've configured your fax server and modem, startup the fax server as shown above and then log out as root and log in again as a "normal" user. First check with faxstat(1) to make sure the server is running: $ faxstat -s the hfaxd(1M) daemon should respond with something like: $ faxstat -s HylaFAX scheduler on trrsco: Running Modem ttyy1H (+1.xxx.xxx-xxxx): Running and idle $ then send a short fax (change +123456789 below to the number of a nearby fax machine): $ sendfax -n -d +123456789 <