Instructions for installing Z-Fax


You will need approximately 10 megabytes of available disk space to
install Z-Fax.  You will also need your Z-Fax activation key to do a
full installation.

There are various components to Z-Fax that need to be installed; you
may or may not want to install all of them at the same time.  If your
fax modem is installed on the same machine you are going to use to send
and received faxes, then you should install everything on the same
machine.  If you have a network of users that are going to send and
receive (view) faxes, then only certain components need to be installed
on their machines.  The following is a list of all the components and
how they are used:

zfax
    This program is the Z-Fax graphical user interface.  Install
    this program wherever your users will be using a graphical
    environment to access Z-Fax.

netfaxq
    The network fax server.  This utility listens for connections from
    Z-Fax clients, and services queue requests for outgoing faxes or
    queue listings.  This way, users on machines all over the network can
    send faxes without having to be logged into the machine that has the
    fax modem.

zfaxd
    The program that takes outgoing faxes out of the queue, and invokes
    the transmission program to actually send the fax.  This only needs
    to be installed on the Z-Fax server, where the fax modem(s) are
    installed.

queuefax
    The utility which places outgoing fax requests on the fax queue.
    This utility handles both network and local queueing, so it should
    be installed on all machines.  Other queue utilities, dequeuefax,
    listqueue, and requeuefax, should be links to queuefax.

buildfax printfax faxit
    These utilities comprise the command-line interface to Z-Fax, used
    for building, printing, and sending faxes.

faxmail mailfax
    The link between Z-Fax and electronic mail.

fax-send fax-recv c2send c2recv c2test
    The scripts and programs that handle transmission and reception of
    fax documents through a Class 2 fax modem.

gs and the Ghostscript library
    gs is the Ghostscript program, a Postscript language interpreter
    used by Z-Fax to convert Postscript and ASCII text files into fax
    files.  The Ghostscript library contains initialization files,
    some Ghostscript documentation, and font files.


Installation Process

The tape extraction process is different from the software installation
procedure.  Depending on the complexity of your network and the location
of your tape drive, you may need to extract software from tape first,
move it to the target machine, then do an install.  If you use NFS to
mount file systems from different computers, the remote installation
process is much easier.

Note: to install the software, you will eventually have to be "root".
However, you don't have to be root just to extract the software from
tape.  You may wish to wait before becoming root if you are using
remote host tape extraction.


1.  cd to any directory that has at least 10 megabytes of space and has
    permissions that will allow you to create a new subdirectory.  The
    tape contains files in "tar" format, and will extract everything
    into a new subdirectory named zfax.<system> where <system> is the
    type of computer you are running on, such as sgi, sco, sun4, etc.
    This is not the installation directory -- the installation will move
    files and directories out of this location into the appropriate
    location on the disk.


2.  Extract the Z-Fax files from the tape:

    a) If you're using a local tape drive:
	     % tar xv
	If your default tape drive is not the default drive, you may need
	to specify the device name:
	    % tar xvf /dev/tape-device
	Replace "tape-device" with the device name of the tape drive
	associated with the media you have (tape, floppy, DAT, etc).

    b) If you're using a tape drive over the network:
	    % rsh machine dd if=/dev/tape-device | tar fxv -
	Note: You may have security problems with accessing a remote
	      machine; see your system admin manual if you have problems.

    If "tar" fails to create a directory due to permissions or disk
    space problems, you should either change users to an appropriate
    account (root) or move to another file system that has more space.
    You should remove whatever it created so far so as not to waste
    more disk space.


3.  The "tar" command should have extracted the zfax.<system> directory
    at this point.  cd into this subdirectory:

	cd zfax.sgi (for example)

    You should see the following files:
    % ls -F
    Ghostscript/   Manual         bin/           lib/           register.sh*
    INSTALL        RELNOTES       doinstall.sh   man/

    The tape extraction is now complete and you are ready to install the
    software.  If you have extracted the distribution to a temporary
    machine where you do not want to install the software, then you must
    copy the data to the desired machine(s).


4.  Begin the installation process by giving the command:
    (Here is where you need to su to root.)

	 sh doinstall

    This utility will create Z-Fax-related directories, and move the
    Z-Fax files into those directories.  You will be given the opportunity
    to override the default directories where Z-Fax installs its files.

    If your distribution contains both the client and server portions
    of Z-Fax, doinstall will allow you to install either portion alone,
    or both together.

    The Z-Fax server consists of the queue manager, network queue interface,
    and modem drivers.  The Z-Fax client consists of the graphical user
    interface, command-line utilities, Postscript interpreter and fonts,
    and the client portion of the network queue interface.


5.  After the Z-Fax files and utilities have been installed, you will be
    asked for your Z-Fax activation key, and be given the opportunity to
    register users.

    Each activation key you receive enables a single computer to have a
    certain number of users depending on the term of your license.  This
    script will enable you to register licensing information on more than
    one host and store multiple host/user information in a single license
    database.

    The database consists of the following file:

        /usr/lib/Zfax/license/license.data  --the file Z-Fax uses

    This program will help you to create and/or edit license.data.

    Since this file contain information about multiple hosts, the same
    file can be replicated among all the hosts where Z-Fax will be used.
    You can do this using rcp, ftp, or by using NFS mounting techniques.
    Replicating the file simplifies system administration for sites where
    file sharing is easy.

    For sites that have many system administrators or remote machines that
    are not well connected, you may want to maintain a separate database
    for each host.  If this is the case, run this script separately while
    logged in to the other (remote) machines.
 
    If you have only one or two machines and a short list of users, or if you
    are unfamiliar with text file editing in UNIX, you may prefer to register
    each machine interactively by using "zfax -register"  This is a simpler
    but potentially more time-consuming way to register your users.


6.  Once Z-Fax has been installed, you will need to set up the Z-Fax
    configuration.  If you are using the X Window interface to Z-Fax,
    give the command:

	 zfax

    Bring up the Z-Fax Send window (it startes out as an icon).  From the
    menu bar, select Options --> Configuration.  Alter the settings as
    desired, then press the Save button to write the settings to the
    configuration file.  The configuration items control various aspects of
    the Z-Fax fax spooling system, such as how failed faxes are handled,
    how received faxes are delivered, and what times off-peak faxes are
    transmitted.  See the Z-Fax manual for details on what each item does.

    Anyone can view the configuration information, but you must be
    logged in as root to change and save any of the settings. Changes
    made in the window do not take effect until the changes are saved
    by pressing the Save button, and the fax queue manager "zfaxd" is
    stopped and restarted.

    If you are not using the X Window interface, you will need to edit the
    configuration file /usr/lib/Zfax/config directly, using vi or another
    text editor.


Setting up the Z-Fax server

1.  The Z-Fax server listens on the network for requests to send faxes.
    This program must have a network "port number" associated with it.
    To select a network port number, choose one that is not currently
    in use.  A safe number to use is usually in the range of 2000 to 2500;
    check the file /etc/services to find out what ports are in use on your
    network.

2.  Add the following line to your /etc/services file:

         zfax   2066/tcp		# Z-Fax Network Server

    Replace "2066" with another network port number if you need or want to.

3.  Add the following line to your inetd.conf file.  Depending on your
    operating system, this file will be in the directory /etc or /usr/etc:

         zfax   stream   tcp   nowait   root   /usr/lib/Zfax/bin/netfaxq

4.  Use the ps command to find the process number of your inetd daemon.
    For example:

	 ps -ae | grep inetd

    The actual arguments to "ps" differ among different unix systems.
    (BSD-derived unix systems like SunOS use "ps aux".)  Identify the
    process id (pid) of the inetd process.

5.  Signal your inetd daemon to re-read the modified configuration files
    by sending it a SIGHUP signal.  For example:

	 kill -1 <pid>

    Replace <pid> with the process number of your inetd process obtained
    in step 4.

    Your computer's inetd daemon will now automatically execute the Z-Fax
    utility /usr/lib/Zfax/bin/netfaxq to service fax queue requests arriving
    from Z-Fax clients.

6.  To verify the Z-Fax server is working correctly, go to a client
    computer and execute the command "listqueue."  You should receive
    the message "The fax queue is currently empty."  This message verifies
    that the client and server have been properly configured and are
    working correctly.

To set up Z-Fax clients, check the "configuration" procedure discussed
earlier to make sure the machine name acting as the fax server name and
the port number fields match the changes you made in /etc/services.

Note: An alternative to setting the host and port in the Z-Fax
configuration file, you can also use the environment variable
ZFAXSERVER to specify a server name and port number.  ZFAXSERVER should
be set to <name>:<port>, where <name> is the name of the server
computer, and <port> is the port number assigned to Z-Fax.  For
example, if the server computer is "zindigo" and the port number is
2244, ZFAXSERVER should be set to "zindigo:2244".  The ZFAXSERVER
variable will take precedence over any predefined host and port
configuration settings.


Setting up the Z-Fax queue manager

The Z-Fax queue manager "zfaxd" is the program that takes outgoing
faxes out of the queue, and invokes the transmission program to
actually send the fax.  Normally, zfaxd is started at system boot in
one of the /etc/rc files.  zfaxd requires at least one argument:
one or more device names to which your fax modems are connected.
For example, if you have one fax modem connected to the serial device
named /dev/ttyd2, your zfaxd startup command would be:

     zfaxd /dev/ttyd2 &

If you have more than one fax modem, add the corresponding device names
to the end of the command.

To specify send-only without receiving faxes, use the -norecv flag.
Using the example from above, this would be:

     zfaxd -norecv /dev/ttyd2 &

Different variants of UNIX require startup commands to be placed in
different places.  On Sun systems, place the above command at the end
of the /etc/rc file.  On SCO UNIX and SGI systems, place the command in
a separate file named "S99Zfax" in the directory /etc/rc2.  On other
systems, consult your system administration documentation.


Removing Z-Fax

To remove the Z-Fax software from your system:

1. If you have installed the Z-Fax server, remove the zfaxd command
   from your /etc/rc file or /etc/rc.2 directory, and remove the
   zfax line from your /etc/services and inetd.conf files.

1. Delete the directory /usr/lib/Zfax (or the Z-Fax library directory
   you specified during the installation) and its contents.

2. Delete the directory /usr/lib/Ghostscript (or the Ghostscript library
   directory you specified during installation) and its contents.

4. Delete the directory /usr/spool/fax (or the spool directory you
   during installation) and its contents.

5. Remove the following files from /usr/local/bin, or the directory you
   specified during installation to contain the executable files:

	buildfax
	c2recv
	c2send
	c2test
	dequeuefax
	fax-recv
	fax-send
	faxit
	faxmail
	listqueue
	mailfax
	netfaxq
	printfax
	queuefax 
	requeuefax
	zfax
	zfaxd


Checking your Class 2 fax modem

Z-Fax provides a utility "c2test" to verify the operation of your fax modem.
To test the modem, enter the command "c2test <device>" where <device> is
the device name to which your fax modem is attached.  c2test will then report
whether it was able to verify the connection to your modem.  c2test does
*not* check whether a phone line is hooked up to the modem.


Troubleshooting

Here are some things to check when Z-Fax doesn't behave the way we say
or the way you think it should:

The fax queue is very sensitive to permissions. Be sure file and directory
ownership and permissions are set EXACTLY as follows:

    The incoming and outgoing spool directories (set by TRANSMIT_DIR and
    RECEIVE_DIR in the configuration file) must be owned by and in group
    "uucp", and have permissions of 775.

    The programs zfaxd and queuefax must be in group "uucp" and have the
    set-group-ID permission turned on.

    The program c2test must be owned by and in group "uucp", and have both
    the set-user-ID and set-group-ID permissions turned on.

    The serial devices used for the fax modems must be readable and
    writable by either user or group "uucp".

To perform the fax server tasks, netfaxq executes the queuefax, dequeuefax,
listqueue, and requeuefax utilities.  Therefore, the directory into which
you installed these files during the installation process must be in the
command search path when netfaxq is invoked by inetd.  If you are having
trouble getting the server to respond, make sure that /usr/local/bin, or
the directory you selected, is in the search path when inetd is started.

Z-Fax uses Ghostscript utility "gs" to convert ASCII text and Postscript to
fax format.  If Z-Fax is reporting errors when attempting to convert files,
be sure that "gs" is in your command search path.  If you specified a
Ghostscript library directory other than /usr/lib/Ghostscript, be sure
the environment variable GS_LIB is set to the new directory.
