Abstract

The personal.tcl mailbot implements a highly-specialized filter for personal messages. It MUST not be used by people who receive mailing list traffic in their personal mailboxes.

Table of Contents

1.  SYNOPSIS
1.1  Requirements
1.2  Copyrights
2.  PHILOSOPHY
2.1  Guest Lists
3.  BEHAVIOR
3.1  Arguments
3.2  Actions
3.3  The Configuration File
3.3.1  Configuration Options
3.3.1.1  dataDirectory
3.3.1.2  defaultMaildrop
3.3.1.3  auditInFile
3.3.1.4  auditOutFile
3.3.1.5  friendlyDomains
3.3.1.6  logFile
3.3.1.7  myMailbox
3.3.1.8  noticeFile
3.3.1.9  pdaMailboxes
3.3.1.10  remoteMailboxes
3.3.2  Configurable Procedures
3.3.2.1  adminP
3.3.2.2  friendP
3.3.2.3  ownerP
3.3.2.4  saveMessage
3.3.2.5  findPhrase
3.3.2.6  makePhrase
3.3.2.7  pruneDir
3.3.2.8  tclLog
§  References
§  Author's Address
A.  Impersonal Mail
A.1  Configuration Options
A.1.1  foldersDirectory
A.1.2  foldersFile
A.1.3  announceMailboxes
A.1.4  mappingFile
A.2  Configurable Procedures
A.2.1  impersonalMail
B.  An Example configFile
C.  Acknowledgements

1. SYNOPSIS

Create a configuration file and add this line to your ".forward" file:

where "LIB" is where the Tcl library lives, "FILE" is the name of your configuration file, and "USER" is your username.

1.1 Requirements

This package requires:

• Tcl/Tk version 8.0
• Trf version 1.8
• Tcl MIME version 1.1

1.2 Copyrights

(c) 1999 Marshall T. Rose

Hold harmless the author, and any lawful use is allowed.

2. PHILOSOPHY

The mailbot's philosophy is simple:

• The mailbot receives all of your incoming personal mail.
• You ALWAYS copy yourself on every message you send, so that the mailbot receives all of your outgoing personal mail.
• The mailbot performs five tasks:
  • makes audit copies of your incoming and outgoing mail;
  • performs duplicate supression;
  • performs originator supression by rejecting messages from people who aren't your friends or on a guest list;
  • sends a textual synopsis to your PDA; and,
  • sends a copy to your remote mailbox.

Do NOT use the personal.tcl mailbot if you receive mailing list traffic in your personal mailbox. When sending mail to a mailing list, either:

• use a "From" address that the personal.tcl mailbot will process as "impersonal" mail, (e.g., "[email protected]"); or,
• set the "Reply-To" for the message to the mailing list.

2.1 Guest Lists

Guest lists are an effective mechanism for cutting back on excessive mail.

• when the mailbot receives a message from you, it adds any recipients it finds to a permanent-guest list;
• when the mailbot receives a message from someone on a guest list, it adds any recipients it finds to a temporary-guest list; but,
• when the mailbot receives a message from someone not on any guest list, they get a rejection notice.

Here are the fine points:

• rejection notices contain a passphrase that may be used at most once to bypass the guest list mechanism (notices also contain the original message to minimize type-in by the uninvited);
• a flip-flop is used to avoid mail loops; and,
• messages originated by an administrative address (e.g., "Postmaster") bypass the guest list mechanism (unless the message refers to a previously-rejected message, in which case it is supressed).

The rejection notice should be written carefully to minimize an extreme negative reaction on the part of the uninvited. Of course, by allowing a passphrase, this provides something of a CQ test for the uninvited -- if someone can't pass the test...

3. BEHAVIOR

3.1 Arguments

The mailbot supports the following command line arguments:

-config configFile:

specifies the name of the configuration file to use;

-debug boolean:

enables debug output;

-file messageFile:

specifies the name of the file containing the message;

-originator orginatorAddress:

specifies the email-address of the originator of the message; and,

-user userName:

specifies the user-identity of the recipient.

The default values are:

Given the default values, only "-user" need be specified. The reason is that if a message is being delivered to multiple local recipients, and if any of the ".forward" files are identical in content, then sendmail may not deliver the message to all of the local recipients.

A few other (sendmail related) tips:

• If sendmail is configured with smrsh, you'll need to symlink personal.tcl into the /usr/libexec/sm.bin/ directory.
• Make sure that tclsh8.0 is in the path specified on the third-line of personal.tcl.
• You should chmod your ".forward" file to 0600.

3.2 Actions

The mailbot begins by parsing its arguments, sourcing configFile, and then examining the incoming message:

1. If auditInFile is set, a copy of the message is saved there.
2. If the message contains a previously-encountered "Message-ID", processing terminates.
3. If the message's originator can not be determined, a copy of the message is saved in the defaultMaildrop and processing terminates.
4. The originator's email-address is examined:
   1. If the originator appears to be an automated administrative process, and if a previously rejected email-address is found in the message, processing terminates.
   2. Otherwise, if the originator isn't the user, or a friend, or a permanent-access guest, or a temporary-access guest, and if noticeFile is set, then the message is rejected.
   3. Otherwise, each recipient email-address in the message's header is added to a guest list. (If the originator is the user, the permanent-guest list is used instead of the temporary-guest list.)
5. If the originator is the the user, then:
   1. If auditOutFile is set, saved there.
   2. Regardless, processing terminates.
6. If pdaMailboxes is set, and if any plaintext is contained in the message, then the plaintext is sent to those email-addresses.
7. If remoteMailboxes is set, and if the message is successful resent to those email-addresses, then processing terminates.
8. A copy of the message is saved in the defaultMaildrop and processing terminates.

3.3 The Configuration File

There are two kinds of information that may be defined in configFile: configuration options and configurable procedures.

Here's a simple example of a configFile for a user named "example":

3.3.1 Configuration Options

configFile must define dataDirectory and defaultMaildrop. All other configuration options are optional.

3.3.1.1 dataDirectory

The directory where the mailbot keeps its databases. The subdirectories are:

badaddrs:

the directory of rejected email-addresses

inaddrs:

the directory of originator email-addresses

msgids:

the directory of Message-IDs

outaddrs:

the permanent-guest list

phrases:

the directory of at-most-once passphrases

tmpaddrs:

the temporary-guest list

3.3.1.2 defaultMaildrop

The filename where messages are saved for later viewing by your user agent.

3.3.1.3 auditInFile

The filename where messages are saved for audit purposes.

3.3.1.4 auditOutFile

The filename where your outgoing messages are saved for audit purposes.

3.3.1.5 friendlyDomains

A list used by friendP giving the domain names where your friends live.

3.3.1.6 logFile

The filename where the mailbot logs its actions.

3.3.1.7 myMailbox

Your preferred email-address with commentary text, e.g.,

3.3.1.8 noticeFile

The filename containing the textual notice sent when a message is rejected. Note that all occurrances of "%passPhrase%" within this file are replaced with an at-most-once passphrase allowing the originator to bypass the mailbot's filtering. Similarly, any occurrences of "%subject%" are replaced by the "Subject" of the incoming message.

3.3.1.9 pdaMailboxes

The email-addresses where a textual synopsis of the incoming message is sent.

3.3.1.10 remoteMailboxes

The email-addresses where a copy of the incoming message is resent.

3.3.2 Configurable Procedures

All of these procedures are defined in personal.tcl. You may override any of them in configFile.

3.3.2.1 adminP

Returns "1" if the email-address is an automated administrative process.

3.3.2.2 friendP

Returns "1" if the email-address is from a friendly domain or sub-domain.

3.3.2.3 ownerP

Returns "1" if the email-address refers to the user (as determined by looking at myMailbox, pdaMailboxes, and remoteMailboxes.

3.3.2.4 saveMessage

Saves a copy of the message contained in the file inF. If the destination file, outF, isn't specified, it defaults to the defaultMaildrop.

3.3.2.5 findPhrase

Returns "1" if a previously-allocated passphrase is present in the subject. If so, the passphrase is forgotten.

3.3.2.6 makePhrase

Returns an at-most-once passphrase for use with a rejection notice.

3.3.2.7 pruneDir

Removes old entries from one of the mailbot's databases. The second parameter is one of "addr", "msgid", or "phrase".

3.3.2.8 tclLog

Writes a message to the logFile.

References

Author's Address

Appendix A. Impersonal Mail

If impersonalMail returns a non-empty string then the message is processed differently than the algorithm given in Actions. Specifically:

1. If the message contains a previously-encountered "Message-ID", processing terminates.
2. If the message's originator can not be determined, processing terminates.
3. The value returned by impersonalMail is the folder's name and is broken into one or more components seperated by dots ("."). If there aren't at least two components, or if any of the components are empty (e.g., the folder is named "sys..announce"), then the message is bounced.
4. If mappingFile exists, that file is examined to see if an entry is present for the folder. If so, the message is processed according to the value present, one of:

   "ignore":

   the message is silently ignored;

   "bounce":

   the message is noisily bounced; or,

   otherwise:

   the message is resent to the address.

   Regardless, if an entry was present for the folder, then processing terminates.
5. The message is saved in a file whose name is constructed by replacing each dot (".") in the folder name with a directory seperator (e.g., if the folder is named "sys.announce", then the file is called "announce" underneath the directory "sys" underneath the directory identified by foldersDirectory.
6. Finally, the file identified by foldersFile is updated as necessary.

A.1 Configuration Options

If "impersonal" mail is received, then foldersFile and foldersDirectory must exist.

A.1.1 foldersDirectory

The directory where the mailbot keeps private folders.

A.1.2 foldersFile

This file contains one line for each private folder.

A.1.3 announceMailboxes

The email-addresses where an announcement is sent when a new private folder is created.

A.1.4 mappingFile

The file consulted by the mailbot to determine how to process "impersonal" messages. Each line of the file consists of a folder name and value, seperated by a colon (":"). There are three reserved values: "bounce", "ignore", and "store".

A.2 Configurable Procedures

All of these procedures are defined in personal.tcl. You may override any of them in configFile.

A.2.1 impersonalMail

If the message is deemed "impersonal", return the name of a corresponding private folder; otherwise, return the empty-string.

Many mail systems have a mechanism of passing additional information when performing final delivery using a program. With modern versions of sendmail, for example, if mail is sent to a local user named "user+detail", then, in the absense of an alias for either "user+detail" or "user+*", then the message is delivered to "user". The trick is to get sendmail to pass the "detail" part to the mailbot.

At present, sendmail passes this information only if procmail is your local mailer. Here's how I do it:

This makes available an environment variable called "SUFFIX" which has the "details" part. The drawback in this approach is that this information is lost if the message is re-queued for delivery (what's really needed is an addition to the .forward syntax to allow macros such as $h to be passed).

The corresponding impersonalMail procedure is defined as:

Appendix B. An Example configFile

Here is the ".forward" file for the user "hewes":

(Of course, it's all on one line.)

Here is the user's ".personal/config.tcl" file:

Note that because remoteMailboxes isn't defined, personal messages are ultimately stored in the user's defaultMaildrop.

Appendix C. Acknowledgements

The original version of this mailbot was written by the author in 1994, implemented using the safe-tcl package (Borenstein and Rose, circa 1993).