INSTALL   [plain text]


Discusses:
		1. Getting the lot to compile
		2. IMPORTANT info for people with remote filesystems (like NFS)
		3. DEBUGGING AID
		4. Setting up the environment
		5. Extra options if you are a system administrator

				---

1. Getting the lot to compile
   --------------------------

To install procmail, lockfile and formail: edit Makefile & config.h accordingly
and type 'make install'.
Intended configurable options in Makefile are:
	the install-destinations (primarily BASENAME) and the
	LOCKINGTEST directories (you can optionally use something like
	'make BASENAME=$HOME install' instead).
Intended configurable options in config.h are:
	MMDF support, standard environment presettings including PATH,
	trusted userids, whether each user has their own group.

If an older version of procmail is currently installed, you should
review all the entries in the HISTORY file between that revision and
this one.

'make install' will:
      - implicitly do a 'make init', which will check your basic utilities for
	POSIX compliance, and generates correcting Makefiles accordingly
      - execute autoconf (a shell script that repeatedly calls the C compiler
	to determine if certain features/symbols are supported), which will
	create a file named autoconf.h
      - create three stripped binaries, a shell script and five man pages in
	the new/ subdirectory (all that is needed to install):
	procmail, lockfile, formail, mailstat, procmail.1, lockfile.1,
	formail.1, procmailrc.5, procmailsc.5, procmailex.5
      - copy these binaries and mailstat to $(BINDIR)
      - copy the man pages to $(MAN1DIR) and $(MAN5DIR)
      - BEWARE: the installation obeys the current umask setting.  If you
	want the files to be available to anyone, correct your umask first.

'make deinstall' will:
      - remove the just installed files in $(BINDIR)
      - remove the just installed files in $(MAN1DIR) and $(MAN5DIR)


Minimal requirements (for regular uses):

procmail must be installed.

Optional files (depending on your requirements):

lockfile only needs to be installed if you plan to read several mailboxes
	with one of the standard mailers that doesn't support lockfiles.
formail only needs to be installed if mail sometimes arrives in nonstandard
	mailbox format (or if you want to generate auto replies, split up
	mailboxes/digests etc., see the man page of formail for more info).
mailstat is an "example" shell script that can be used as is to produce
	summaries of the procmail generated logfiles; it is not needed by
	procmail itself in any way.

procmail, lockfile, formail and mailstat are all *standalone* programs, i.e.
they do *not* use any compiled-in paths or files that need to be there, they
all can be used and installed independently without the need to install the
others.

If things don't compile automagically, I suggest you take a look at:
src/autoconf, autoconf.h, config.h, src/includes.h

For autoconf to work as intended, your compiler should either be fully ANSI
compliant, or you should NOT turn off all warnings; enabling all warnings
shouldn't hurt.	 In most cases the default options in the Makefile will do.

The sources are supposed to be fully ANSI, K&R and POSIX compliant.

N.B. If you encounter any difficulty at all in installing procmail (e.g. if you
     had to change Makefile or config.h in unpredicted ways, or a simple
     "make install" doesn't work), I'd very much like to hear about it; who
     knows, next time you might be able to simply "make install" as well.

				---

2. IMPORTANT info for people with remote filesystems (like NFS)
   ------------------------------------------------------------

The autoconf script tries to determine what kernel locking functions are
available *and* reliable on your system.  In order to do this it exercises
all the available locking methods (fcntl(), lockf() and flock()) on some
sample files extensively.

These tests produce results which depend on the filesystem which is
being used to perform the tests.  If you haven't changed the definition
of LOCKINGTEST in the Makefile (you can include as many directories as
you want) autoconf will prompt you to enter any additional directories
(preferably on distinct filesystems) you want it to run the tests on.

When specifying directories to test, it would probably be advisable to
pick exactly those directories which belong to a unique fileserver-fileclient
pair.  I.e. one local file system will suffice.	 Only if you have remote
filesystems, you might have to specify several.
This makes sure that the locking tests will properly reflect the (lowest common
denominator) locking capabilities on all filesystems available.

If you have a very heterogenous environment (like several OS versions
on machines (perhaps even from different vendors) that have NFS mounted file
systems all over each other), then it could happen that some tests which
are reliable with one remote filesystem, turn out to be unreliable across
another (it all depends on the OS versions of clients and servers).

If do not want to perform the locking tests on all those filesystems, but
if you know what locking methods are unreliable anyway, then you can edit
some defines in the config.h file (NO_fcntl_LOCK, NO_lockf_LOCK and
NO_flock_LOCK).	 These can be uncommented by hand to prevent procmail
from using them.

The most typical case would be if you happen to be using NFS.  Autoconf
normally is very well capable of finding out if your lockd is reliable enough.
In a very heterogenous environment (many different servers, many different
lockd's (of perhaps different version and patchlevel)) however, it might
be hard to determine if all the lockd's are equally reliable.  In such a
case (typically on SunOS :-), you might consider uncommenting both
NO_fcntl_LOCK and NO_lockf_LOCK (NO_flock_LOCK normally doesn't rely on the
infamous lockd, so you can leave it commented out).  But, only do so if you
think you know it better than autoconf.

				---

3. DEBUGGING AID
   -------------

Since procmail is intended to run completely independent of any terminals, you
will typically have difficulties seeing it display error messages on the stderr
output.	 It is recommended, especially during debugging, to specify a LOGFILE
(see the procmailrc(5) man page) in the rcfile or on the command line.
Procmail will log all serious problems it encounters.  Of course, instead of a
regular file, one could also specify a terminal as the default logfile.

Also, procmail can be persuaded to be a lot more verbose by inserting the
following assignment at the top of your rcfile:

	VERBOSE=on

Therefore a suggested command line for your first trial run (no rcfiles
needed) would be:

	procmail VERBOSE=on

(now type in a pseudo mail-message)

If all else fails, you can try uncommenting the "#define console" entry
in the config.h file.  This will provide you with the most verbose procmail
you can make.  It is of course a good idea to comment out this line again
after your troubles have been solved.

If you run procmail by hand and pipe in some sample mail, then make
sure that if you kill procmail, you use "kill pid" and NOT "kill -9 pid".
Should procmail seem to hang, check if any lockfiles are still present.
If you kill procmail with "kill pid" it will clean up any lockfiles it created
itself.

				---

4. Setting up the environment
   --------------------------

Every user that wants to use procmail should have a .forward and a
.procmailrc file in his HOME directory.	 For starters, you can look
at the supplied example files in "examples" or the NOTES section in
the procmail(1) man page.
BTW, be sure to make .forward *world* readable.
MMDF users should note that they need a .maildelivery file *instead* of the
.forward file (see the procmail(1) man page for more information).

				---

5. Extra options if you are a system administrator
   -----------------------------------------------

If you are a system administrator you can decide to install procmail
globally (i.e. as a more robust drop-in replacement for the local-
maildelivery-capabilities of /bin/mail, this also gets rid of the known
security holes in some /bin/mails), this has the advantage that users do
not need to have a .forward file anymore that calls up procmail.  Simply
having a .procmailrc file in the HOME directory will suffice.  Operation is
transparent in this case (i.e. if no .procmailrc file is present in the HOME
directory, mail will be delivered as usual and procmail behaves like a faster
and more reliable /bin/mail substitute).

For direct examples on how to do this, look at the examples/advanced file.

*******************************************************************************
HIGHLY RECOMMENDED: install "procmail" suid root (and/or sgid maildaemon)
		    install "lockfile" sgid maildaemon

To obtain specific instructions on the best installation, type "make recommend"
*******************************************************************************

				---

For more info about the program, see the man pages or the FAQ list.