GNU Mailutils

3.10.1.1 Invoking sieve

The sieve invocation syntax is:

sieve [options] script

Normally, script is the name of the disk file with the Sieve script. If script is a single dash, the script is read from the standard input. If the -E (--expression) option is given, script is taken to be the sieve script text.

where script denotes the filename of the sieve program to parse, and options is one or more of the following:

-c

--compile-only

Compile script and exit.

--clear-library-path

--clearpath

Clear Sieve library path. See also clear-library-path.

--clear-include-path

Clear Sieve include path. See also clear-include-path.

-d[flags]

--debug[=flags]

Specify debug flags. The flags argument is a sequence of one or more of the following letters:

‘g’	Enable main parser traces
‘T’	Enable mailutils traces
‘P’	Trace network protocols
‘t’	Enable sieve trace
‘i’	Trace the program instructions

-D

--dump

Compile the script, dump disassembled code on standard output and exit.

--environment=name=value

Set sieve environment variable name to the value.

-e address

--email address

Override the user email address. This is useful for reject and redirect actions. By default, the user email address is deduced from the user name and the full name of the machine where sieve is executed. See also email.

-E,

--expression

Treat the script argument as Sieve program text.

-I dir

--includedir=dir

Append directory dir to the list of directories searched for include files. See also include-path.

-f

--mbox-url=mbox

Mailbox to sieve (defaults to user’s system mailbox). See also mbox-url.

-k

--keep-going

Keep on going if execution fails on a message. See also keep-going.

-L dir

--libdir=dir

Append directory dir to the list of directories searched for library files. See also library-path.

--libdir-prefix=dir

Add dir to the beginning of the list of directories searched for library files.

--line-info=bool

Print source location along with action logs (default).

-M url

--mailer=url

Define the URL of the default mailer.

-n

--no-actions

--dry-run

Dry run: do not execute any actions, just print what would be done.

--no-program-name

Do not prefix diagnostic messages with the program name.

-t ticket

--ticket=ticket

Ticket file for mailbox authentication. See also ticket.

--variable=name=value

Set Sieve variable name. This option automatically inserts ‘require "variables"’ at the top of the script.

-v

--verbose

Log all actions executed. See also verbose.

See also Options That are Common for All Utilities..

3.10.1.2 Sieve Configuration

The behavior of sieve is affected by the following configuration statements:

The following statements configure sieve-specific features:

Sieve Conf: sieve { ... } ¶

This block statement configures search paths sieve uses to locate its loadable modules. See Require Statement, for a detailed information about loadable modules.

This statement may contain the following sub-statements:

Sieve Conf: clear-library-path bool ¶

If bool is ‘true’, clear library search path.

Sieve Conf: clear-include-path bool ¶

If bool is ‘true’, clear include search path.

Sieve Conf: library-path path ¶

Add directories to sieve library search path. Argument is a string containing a colon-separated list of directories.

Sieve Conf: library-path-prefix path ¶

Add directories to the beginning if the library search path. Argument is a string containing a colon-separated list of directories.

Sieve Conf: include-path path ¶

Add directories to the include search path. Argument is a string containing a colon-separated list of directories.

Sieve Conf: keep-going bool ¶

If bool is ‘true’, do not abort if execution of a Sieve script fails on a particular message.

Sieve Conf: mbox-url url ¶

Sets URL of the mailbox to be processed.

Sieve Conf: ticket file ¶

Sets the name of the ticket file for user authentication.

Sieve Conf: debug flags ¶

Sets Sieve debug flags. See Logging and debugging, for a detailed description.

Sieve Conf: verbose bool ¶

If bool is ‘true’, log all executed actions.

Sieve Conf: line-info bool ¶

If bool is ‘true’, print source locations along with action logs. This statement takes effect only if verbose true is also set.

Sieve Conf: email addr ¶

Set user e-mail address. This is useful for reject and redirect actions. By default, the user email address is deduced from the user name and the full name of the machine where sieve is executed.

3.10.1.3 Logging and debugging

The default behavior of sieve is to remain silent about anything except errors. However, it is sometimes necessary to see which actions are executed and on which messages. This is particularly useful when debugging the sieve scripts. The --verbose (-v) option outputs log of every action executed.

Option --debug allows to produce even more detailed debugging information. This option takes an argument specifying the debugging level to be enabled. The argument can consist of the following letters:

‘t’

This flag enables sieve tracing. It means that every test will be logged when executed.

‘T’

This flag enables debugging of underlying mailutils library.

‘P’

Trace network protocols: produces log of network transactions executed while running the script.

‘g’

Enable main parser traces. This is useful for debugging the sieve grammar.

‘i’

Trace the program instructions. It is the most extensive debugging level. It produces the full execution log of a sieve program, showing each instruction and states of the sieve machine. It is only useful for debugging the code generator.

Note, that there should be no whitespace between the short variant of the option (-d), and its argument. Similarly, when using long option (--debug), its argument must be preceded by equal sign.

If the argument to --debug is omitted, it defaults to ‘TPt’.

Option --dump produces the disassembled dump of the compiled sieve program.

By default sieve outputs all diagnostics on standard error and verbose logs on standard output. This behaviour is changed when --log-facility is given in the command line (see logging). This option causes sieve to output its diagnostics to the given syslog facility.

3.10.1.4 Extending sieve

The basic set of sieve actions, tests and comparators may be extended using loadable extensions. The usual require mechanism is used for that.

When processing arguments for require statement, sieve uses the following algorithm:

1. Look up the name in a symbol table. If the name begins with ‘comparator-’ it is looked up in the comparator table. If it begins with ‘test-’, the test table is searched instead. Otherwise the name is looked up in the action table.
2. If the name is found, the search is terminated.
3. Otherwise, transform the name. First, any ‘comparator-’ or ‘test-’ prefix is stripped. Then, any character other than alphanumeric characters, ‘.’ and ‘,’ is replaced with dash (‘-’). The name thus obtained is used as a file name of an external loadable module.
4. Try to load the module. The module is searched in the following search paths (in the order given):
   1. Mailutils module directory. By default it is $prefix/lib/mailutils.
   2. The value of the environment variable LTDL_LIBRARY_PATH.
   3. Additional search directories specified with the. --libdir-prefix command line option (see libdir-prefix), or the library-path-prefix configuration statement (see library-path-prefix).
   4. Additional search directories specified with the library-path statement (see library-path) in Sieve configuration file.
   5. Additional search directories specified with the. --libdir command line option (see libdir).
   6. Additional search directories specified with the #searchpath Sieve directive (see Sieve #searchpath directive).
   7. System library search path: The system dependent library search path (e.g. on Linux it is set by the contents of the file /etc/ld.so.conf and the value of the environment variable LD_LIBRARY_PATH).

   The value of LTDL_LIBRARY_PATH and LD_LIBRARY_PATH must be a colon-separated list of absolute directories, for example, ‘"/usr/lib/mypkg:/lib/foo"’.

   In any of these directories, sieve first attempts to find and load the given filename. If this fails, it tries to append the following suffixes to the file name:

   1. the libtool archive extension ‘.la’
   2. the extension used for native dynamic libraries on the host platform, e.g., ‘.so’, ‘.sl’, etc.
5. If the module is found, sieve executes its initialization function (see below) and again looks up the name in the symbol table. If found, search terminates successfully.
6. If either the module is not found, or the symbol wasn’t found after execution of the module initialization function, search is terminated with an error status. sieve then displays the following diagnostic message:

   source for the required action NAME is not available