************************************************************************
WARNING:
	THIS SOFTWARE HAS BEEN DISCONTINUED. IT IS NO LONGER MAINTAINED.
************************************************************************

	The author recommends that you do not depend upon renattach to
	filter emails for dangerous content. As of 2006, renattach used
	on its own is not enough to filter potentially harmful emails.
	Dangerous attachments, or other attacks, may pass through the
	filter undetected. Please switch from renattach to some other
	actively developed security system.
						Jem E. Berkes
						2006-03-19

************************************************************************


The build & install is automated by autoconf and automake. Basic steps:

./configure
make
make install

By default, the binary 'renattach' is put in '/usr/local/bin' and the 
example conf file 'renattach.conf.ex' is put in '/usr/local/etc'. Please 
run "./configure --help" to see all the options. For instance, to install 
under your home directory: "./configure --prefix=$HOME"

To customize your installation, modify the options in renattach.conf. Use 
the command "renattach --settings" to see the active configuration.

Since renattach is a standard UNIX filter, it can be installed into a wide
variety of mailing systems. The filter reads a single email message as
input at stdin, then writes the filtered output either to stdout or to a 
pipe (external command) if the --pipe option is used.

There are many ways to install renattach in both the user and site-wide
contexts. The cases below are by no means exhaustive.


=============================
procmail for individual users
=============================

Most mail servers use procmail for local mail delivery. This is the 
default configuration for Sendmail. In Postfix, main.cf has to include:
mailbox_command = /usr/bin/procmail

If your site uses procmail, then you can create the ".procmailrc" file in 
your home directory to instruct procmail to run certain scripts. The 
following basic ".procmailrc" will filter all incoming mail through 
renattach. Please see "man procmailrc" to learn more about the format:

# Filter mail through renattach, and wait for success exit code
:0 wf
| /path/to/renattach

There is a minor complication when using renattach's "kill" feature since
nothing will leave the filter. Procmail does not know to stop processing,
so it will deliver a blank stub of a message to your mailbox. To prevent
this, you can add this rule after renattach to handle killed messages:

# If message is blank (killed), drop it and stop processing.
:0
*! .
/dev/null


=================================
procmail for entire site (global)
=================================

If your site uses procmail, then you can take advantage of procmail's 
site-wide filtering capabilities via the /etc/procmailrc configuration 
file. You can use the same filtering 'rule' as in the above example for 
individual users. Please see "man procmail" for more information.

Please check to make sure that procmail does not run procmailrc 
with root privileges. renattach SHOULD NOT run as 'root'.


===================
Postfix integration
===================

The Postfix MTA has a flexible modular design that makes it relatively
easy to add content filters such as renattach. There are several
advantages to installing renattach at the MTA level:

+	Tighter integration into the mail system, ensuring that all mail
	is filtered (instead of relying on procmail operating correctly)

+	Possibility for both inbound and outbound SMTP filtering

+	Superior security, since the filter can run under dedicated UID

+	Superior feedback on filtering errors (mail bounces or temporary
	failures) due to strict interpretation of filter exit codes. In
	other words, if renattach encounters a temporary error such as
	resource shortage or dead external pipe, mail will remain queued
	and delivery will be attempted later. If renattach encounters a
	fatal error (bad command usage) then mail will bounce.

To install renattach, you only need to modify /etc/postfix/master.cf
The following instructions are based on Postfix's FILTER_README file and 
describe how to install renattach as a content filter for SMTP.

1) Create a new user 'filter' with a disabled password, unique group, no 
home directory and no login shell. /etc/passwd would have something like:
filter:*:952:952:filter:/dev/null:/dev/null

2) Insert the following into /etc/postfix/master.cf to define the 'filter' 
service that uses the Postfix pipe program. Note the long second line; 
this instructs Postfix to pipe mail into renattach using privileges of the 
dedicated filter user. You can specify any renattach options you wish. 
Here, we MUST use renattach's -p (or --pipe) to send the filtered output 
to the Postfix 'sendmail' command. This re-injects the filtered message 
back into the mail system. Do not include quotes around the sendmail 
command line (this has changed in version 1.2.2).

filter    unix  -       n       n       -       -       pipe
  flags=q user=filter argv=renattach -l -p sendmail -i -f ${sender} -- ${recipient}

The pipe option must be the last option specified, with everything after 
it being taken as the command and arguments. Be sure to specify the full 
path to the renattach and sendmail commands.

The -l option additionally protects Postfix against a spammer's attack
that causes a "mail forwarding loop" to relay spam. (See man page).

3) Now that you have defined a new 'filter' module, you can instruct the 
smtp module to use 'filter' as a content filter. This is done simply by 
editing /etc/postfix/master.cf and adding the -o content_filter=filter 
option to smtpd. This means that the smtp service should appear like this:

smtp      inet  n       -       n       -       -       smtpd
	-o content_filter=filter

4) Save master.cf and run 'postfix reload'. Now test your configuration.  
Any mail coming into your system via SMTP should now leave with the
additional renattach headers. The system mail logs should indicate mail
being passed with relay=filter. There should also be log entries from the
postfix/pipe program. Make sure use_syslog is enabled so that your mail
logs show filtered attachments and message-id's. Send some dangerous
attachments to confirm that they are filtered and logged.

It's important to understand how mail now flows through your system. The 
following illustrates step-by-step how mail is processed with the above 
configuration:

a. Client connects to server:25 (smtpd) and uploads an email
b. smtpd relays the mail to the content filter, the 'filter' service
c. The 'filter' service pipes the mail to renattach
d. renattach pipes its output to the Postfix sendmail command, specifying  
   as command line options the original sender and recipient(s). If that
   sendmail command fails in any way, renattach's exit code tells Postfix
   to keep the mail queued and retry later (no mail is lost).
e. The sendmail command locally re-injects the mail into the system
f. Delivery continues as normal


====================
sendmail integration
====================

While the procmail-based methods described earlier are probably the best
way to install renattach on a sendmail server, it is also possible to
install renattach as the local delivery agent (Mlocal option). In 
this configuration, renattach sits between sendmail and procmail.

Installations typically rely on procmail. The following example shows a
standard configuration before renattach is installed:

Mlocal,		P=/usr/bin/procmail, F=lsDFMAw5:/|@qSPfhn9,
		S=EnvFromL/HdrFromL, R=EnvToL/HdrToL, T=DNS/RFC822/X-Unix,
		A=procmail -t -Y -a $h -d $u

Instead of invoking procmail as the local mail delivery agent, sendmail
can invoke renattach and instruct the filter to pipe its output to
procmail (or any other program, as required). Few changes are required to
the above configuration:

Mlocal,		P=/usr/local/bin/renattach, F=lsDFMAw5:/|@qSPhn9,
		S=EnvFromL/HdrFromL, R=EnvToL/HdrToL, T=DNS/RFC822/X-Unix,
		A=renattach --pipe /usr/bin/procmail -f $g -t -Y -d $u

Note the following:

o The F=f (lowercase 'f' flag) must be removed from the flags field, 
  because this automatically places the -f option in the wrong place.
  The procmail -f option is manually specified after --pipe.

o The procmail -a feature (for passing meta data) appeared to be causing
  strange problems. Removing it solved delivery problems we encountered.


=========================================================================
sendmail support has NOT been thoroughly tested. Details of sendmail (and 
other MTA) installation is beyond the scope of this document. These basic 
installation instructions are provided as a convenience.
=========================================================================
