Replacing antispam plugin with IMAPSieve
========================================

Contents


 1. Replacing antispam plugin with IMAPSieve

     1. Caveats and possible pitfalls

     2. Dovecot configuration

     3. Sieve scripts

     4. Shell scripts

         1. For spamassassin

         2. For dspam

         3. For rspamd

     5. Debugging

     6. RoundCube

You will need at least pigeonhole v0.4.14 for this. If you have already
configured sieve, please adjust the following to match your setup.

Caveats and possible pitfalls
-----------------------------

 * INBOX name is case-sensitive
 * <IMAP Sieve> [Pigeonhole.Sieve.Plugins.IMAPSieve.txt] will *only* apply to
   IMAP. It *will not* apply to LDA or LMTP. Use <Sieve> [Pigeonhole.Sieve.txt]
   normally for LDA/LMTP.
 * With this configuration, moving mails will slow down due to learn being done
   per email. If you want to avoid this, you need to think of something else.
   Probably piping things into a FIFO or perhaps using a socket based worker
   might work better.
 * Please read <Pigeonhole.Sieve.txt> and <Pigeonhole.Sieve.Configuration.txt>
   to understand sieve configuration better.
 * Please read <Pigeonhole.Sieve.Plugins.txt> for more information about sieve
   extensions.
 * If you run Spamassassin trough Amavis and you use a virtual users setup, you
   should instead configure Spamassassin to use MySQL/PostgreSQL as a backend,
   unless you want a headache with file permissions and lock files. You can
   find instructions here
   [http://www.iredmail.org/docs/store.spamassassin.bayes.in.sql.html]. In this
   case, the '-u' parameter passed to 'sa-learn' (and the relevant sieve
   variables) is obsolete and can be safely removed.

Changes:

 * 2017/11/20 - Possibility of using spamc with <SpamAssassin.txt> to mitigate
   multi-message delays
 * 2017/05/05 - Recommendation about Virtual Users and using an SQL Backend.
   Added brief info about <RoundCube.txt>.
 * 2017/04/01 - Pass imap user to scripts.
 * 2017/03/19 - Added rspamd scripts and mention about sieve plugins.
 * 2017/02/13 - Improved documentation and added instructions for Spam->Trash.
   (Thanks for everyone who commented on mailing list)
 * 2017/02/10 - Removed imap_stats (it's not needed).
 * 2018/04/11 - Added notes about sa-learn/spamc and warning about sieve script
   location.

Dovecot configuration
---------------------

---%<-------------------------------------------------------------------------
protocol imap {
  mail_plugins = $mail_plugins imap_sieve
}

plugin {
  sieve_plugins = sieve_imapsieve sieve_extprograms

  # From elsewhere to Spam folder
  imapsieve_mailbox1_name = Spam
  imapsieve_mailbox1_causes = COPY
  imapsieve_mailbox1_before = file:/usr/lib/dovecot/sieve/report-spam.sieve

  # From Spam folder to elsewhere
  imapsieve_mailbox2_name = *
  imapsieve_mailbox2_from = Spam
  imapsieve_mailbox2_causes = COPY
  imapsieve_mailbox2_before = file:/usr/lib/dovecot/sieve/report-ham.sieve

  sieve_pipe_bin_dir = /usr/lib/dovecot/sieve

  sieve_global_extensions = +vnd.dovecot.pipe +vnd.dovecot.environment
}
---%<-------------------------------------------------------------------------

Sieve scripts
-------------

*You cannot run scripts anywhere you want*

Sieve allows you to only run scripts under sieve_pipe_bin_dir. You can't use
/usr/local/bin/my-sieve-filter.sh, you have to put the script under
sieve_pipe_bin_dir and use my-sieve-filter.sh instead.

Create directory /usr/lib/dovecot/sieve and put following files to that:

report-spam.sieve

---%<-------------------------------------------------------------------------
require ["vnd.dovecot.pipe", "copy", "imapsieve", "environment", "variables"];

if environment :matches "imap.user" "*" {
  set "username" "${1}";
}

pipe :copy "sa-learn-spam.sh" [ "${username}" ];
---%<-------------------------------------------------------------------------

report-ham.sieve

---%<-------------------------------------------------------------------------
require ["vnd.dovecot.pipe", "copy", "imapsieve", "environment", "variables"];

if environment :matches "imap.mailbox" "*" {
  set "mailbox" "${1}";
}

if string "${mailbox}" "Trash" {
  stop;
}

if environment :matches "imap.user" "*" {
  set "username" "${1}";
}

pipe :copy "sa-learn-ham.sh" [ "${username}" ];
---%<-------------------------------------------------------------------------

Shell scripts
-------------

For spamassassin
----------------

*Untested*

spamc interaction scripts are not tested yet.

sa-learn-spam.sh

---CodeArea-------------------------------------------------------------------
#!/bin/sh    1
# you can also use tcp/ip here, consult spamc(1)    2
exec /usr/bin/spamc -u ${1} -L spam -C report    3
---CodeArea-------------------------------------------------------------------

sa-learn-ham.sh

---CodeArea-------------------------------------------------------------------
#!/bin/sh    1
# you can also use tcp/ip here, consult spamc(1)    2
exec /usr/bin/spamc -u ${1} -L ham -C report    3
---CodeArea-------------------------------------------------------------------

You can also use sa-learn.

Note that using sa-learn often incurs significant start-up time for every
message. This can cause "lockout" of the user until all the processes
sequentially complete, potentially tens of seconds or minutes. If spamd is
being used and the administrator is willing to accept the potential security
issues of allowing unauthenticated learning of spam/ham, spamd can be envoked
with the --allow-tell option and spamc with the --learntype= option. Please
consult the man pages of spamd and spamc for further details.

sa-learn-spam.sh

---CodeArea-------------------------------------------------------------------
#!/bin/sh    1
exec /usr/bin/sa-learn -u ${1} --spam    2
---CodeArea-------------------------------------------------------------------

sa-learn-ham.sh

---CodeArea-------------------------------------------------------------------
#!/bin/sh    1
exec /usr/bin/sa-learn -u ${1} --ham    2
---CodeArea-------------------------------------------------------------------

For dspam
---------

sa-learn-spam.sh

---CodeArea-------------------------------------------------------------------
#!/bin/sh    1
exec /usr/bin/dspam --client --user ${1} --class=spam --source=error    2
---CodeArea-------------------------------------------------------------------

sa-learn-ham.sh

---CodeArea-------------------------------------------------------------------
#!/bin/sh    1
exec /usr/bin/dspam --client --user ${1} --class=innocent --source=error    2
---CodeArea-------------------------------------------------------------------

*CRLF handling*

dspam may fail to read the mail if it contains CRLF line endings, add the
*Broken lineStripping* option in dspam.conf if needed.

For rspamd
----------

By default, rspamd does global learning. If you want per-user classification,
or something more complex, see
https://rspamd.com/doc/configuration/statistic.html

sa-learn-spam.sh

---CodeArea-------------------------------------------------------------------
#!/bin/sh    1
exec /usr/bin/rspamc -h /run/rspamd/worker-controller.socket -P <secret>
learn_spam    2
---CodeArea-------------------------------------------------------------------

sa-learn-ham.sh

---CodeArea-------------------------------------------------------------------
#!/bin/sh    1
exec /usr/bin/rspamc -h /run/rspamd/worker-controller.socket -P <secret>
learn_ham    2
---CodeArea-------------------------------------------------------------------

Before running following commands, make sure dovecot.conf has all the sieve
configuration you want. Then run following commands:

---%<-------------------------------------------------------------------------
sievec /usr/lib/dovecot/sieve/report-spam.sieve
sievec /usr/lib/dovecot/sieve/report-ham.sieve
chmod +x /usr/lib/dovecot/sieve/sa-learn-ham.sh
/usr/lib/dovecot/sieve/sa-learn-spam.sh
---%<-------------------------------------------------------------------------

Now your learn scripts should be invoked when you move mails between folders.

Debugging
---------

To debug, you need to import "vnd.dovecot.debug" extension. Then you can put,
when required

---%<-------------------------------------------------------------------------
debug_log "something"
---%<-------------------------------------------------------------------------

variables are supported in this.

RoundCube
---------

Recent versions of RoundCube [https://roundcube.net/] include a markasjunk2
plugin [https://plugins.roundcube.net/packages/johndoh/markasjunk2] for
allowing users to mark Spam/Ham in a convenient way. Please make sure the
Junk/Spam folder matches your configuration.

(This file was created from the wiki on 2019-03-05 04:42)