GNU Mailutils |
|
General-Purpose Mail Package |
Official GNU Software |
sieve
Editor’s note:
The information in this node may be obsolete or otherwise inaccurate. This message will disappear, once this node revised. |
Sieve is a language for filtering e-mail messages at time of final delivery, described in RFC 3028. GNU Mailutils contains stand-alone sieve interpreter, which is described in detail below.
The sieve interpreter sieve
allows you to apply Sieve scripts to
arbitrary number of mailboxes. GNU sieve
implements a superset
of the Sieve language as described in RFC 3028. See Sieve Language,
for a description of the Sieve language. See GNU Extensions, for a
discussion of differences between the GNU implementation of Sieve and
its standard.
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:
Compile script and exit.
Clear Sieve library path. See also clear-library-path.
Clear Sieve include path. See also clear-include-path.
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 |
Compile the script, dump disassembled code on standard output and exit.
Set sieve environment variable name to the value.
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.
Treat the script argument as Sieve program text.
Append directory dir to the list of directories searched for include files. See also include-path.
Mailbox to sieve (defaults to user’s system mailbox). See also mbox-url.
Keep on going if execution fails on a message. See also keep-going.
Append directory dir to the list of directories searched for library files. See also library-path.
Add dir to the beginning of the list of directories searched for library files.
Print source location along with action logs (default).
Define the URL of the default mailer.
Dry run: do not execute any actions, just print what would be done.
Do not prefix diagnostic messages with the program name.
Ticket file for mailbox authentication. See also ticket.
Set Sieve variable name. This option automatically inserts ‘require "variables"’ at the top of the script.
Log all actions executed. See also verbose.
See also Common Options.
The behavior of sieve
is affected by the following
configuration statements:
Statement | Reference |
---|---|
debug | See debug statement. |
tls | See tls statement. |
mailbox | See mailbox statement. |
locking | See locking statement. |
logging | See logging statement. |
mailer | See mailer statement. |
The following statements configure sieve-specific features:
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:
If bool is ‘true’, clear library search path.
If bool is ‘true’, clear include search path.
Add directories to sieve
library search path. Argument is a
string containing a colon-separated list of directories.
Add directories to the beginning if the library search path. Argument is a string containing a colon-separated list of directories.
Add directories to the include search path. Argument is a string containing a colon-separated list of directories.
If bool is ‘true’, do not abort if execution of a Sieve script fails on a particular message.
Sets URL of the mailbox to be processed.
Sets the name of the ticket file for user authentication.
Sets Sieve debug flags. See Logging and Debugging, for a detailed description.
If bool is ‘true’, log all executed actions.
If bool is ‘true’, print source locations along with action
logs. This statement takes effect only if verbose true
is also
set.
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.
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:
This flag enables sieve tracing. It means that every test will be logged when executed.
This flag enables debugging of underlying mailutils
library.
Trace network protocols: produces log of network transactions executed while running the script.
Enable main parser traces. This is useful for debugging the sieve grammar.
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.
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:
LTDL_LIBRARY_PATH
.
library-path-prefix
configuration
statement (see library-path-prefix).
library-path
statement (see library-path) in Sieve configuration file.
#searchpath
Sieve directive (see #searchpath).
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:
sieve
executes its
initialization function (see below) and again looks up the name
in the symbol table. If found, search terminates successfully.
sieve
then displays
the following diagnostic message:
source for the required action NAME is not available
This document was generated on January 2, 2022 using makeinfo.
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.