5. The Rule System

The rule system is a core part of GNU Anubis. It can be regarded as a program that is executed for every outgoing message.

Throughout this chapter, when showing syntax definitions, the optional parts of these will be enclosed in a pair of square brackets, e.g.:

keyword [optional-part] mandatory-part

When the square braces are required symbols, they will be marked as such, e.g.:

remove ‘[’key‘]’

The rule system is defined in RULE section. The statements within this section are executed sequentially. Each statement is either an action or a conditional statement.

5.1 Actions

An action is a statement defining an operation to be performed over the message. Syntactically, each action is

command [=] right-hand-side

Where command specifies a particular operation and right-hand-side specifies the arguments for it. The equal sign is optional.

5.2 Conditional Statements

A conditional statement defines the control flow in a section. It allows to execute arbitrary actions depending on whether a certain condition is met. The conditional statement in its simplest form is:

if condition
  action-list-1
fi

If condition evaluates to true, then the list of statements action-list-1 is executed.

A simple condition has the following syntax:

part [sep] [op] [pattern-match-flags] regex

(where the square brackets denote optional parts). Its parts are:

part

The part specifies which part of the input should be considered when evaluating the condition. It is either ‘command’, meaning the text of an smtp command issued while sending the message, or ‘header’, meaning the value of an RFC822 header. Either of the two may be followed by the name of the corresponding command or header enclosed in square brackets. If this part is missing, all command or headers will be searched.

sep

Optional concatenation separator. See section Concatenations, for its meaning.

op

Either ‘=’, meaning “match”, or ‘!=’, meaning “does not match”. Missing op is equivalent to ‘=’.

pattern-match-flags

Optional pattern-match-flags alter the pattern matching type used in subsequent conditional expression. It will be described in detail in the section Regular Expressions.

regex

The regex is a regular expression enclosed in double quotes.

The condition yields true if the requested part of the input matches the given regular expression (if op is ‘=’), or does not match it (if op is ‘!=’).

The simplest example:

if header [Subject] "^ *Re:"
  ...
fi

The actions represented by … will be executed only if the ‘Subject:’ header of the message starts with ‘Re:’ optionally preceded by any amount of whitespace.

The more elaborate form of a conditional allows you to choose among the two different action sets depending on a given condition. The syntax is:

if condition
  action-list-1
else
  action-list-2
fi

Here, the action-list-1 is executed if the condition is met. Otherwise, action-list-2 is executed.

if condition
  action-list-1
else
  action-list-2  
fi

Note also, that in the examples above any of the statements action-list may contain conditionals, so that the conditional statements may be nested. This allows to create very sophisticated rule sets. As an example, consider the following statement:

if [List-Id] :re ".*<anubis-commit@gnu.org>"
  modify [Subject] "[Anubis Commit Notice] &"
else
  if [List-Id] :re ".*<bug-anubis@gnu.org>"
    modify [Subject] "[Anubis Bug Notice] &"
  else
    add [X-Passed] "Subject checking"
  fi
fi  

This statement, depending on the value of List-Id header, will prepend the Subject header with an identification string, or add an X-Passed header if no known List-Id was found.

5.2.1 Concatenations

It is important to understand that conditional expressions choose the first match. To illustrate this, lets suppose you need to store values of all recipients from the envelope in the ‘X-Also-Delivered-To’ header. A naive way to do so is:

if command [rcpt to:] = "(.*)"
  add header [X-Also-Delivered-To] "\1"
fi

However, this will store only the very first RCPT TO value, so you will not achieve your goal.

To help you in this case, anubis offers a concatenation operator, whose effect is to concatenate the values of all requested keys prior to matching them against the regular expression. Syntactically, the concatenation operator is a string enclosed in parentheses, placed right after the key part of a condition. This string is used as a separator when concatenating values. For example:

if command [rcpt to:] (",") = "(.*)"
  add header [X-Also-Delivered-To] "\1"
fi

This fragment will first create a string consisting of all RCPT TO addresses, separated by a comma, and then will match it against the regular expression on the right hand side. Since this expression matches any string, the ‘\1’ will contain a comma-separated list of addresses.

5.3 Triggers

Triggers are conditional statements that use the value of the ‘Subject’ header to alter the control flow. Syntactically, a trigger is:

trigger [flags] pattern
  action-list
done

Here, pattern is the pattern against which the ‘Subject’ header is checked, flags are optional flags controlling the type of regular expression used (see section Regular Expressions). For backward compatibility, the keyword rule may be used instead of trigger.

The triggers act as follows: First, the value of the ‘Subject’ header is matched against the pattern ‘@@’pattern. If it matches, then the matched part is removed from the ‘Subject’, and the action-list is executed.

Basically, putting aside the possibility to use different flavors of regular expressions, a trigger is equivalent to the following statement:

if header[Subject] :posix "(.*)@@pattern"
  modify header [Subject] "\1"
  action-list
fi

Thus, adding the ‘@@rule-name’ code to the ‘Subject’ header of your message, triggers a rule named rule-name, specified in a user configuration file. For example:

---BEGIN RULE---
trigger :basic "^gpg-encrypt-john"
   gpg-encrypt "john's_gpg_key"
done
---END---

Now you can simply send an email with the following subject: ‘hello John!@@gpg-encrypt-john’ to process an outgoing message with the rule specified above—encrypt message with a John's public key. Moreover, the trigger will remove the ‘@@’, so John will only receive a message with a subject ‘hello John!’.

Another example shows an even more dynamic trigger, that is using a substitution and back-references:

---BEGIN RULE---
trigger :extended "^gpg-encrypt:(.*)"
   gpg-encrypt "\1"
   add [X-GPG-Comment] "Encrypted for \1"
done
---END---

To encrypt a message to user e.g. ‘John’, simply send an email with a subject ‘hello John!@@gpg-encrypt:john's_gpg_key’. This way, you decide at a run time which public key should be used, without creating separate rules for each user; thanks to back-references, those 3—4 lines are enough.

5.4 Boolean Operators

The following table lists the three boolean operators that can be used in Anubis conditional expressions in the order of increasing binding strength:

• ‘OR’
• ‘AND’
• ‘NOT’

As an example, let's consider the following statement:

if header[X-Mailer] "mutt" or header[X-Mailer] "mail" \
   and not header[Content-Type] "^multipart/mixed;.*"
   action
fi

In this case the action will be executed if the X-Mailer header contains the word ‘mutt’. The same action will also be executed if the X-Mailer header contains the word ‘mail’ and the value of the Content-Type header does not begin with the string ‘multipart/mixed’.

Now, if we wished to execute the action for any message sent using mail or mutt whose Content-Type header does not begin with the string ‘multipart/mixed’, we would write the following:

if (header[X-Mailer] "mutt" or header[X-Mailer] "mail") \
   and not header[Content-Type] "^multipart/mixed;.*"
   action
fi

Notice the use of parentheses to change the binding strength of the boolean operators.

5.5 Regular Expressions

GNU Anubis supports two types of regular expressions: POSIX (both basic and extended), and Perl-style regular expressions. Among this, the former are always supported, whereas the support for the latter depends on the configuration settings at compile time. The default type of regular expressions is POSIX Extended.

Notice, that regular expressions often contain characters, prefixed with backslash (e.g. ‘\(’ in basic POSIX or ‘\s’ in perl-style regexp). Due to escape substitution (see section Configuration), you will have to escape the backslash character, e.g. write:

modify :perl body ["\\stext"] "text"

instead of

# WRONG!
modify :perl body ["\stext"] "text"

However, this rule does not apply to back references, i.e. "\1" is OK.

A number of modifiers is provided to change the type of regular expressions. These are described in the following table.

:regex

:re

Indicates that the following pattern should be considered a regular expression. The default type for this expression is assumed.

:perl

:perlre

The regular expression is a Perl-style one.

:exact

:ex

Disables regular expression matching, all patterns will be matched as exact strings.

:scase

Enables case-sensitive comparison.

:icase

Enables case-insensitive comparison.

:basic

Switches to the POSIX Basic regular expression matching.

:extended

Switches to the POSIX Extended regular expression matching.

The special statement regex allows you to alter the default regular expression type. For example, the following statement

regex :perl :scase

sets the default regular expression types to Perl-style, case-sensitive. The settings of regex statement regard only those patterns that appear after it in the configuration file and have force until the next occurrence of the regex statement.

A couple of examples:

if header[Subject] :perlre "(?<=(?<!foo)bar)baz"
 ...
fi

This will match any Subject header whose value matches an occurrence of ‘baz’ that is preceded by ‘bar’ which in turn is not preceded by ‘foo’.

if header[Subject] :scase "^Re"

will match a Subject header whose value starts with ‘Re’, but will not match it if it starts with ‘RE’ or ‘re’.

When using POSIX regular expressions, the extended syntax is enabled by default. If you wish to use a basic regular expression, precede it with the :basic flag.

For the detailed description of POSIX regular expressions, See (regex)Top section `Regular Expression Library' in Regular Expression Library. For information about Perl-style regular expressions, refer to the Perl documentation.

5.6 Action List

An action list is a list of action commands, which control processing of an outgoing messages. All action command names are case insensitive, so you can use for instance: ‘add’ or ‘ADD’ or ‘AdD’, and so on.

5.6.1 Stop Action

The stop command stops immediately the processing of the section. It may be used in the main RULE section as well as in any user-defined section. For example:

if not header[Content-Type] "text/plain; .*"
  stop;
fi

5.6.2 Call Action

The call command allows to invoke a user-defined section much in the same manner as a subroutine in a programming language. The invoked section continues to execute until its end or the stop statement is encountered, whichever the first.

BEGIN myproc
if header[Subject] "Re: .*"
  stop;
fi
trigger "pgp"
  gpg-encrypt "my_gpg_key"
done
END

BEGIN RULE
call myproc
END

5.6.3 Adding Headers or Text

The add command allows you to add arbitrary headers or text to the message. To add a header, use the following syntax:

Command: add header ‘[’name‘]’ string

Command: add ‘[’name‘]’ string

For example:

add header[X-Comment-1] "GNU's Not Unix!" add [X-Comment-2] "Support FSF!"

Command: add body text

Adds the text to the message body. Use of this command with ‘here document’ syntax allows to append multi-line text to the message, e.g.:

add body <<-EOT Regards, Hostmaster EOT

5.6.4 Removing Headers

The command remove removes the specified header from the message. The syntax is:

Command: remove [flags] header ‘[’string‘]’

Command: remove [flags] ‘[’string‘]’

The name of the header to delete is given by string parameter. By default only those headers are removed whose names match it exactly. Optional flags allow to change this behavior. See section Regular Expressions, for the detailed description of these.

An example:

remove ["X-Mailer"] remove :regex ["^X-.*"]

The first example will remove the ‘X-Mailer:’ header from an outgoing message, and the second one will remove all "X-*" headers.

5.6.5 Modifying Messages

The action command modify allows to alter the headers or the body of the message.

Command: modify [flags] header ‘[’key‘]’ ‘[’new-key‘]’

Command: modify [flags] ‘[’key‘]’ ‘[’new-key‘]’

For each header whose name matches key, replaces its name with new-key. If key is a regular expressions, new-key may contain back references. For example, the following statement will select all headers whose names start with ‘X-’ and change their names to begin with ‘X-Old-’:

modify header :re ["X-\(.*\)"] ["X-Old-\1"]

Command: modify [flags] header ‘[’key‘]’ value

Command: modify [flags] ‘[’key‘]’ value

For each header whose name matches key, changes its value to value. For example:

modify [Subject] "New subject"

This statement sets the new value to the Subject header.

Every occurrence of unescaped ‘&’ in the new value will be replaced by the old header value. To enter the ‘&’ character itself, escape it with two backslash characters (‘\\’). For example, the following statement

modify [Subject] "[Anubis \\& others] &"

prepends the Subject header with the string ‘[Anubis & others]’. Thus, the header line

Subject: Test subject

after having been processed by Anubis, will contain:

Subject: [Anubis & others] Test subject

Command: modify [flags] header ‘[’key‘]’ ‘[’new-key‘]’ value

Command: modify [flags] ‘[’key‘]’ ‘[’new-key‘]’ value

Combines the previous two cases, i.e. changes both the header name and its value, as shown in the following example:

modify header [X-Mailer] [X-X-Mailer] "GNU Anubis"

Command: modify [flags] body ‘[’key‘]’

Removes all occurrences of key from the message body. For example, this statement will remove every occurrence of the word ‘old’:

modify body ["old"]

Command: modify [flags] body ‘[’key‘]’ string

Replaces all occurrences of key with string. For example:

modify body :extended ["the old \([[:alnum:]]+\)"] "the new \1"

5.6.6 Inserting Files

Command: signature-file-append yes-or-no

This action command adds at the end of a message body the ‘-- ’ line, and includes a client's ‘~/.signature’ file. Value ‘no’ is the default.

Command: body-append file-name

This action command includes at the end of a message body the contents of the given file. If ‘file-name’ does not start with a ‘/’ character, it is taken relative to the current user home directory

Command: body-clear

Removes the body of the message

Command: body-clear-append file-name

Replaces the message body with the contents of the specified file. The action is equivalent to the following command sequence:

body-clear body-append file-name

5.6.7 Mail Encryption

Command: gpg-passphrase passphrase

Specifies your private key's pass phrase for signing an outgoing message using the GNU Privacy Guard (a tool compatible with the Pretty Good Privacy). Of course, to protect your passwords in the configuration file use the 0600 (u=rw,g=,o=) permissions, otherwise GNU Anubis won't accept them. We recommend setting the ‘gpg-passphrase’ once in your configuration file, e.g. at the start of RULE section.

GNU Anubis supports the GNU Privacy Guard via the GnuPG Made Easy library, available at http://www.gnupg.org/gpgme.html.

Command: gpg-encrypt gpg-keys

This command enables encrypting your outgoing message with the GNU Privacy Guard (Pretty Good Privacy) public key(s). gpg-keys is a comma separated list of keys (with no space between commas and keys).

gpg-encrypt "John's public key"

Command: gpg-sign gpg-signer-key

Command: gpg-sign ‘yes-or-default’

This command signs the outgoing message with your GNU Privacy Guard private key. Specify a passphrase with gpg-passphrase. Value ‘default’ means your default private key, but you can change it if you have more than one private key.

For example:

gpg-sign default

or

gpg-passphrase "my office key passphrase" gpg-sign office@example.key

Command: gpg-sign-encrypt gpg-keys[:gpg-signer-key]

Command: gpg-se gpg-keys[:gpg-signer-key]

This command simultaneously signs and encrypts your outgoing message. It has the same effect as gpg command line switch ‘-se’. The argument before the colon is a comma-separated list of PGP keys to encrypt the message with. This argument is mandatory. The second argument is optional and is separated from the first one by a colon (‘:’). This argument specifies the signer key. In the absence of the second argument your default private key is used.

For example:

gpg-sign-encrypt John@example.key

or

gpg-se John@example.key:office@example.key

5.6.8 Using an External Processor

Command: external-body-processor program [args]

Pipes the message body through program. program should be a filter program, that reads the text from the standard input and prints the transformed text on the standard output. The output from the program replaces the body of the message. args are any additional arguments the program may require.

The amount of data fed to the external program depends on the message. For plain messages, the entire body is passed. For multi-part messages, only the first part is passed by default. This is based on the assumption that in most multi-part messages the first part contains textual data, while the rest contains various (mostly non-textual) attachments. There is a special configuration variable read-entire-body that controls this behavior (see section Basic Settings). Setting read-entire-body yes in CONTROL section of your configuration file instructs Anubis to pass the entire contents of multi-part messages to your external processor.

There is a substantial difference between operating in read-entire-body no (the default) and read-entire-body yes modes. When operating in read-entire-body no, the first part of the message is decoded and then passed to the external program. In contrast, when read-entire-body is set to yes, the message is not decoded. Thus, your external processor must be able to cope with MIME messages.

5.6.9 Quick Example

Here is a quick example of using an action list:

---BEGIN RULE---
if header [X-Mailer] :re ".*"
   remove [X-Mailer]
   add [X-Comment] "GNU's Not Unix!"
   gpg-sign "my password"
   signature-file-append yes
fi
---END---

The example above will remove (on-the-fly) the ‘X-Mailer:’ line from an outgoing message, add an extra header line (‘X-Comment:’), sign your message with your private key, and add a simple signature file from your home directory.

5.7 Using Guile Actions

The name Guile stands for GNU's Ubiquitous Intelligent Language for Extensions. It provides a Scheme interpreter conforming to the R4RS language specification. GNU Anubis uses Guile as its extension language.

This section describes how to write GNU Anubis actions in Scheme. It assumes that the reader is sufficiently familiar with the Scheme language. For information about the language, refer to (r4rs)Top section `Top' in Revised(4) Report on the Algorithmic Language Scheme. For more information about Guile, See (guile)Top section `Overview' in The Guile Reference Manual.

Predefined Guile Actions

5.7.1 Defining Guile Actions

A Guile action is defined as follows:

(define (function-name header body . rest)
 ...)

Its arguments are:

header

List of message headers. Each list element is a cons

(name . value)

where name is the name of the header field, and value is its value with final CRLF stripped off. Both name and value are strings.

body

A string containing the message body.

rest

Any additional arguments passed to the function from the configuration file (see section Invoking Guile Actions). This argument may be absent if the function is not expected to take optional arguments.

The function must return a cons whose car contains the new message headers, and cdr contains the new message body. If the car is #t, it means that no headers are changed. If the cdr is #t, it means that the body has not changed. If the cdr is #f, Anubis will delete the entire message body.

As the first example, let's consider a no-operation action, i.e. an action that does not alter the message in any way. It can be written in two ways:

(define (noop-1 header body)
  (cons header body))
  
(define (noop-2 header body)
  (cons #t #t))

The following example is a function that deletes the message body and adds an additional header:

(define (proc header body)
  (cons (append header
                (cons "X-Body-Deleted" "yes"))
        #f))

Let's consider a more constructive example. The following function checks if the Subject header starts with string ‘ODP:’ (a Polish equivalent to ‘Re:’), and if it does, the function replaces it with ‘Re:’. It always adds to the message the header

X-Processed-By: GNU Anubis

Additionally, if the optional argument is given, it is appended to the body of the message.

(define (fix-subject hdr body . rest)
  "If the Subject: field starts with characters \"ODP:\", replace
them with \"Re:\".
If REST is not empty, append its car to BODY"
  (cons (append
	 (map (lambda (x)
		(if (and (string-ci=? (car x) "subject")
			 (string-ci=? (substring (cdr x) 0 4) "ODP:"))
		    (cons (car x)
			  (string-append "Re:"
					 (substring (cdr x) 4)))
		    x))
	      hdr)
	 (list (cons "X-Processed-By" "GNU Anubis")))
	(if (null? rest)
	    #t
	    (string-append body "\n" (car rest)))))

5.7.2 Invoking Guile Actions

The Guile actions are invoked from the RULE section using the guile-process command. Its syntax is:

Scheme Function: function args

Arguments:

function

The name of the Guile function to be invoked.

args

Additional arguments. These are passed to the function as its third argument (rest).

To pass keyword arguments to the function, use the usual Scheme notation: ‘#:key’.

As an example, let's consider the invocation of the fix-subject function, defined in the previous subsection:

guile-process fix-subject <<-EOT
                                ----------
                                Kind regards,
                                Antonius Block
                          EOT

In this example, the additional argument (a string of three lines) is passed to the function, which will add it to the message of the body.

5.7.3 Support for ROT-13

The ROT-13 transformation is a simple form of encryption where the letters A-M are transposed with the letters L-Z. It is often used in Usenet postings/mailing lists to prevent people from accidentally reading a disturbing message.

GNU Anubis supports ROT-13 via a loadable Guile function. To enable this support, you will have to add the following to your GUILE section:

guile-load-program rot-13.scm

Then, in your RULE section use:

Scheme Function: rot-13 keyword-arguments

The command accepts the following keyword-arguments:

#:body

Encrypt the entire body of the message

#:subject

Encrypt the ‘Subject’ header.

For example:

trigger "rot-13.*body" guile-process rot-13 #:body done trigger "rot-13.*subj" guile-process rot-13 #:subject done

5.7.4 Remailers Type-I

GNU Anubis supports remailers of type I. The support is written entirely in Scheme. To enable it you need to specify the following in the GUILE section of your configuration file:

guile-load-program remailer.scm

To send the message via a remailer, use the following command in the RULE section:

Scheme Function: remailer-I keyword-arguments

The keyword-arguments specify the various parameters for the remailer. These are:

#:rrt string

This is the only required keyword argument. It sets the value for the Request Remailing To line. string should be your actual recipient's email address.

#:post news-group

Adds the ‘Anon-Post-To: news-group’ line, and prepares the message for sending it to the Usenet via a remailer. Note, that this is only possible with remailers that support ‘Anon-Post-To:’ header.

#:latent time

Adds the ‘Latent-Time:’ line, that causes a remailer to keep your message for specified time before forwarding it.

#:random

Adds random suffix to the latent time.

#:header string

Adds an extra header line to the remailed message.

Example:

trigger "remail:(.*)/(.*)" guile-process remailer-I \ #:rrt antonius_block@helsingor.net \ #:post \1 \ #:latent \2 \ #:header "X-Processed-By: GNU Anubis & Remailer-I" done

Some remailers require the message to be GPG encrypted or signed. You can achieve this by placing gpg-encrypt or gpg-sign statement right after the invocation of remailer-I, for example:

trigger "remail:(.*)/(.*)"
 guile-process remailer-I \
             #:rrt antonius_block@helsingor.net \
             #:post \1 \
             #:latent \2 \
             #:header "X-Processed-By: GNU Anubis & Remailer-I"
 gpg-sign mykey
done

See section Mail Encryption, for more information on mail encryption in GNU Anubis.

5.7.5 Entire Message Filters

There may be some cases when you need to use an external filter that processes the entire message (including headers). You cannot use external-body-processor, since it feeds only the message body to the program. To overcome this difficulty, GNU Anubis is shipped with ‘entire-msg.scm’ module. This module provides Scheme function entire-msg-filter, which is to be used in such cases.

Scheme Function: entire-msg-filter program [args]

Feeds entire message to the given program. The output from the program replaces message headers and body.

progname

Full pathname of the program to be executed.

args

Any additional arguments it may require.

Suppose you have a program /usr/libexec/myfilter, that accepts entire message as its output and produces on standard output a modified version of this message. The program takes as its argument he name of a directory for temporary files. The following example illustrates how to invoke this program:

BEGIN GUILE
guile-load-program entire-msg.scm
END

BEGIN RULE
guile-process entire-msg-filter /usr/libexec/myfilter /tmp
END

Another function defined in this module is openssl-filter:

Scheme Function: openssl-filter program [args]

This function is provided for use with openssl program. Openssl binary attempts to rewind its input and fails if the latter is a pipe, so openssl cannot be used with entire-msg-filter. Instead, you should use openssl-filter. Its arguments are:

program

Path to openssl binary.

args

Its arguments

See section Using S/MIME Signatures, for an example of use of this function.

This document was generated by Sergey Poznyakoff on November, 5 2007 using texi2html 1.78.