[GUIDE] How to Enable Rspamd Learning in DirectAdmin with Dovecot 2.4+ Sieve

[souzadavi]

Hello everyone,

If you're running Rspamd with DirectAdmin, you have a powerful anti-spam engine. However, the default setup often lacks a critical feature: automatic learning. Without it, Rspamd can't learn from your users' actions (like moving an email to Junk), and its accuracy won't improve over time.

This guide will walk you through the complete, step-by-step process of enabling Rspamd's learning feature with Dovecot using the more modern and powerful Dovecot Sieve method. This is the secure, robust, and professional way, with no insecure file permissions and no sudo.

Prerequisites:

• A DirectAdmin server with Rspamd and Dovecot (version 2.4+ recommended) installed.
• Pigeonhole Sieve enabled in CustomBuild. If you're not sure, run this:
  

  cd /usr/local/directadmin/custombuild
  ./build set pigeonhole yes
  ./build dovecot_conf

## Step 1: Configure Dovecot for Sieve Actions

First, we'll tell Dovecot to enable the necessary Sieve plugins and define the actions that will trigger our learning scripts when an email is moved.

1. Enable Sieve in LMTP Protocol:
Edit /etc/dovecot/conf.d/20-lmtp.conf and ensure the sieve plugin is listed:

protocol lmtp {
mail_plugins = $mail_plugins sieve
}

2. Configure IMAP Sieve Actions:
This is the core of the configuration. We will create a new file to control what happens when a user moves an email.

Create and edit the file /etc/dovecot/conf.d/99-imap-sieve.conf:

nano /etc/dovecot/conf.d/99-imap-sieve.conf

Paste the entire configuration below. This enables the required plugins and tells Dovecot to run specific Sieve scripts when a message is moved to or from the Junk or spam folders.

# Enable the IMAP Sieve plugin
protocol imap {
mail_plugins = $mail_plugins imap_sieve
}

Enable required Sieve extensions
sieve_plugins {
sieve_imapsieve   = yes
sieve_extprograms = yes
}

sieve_global_extensions {
vnd.dovecot.pipe = yes
}

Set the directory for our learning scripts
sieve_pipe_bin_dir = /usr/local/bin/dovecot-sieve

--- Main Logic: Define actions for specific mailboxes ---
namespace inbox {

ACTION: When a message is MOVED TO these folders, learn it as SPAM.
The "auto = create" will create these folders for new users if they don't exist.
mailbox "Junk" {
auto = create
sieve_script = report-spam
}
mailbox "spam" {
auto = create
sieve_script = report-spam
}

ACTION: When a message is MOVED FROM these folders, learn it as HAM.
imapsieve_from1 = Junk
imapsieve_from2 = spam
}

--- Script Definitions ---
This links the script names above to the actual script files on disk.
plugin {
sieve_script_name = report-spam
sieve_script_path = /usr/local/bin/dovecot-sieve/report-spam.sieve
sieve_script_is_active = yes

sieve_script_name = report-ham
sieve_script_path = /usr/local/bin/dovecot-sieve/report-ham.sieve
sieve_script_is_active = yes
}

Pro Tip: Your users might use different folder names (e.g., Lixo, Spam). You can find the exact folder names for a user with the command: doveadm mailbox list -u [email protected]

## Step 2: Create the Sieve and Shell Scripts

Now we'll create the actual scripts that Dovecot will execute.

1. Create the directory:

mkdir -p /usr/local/bin/dovecot-sieve

2. Create the report-spam.sieve script:
This script pipes the email to our shell script to learn as "spam".

nano /usr/local/bin/dovecot-sieve/report-spam.sieve

Paste this in:

require ["vnd.dovecot.pipe"];
pipe "rspamd-learn.sh" [ "spam" ];

3. Create the report-ham.sieve script:

nano /usr/local/bin/dovecot-sieve/report-ham.sieve

Paste this in:

require ["vnd.dovecot.pipe", "copy", "environment", "imapsieve"];
if environment :matches "imap.mailbox" "Spam" {
    stop;
}
if environment :matches "imap.mailbox" "Trash" {
    stop;
}
pipe :copy "rspamd-learn.sh" [ "ham" ];

4. Create the rspamd-learn.sh shell script:
This is the script that does the actual work of talking to Rspamd.

nano /usr/local/bin/dovecot-sieve/rspamd-learn.sh

Paste this in:

#!/bin/bash
# A simple, secure learning script without sudo
SOCKET_PATH="/var/run/rspamd/rspamd_controller.sock"
ACTION="$1"
if [ "$ACTION" = "spam" ]; then
    # Execute rspamc directly as the email user
    cat | /usr/bin/rspamc -h "$SOCKET_PATH" learn_spam >/dev/null 2>&1
elif [ "$ACTION" = "ham" ]; then
    cat | /usr/bin/rspamc -h "$SOCKET_PATH" learn_ham >/dev/null 2>&1
fi

5. Set final permissions:
Make the shell script executable and compile the Sieve scripts.

chmod +x /usr/local/bin/dovecot-sieve/rspamd-learn.sh
sievec /usr/local/bin/dovecot-sieve/report-spam.sieve
sievec /usr/local/bin/dovecot-sieve/report-ham.sieve

## Step 3: Configure Rspamd for Secure Socket Access

This is the key to a secure, sudo-less setup. We will configure Rspamd's socket so Dovecot can access it directly via group permissions.

1. Allow Rspamd to Manage Group Permissions:
The Rspamd process (_rspamd user) needs permission to assign the socket file to the dovecot group. We grant this by adding the _rspamd user to that group.

usermod -a -G dovecot _rspamd

2. Create the Rspamd Controller Override File:
This file will force our secure configuration to be loaded.

nano /etc/rspamd/local.d/worker-controller.inc

Paste the following secure configuration:

# /etc/rspamd/local.d/worker-controller.inc

Secure configuration for Dovecot integration without sudo.
owner=_rspamd: The user who owns the socket.
group=dovecot: The group who owns the socket.
mode=0660: Allows read/write for the owner AND the group, but NO ONE else.
bind_socket = "/var/run/rspamd/rspamd_controller.sock owner=_rspamd group=dovecot mode=0660";

Explicitly enable the learn commands on this socket.
allow_learn = true;

## Step 4: Final Restart and Verification

Let's apply everything and confirm it's working.

1. Check Dovecot configuration for syntax errors:

doveconf -N

(If it returns your configuration without errors, you're good).

2. Restart both services:

systemctl restart rspamd
systemctl restart dovecot

3. Verify the socket permissions. Run this command:

ls -l /var/run/rspamd/rspamd_controller.sock

The output should show _rspamd as the owner and dovecot as the group:

[font=monospace]srw-rw---- 1 _rspamd dovecot 0 Oct 12 01:10 /var/run/rspamd/rspamd_controller.sock[/font]

4. Test it!

• Log in to Roundcube webmail.
• Drag a spam email from your Inbox to your Junk/Spam folder.
• Open the Rspamd web UI in DirectAdmin and check the Learns count for BAYES_SPAM. It should increase!
• Drag the email back to your Inbox. The Learns count for BAYES_HAM should now increase.

## Troubleshooting

If something isn't working, these commands are your best friends:

• Check Dovecot logs for Sieve errors: journalctl -u dovecot --since "1 minute ago" | grep -i sieve
• Watch Dovecot logs in real-time: journalctl -u dovecot -f
• Watch Rspamd logs: journalctl -u rspamd -f

That's it! You now have a modern, secure, and fully functional Rspamd learning setup. I hope this guide helps you out!