>>> TMDA 
  
TMDA Homepage TMDA @ SourceForge      
Overview
Introduction
History
Features
Results & Testimonials
TMDA In Use
Press Coverage
 
Usage
Requirements
Download
Installation
Configuration
HOWTOs
 
HOWTOs
Overview
Templates
tmda-ofmipd
tmda-cgi
 
Support
Troubleshooting
FAQ
Bugs & Patches
Mailing Lists
List Archive
Commercial Support
External Resources
 
Author
Jason R. Mastaler
 
© 2001-2002
  

tmda-cgi (contributed by Gre7g Luterman)

What is it?
Requirements
Credit/blame
Installation
    System-wide mode
    Single-user mode
    no-su mode
        Centralized no-su setup
Passwords
Configuration
Templates (URL confirmation)


What is it?

tmda-cgi is an alpha-release program for managing your TMDA account over the web. At the time of this writing, tmda-cgi can:

  • Page through lists of pending e-mail (mail received by your MTA, but still awaiting confirmation)
  • View the text content (and see what sorts of attachments are included) in any of your pending e-mails
  • Release (move into your mail folder as if a confirmation had been received) any of your pending e-mails.
  • Delete any pending e-mail
  • Whitelist or blacklist the author of any pending e-mails.

At the moment, tmda-cgi's focus is clearly manipulating pending e-mails. At some point, I would like tmda-cgi to become more of a general system tool. Features I hope to add soon include:

  • Filter configuration
  • List editing
  • Automated clean-ups of pending e-mails
  • E-mail address generation (keyword, dated, or sender)

tmda-cgi provides quick and easy access to your pending e-mails. This is an ideal tool for users who either do not have access to a shell account or are intimidated by operating in a command-line environment.

Although TMDA users do not generally need to mess with their pending e-mails, there are times when this is the most convenient way to go. For instance:

  • When you use a web site that says it will automatically mail you a password, authentication link, or a receipt for a transaction you are making right now, but you're not interested in any follow-up e-mail they will likely send you in the future (and you don't feel like generating a dated address).

    Simply fill out the web form like you normally would and give your regular, filtered e-mail address. The web site will send the e-mail to your mail server, and your mail server will send a confirmation request back to the web site (which will most likely never be seen by a human being). Then log into tmda-cgi and manually release their letter. Any further mail they send you will sit quietly in your pending directory like the one you released.

  • To search your incoming mail for automated mailings you want to receive.

    Using tmda-cgi regularly for a few weeks or months after you begin filtering your e-mail is a good way to make sure your filters are configured correctly.

  • To look for "lost" e-mail.

    It's really rare that e-mail will get lost, but it's bound to happen sometimes. Perhaps Aunt Margaret can't figure out what the confirmation e-mail meant (even though it is written in a very obvious way). Perhaps your boss was in a hurry and deleted the confirmation request thinking it was spam (or perhaps he has a really crappy spam filter that mistook the confirmation for spam). Perhaps Grandpa Joe sent you some e-mail from someone else's e-mail account and they deleted the confirmation request, not realizing what it was.

  • To remind you why you got TMDA in the first place.

    "Wow, I would have gotten 100 e-mails about Viagara, cheap cigarettes, weight loss drugs, penis enlargement, and Nigerian swindles today! Now I remember why the rest of my family thinks that e-mail is a pain."


Requirements

TBD. Until we do more testing it isn't clear what systems have problems with tmda-cgi.


Credit/blame

As already mentioned, this is contributed software at an alpha-level release. That means:

  • Use at your own risk.

    That's true of all software in general, but we're telling you up front that not a lot of people have tested or analyzed the code yet. If it goes awry or opens a security hole on your machine, I won't drop dead from the shock.

  • tmda-cgi was written by Gre7g Luterman, with support from Jason R. Mastaler, David Guerizec, Tim Legant, and others on the TMDA lists.

Installation

tmda-cgi is provided in your distribution's contrib/cgi directory.

Once you've obtained a copy of tmda-cgi, you need to decide how you want to use tmda-cgi. tmda-cgi has been designed to run three different ways: system-wide, single-user, and in no-su modes.

  • In system-wide mode, multiple users can use tmda-cgi to access their TMDA system. The program launches as root and then performs a seteuid to run as the requested user once password authentication has been accomplished. This is the best solution for system administrators who wish to set up their TMDA system for use by multiple users.
  • In single-user mode, only one user can access tmda-cgi. That user will still need to authenticate their access with a password, but the program runs as the user who compiled it and therefore cannot access anyone else's personal data. If multiple users wish to install tmda-cgi in single-user mode (strange, but not absurd) then each user can compile a different 14k shell that launches the Python code. This method is less convenient than the system-wide installation, but it is the best solution for users without root access to their server, or for users who don't trust any program running as root that does not absolutely have to run as root.
  • no-su mode, which is in testing, runs the program with no special privileges of any sort. The downside of such an installation is that to allow the program access to your personal files (such as pending e-mails) you will have to make some of your files and directories group or world readable and writable. no-su mode is a good solution for an unusual breed of user: someone who doesn't trust the software, but trusts the other users on the server (since they could get read/write access to his/er pending e-mail)

Notes:

  • tmda-cgi assumes it will run from within the source tree. No testing has been done to date to see if it will work in other locations.
  • You will have to recompile tmda-cgi if you move your configuration files or source tree.
  • You will have to recompile tmda-cgi if you change which mode (system-wide, single-user, or no-su) you run in.

Installing system-wide

As root, change to the cgi directory.

# cd contrib/cgi

Compile tmda-cgi to a web directory that is configured to execute CGI. The filename you use is completely up to you. For example:

# ./compile -t /path/to/cgi-bin/directory

or

# ./compile -t /path/to/webpage/directory/index.cgi

Finally, tmda-cgi expects to find a variety of visual elements in a subdirectory called "display". This directory should be located directly below the CGI itself. Sample files are provided in contrib/cgi/display. Feel free to use these files as-is or modify/replace them to personalize the program.

The simplest way to provide this directory is with a symbolic link (assuming you have you web server configured to follow symbolic links). For example:

# ln -s display /path/to/webpage/directory

Installing single-user

As the (only) user who will be able to access tmda-cgi, change to the cgi directory.

$ cd contrib/cgi

Compile tmda-cgi to a web directory that is configured to execute CGI. The filename you use is completely up to you. For example:

$ ./compile -t /path/to/cgi-bin/directory

or

$ ./compile -t /path/to/webpage/directory/index.cgi

Finally, tmda-cgi expects to find a variety of visual elements in a subdirectory called "display". This directory should be located directly below the CGI itself. Sample files are provided in contrib/cgi/display. Feel free to use these files as-is or modify/replace them to personalize the program.

The simplest way to provide this directory is with a symbolic link (assuming you have you web server configured to follow symbolic links). For example:

$ ln -s display /path/to/webpage/directory

Installing no-su

To compile tmda-cgi for no-su mode, first change to the cgi directory.

$ cd contrib/cgi

Compile tmda-cgi to a web directory that is configured to execute CGI. The filename you use is completely up to you. For example:

$ ./compile -nt /path/to/cgi-bin/directory

or

$ ./compile -nt /path/to/webpage/directory/index.cgi

tmda-cgi expects to find a variety of visual elements in a subdirectory called "display". This directory should be located directly below the CGI itself. Sample files are provided in contrib/cgi/display. Feel free to use these files as-is or modify/replace them to personalize the program.

The simplest way to provide this directory is with a symbolic link (assuming you have you web server configured to follow symbolic links). For example:

$ ln -s display /path/to/webpage/directory

At this point you will have to change permissions on any existing pending mail and add something akin to:

os.umask(027)

to your configuration file. That will make sure that future pending e-mails are written such that they can be read by group members (i.e. the CGI).

Centralized no-su setup

If you multiple users plan on using tmda-cgi in no-su mode, then you might consider moving all of your TMDA files into one central location. This will make it easier to keep group permissions on your directories and files. Here's some sample directories and file contents I set up for my user cgitest:

/etc:
-rw-r--r--    1 root     root           22 Nov 24 23:54 tmda-cgi
-rw-r--r--    1 root     root          557 Nov 27 15:05 tmdarc
-rw-------    1 tofmipd  tofmipd        49 Nov 10 11:02 tofmipd

/var:
drwxr-s--x    3 root     nobody         72 Nov 27 11:24 tmda

/var/tmda:
drwx--s---    6 cgitest  nobody        200 Nov 27 11:39 cgitest

/var/tmda/cgitest:
-rw-r-----    1 cgitest  nobody          0 Nov 27 11:39 config
-rw-r-----    1 cgitest  nobody         41 Nov 27 11:39 crypt_key
drwx--s---    2 cgitest  nobody         96 Nov 27 12:55 filters
drwx--s---    2 cgitest  nobody        144 Nov 27 12:59 lists
drwx--s---    2 cgitest  nobody        120 Nov 27 12:57 logs
drwxrws---    2 cgitest  nobody         48 Nov 27 11:37 pending
drwx--s---    2 cgitest  nobody        768 Nov 29 09:54 responses
drwxr-sr-x    2 cgitest  nobody        200 Dec  6 20:33 templates

/var/tmda/cgitest/filters:
-rw-rw----    1 cgitest  nobody        153 Nov 27 12:54 incoming
-rw-rw----    1 cgitest  nobody        150 Nov 27 12:55 outgoing

/var/tmda/cgitest/lists:
-rw-rw----    1 cgitest  nobody          0 Nov 27 12:59 blacklist
-rw-rw----    1 cgitest  nobody          0 Nov 27 12:59 confirmed
-rw-rw----    1 cgitest  nobody          0 Nov 27 12:59 whitelist

/var/tmda/cgitest/logs:
-rw-r-----    1 cgitest  nobody          0 Nov 27 12:57 debug
-rw-r-----    1 cgitest  nobody          0 Nov 27 12:57 in
-rw-r-----    1 cgitest  nobody          0 Nov 27 12:57 out

/var/tmda/cgitest/templates:
-rw-r--r--    1 cgitest  nobody        407 Dec  6 20:30 bounce.txt
-rw-r--r--    1 cgitest  nobody        215 Dec  6 20:30 confirm_accept.txt
-rw-r--r--    1 cgitest  nobody        702 Dec  6 20:33 confirm_request.txt

/etc/tmda-cgi:
cgitest:XPkY0q/9Uge9I

/var/tmda/cgitest/filters/incoming:
from-file /var/tmda/cgitest/lists/blacklist reject
from-file /var/tmda/cgitest/lists/whitelist accept
from-file /var/tmda/cgitest/lists/confirmed accept

/var/tmda/cgitest/filters/outgoing:
to-file /var/tmda/cgitest/lists/whitelist tag envelope dated=10d from bare
to-file /var/tmda/cgitest/lists/confirmed tag envelope dated=10d from bare

/var/tmda/cgitest/templates/confirm_request.txt:
From.US-ASCII: "%(FULLNAME)s" <%(recipient_address)s>
Subject.US-ASCII: Please confirm your message
Reply-To.US-ASCII: %(confirm_accept_address)s
BodyCharset: US-ASCII
 
This message was created automatically by mail delivery software
(TMDA).
 
Your message attached below is being held because the address
<%(confirm_append_address)s> has not been verified.
 
To release your message for delivery, please send an empty message
to the following address, surf the following link, or use your
mailer's "Reply" feature.
 
  %(confirm_accept_address)s
 
  %(confirm_accept_url)s
 
This confirmation verifies that your message is legitimate and not
junk-mail. You should only have to confirm your address once.

/etc/tmdarc:
import Util
 
# Allow group access to critical files
ALLOW_MODE_640 = 1
os.umask(0027)
 
# Locate important files and directories
DATADIR = "/var/tmda/%s/" % os.environ["USER"]
CONFIRM_APPEND           = DATADIR + "lists/whitelist"
FILTER_INCOMING          = DATADIR + "filters/incoming"
FILTER_OUTGOING          = DATADIR + "filters/outgoing"
LOGFILE_DEBUG            = DATADIR + "logs/debug"
LOGFILE_INCOMING         = DATADIR + "logs/in"
LOGFILE_OUTGOING         = DATADIR + "logs/out"
PENDING_BLACKLIST_APPEND = DATADIR + "lists/blacklist"
PENDING_WHITELIST_APPEND = DATADIR + "lists/whitelist"
TEMPLATE_DIR             = DATADIR + "templates/"
 
# CGI location
CGI_URL = "http://wolfhome.com/~cgitest/index2.cgi"

# Define X-Primary-Address key for TMDA-to-TMDA communications
ADDED_HEADERS_CLIENT = { "X-Primary-Address": "%s@%s" % \
 (os.environ["USER"], Util.gethostname()) }

~cgitest/.qmail:
|preline /usr/src/tmda/bin/tmda-filter -c /var/tmda/cgitest/config
./Maildir/

tmda-cgi was compiled with the following:

./compile -nc /var/tmda/~/config -t /www/tmda.cgi

Use the ./compile -h for more details on how to use compile.


Passwords

tmda-cgi currently authenticate logins against user name & password pairs stored in a password file (or files). tmda-cgi will look in two different places for password file(s), but it (they) must be readable by the CGI.

If you are running in system-wide mode, the password file can be owned by root. If you are running in single-user mode, the password file can be owned by the user who will be running the CGI. If you are running in no-su mode, the file must either be owned by "nobody" (or whatever user your web server is configured to run as) or made globally readable See the table below for a better breakdown of your options.

tmda-cgi first checks for a readable file called tmda-cgi in the same directory as the user's configuration file (if that location has been specified, otherwise it will look in ~user/.tmda/tmda-cgi). It then tries /etc/tmda-cgi if it can't find a match or cannot read the file. This allows the system administrator to keep a list of access passwords while allowing the user to override what the sysadmin has set.

        ~user/.tmda/tmda-cgi   /etc/tmda-cgi
        owner permissions   owner permissions
    system-wide   user 600   root 600
    single-user   user 600   n/a
    no-su   user 644   root
nobody
644
600
  File owner & permission options

The password file for tmda-cgi is formatted in much the same way as the password file for tofmipd. In fact, if you are using a password file with tofmipd and you wish to run tmda-cgi in system-wide mode, feel free to make a symbolic link between the two:

 # ln -s /etc/tofmipd /etc/tmda-cgi

Password files for tmda-cgi look like:

<user1>:<password1>
<user2>:<password2>

where each item in <> is replaced with text.

The difference between this password file and the one for tofmipd is that the file does not need to have
permissions of 400 or 600. If you, for example, are running in no-su mode, you will have to make your password file group or world readable.

To keep the passwords secure, tmda-cgi will assume all passwords are DES encrypted if the file permissions are anything other than 400 or 600. Plaintext passwords will not work in such cases.

Additionally, any entry with a blank password field, such as:

cantlogin:

will be prohibited from login, regardless of the file permissions.

contrib/cgi/genpass.py is provided for encrypted password generation. Output from genpass.py can be safely piped with > or >> into a password file. For example:

# contrib/cgi/genpass.py joe >> /etc/tmda-cgi

or

$ contrib/cgi/genpass.py joe > /home/joe/.tmda/tmda-cgi

If you encounter difficulties logging in, the problem may be a result of incorrect permissions on your password file(s). To debug this, append a ?debug=1 onto the end of your CGI URL. This will display some diagnostic information if the login fails instead of simply saying "Wrong password. Try again."


Configuration

tmda-cgi is configured by a set of parameters in your configuration file(s). All tmda-cgi configuration variables begin with a "CGI_" and are described on the Configuration Variables page.

Note: If you change nothing else, you will have to at least set the value for CGI_ACTIVE.


Templates

By supplying your own templates (see the Template HOWTO for more on customizing your templates) you can use tmda-cgi's URL confirmation feature. This allows you to specify a URL in your confirmation e-mail as an alternative to confirming by e-mail.

To supply a confirmation URL, simply use the %(confirm_accept_url)s variable in confirm_request.txt as shown in Centralized no-su setup.

Notes:

  • Be sure you set CGI_ACTIVE, CGI_URL, and TEMPLATE_DIR before modifying your template! No confirmation e-mails will be sent if you specify a %(confirm_accept_url) until these variables are properly configured.
  • Always test your configuration after making a change to your templates.
  • Your crypt_key file must be readible by tmda-cgi to use this feature.

    This is not and issue if you are running in system-wide orf single-user modes, but in no-su mode, you will have to:

    • Put crypt_key in the CGI's group.
    • Assign crypt_key 640 permissions.
    • Turn on ALLOW_MODE_640.