ManageSieve Troubleshooting¶
Like Dovecot itself, the ManageSieve service always logs a detailed
error message if something goes wrong at the server (refer to Dovecot
Logging for more details): the logs are the first place to look if you suspect
something is wrong. To get additional debug messages in your log file,
you should set log_debug=category=sieve in dovecot.conf (inside
protocol sieve {...}if you want to enable this for ManageSieve
only).
If the client commits protocol violations or sends invalid scripts, an error response is provided to the client which is not necessarily logged on the server. A good ManageSieve client presents such error messages to the user.
Keep in mind that the ManageSieve service only provides the Sieve protocol, which may be somewhat confusing. This protocol can only be used to upload Sieve scripts and activate them for execution. Performing the steps below therefore only verifies that this functionality is working and not whether Sieve scripts are correctly being executed upon delivery. The execution of Sieve scripts is performed by the Dovecot Local Delivery Agent or its LMTP service using the LDA Sieve plugin. If you have problems with Sieve script execution upon delivery, you are referred to the Sieve Troubleshooting page.
Manual Login and Script Upload¶
If you fail to login or upload scripts to the server, it is not
necessarily caused by Dovecot or your configuration. It is often best to
test your ManageSieve server manually first. This also provides you with
the direct error messages from the server without intermission of your
client. If you do not use TLS, you can connect using a simple telnet
or netcat connection to the configured port (typically 4190 or 2000
for older setups). Otherwise you must use a TLS-capable text protocol
client like gnutls-cli as described below. Upon connection, the
server presents the initial greeting with its capabilities:
"IMPLEMENTATION" "dovecot"
"SASL" "PLAIN"
"SIEVE" "comparator-i;ascii-numeric fileinto reject vacation imapflags notify include envelope body relational regex subaddress copy"
"STARTTLS"
OK "Dovecot ready."
Note that the reported STARTTLS capability means that the server
accepts TLS, but, since you are using telnet/netcat, you cannot use this
(refer to Manual TLS Login below). The SASL capability lists the
available SASL authentication mechanisms. If this list is empty and
STARTTLS is available, it probably means that the server forces you
to initiate TLS first (as dictated by disable_plaintext_auth=no
in dovecot.conf).
Now you need to log in. Although potentially multiple SASL mechanisms
are available, only PLAIN is described here. Authentication is
performed using the ManageSieve AUTHENTICATE command. This command
typically looks as follows when the PLAIN mechanism is used:
AUTHENTICATE "PLAIN" "<base64-encoded credentials>"
The credentials are the base64-encoded version of the string
"\0<username>\0<password" (in which \0 represents the ASCII NUL
character). Generating this is cumbersome and a bit daunting for the
novice user, so for convenience a simple Perl script is provided to
generate the AUTHENTICATE command for you. It is available
here
and used as follows:
sieve-auth-command.pl <username> <password>
The command is written to stdout and you can paste this to your protocol session, e.g.:
AUTHENTICATE "PLAIN" "<base64-encoded credentials>"
OK "Logged in."
Now that you are logged in, you can upload a script. This is done using
the PUTSCRIPT command. Its first argument is the name for the script
and its second argument is a string literal. A string literal starts
with a length specification '{<bytes>+}' followed by a newline.
Thereafter the server expects <bytes> bytes of script data. The
following uploads a trivial 6 byte long sieve script that keeps every
message (6th byte is the newline character):
PUTSCRIPT "example" {6+}
keep;
OK "Putscript completed."
Upon successful upload, you should find a file called
example.sieve in your sieve_dir directory. The script should
also be listed by the server as follows when the LISTSCRIPTS command
is issued:
LISTSCRIPTS
"example"
OK "Listscripts completed."
You can check whether your script is uploaded correctly by downloading
it using the GETSCRIPT command. This command accepts the name of the
downloaded script as its only parameter:
GETSCRIPT "example"
{6}
keep;
OK "Getscript completed."
To let the Sieve plugin use your newly uploaded script, you must
activate it using the SETACTIVE command (only one script can be
active at any time). The active script is indicated ACTIVE in the
LISTSCRIPTS output, e.g.:
SETACTIVE "example"
OK "Setactive completed."
LISTSCRIPTS
"example" ACTIVE
OK "Listscripts completed.
The symbolic link configured with the sieve setting should now point
to the activated script in the sieve_dir directory. If no script is
active, this symbolic link is absent.
Manual TLS Login¶
When TLS needs to be used during manual testing, gnutls-cli provides
the means to do so. This command-line utility is part of the GNUTLS
distribution and on most systems this should be easy to install. It is
used to connect to ManageSieve as follows:
gnutls-cli --starttls -p <port> <host>
This starts the client in plain text mode first. As shown in the
previous section, the server presents a greeting with all capabilities
of the server. If STARTTLS is listed, you can issue the STARTTLS
command as follows:
STARTTLS
OK "Begin TLS negotiation now."
If an OK response is given by the server you can press Ctrl-D to
make gnutls-cli start the TLS negotiation. Upon pressing Ctrl-D,
gnutls-cli will show information on the negotiated TLS session and
finally the first response of the server is shown:
"IMPLEMENTATION" "dovecot"
"SASL" "PLAIN"
"SIEVE" "comparator-i;ascii-numeric fileinto reject vacation imapflags notify include envelope body relational regex subaddress copy"
OK "TLS negotiation successful."
Hereafter, you can continue to authenticate and upload a script as described in the previous section.
Client Problems¶
See Rawlog for details how to log client-server traffic.
Refer to the ManageSieve Clients page for information on known client problems.
Known Server Issues and Protocol Deviations¶
The ANONYMOUS authentication mechanism is currently not supported and explicitly denied.
