T M D A

  
TMDA Homepage TMDA @ SourceForge      
Overview
Introduction
History
Features
Results & Testimonials
TMDA In Use
 
Usage
Requirements
Download
Installation
Configuration
 
Configuration
Overview
Pre-Configuration
Server Configuration
Client Configuration
Filter Specification
 
Support
FAQ
Mailing Lists
Bugs & Patches
External Resources
 
Author
Jason R. Mastaler
 
© 2002
  

TMDA Filter Specification

TMDA filter files are used to control mail both coming in to and going out of TMDA. For incoming, the filter controls how the message is disposed of. For outgoing, it controls how the message is tagged. The incoming filter file default is ~/.tmda/filters/incoming, which can be changed by setting FILTER_INCOMING in your tmdarc. The outgoing filter file default is ~/.tmda/filters/outgoing, which can be changed by setting FILTER_OUTGOING.

Format of Filter Files:

Each line of a filter file is expected to be a string containing three unquoted fields separated by whitespace. Everything after # on a line is considered a comment and ignored. Blank lines and lines with invalid syntax are also ignored: Lines are read sequentially from top to bottom, and the first match wins. The three fields are:

source match action

  • source: specifices the source of the match and can be one of:

    (for both incoming and outgoing):
    to (recipient address)
    to-file
    to-cdb
    to-dbm
    
    
    (for incoming only):
    from (sender address)
    from-file
    from-cdb
    from-dbm
    body (message body)
    body-file
    headers (message headers)
    headers-file
    size (message size)
    
    
  • match: should be an expression, or the full path to a textfile, CDB database, or DBM database containing more expressions if source was suffixed with `-file', `-cdb', or `-dbm'.

    The second field within a textfile, CDB or DBM is optional, but overrides action if present. e.g,
    foo@mastaler.com
    bar@mastaler.com bounce
    
    
    In a CDB or DBM, the keys should be the e-mail addresses to match, and their corresponding values (or records) should be empty unless you want to override the action specified in the filter file. Example scripts are included in the contrib directory to convert your TMDA-style lists into CDB/DBM files and vice-versa. These are list2cdb/list2dbm and printcdb/printdbm. For CDB, you can also use the utilities (cdbmake, cdbdump, etc.) from DJB's CDB distribution if you prefer. DBM support comes with your Python intrepreter, but CDB support currently requires that you first install the python-cdb extension module. Also see this message for more on installing python-cdb.

    The following table shows what the match expression should contain for a given source:

    source:		match:
    -------		------
    to*		recipient e-mail address or wildcard expression.
    from*		sender e-mail address or wildcard expression.
    body*		regular expression matching message body content.
    headers*	regular expression matching message header content.
    size		comparison operator and number of bytes to compare to the
    		size of the message.  Only `<' and `>' are supported.
    
    
    NOTE: To match the empty envelope sender such as bounce messages are sent with, use <> as the expression.

    In addition to explicit e-mail addresses, you can use expressions based on UNIX shell-style wildcard characters in either the match field of a line, or within the textfile in the match field. Wildcard characters are not recognized in a CDB or DBM file. The special characters are:
    
    Characters(s)    Description
    -------------    -----------
    *                Matches everything.
    ?                Matches any single character.
    [seq]            Matches any character in seq.
    [!seq]           Matches any character not in seq.
    
    
    In addition, `@=' (a custom rule) will expand to match both @ and @*.

    Here are some common examples:
       
    # match only jdoe@domain.dom
    jdoe@domain.dom
    # match anyone@domain.dom, but not anyone@sub.domain.dom
    *@domain.dom 
    # match anyone@sub.domain.dom, but not anyone@domain.dom
    *@*.domain.dom
    # match both anyone@domain.dom, and anyone@sub.domain.dom
    *@=domain.dom   
    
    
    The body* and headers* sources on the other hand take regular expressions as defined in Python's re module.

  • action: action specifies what action to take on the message. An optional = separates the action from the action's option. Possible values differ based on whether the message is incoming or outgoing.

    (for incoming, action can be one of):
    bounce,reject (bounce the message)
    drop,exit,stop (silently drop the message)
    ok,accept,deliver (deliver the message)
    confirm (request confirmation for the message)
    
    
    (for outgoing, action can be one of):
    bare (don't tag)
    bare=append (don't tag, and also add recipient to your BARE_APPEND file)
    sender (tag with a sender address based on recipient)
    sender=address (tag with a sender address based on address instead)
    dated (tag with a dated address)
    dated=timeout_interval 
    exp,explicit,as=full_address (use an explicit address)
    ext,extension=address_extension (add an extension to the address)
    kw,keyword=keyword (tag with a keyword address)
    
    
    Example Incoming Filter:
    
    ### ~/.tmda/filters/incoming (first match wins) ###
    
    # Accept all bounces (messages with an empty envelope sender)
    from <> ok
    
    # Accept all messages to postmistress
    to postmistress@* accept
    
    # Bounce all messages from badboy.dom
    from *@=badboy.dom bounce
    
    # Accept all messages from mycorp.dom
    from *@=mycorp.dom ok
    
    # Include my blacklist and whitelist
    from-dbm ~/.tmda/lists/blacklist.db drop
    from-cdb ~/.tmda/lists/whitelist.cdb accept
    from-file ~/.tmda/lists/whitelist_wildcards accept
    
    # Revoked addresses
    to jason-stupid-promo.289076@mastaler.com bounce
    to jason-jcrew.832234@mastaler.com confirm
    
    # Examine the message content
    body (viagra|ginseng) confirm
    headers (Precedence:.*junk) reject
    
    # Accept all messages smaller than 10KB, but drop messages larger than 1MB
    size <10000 deliver
    size >1000000 exit
    
    
    Example Outgoing Filter:
    
    #### ~/.tmda/filters/outgoing (first match wins) ###
    
    # All whitelisted contacts receive untagged messages
    to-cdb ~/.tmda/lists/whitelist.cdb bare
    to-file ~/.tmda/lists/whitelist_wildcards bare
    
    # Keyword Addresses
    to *@myisp.net kw=myisp
    to king@grassland.com keyword=elvis_parsley
    
    # Dated addresses (some with a non-default timeout interval)
    to bobby@peru.com dated
    to-dbm /var/dbm/slowpokes.db dated=6M
    
    # Several ways of handling subscriber-only mailing lists
    to *postfix-users*@postfix.org keyword=postfix-users
    to exim-users@exim.org extension=mlist-exim-users
    to-file ~/.lists ext=mlists
    to owner-python-crypto@nic.surfnet.nl sender
    to python-crypto@* sender=owner-python-crypto@nic.surfnet.nl
    
    # Use a different username and/or domain
    to *@gnus.org exp=jason@gnus.org
    to xemacs-binary-kits* explicit=binkit-manager@XEmacs.ORG
    to *mail*@=xemacs.org as=postmaster@XEmacs.ORG
    to *@=xemacs.org as=jasonrm@xemacs.org