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.

This document was generated on January 6, 2024 using texi2html 5.0.