INSTALLATION (Qfax 1.3):

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.

NOTE: This version of Qfax includes the patched sources for efax 0.7a.
i.e. NO PATCHING OF EFAX IS NECESSARY.  If you want to find the virgin
0.7a sources for efax, they can be found at available from
sunsite.unc.edu and its mirrors as /pub/Linux/apps/comm/fax/efax07a.tar.gz.


<<< 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. ]

IMPORTANT NOTE: This version of Qfax doesn't understand multi-part
MIME mail (i.e. mail with attachments).  This is because the way
multi-part headers are written confuses Qfax.  If you use a
MIME-capable mailer (e.g. pine, Eudora, etc.), be sure not to include
any attachments if you intend to use the mail-to-fax gateway.

****** If you use sendmail (8.6.x):

The first thing you'll have to do is make a couple of minor changes to
your /etc/sendmail.cf file.

As you're doubtless aware if you've poked around in a sendmail.cf
file, there are two things you have to add to create an e-mail-to-fax
gateway: an address-rewriting rule that catches all addresses of the
form user@company.fax, and a mailer definition that sends this mail to
Qfax.  Depending on your setup (i.e. whether you use a nameserver or
not) you may also need to prevent Sendmail from trying to resolve
*.fax addresses via DNS.  Lastly, if you're using Qfax v1.x, you may
need to make a change to the way Sendmail writes its headers.  I'll
outline the necessary additions one at a time, below. 


*** Step 1 : The Address Rewriting Rule ***

You should place the following lines immediately after the "$#error"
definitions in Ruleset 0:

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

Note that there are two tabs in this line--one between '>' and
"$#fax", the other between "$1" and "user".  You cannot simply use
spaces here, since Sendmail is looking for tabs as field delimiters.

Here's the relevant portion of my sendmail.cf file for context:

######################################
###   Ruleset 0 -- Parse Address   ###
######################################

S0

R<@>			$#local $: <>			special case error msgs
R$* : $* ;		$#error $@ USAGE $: "list:; syntax illegal for recipient addresses"
R<@ $+>			$#error $@ USAGE $: "user address required"
R<$* : $* >		$#error $@ USAGE $: "colon illegal in host name part"


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

# handle numeric address spec
R$* < @ [ $+ ] > $*	$: $>98 $1 < @ [ $2 ] > $3	numeric internet spec
R$* < @ [ $+ ] > $*	$#smtp $@ [$2] $: $1 < @ [$2] > $3	still numeric: send


*** Step 2: The Mailer definition ***

The mailer definition for Qfax resembles the definition for programs
(Mprog), and simply outputs the mail to Qfax.  Add the following line
at the end of your "Local and Program Mailer" definitions:

Mfax,		P=/usr/local/bin/qfax, F=lsDFheu, S=14, R=24, M=100000,
		A=qfax $u

Of course, if you've installed qfax somewhere other than
/usr/local/bin, be sure to set the appropriate (full) path instead.
Once again, for context, here's the appropriate section of my
sendmail.cf file:

##################################################
###   Local and Program Mailer specification   ###
##################################################

#####  @(#)local.m4	8.6 (Berkeley) 10/24/93  #####

Mlocal,		P=/usr/bin/procmail, F=lsDFMShP, S=10, R=20/40,
		A=procmail -d $u
Mprog,		P=/bin/sh, F=lsDFMeu, S=10, R=20/40, D=$z:/,
		A=sh -c $u
Mfax,		P=/usr/local/bin/qfax, F=lsDFheu, S=14, R=24, M=100000,
		A=qfax $u


*** Step 3: Bypassing Name Service ***

Obviously the top-level domain ".fax" doesn't exist, so if you allow
Sendmail to try to resolve these addresses with a name server you'll
find that it hangs indefinitely in the mail queue.  If this happens to
you, the solution is to find the line in your sendmail.cf file (under
Ruleset 96) which looks like this:

# pass to name server to make hostname canonical
R$* < @ $* $~P > $*		$: $1 < @ $[ $2 $3 $] > $4

Comment out this line (by putting a '#' in front of the 'R' line) and
this should bypass the name server.  This is generally harmless to do
in any case, since by this point the address is almost always
canonical anyway.


*********** 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$'"

NOTE: If the "${lc:host}" expression doesn't evaluate properly with
your shell, try using "${lc:-$host}" instead, as in:

	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 775, otherwise set it to 770.

	/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 770.

	/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 755.

	/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 770.

	/usr/spool/fax/result

This is a directory used to store the result of the most recent fax
operation.  The efax program writes its result code here, which Qrun
uses to determine whether an outgoing fax succeeded or not.  It should
be set to mode 770.

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 and efax distribution in a temporary 
directory of its own (e.g. /tmp works just fine).

To do this, move the archive file qfax1.3.tar.gz to the new
directory and type:

	zcat qfax1.3.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. Define any privileged users  >>>

Privileged users are allowed to have faxes sent out immediately,
rather than having their faxes thrown onto the queue for later
processing.  The FAXGROUP setting in config.h defines the name of this
privileged group, which you should add to /etc/group.  Add the
usernames of any users you want to give this privilege to.  For
instance, if you wanted to give this privilege to users named "huey",
"dewey", and "louie", and the name of the privileged group was
"faxnow", you'd add the following line to /etc/group:

	faxnow::1006:huey,dewey,louie

(The "1006" is just the group ID number; use any unused number you
like for this group)


<<<  9. Edit the efax fax script  >>>

Take a look at the fax script (/usr/bin/fax, or /usr/local/bin/fax)
and edit it to conform to your particular modem, phone number, and so
on.  efax requires that this file be configured in order to send
faxes, and to answer fax calls.


<<<  10. 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.

NOTE: Qfax requires ALL the fields in this data file to be filled in;
leaving a field blank will cause the data to be improperly read, as it
messes with the expected order.  If you have to leave an entry blank
because it doesn't apply to you, try leaving a '.' or similarly
innocuous character there instead.


<<<  11. 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.

NOTE: Every entry in these phonebooks (including the last one) has to
be terminated by a '+' at the beginning of a new line, just as the
example above shows.


<<<  12. 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.


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

Typing "make install" will cause everything (including efax) to be
built and installed.  Note that some 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.


<<<  14. Test efax  >>>

Before you try using Qfax, make sure that efax is configured properly
and works by itself; this makes it MUCH easier to diagnose problems
with your system.  To test efax, you'll want to make sure it can do
two things--convert text files into fax files, and send those fax
files.

(1) Write up a simple text message (a paragraph will do) and save it
    to a file (e.g. test.txt).  Now, type "fax make test.txt".  If
    this is successful, you should see the file test.001 in the same
    directory; this is your fax file.  If this didn't work, chances
    are you don't have GhostScript installed, or your fax script
    doesn't know where to find GhostScript.  It may also be that the
    fax devices have not been compiled into your particular version of
    GhostScript (try "gs -h" to see a list of the devices your
    GhostScript supports); in this case, fetch the sources for
    GhostScript and rebuild it with support for dfaxhigh and dfaxlow.

(2) Try sending your new fax file to someone who can verify that it
    arrived intact.  To send the fax to 123-4567, you'd do this by
    typing "fax send 1234567 test.001".  If the fax doesn't arrive
    properly, you've probably got a configuration problem in your fax
    script, so look there to solve it.  You may find your modem's
    manual handy in this case.


<<<  15. 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.


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

If you'd like to use efax to answer incoming fax calls, make sure that
USE_DAEMON is defined in config.h.  If you'd rather not use efax for
receiving faxes, comment out this definition.

If you are using efax's "fax answer" process to handle incoming calls,
you should put an entry in your /etc/inittab file that looks like:

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

NOTE: Only put this entry in your /etc/inittab if you defined
      USE_DAEMON in config.h.


<<<  17. 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/efax
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.

There's also a digested version of the mailing list available, if
you'd prefer to receive accumulated postings instead of individual
messages.  To subscribe to the digested version, send your request to
qfax-digest-request@renaissoft.com.


<<<  18. Check out the FTP archives  >>>

You might also want to take a look at the FTP archives at Qfax's home
site, ftp.renaissoft.com, under /pub/qfax.  This is where you'll find the
latest (often alpha) versions of Qfax, and where you'll find patches
and documentation.  You can also reach these archives via gopher
(gopher.renaissoft.com) and the WWW (http://www.renaissoft.com/Qfax/). 
