1 |
@c This is part of the GNU Mailutils manual. |
@c This is part of the GNU Mailutils manual. |
2 |
@c Copyright (C) 1999,2000,2001 Free Software Foundation, Inc. |
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc. |
3 |
@c See file mailutils.texi for copying conditions. |
@c See file mailutils.texi for copying conditions. |
4 |
@comment ******************************************************************* |
@comment ******************************************************************* |
5 |
|
|
196 |
@menu |
@menu |
197 |
* default:: Options understood by most GNU utilities. |
* default:: Options understood by most GNU utilities. |
198 |
* mailbox:: Specifies the mail spool location, and locking strategy. |
* mailbox:: Specifies the mail spool location, and locking strategy. |
199 |
|
* mailer:: Sets the mailer URL. |
200 |
* address:: Specifies the default email address and domain. |
* address:: Specifies the default email address and domain. |
201 |
* daemon:: Options common for daemon programs. |
* daemon:: Options common for daemon programs. |
202 |
* auth:: Authentication-specific options. |
* auth:: Authentication-specific options. |
239 |
Set the default mailbox lock flags (E=external, R=retry, T=time, P=pid). |
Set the default mailbox lock flags (E=external, R=retry, T=time, P=pid). |
240 |
@end table |
@end table |
241 |
|
|
242 |
|
@node mailer |
243 |
|
@subsection mailer --- Sets the default mailer URL. |
244 |
|
@cindex :mailer |
245 |
|
|
246 |
|
This option group overrides the default mailer URL (@url{sendmail:}). |
247 |
|
|
248 |
|
@table @option |
249 |
|
@item -m @var{url} |
250 |
|
@itemx --mailer @var{url} |
251 |
|
@end table |
252 |
|
|
253 |
@node address |
@node address |
254 |
@subsection address --- Specifies the default email address and domain. |
@subsection address --- Specifies the default email address and domain. |
255 |
@cindex :address |
@cindex :address |
2191 |
@subsection A Sieve Interpreter |
@subsection A Sieve Interpreter |
2192 |
|
|
2193 |
Sieve interpreter @command{sieve} allows to apply Sieve scripts to an |
Sieve interpreter @command{sieve} allows to apply Sieve scripts to an |
2194 |
arbitrary number of mailboxes. Currently @command{sieve} supports the |
arbitrary number of mailboxes. GNU @command{sieve} supports full set |
2195 |
following actions: |
of actions and tests described in RFC 3028. |
2196 |
|
|
2197 |
@itemize |
@menu |
2198 |
@item stop |
* Invoking Sieve:: |
2199 |
@item keep |
* Logging and Debugging:: |
2200 |
@item discard |
* Input Language:: |
2201 |
@item fileinto |
* Extending Sieve:: |
2202 |
@end itemize |
@end menu |
2203 |
|
|
2204 |
@subheading Invocation |
@node Invoking Sieve |
2205 |
|
@subsubsection Invocation |
2206 |
|
|
2207 |
The @command{sieve} invocation syntax is: |
The @command{sieve} invocation syntax is: |
2208 |
|
|
2225 |
more of the following letters: |
more of the following letters: |
2226 |
|
|
2227 |
@multitable @columnfractions .40 .45 |
@multitable @columnfractions .40 .45 |
|
@item @samp{a} @tab Enable address parser traces |
|
2228 |
@item @samp{g} @tab Enable main parser traces |
@item @samp{g} @tab Enable main parser traces |
2229 |
@item @samp{T} @tab Enable mailutil traces |
@item @samp{T} @tab Enable mailutil traces |
2230 |
@item @samp{P} @tab Trace network protocols |
@item @samp{P} @tab Trace network protocols |
2231 |
@item @samp{t} @tab Enable sieve trace |
@item @samp{t} @tab Enable sieve trace |
2232 |
@item @samp{h} @tab Debug sieve header filling |
@item @samp{i} @tab Trace the program instructions |
|
@item @samp{q} @tab Trace sieve message queries |
|
2233 |
@end multitable |
@end multitable |
2234 |
|
|
2235 |
When omitted, @var{flags} defaults to @samp{TPt}. |
@xref{Logging and Debugging}, for detailed discussion of these. |
2236 |
|
|
2237 |
|
@item -D |
2238 |
|
@itemx --dump |
2239 |
|
Compile the script, dump disassembled code on standard output and exit. |
2240 |
|
|
2241 |
|
@item -e @var{address} |
2242 |
|
@item --email @var{address} |
2243 |
|
Override the user email address. This is useful for @code{reject} and |
2244 |
|
@code{redirect} actions. By default, the user email address is deduced |
2245 |
|
from the user name and the full name of the machine where sieve is |
2246 |
|
executed. |
2247 |
|
|
2248 |
@item -f |
@item -f |
2249 |
@itemx --mbox-url=@var{mbox} |
@itemx --mbox-url=@var{mbox} |
2253 |
@itemx --keep-going |
@itemx --keep-going |
2254 |
Keep on going if execution fails on a message |
Keep on going if execution fails on a message |
2255 |
|
|
|
@item -M |
|
|
@itemx --mailer-url=@var{mailer} |
|
|
Override the mailer URL (defaults to "sendmail:") |
|
|
|
|
2256 |
@item -n |
@item -n |
2257 |
@itemx --no-actions |
@itemx --no-actions |
2258 |
Dry run: do not execute any actions, just print what would be done. |
Dry run: do not execute any actions, just print what would be done. |
2260 |
@item -t @var{ticket} |
@item -t @var{ticket} |
2261 |
@itemx --ticket=@var{ticket} |
@itemx --ticket=@var{ticket} |
2262 |
Ticket file for mailbox authentication |
Ticket file for mailbox authentication |
2263 |
|
|
2264 |
|
@item -v |
2265 |
|
@itemx --verbose |
2266 |
|
Log all actions executed. |
2267 |
@end table |
@end table |
2268 |
|
|
2269 |
Apart from these, @command{sieve} understands the options from the |
Apart from these, @command{sieve} understands the options from the |
2270 |
@code{mailbox} option group (@pxref{mailbox}). |
following groups: @code{mailbox}, @code{mailer}, @code{logging}. |
2271 |
|
|
2272 |
|
@node Logging and Debugging |
2273 |
|
@subsubsection Logging and debugging |
2274 |
|
|
2275 |
|
The default behavior of @command{sieve} is to remain silent about |
2276 |
|
anything except errors. However, it is sometimes necessary to see |
2277 |
|
which actions are executed and on which messages. This is particularly |
2278 |
|
useful when debugging the sieve scripts. The @option{--verbose} |
2279 |
|
(@option{-v}) option outputs log of every action executed. |
2280 |
|
|
2281 |
|
Option @option{--debug} allows to produce even more detailed debugging |
2282 |
|
information. This option takes an argument specifying the |
2283 |
|
debugging level to be enabled. The argument can consist of the |
2284 |
|
following letters: |
2285 |
|
|
2286 |
|
@table @samp |
2287 |
|
@item @samp{t} |
2288 |
|
This flag enables sieve tracing. It means that every test will be logged |
2289 |
|
when executed. |
2290 |
|
|
2291 |
|
@item @samp{T} |
2292 |
|
This flag enables debugging of underlying @code{mailutils} library. |
2293 |
|
|
2294 |
|
@item @samp{P} |
2295 |
|
Trace network protocols: produces log of network transactions executed |
2296 |
|
while running the script. |
2297 |
|
|
2298 |
|
@item @samp{g} |
2299 |
|
Enable main parser traces. This is useful for debugging the sieve grammar. |
2300 |
|
|
2301 |
|
@item @samp{i} |
2302 |
|
Trace the program instructions. It is the most extensive debugging |
2303 |
|
level. It produces the full execution log of a sieve program, showing |
2304 |
|
each instruction and states of the sieve machine. It is only useful |
2305 |
|
for debugging the code generator. |
2306 |
|
@end table |
2307 |
|
|
2308 |
|
@emph{Note}, that there should be no whitespace |
2309 |
|
between the short variant of the option (@option{-d}), and its |
2310 |
|
argument. Similarly, when using long option (@option{--debug}), |
2311 |
|
its argument must be preceded by equal sign. |
2312 |
|
|
2313 |
|
If the argument to @option{--debug} is omitted, it defaults to |
2314 |
|
@samp{TPt}. |
2315 |
|
|
2316 |
|
Option @option{--dump} produces the disassembled dump of the compiled |
2317 |
|
sieve program. |
2318 |
|
|
2319 |
|
By default @command{sieve} output all diagnostics on standard error and verbose |
2320 |
|
logs on standard output. This behaviour is changed when |
2321 |
|
@option{--log-facility} is given in the command line (@pxref{logging}). |
2322 |
|
This option causes @command{sieve} to output its diagnostics to |
2323 |
|
the given syslog facility. |
2324 |
|
|
2325 |
|
@node Input Language |
2326 |
|
@subsubsection Input Language |
2327 |
|
|
2328 |
|
@node Extending Sieve |
2329 |
|
@subsubsection Extending Sieve |
2330 |
|
The basic set of sieve actions, tests and comparators may be extended |
2331 |
|
using loadable extensions. Usual @code{require} mechanism is used for |
2332 |
|
that. |
2333 |
|
|
2334 |
|
When processing arguments for @code{require} statement, @command{sieve} |
2335 |
|
uses the following algorithm: |
2336 |
|
|
2337 |
|
@enumerate 1 |
2338 |
|
@item Look up the name in a symbol table. If the name begins with |
2339 |
|
@samp{comparator-} it is looked up in the comparator table. If it |
2340 |
|
begins with @samp{test-}, the test table is used instead. Otherwise |
2341 |
|
the name is looked up in the action table. |
2342 |
|
|
2343 |
|
@item If the name is found, the search is terminated. |
2344 |
|
|
2345 |
|
@item Otherwise, transform the name. First, any @samp{comparator-} or |
2346 |
|
@samp{test-} prefix is stripped. Then, any character other than |
2347 |
|
alphanumeric characters, @samp{.} and @samp{,} is replaced with |
2348 |
|
dash (@samp{-}). The name thus obtained is used as a file name |
2349 |
|
of an external loadable module. |
2350 |
|
|
2351 |
|
@item Try to load the module. The module is searched in the |
2352 |
|
following search paths (in the order given): |
2353 |
|
|
2354 |
|
@enumerate 1 |
2355 |
|
@item Mailutils module directory. By default it is |
2356 |
|
@file{$prefix/lib/mailutils}. |
2357 |
|
|
2358 |
|
@item The value of the environment variable LTDL_LIBRARY_PATH. |
2359 |
|
|
2360 |
|
@item System library search path: The system dependent library |
2361 |
|
search path (e.g. on Linux it is set by the contents of the file |
2362 |
|
@file{/etc/ld.so.conf} and the value of the environment variable |
2363 |
|
LD_LIBRARY_PATH). |
2364 |
|
|
2365 |
|
@end enumerate |
2366 |
|
|
2367 |
|
Each search path must be a colon-separated list of absolute directories, |
2368 |
|
for example, @samp{"/usr/lib/mypkg:/lib/foo"}. |
2369 |
|
|
2370 |
|
In any of these directories, @command{sieve} first attempts to find |
2371 |
|
and load the given filename. If this fails, it tries to append the |
2372 |
|
following suffixes to the file name: |
2373 |
|
|
2374 |
|
@enumerate 1 |
2375 |
|
@item the libtool archive extension @samp{.la} |
2376 |
|
|
2377 |
|
@item the extension used for native dynamic libraries on the host |
2378 |
|
platform, e.g., @samp{.so}, @samp{.sl}, etc. |
2379 |
|
@end enumerate |
2380 |
|
|
2381 |
|
@item If the module is found, @command{sieve} executes its |
2382 |
|
initialization function (see below) and again looks up the name |
2383 |
|
in the symbol table. If found, search terminates successfully. |
2384 |
|
|
2385 |
|
@item If either the module is not found, or the symbol wasn't |
2386 |
|
found after execution of the module initialization function, |
2387 |
|
search is terminated with an error status. @command{sieve} then displays |
2388 |
|
the following diagnostic message: |
2389 |
|
|
2390 |
|
@example |
2391 |
|
source for the required action NAME is not available |
2392 |
|
@end example |
2393 |
|
|
2394 |
|
@end enumerate |
2395 |
|
|
2396 |
|
|
2397 |
@c *********************************************************************** |
@c *********************************************************************** |
2398 |
|
|
2399 |
@page |
@page |