portmanteau(1)

NAME
portmanteau - generates Spamassassin rules from definition files

SYNOPSIS
portmanteau [srcedir] [outfile]

DESCRIPTION
portmanteau provides an easier way to maintain portmanteau rules for Spamassassin. These are rules with a large number of alternates. They are difficult to read because if they have more than 4-5 alterates the rule definition exceeds the screen width or must to be broken into a set of sub rules and a meta that ORs them together. Either way they are hard to maintain.

portmanteau reads a set of definition files and generates a file holding all the generated rules. Each definition file holds all the information needed to generate one Spamassassin rule and is designed to be easier to maintain than the equivalent hand-written rule. A definition sets a few items such as the rule name, description, score and which part of the message it scans. These are followed by a list of alternates, one per line.

The generated rules may be referenced from any other locally generated rules provided that the portmanteau output file has a .cf extension and is put in the same place as the other locally defined rules, typically /etc/mail/spamassassin

If portmanteau finds errors, the details are written to the output file along with the contents of the of the definition file being processes. The error count for the file is sent to stderr and the run continues.

Note: the output file is not guaranteed to be error free or to be acceptable to SpamAssassin because the syntax of alternates is not validated. Since rigorous error checking can only be done by a Spamassassin --lint check, it is responsibility of the user to run these checks.

OPTIONS

-?  display summary help for portmanteau

ARGUMENTS

srcedir
    The directory holding the rule definition files.

outfile
    The pathname name of the output file, which will hold all the generated rules.

Arguments are optional. If they are omitted the default values will, be used. These are defined in the portmanteau configuration file.

CONFIGURATION
The default values for srcedir and outfile are defined in the configuration file, portmanteau.conf which will be searched for in the following locations:
/etc
/usr/local/etc
the current working directory

The directories are searched in the order given. If more than one configuration file is found during the search, the values from the last one found take precedence. This allows a rule development environment to be defined that does not overwrite live rules.

Within portmanteau.conf blank lines will be ignored and lines starting with a hash (#) are treated as comments. The only significant lines define the srcedir and outfile defaults and are written exactly as follows:

SRCEDIR=directory_name
OUTFILE=outfile_name

Example lines:

# srcedir defined relative to the working directory
SRCEDIR=ruledefs
# Output file defined as an absolute pathname
OUTFILE=/etc/mail/spamassassin/portmanteau.cf

RULE DEFINITIONS
Each rule definition is held in a separate text file which must have the .def extension.

Blank lines are ignored.

Lines starting with a hash (#) are treated as comment and ignored.

A rule definition consists of statements declaring the static properties of the rule, such as its name and description, followed by one or more lists of alternates, each preceded by a scan directive, which will be combined to form a regex. This takes the general form:

/(alt1|alt2|alt3)/

where alt1, alt2, alt3, ... are the alternates. If more than one alternates list is included in the definition a subrule is created for each list using a name constructed from the subrule name supplied by the meta declaration. A meta rule is generated to combine the subrules.

  Declarations
The common properties of a rule must be declared before the first alternates list. Each declaration is a single line starting with the declaration name, which is followed by a value. The name and value are separated by whitespace.

rule rulename
    Declares the Spamassassin rule name. Mandatory.

describe Spamassassin rule description
    Describes the Spamassassin rule with a sentence. Mandatory.

score value
    Sets the Spamassassin rule score. Default is 1.0

wordlim yes|no
    "yes" encloses the alternates list with \b....\b. Defaults to "no".

caseless yes|no
    "yes" uses case-insensitive matching. Defaults to "no".

meta subrule
    Must be present if the rule uses more than one alternates list. Its value is used to construct subrule names with the form "__subrule9" where "9" is a number starting from zero.

tflags flaglist
    Used if the tflags directive is to be included in this rule. "flaglist" is a comma separated list of valid Spamassassin tflag values. The list must not have included spaces and the tflag names are not validated.

  The scan directive
A scan directive should immediately preceed an alternates list. It defines the type of rule that will be generated and can take one of two forms:

scan ruletype
    The ruletype is one of the recognised Spamassassin rule types, e.g. body, rawbody, uri, etc.

scan header headertype
    The header type sets the type of message header that the rule applies to, e.g. From, Subject, etc.

  The alternates list
The alternates list is simply a list of regexes, one per line. No prefixes or suffixes are needed. Valid examples are:

get your meds here
www.spammer.com
www..{1,30}.spamming-webhost.(com|org|net)

EXAMPLE
Here is an example of a rule definition that uses all declarations and two alternate lists:

#
# All possible declarations set
#
rule      ALLUSED
describe  All possible declarations used
score     42
wordlim   yes
caseless  yes
meta      AU
tflags    noautolearn,multiple
scan body
alt1
alt2
alt3
scan header From
alt1
alt2
alt3

And here is the rule it generated:

#
# All possible declarations set
#
describe ALLUSED All possible declarations used
body     __AU0 /\b(alt1|alt2|alt3)\b/i
header   __AU1 From =~ /\b(alt1|alt2|alt3)\b/i
meta     ALLUSED (__AU0||__AU1)
tflags   ALLUSED noautolearn,multiple
score    ALLUSED 42

BUGS
portmanteau contains only minimal definition file validation. It is assumed that its output will be checked with a spamassassin --lint check and/or by visual inspection. The user should be aware that:

*   Anything that is not explicitly recognised as a blank line, comment, declaration or scan directive is assumed to be an alternate.

*   A rule may only have a single score value. Score value lists are not supported.

*   The tflags declaration does not check whether the supplied flag names are valid and expects, but does not check, that the list does not contain spaces. The list is terminated by the first included space.

*   No checks are made on the type of rule specified as the first argument of the scan directive and, if a header scan is requested, no check is made on the header type being compared.