Contributed by Ron Bickers <rbickers@logicetc.com>

-------------------------------------------------------------------------

This is a HOWTO for running tmda-inject on a qmail relay so that
clients sending e-mail through the relay can have their addresses
rewritten according to their .tmdarc settings.  This means that those
running Microsoft Windows clients can take full advantage of TMDA.  In
order to use this, you need to be using a client that supports SMTP
authentication.  At least the following clients should work, but there
are likely others:

  * Microsoft Outlook
  * Microsoft Outlook Express
  * Netscape Communicator
  * Pegasus Mail
  * Qualcomm Windows Eudora

IMPORTANT NOTE FOR NETSCAPE COMMUNICATOR: For some reason, Netscape
thinks that because the SMTP server supports authentication, it must
use authentication.  This means that everyone sending mail with
Netscape will need to be assigned a username and password even if they
are not using TMDA.

Note that there as some security questions that have not been fully
analyzed with this setup.  Although I feel that it's reasonably
secure, it may not be.

Required software:

This setup requires several different components to be installed:

* qmail 1.03 with the following patches:

    - Bruce Guenter's QMAILQUEUE patch
      (http://qmail.goof.com/qmailqueue-patch)

    - A modified version of Eric M. Johnston's YAQSAP
      (Yet Another qmail SMTP AUTH Patch)
      original+docs: http://qmail.goof.com/qmail-auth-20010105.tar.gz

      The modified patch file is included in the contrib/ directory as
      `qmail-smtpd_auth.patch' You still need the original for other
      supporting files.  NOTE: It's a one line addition to his patch
      to set TCPREMOTEINFO to the authenticated user.

* Bruce Guenter's qmail-qfilter program
  (http://untroubled.org/qmail-qfilter/)

After you have the above software installed, make sure that you
can send mail with your client set to use SMTP authentication.
Once that's working, proceed with the following steps:

1. Setup TMDA as per the install instructions with the following
   additional notes:

   * .tmdarc, .tmda-whitelist, etc. needs to be chmod 640 and chown
     username.nofiles so that qmail can read them. (is this safe?) You
     also need to set "ALLOW_MODE_640 = 1" in your .tmdarc.

   * References to os.path.expanduser may need to be expanded manually
     since the user that will be running this won't be yours.  For
     example, if you have WHITELIST_TO_BARE = 1, you must specify the
     full path of your whitelist file (without the ~).

   * You should also specify USERNAME and FULLNAME in .tmdarc since
     TMDA will not be able to correctly determine these on its own.

2. Create a qfilter script to run the mail through tmda-inject.  Here
   is a working sample /usr/local/bin/qfilter-tmda:

   #!/bin/sh
   export -n QMAILQUEUE  # Muy importante to avoid infinite loop!
   if [ $TCPREMOTEINFO ] && [ -r /home/$TCPREMOTEINFO/.tmdarc ]; then
       exec /usr/bin/qmail-qfilter /usr/local/tmda/bin/tmda-inject -q \
       -c /home/$TCPREMOTEINFO/.tmdarc
   else
       exec /var/qmail/bin/qmail-queue
   fi

3. Modify the tcprules file you use for qmail-smtpd to include a
   QMAILQUEUE environment variable.  For example:

   1.2.3.:allow,RELAYCLIENT="",QMAILQUEUE="/usr/local/bin/qfilter-tmda"

   If you are already using SMTP authentication to authenticate for
   permission to relay, you should remove RELAYCLIENT="" above, so
   that it will only be set upon authentication.  However, if you're
   only using authentication to determine the user for TMDA, and you
   also want non-authenticated users to be allowed to relay, the
   RELAYCLIENT="" must be there.

   NOTE: The SMTP authentication is only needed to provide TMDA with
   the correct username for processing.  If your client has a static
   IP address (ex: 1.2.3.4), and you are the only user of this
   address, you could modify tcprules as follows and there would be no
   need for authentication:

   1.2.3.4:allow,RELAYCLIENT="",TCPREMOTEINFO="username",QMAILQUEUE="/usr/local/bin/qfilter-tmda"

4. Recompile the tcprules .cdb and it's ready to go.

-------------------------------------------------------------------------
