============================================================
TMDA Tools Version 1.00 by David Morison (david@morison.net)
============================================================
 http://www.morison.net/squirrelmail-plugins/tmdatools.html
============================================================

TMDA Tools is a fully featured TMDA (Tagged Message Delivery Agent) plugin for 
Squirrelmail. It extends Squirrelmail functionality by adding X-TMDA header 
injection into outgoing messages, together with a collection of end user TMDA 
tools, including the ability to edit user specific files such as a whitelist, 
and to create TMDA coded addresses for use outside Squirrelmail. It has been 
designed with an untrusted environment in mind; with administrator control over 
how much TMDA functionality may be managed by users of the plugin.

============
INSTALLATION
============

See the file INSTALL included in this distribution for installation instructions.

=============
CONFIGURATION
=============

Note: These instructions assume that your TMDA user files are located in 
~/.tmda/. If your TMDA installation uses a different location you will have to 
modify the instructions below and the sample configuration file accordingly.

Warning: The following instructions involve changing permissions on the user 
files accessed by TMDA, and may stop TMDA from processing your incoming email if 
you make a mistake. Make a note of all access modes and ownership of files in 
your ~/.tmda/ directory before making any changes. Proceed with caution!

Follow the steps below in sequence and perform the checkpoint tests at the end 
of each step. If things stop working you can then rollback easily, and also let 
other people know where you have got up to if you need help in getting TMDA 
Tools to work on your system.

1. Configure TMDA Tools and set file permissions
================================================

Read the comments in tmdatools_config.php and make any changes needed on your 
system. In order for TMDA Tools to gain write access to the files specified in 
$plugin_tmdatools_editfiles you need to set ownership and permissions as shown 
below, where user=your user name and squirreluser=a group to which the user that 
Squirrelmail is running as on your system belongs.

 $ chown user:squirreluser filename
 $ chmod 660 filename

Checkpoint Test: Login to Squirrelmail. Go to the TMDA Tools page. Verify that 
you can edit the files as required.

Checkpoint Test: Send email to yourself from both another account on the same 
system and an external account. This will verify that you have not broken TMDA's 
incoming email processing by changing file permissions.

2. Configure TMDA
=================

TMDA must be configured to show the appropriate headers for the TMDA Tools 
pending list manager; to allow mode 640 on ~/.tmda/crypt_key; and to override 
the default mode used when created messages in your pending folder (so that 
squirreluser can view pending messages). Open your TMDA configuration file 
~/.tmda/config into a text editor. Add the following lines:

TERSE_SUMMARY_HEADERS = ["from_name", "subject", "date"]
ALLOW_MODE_640 = 1
os.umask(027) 

When sending email via the tmda-sendmail wrapper as called by Squirrelmail, 
squirreluser will require read access to your ~/.tmda/config and 
~/.tmda/crypt_key files. Go to a shell prompt and and change the ownership and 
access mode as follows:

 $ cd ~/.tmda
 $ chmod 640 config crypt_key
 $ chown user:squirreluser config crypt_key 

Checkpoint Test: Login to Squirrelmail. Go to the TMDA Tools page. Verify that 
you can use the Address Generator.

Checkpoint Test: Send email to yourself from both another account on the same 
system and an external account. This will verify that you have not broken tmda's 
incoming email processing by changing these file permissions.

3. Set directory and existing file permissions
==============================================

If you have TMDA configured to log outgoing messages, squirreluser will require 
write access to your TMDA log directory, and to any outgoing log file that 
already exists. To view pending messages, squirreluser will require write access 
to the pending messages directory and any pending messages currently in that 
directory. The sticky bit must be set on these directories to ensure that 
squirreluser is set to be the group owner of new files created in these 
directories by other processes. If these directories are ~/.tmda/logs/ and 
~/.tmda/pending/ respectively, set permissions as follows:

 $ cd ~/.tmda/
 $ chown -R user:squirreluser logs
 $ chmod -R 770 logs
 $ chmod 2770 logs
 $ chown -R user:squirreluser pending
 $ chmod -R 770 pending
 $ chmod 2770 pending

Checkpoint Test: Send email to yourself from both another account on the same 
system and an external account. This will verify that you have not broken TMDA's 
incoming email processing by changing these permissions.

4. Configure Squirrelmail to send email via sendmail (if required)
==================================================================

Note: This step is only required if you have not already configured Squirrelmail 
to send email via TMDA through some other mechanism, such as authenticated SMTP.

Open your Squirrelmail configuration file 
/home/httpd/html/squirrelmail/config/config.php into a text editor. Make changes 
as follows:

$useSendmail = true;

The $sendmail_path variable should remain as the system sendmail binary; as this
will be overridden with the path to the tmda-sendmail wrapper if the plugin is
activated for the logged in user.

Checkpoint Test: Log out of Squirrelmail, and then log back in. You should now 
be able to send email via TMDA. The default TMDA send mode depends on your TMDA 
configuration. You can override the default send mode on a per-message basis by 
selecting a specific TMDA send mode on the compose email form.
