<!doctype linuxdoc system>

<!--
The line above starts a comments section


A changelog is useful if you don't use cvs etc.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Changelog:
        20030618: Initial draft
        20030624: Fixed a typo
        20030624: Changed disclaimer script name
                  Added text to set permissions for disclaimer script
                  Some minor config file layout changes
        20041203: Changed my name
                  Added explicit information for allowing localhost
                  connections (suggestion from Ian Clancy)
        20050413: Added Appendix A : FDL text (Julien Valroff)
                  Added a paragraph with the link to the most recetn version of this how-to	  

The line below ends the comments section.
 -->

<article>

<title>Postfix-alterMIME-HOWTO     <!-- insert your title here -->
<author>Derrick J Houy, <tt/djhouy@paw.za.org/ <!-- insert your name here -->
<date>v0.05, 13 Apr 2005            <!-- always have a version number and a date -->
<abstract>                          <!-- the abstract: a short and precise description -->
<nidx>(your index root)</nidx>    <!-- add indexing keywords as you go along -->
                         <!-- nidx means the indexed word is not in output of main text, only in the index -->
This HOWTO outlines the installation and use of alterMIME to add
disclaimer text to outgoing emails with Postfix.
</abstract>

<!-- Table of contents -->
<toc>

<!-- Begin the document -->

<sect>Introduction

<p> <!-- always use a p tag (paragraph) immediately after a sect tag -->
<nidx>(your index root)!introduction</nidx>   <!-- here introduction is a sub entry of template, exclamationmark is separator -->
<p>
In this HOWTO, I will attempt to outline the necessary steps to install and configure alterMIME to be used
with Postfix, for the purpose of adding disclaimer text to outgoing email messages.

<p>
I do not intend for this to be the final authority on the subject, only an example of how I got it working
in my own situation. In the attempt to add disclaimers to email messages, I was faced with a lack of easy to
follow documentation, and so I hope that this small contirbution will fill that gap.

<p>
The most recent version of this HOWTO shall be found at: <htmlurl url="http://www.paw.co.za/docs/howtos/postfix-altermime/postfix-altermime-howto.html">

<sect1>Copyright
<p>
This document is Copyright 2003-2004 by Derrick J Houy.
Permission is granted to
copy, distribute and/or modify this document under the terms of the
GNU Free Documentation License, Version 1.1 or any later version
published by the Free Software Foundation with no Invariant Sections,
no Front-Cover Texts, and no Back-Cover Texts. A copy of the license
can be found in Appendix A.

<sect1>Disclaimer
<p>
Use the information in this document at your own risk. I disavow any
potential liability for the contents of this document. Use of the
concepts, examples, and/or other content of this document is entirely
at your own risk.

All copyrights are owned by their owners, unless specifically noted
otherwise.  Use of a term in this document should not be regarded as
affecting the validity of any trademark or service mark.

Naming of particular products or brands should not be seen as endorsements.

You are strongly recommended to take a backup of your system before
major installation and backups at regular intervals.


<!--
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 -->


<sect>Installation and Configuration
<p>
This documentation is based on the Linux distribution I used (Red Hat 9 with Postfix), and although
it should work on most any Linux distribution, you may need to defiate from the exact instructions to
get it working on your particular flavour of Linux.

<sect1>Installing alterMIME
<p>
alterMIME can be downloaded from <htmlurl url="http://www.pldaniels.com/altermime/">. The version I used was 0.3.1.

<p>
Once downloaded, you need to unpack the tarball, change into the new directory and run

<verb>make</verb>

<p>
After building the altermime executable, install it as follows

<verb>
cp altermime /usr/bin/
chown root.root /usr/bin/altermime
chmod 755 /usr/bin/altermime
</verb>

<sect1>Adding a Non-Privileged User To Run alterMIME
<p>
Unless you have already done this to run other filters in Postfix, the next step is to add a user account
to the system that Potfix will use to run the alterMIME filter

<verb>
useradd -r -c "Postfix Filters" -d /var/spool/filter filter
</verb>

Once you have created this account you need to create the account's home directory

<verb>
mkdir /var/spool/filter
chown filter.filter /var/spool/filter
chmod 750 /var/spool/filter
</verb>

<sect1>Creating The Script To Run alterMIME
<p>
You now need to create the following script, changing whatever you need to personalize it

<verb>
/etc/postfix/disclaimer
</verb>

<code>
#!/bin/sh 
# Localize these. 
INSPECT_DIR=/var/spool/filter
SENDMAIL=/usr/sbin/sendmail

# Exit codes from <sysexits.h> 
EX_TEMPFAIL=75 
EX_UNAVAILABLE=69 

# Clean up when done or when aborting. 
trap "rm -f in.$$" 0 1 2 3 15 

# Start processing. 
cd $INSPECT_DIR || { echo $INSPECT_DIR does not exist; exit 
$EX_TEMPFAIL; }

cat >in.$$ || { echo Cannot save mail to file; exit $EX_TEMPFAIL; } 

/usr/bin/altermime --input=in.$$ \
                   --disclaimer=/etc/postfix/disclaimer.txt \
                   --disclaimer-html=/etc/postfix/disclaimer.txt \
                   --xheader="X-Copyrighted-Material: Please visit http://www.company.com/privacy.htm" || \
                     { echo Message content rejected; exit $EX_UNAVAILABLE; } 

$SENDMAIL -oi "$@" <in.$$ 
 
exit $?
</code>

<p>
Once you have created this script, set the permissions to allow it to be executed by the filter user

<verb>
chgrp filter /etc/postfix/disclaimer
chmod 750 /etc/postfix/disclaimer
</verb>

<sect1>Creating The Disclaimer Files
<p>
You need to create the disclaimer text file that was specified in the disclaimer.sh file

<verb>
/etc/postfix/disclaimer.txt
</verb>

<p>
The content of this file is very much dependent on your requirements, but examples can be found at
<htmlurl url="http://www.emaildisclaimers.com">.

<p>
In my situation, I have used the same file for both the <tt/--disclaimer/ and <tt/--disclaimer-html/
files. I tried to use the <tt/--htmltoo/ parameter to tell alterMIME to use the same file for both, but
this did not seem to work correctly.

<sect1>Postfix Configuration
<p>
Finally, you need to configure Postfix to run the filter. In my case, I only wanted outgoing messages
to be modified, so I explicitly configured Postfix to listen on different network interfaces, but to
only run the filter on the one.

<p>
To achieve this, you need to modify the smtp service in <tt//etc/postfix/master.cf/ to be as follows

<code>
&lt;incoming ip&gt;:smtp        inet        n        -        y        -        -        smtpd
&lt;outgoing ip&gt;:smtp        inet        n        -        y        -        -        smtpd
    -o content_filter=dfilt:
</code>

<p>
replacing &lt;incoming ip&gt; and &lt;outgoing ip&gt; with the IP addresses of the different network
interfaces. In practice, these IP addresses could be bound to the same network controller.

<p>
Now you need to add the following new service to the same file

<code>
dfilt     unix    -       n       n       -       -       pipe
    flags=Rq user=filter argv=/etc/postfix/disclaimer -f ${sender} -- ${recipient}
</code>

<p>
NOTE: You need to ensure that local processes are still able to send mail. The simplest case way is to include
a line like the one below in <tt//etc/postfix/master.cf/ (Thank you to Ian Clancy for pointing out this omisson).

<code>
127.0.0.1:smtp        inet        n        -        y        -        -        smtpd
</code>

<p>
Once you have done this, restart Postfix and send through some test messages whilst watching the mail log.
If everything goes through fine, without any errors, you can pat yourself on the back and go get a cup of
coffee.

<!--
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 -->

<sect>Appendix A

<sect1>GNU Free Documentation License

<p>
Please refer to <htmlurl url="http://www.gnu.org/copyleft/fdl.html"> to obtain
a copy of the GNU FDL Licence.
</article>
