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, their optional parts 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 the 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 over the message. Syntactically, each action is

command [=] right-hand-side

Where command specifies the operation and right-hand-side specifies its arguments. The equal sign is optional.

5.2 Conditional Statements

A conditional statement defines control flow within the 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

(square brackets denoting optional parts). Its parts are:

part

Specifies which part of the input should be considered when evaluating the condition. It is either `command', meaning the text of the 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

Regular expression enclosed in double quotes.

The condition yields true if regex matches the part (if op is `='), or does not match it (if op is `!=').

For 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.

A more elaborate form of the 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, action-list-1 is executed if the condition is met. Otherwise, action-list-2 is executed.

Note, that both action-list-1 and action-list-2 can in turn contain conditionals, so that the conditional statements may be nested. This allows for creating 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  

The effect of this statement is: depending on the value of List-Id header, prepend the Subject header with an identification string, or add an X-Passed header if no known List-Id was found.

To simplify writing such nested conditional statements, the `elif' keyword is provided:

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

This statement is equivalent to:

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

Any number of `elif' branches may appear in a conditional statement, the only requirement being that they appear before the `else' statement, if it is used.

5.2.1 Concatenations

It is important to understand that conditional expressions choose the first match. To illustrate this, lets suppose you wish to store all recipient emails 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 containing all RCPT TO addresses, separated by commas, and then 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 trigger acts 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, if you send an email with the subject ending on `@@gpg-encrypt-john' (e.g.: `Subject: hello John!@@gpg-encrypt-john'), it will be encrypted with John's public key. The trigger will remove the `@@' and the characters following it, so John will only receive a message with `hello John!' as a subject.

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.

5.4 Boolean Operators

The following table lists the 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. The former are always supported, whereas the support for the latter depends on the configuration settings at compile time. By default POSIX extended regexps are assumed.

Regular expressions often contain characters, prefixed with a backslash (e.g. `\(' in basic POSIX or `\s' in perl-style regexp). Due to escape substitution (see backslash-interpretation), 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 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 processing of the section immediately. It can 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 invokes 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 adds 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!"

To add text to the body of the message, use:

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 remove command removes headers 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 modify command alters headers or 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 can contain back references. For example, the following statement selects all headers whose names start with `X-' and changes 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"

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 Modifying SMTP Commands

GNU Anubis is able to modify arguments of SMTP commands. To instruct it to do so, define a section named `SMTP'. Anubis will call this section each time it receives an SMTP command. This section can contain any statements allowed for `RULE' section, plus the following special flavor of the `modify' statement:

Command: modify [flags] command `['cmd`]' value

If the current SMTP command matches cmd, rewrite it by using value as its argument.

For example, this is how to force using `my.host.org' as the `EHLO' argument:

BEGIN SMTP
modify command [ehlo] "my.host.org"
END

Additionally, the ESMTP authentication settings (see section ESMTP Authentication Settings) can be used as actions in this section. To do so, you must first set esmtp-auth-delayed to `yes' in the `CONTROL' section (see section esmtp-auth-delayed). Changes in the settings take effect if they occur either before the `MAIL' SMTP command, or while handling this command.

Consider, for example, the following configuration:

BEGIN CONTROL
 mode transparent
 bind 25
 remote-mta mail.example.com
 esmtp-auth-delayed yes
END

BEGIN SMTP
if command ["mail from:"] "<smith(\+.*)?@example.net>"
  esmtp-auth-id smith
  esmtp-password guessme
else
  esmtp-auth no
fi
END

It delays ESMTP authentication until the receipt of the MAIL command from the client. Authentication is used only if the mail is being sent from smith@example.net or any additional mailbox of that user (e.g. smith+mbox@example.net). Otherwise, authentication is disabled.

The following points are worth mentioning:

1. As usual, you may use conditional expressions to decide what to modify and how. For example, the code below replaces the domain part of each `MAIL FROM' command with `gnu.org':

   BEGIN SMTP if command ["mail from:"] "<(.*)@(.*)>(.*)" modify command ["mail from:"] "<\1@gnu.org>\2" fi END

2. Each `modify command' statement applies only if the current command matches its cmd argument. In particular, this means that you cannot modify already transferred SMTP commands nor the commands to be transferred. For example, the following code will not work:

   BEGIN SMTP # Wrong! if command ["mail from:"] "<>(.*)" modify command [ehlo] "domain.net" fi END

   It is because by the time `MAIL FROM' is received, the `EHLO' command has already been processed and sent to the server.

The final point to notice is that you may use an alternative name for that section (if you really want to). To do so, define the new name via the `smtp-command-rule' option in the `CONTROL' section (see section smtp-command-rule).

5.6.7 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.

Default is `no'.

Command: body-append file-name

This action command includes at the end of the message body the contents of the given file. Unless `file-name' starts 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.8 Mail Encryption

Command: gpg-passphrase passphrase

Specifies your private key's pass phrase for signing messages using the GNU Privacy Guard. To protect your passwords from being compromised, use the 0600 (u=rw,g=,o=) permissions for the configuration file, 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 support for the GNU Privacy Guard is based on the GnuPG Made Easy library, available from http://www.gnupg.org/gpgme.html.

Command: gpg-encrypt gpg-keys

This command enables encrypting messages 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 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 the 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 gpg-signer-key part is optional. In the absence of it, 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.9 Using an External Processor

Command: external-body-processor program [args]

Pipes the message body through program. The program must be a filter that reads the text from the standard input and prints the transformed text on the standard output. The output from it replaces the original 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 body 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.10 Quick Example

Here is a quick example of 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 removes the `X-Mailer:' header from the message, adds the `X-Comment:' header, then signs the message with your private key, and finally adds a signature from the file in your home directory.

5.7 Using Guile Actions

Guile is the GNU's Ubiquitous Intelligent Language for Extensions. It provides a Scheme interpreter conforming to the R5RS 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 (r5rs)Top section `Top' in Revised(5) 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, replaces it with `Re:'. It also adds the header

X-Processed-By: GNU Anubis

Additionally, an optional argument can be used. If it is given, it will be 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

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, 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 do so 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 cases when you need to use an external filter that processes 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 input and produces on standard output a modified version of this message. The program takes the name of a directory for temporary files as its argument. 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 on May, 24 2014 using texi2html 1.76.