INSTALLATION:

Installing the Qfax utilities is not exactly a trivial process.  It
involves numerous steps which should be followed carefully, so don't
expect to get this up and running properly in much less than half an
hour.  I suggest printing out this file and going through the process
with the printout in hand, to ensure that nothing gets left out or
mistyped.

You will, first of all, need a CLEAN source distribution of efax (i.e.
with no patches applied to it), either 06a or 06b.  Version 06a is
available from sunsite.unc.edu as /pub/Linux/apps/comm/efax06a.tar.gz.

WARNING: Installing the Qfax utilities requires patching efax and its
script file, fax.  You should make backup copies of both of these
files before proceeding.


<<< 1. Create a fax user >>>

Efax has to be able to read and write UUCP-style lock files.  With
traditional efax this is not a problem because it's typically run by
root, but in a multi-user environment where efax is used as a server
it needs to have a designated userid with appropriate permissions.
Making it setuid root would work, but gives it far more permission
than it really needs, presenting a possible security hole.  A better
solution is to make it setuid uucp.

To do this, first make certain you have a uucp UID in your /etc/passwd
file.  You should have a line something like:

	uucp:*:5:7:Fax/UUCP Agent:/usr/lib/uucp:/bin/false

In this example, the uucp user has a UID of 5 and a GID of 7, but
these numbers may well be different on your machine.

Now edit your /etc/passwd file and add a line AFTER the uucp entry,
defining a fax user to have the same UID as uucp, and GID uucp:

	fax:*:5:7:Fax Agent:/usr/spool/fax:/bin/false

Note that this last step is just cosmetic; as far as Linux is
concerned users fax and uucp are synonymous.  The advantage to doing
this is readability in scripts and such.


<<<  2. Create a mail alias for FaxMaster  >>>

Since you're now thinking of using efax as a server, efax has to send
its messages to a designated "FaxMaster", in the same way that mail
programs direct messages to a "postmaster".  To do this, edit your
mail aliases file, wherever it happens to be.  Some likely places you
might find it are "/usr/local/lib/smail/aliases", "/usr/lib/aliases",
or "/etc/aliases".  Depending on your setup it may be in a different
place.

Simply append a line such as:

	FaxMaster: root

to have all mail to the FaxMaster directed to root, or 

	FaxMaster: some-user-name

to have it sent to "some-user-name".

When you're done, run newaliases (or mkaliases) to have your mailer
reconstruct the mail alias database.


<<<  3. Create an e-mail-to-fax gateway  >>>

Your mailer now has to be told how to read addresses of the form
"person@company.fax" and redirect these letters to Qfax instead of
trying to mail them.  The exact procedure varies depending on whether
you use sendmail or smail as your mailer.  [ These redirections are
based on the mailfax shell scripts by Rick Lyons. ]

*** If you use sendmail:

Edit your sendmail configuration file (sendmail.cf) and add the
following mailer definition:

	Mfax, P=/usr/local/bin/qfax, F=DFMhu, M=100000,
	      A=qfax

Now add the following address-rewriting rule to rule set 0:

	# forward fax messages to Qfax
	R$+<@$+.fax>	$#fax $@ $2 $: $1	user@host.fax


*** If you use smail:

If you do not have a "/usr/local/lib/smail/transports" file, create
one.  Now add the following line to it:

	fax: driver=pipe, local; user=fax, cmd="/usr/local/bin/qfax"

If you do not have a "/usr/local/lib/smail/routers" file, create one.
Add the following line to it:

	fax: driver=queryprogram, transport=fax;
	     cmd="/usr/bin/expr ${lc:host} : '.*\.fax$'"

If you did not already have a routers file, you must also include the
default routing info:

	inet_addrs: driver=gethostbyaddr, transport=smtp;
		    fail_if_error, check_for_local,
	inet_hosts: driver=gethostbyname, transport=smtp;
		    -required, -domain, -only_local_domain,
	paths: driver=pathalias, transport=uux; file=paths,
		      proto=bsearch, optional, -required, domain=uucp,
	uucp_neighbors: driver=uuname, transport=uux;
			cmd=/usr/bin/uuname, domain=uucp,
	smart_host: driver=smarthost, transport=uux; -path,


<<<  4. Create a spool directory for faxes >>>

You'll need to designate a place to store incoming and outgoing faxes
in the same way that mail and news programs need a spool area.  I
recommend making a "/usr/spool/fax" directory, and within that, create
these directories (use "chown uucp.uucp <directory>" to make sure Qfax
and efax can read and write to them):

	/usr/spool/fax/recvq

This is where incoming faxes will be stored, along with their log
files, to be dealt with by the FaxMaster.  If you want all users to be
able to read incoming faxes, you should use chmod to set the
permissions on this directory to 664, otherwise set it to 660.

	/usr/spool/fax/sendq

This is where outgoing faxes will be stored while they wait to be sent
out.  Qrun will look in here for faxes to send.  Its mode should be
set to 660.

	/usr/spool/fax/docq

This is a storage directory for inactive faxes.  Qrun uses it to store
faxes which it couldn't send properly, but you can also use it
yourself to store faxes indefinitely.  This directory should be
accessible to all, i.e. mode 666.

	/usr/spool/fax/log

This is where all send logs are written.  Generally, this is private
to the FaxMaster, and should be set to mode 660.

Note that if you don't choose to use the directories I've specified
above, you'll have to make changes in step 7 to config.h, where these
directories are defined.


<<<  5. Unpack the Qfax sources  >>>

You should unpack the entire Qfax distribution in the directory where
you keep your efax sources.  The Makefile which comes with Qfax also
rebuilds and reinstalls efax, so the two packages get along quite
well.

To do this, move the archive file qfax1.0.tar.gz to the efax source
directory and type:

	zcat qfax1.0.tar.gz | tar xvf -


<<<  6. Create a master directory for fax configuration files  >>>

You'll need to create a directory (e.g. "/conf/fax") for Qfax to store
its configuration information in.  You could just as easily use
"/etc", but that leads to a cluttered mess after awhile; far better to
be organized from the start.

Into this directory you should copy the following files from the Qfax
distribution:

	fax.rc
	fax.db
	cover-template.ps


<<<  7. Configure Qfax for your site's needs  >>>

Edit the file "config.h" to your liking.  In most cases the default
options should suffice; the comments explain the options fairly
clearly.


<<<  8. Apply patches to efax  >>>

Qfax will work just fine with efax 06a or 06b, but if you want to
apply any special patches, now's the time.  This package contains the
06a-06b patch, as well as a couple of minor patches which purport to
improve efax in various ways; have a look at them and determine for
yourself whether you want to install them or not.

If you have efax 06a and want to upgrade it to 06b
(efax.06a-06b.patch), you can do so now by typing:

	make patch-06b

If you want to apply the buffer-size estimation patch
(efax.buffer.patch), type:

	make patch-buffer

If you want to apply the error-capping patch (efax.errcap.patch),
type:

	make patch-errcap

In any case, you MUST install the "efax.qfax.patch" and
"fax.qfax.patch" files in order for fax, efax and Qfax to get along.
To do this, type:

	make patch-qfax


<<<  9. Edit the fax.rc file  >>>

Change directories now to the "configuration directory" you set up in
step 6.  The fax.rc file contains configuration information which is
not compiled into Qfax or efax--you can change it at any time.  It
allows you to define the format and fonts used on your site's cover
pages, your company address, page sizes, and so on.  The comments in
the file provided should be clear enough to help you set up values for
your site.


<<<  10. Create fax.db and ~/.fax files >>>

Qfax uses a phonebook-style database to look up fax information about
a recipient  (see qfax.phonebook(1) for more details).  The master
(site-wide) phonebook is fax.db, while each user can have his own
phonebook in his home directory as a .fax file.  The phonebook
database is presently quite simple and naive, and in future versions I
intend to improve it considerably.  The format of entries in both
files is identical:

	<company-alias>		<full-company-name>
	<voice-phone-number>
	<fax-phone-number>
	<person-1-alias>	<person-1-full-name>
	<person-2-alias>	<person-2-full-name>
		. . .
	<person-n-alias>	<person-n-full-name>
	+

Each entry MUST conform to this format, leaving empty lines for items
which do not apply.  Each entry is terminated by a '+' on a new line.
As an example:

	megacorp	MegaCorp International
	1.212.555.1212
	1.212.555.2121
	john	John Q. Smith, Vice-President
	+
	microcorp	MicroCorp Inc.

	1 (212) 555-4321
	jane	Jane Doe
	john	John Q. Public
	+

In this example, note that we don't have a voice phone number for
MicroCorp, so we leave that line empty (i.e. just '\n').  There is no
limit to the number of contact people at any given company, but there
MUST be at least one at each company.  In this way, mail to
"john@megacorp.fax" would send a fax to John Q. Smith at MegaCorp
International, and "jane@microcorp.fax" would send a fax to Jane Doe
at MicroCorp.

Note that the format for phone numbers is not rigid; Qfax ignores all
non-digit characters when it reads a phone number, so you can include
spaces, dashes, or parentheses as you see fit to make it readable.
However, you MUST include all necessary digits (i.e. a leading "1" or
"0" if it's a long-distance number).  Qfax isn't terribly bright when
it comes to determining whether a phone number is long-distance or
not, so make sure all the necessary digits are there.  Similarly, if a
phone number is local, do NOT include any unnecessary digits (i.e.
area codes, city codes, etc.).  Qfax will be sending this series of
digits to the modem as a dialstring, so just think in those terms when
deciding how to phrase a number.

The master directory (fax.db) should be stocked by the FaxMaster with
commonly used names and sites.  The "~.fax" phonebooks should be
created by each user to suit her personal needs.  Qfax searches the
user's personal directory first (if it exists), and then searches the
master directory if the recipient could not be found, so for sites
where a single phonebook is desirable, the master directory can be
used.


<<<  11. Edit the Makefile  >>>

Just make sure the configurable options at the top of the Makefile are
to your liking.  Mostly this just involves making sure the pathnames
and compiler options are correct for your system.


<<<  12. Build everything and install it  >>>

Typing "make install" will cause everything (including efax) to be
built and installed.  Note that all of the Qfax files and efax are
owned by uucp, of group uucp, and setuid uucp.  This is necessary in a
server-style arrangement, don't be alarmed.


<<<  13. Make an entry in a crontab file  >>>

In order to process the outgoing fax queue at regular intervals,
you'll have to invoke Qrun through cron, at, or something similar.
For instance, to process the queue every 15 minutes, you'd need a
crontab entry like:

	# Process the fax spool
	0,15,30,45 * * * * /usr/local/bin/qrun

To process it only once a day at midnight, try:

	# Process the fax spool
	0 0 * * * /usr/local/bin/qrun

See the man pages for cron and crontab for more details.

Ideally this should be done in fax's (or uucp's) crontab, since the
jobs should be run by that UID.  However, you can put it in root's
crontab instead if you wish.


<<<  14. Make an inittab entry for efax  >>>

Qfax assumes that you will be using "fax answer" to monitor the line
when you're not sending faxes, so you should make sure that your
"/etc/inittab" includes a line like:

	s1:56:respawn:/bin/sh /usr/local/bin/fax answer


<<<  15. Sign on to the mailing list  >>>

Well, strictly speaking this is an optional step :)  Now that you're
effectively done, you might want to put yourself on the Qfax mailing
list to keep yourself apprised of updates and bug fixes.

To subscribe, send email to qfax-request@renaissoft.com, with the word
"subscribe" in the subject field; the body of the message is ignored.
To post to the list itself, send your post to qfax@renaissoft.com.

If you encounter problems getting things to look right or work
properly, the mailing list is the place to ask your questions, and to
share your thoughts with other Qfax users.
