Edit File: Pigeonhole.ManageSieve.Troubleshooting.txt
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> [Logging.txt] 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 'mail_debug=yes' in dovecot.conf (inside 'protocol sieve {...} 'if you want to enable this forManageSieve 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 goodManageSieve client presents such error messages to the user. Keep in mind that the 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 (LDA)> [LDA.txt] or its <LMTP service> [LMTP.txt] using the <LDA Sieve plugin> [Pigeonhole.Sieve.txt]. If you have problems with Sieve script execution upon delivery, you are referred to the <Sieve Troubleshooting page> [Pigeonhole.Sieve.Troubleshooting.txt]. 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 yourManageSieve 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=yes'' 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 theManageSieve '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 [http://pigeonhole.dovecot.org/utilities/sieve-auth-command.pl] 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" "AHVzZXJuYW1lAHBhc3N3b3Jk" 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 "hutsefluts" {6+} keep; OK "Putscript completed." ---%<------------------------------------------------------------------------- Upon successful upload, you should find a file called 'hutsefluts.sieve' in your 'sieve_dir' directory. The script should also be listed by the server as follows when the 'LISTSCRIPTS' command is issued: ---%<------------------------------------------------------------------------- LISTSCRIPTS "hutsefluts" 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 "hutsefluts" {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 "hutsefluts" OK "Setactive completed." LISTSCRIPTS "hutsefluts" 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 toManageSieve 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 --------------- If manual efforts to upload a script are successful, but your client still fails, you need to obtain a view on what the client communicates with the server. A common method is to sniff the client protocol session using a tool like 'ngrep'. However, this will not work when TLS is active. If the problem is not specific to TLS, you are advised to temporarily turn off TLS and sniff the plain text protocol. If TLS is part of the issue, you can use Dovecot's <rawlog> [Debugging.Rawlog.txt] facility to see what is going on if the client is logged in. If the authentication is the problem, there is no real nice way to obtain a transcript of the protocol. One way is to run managesieve from inetd, wrapping it into a script that writes the protocol messages somewhere (*FIXME*: This needs some checking and explanation). Alternatively, if possible, the client can be altered to write its protocol messages somewhere. Refer to the <ManageSieve Clients page> [Pigeonhole.ManageSieve.Clients.txt] for information on known client problems. Known Server Issues and Protocol Deviations ------------------------------------------- * The ANONYMOUS authentication mechanism is currently not supported and explicitly denied. *NOTE*: If you add new issues to this list, notify the author or send an e-mail to the Dovecot mailing list [http://dovecot.org/mailinglists.html]. In any case, you must make sure that the issue is properly explained and that the author can contact you for more information. (This file was created from the wiki on 2018-02-28 04:42)