Tutorial: Integrating Rspamd as a Custom Script in Proxmox Mail Gateway
Proxmox Mail Gateway allows advanced customization with a custom script for spam and virus checks. This tutorial will show you how to integrate Rspamd to evaluate spam scores and return results back to PMG.
1. Requirements
- A running cluster of rspamd
It can be on the same host as PMG or a remote server, however I suggest a remote server.
I will just present a very simple single node installation. - PMG properly installed and configured.
- Basic knowledge of shell scripting.
2. Enable the Custom Script in PMG
- Open the PMG configuration file:
nano /etc/pmg/pmg.conf
- Enable the custom check script by adding or updating the following section:
section: admin
custom_check 1
custom_check_path /usr/local/bin/pmg-custom-check - Install jq - because the script needs it
apt install jq
3. Install and Configure Rspamd
Install Rspamd:
On the same server (or another server):
apt update && apt install rspamd
Enable HTTP API in Rspamd:
Edit the Rspamd controller worker configuration file:
nano /etc/rspamd/rspamd.conf and update the following section so that the controller is available on remote.
On local setup, you can ignore this step. However, the script uses a password.
Code:
worker "controller" {
bind_socket = "0.0.0.0:11334";
bind_socket = "[::]:11334";
password="use-a-strong-password";
enable_password = true;
.include "$CONFDIR/worker-controller.inc"
.include(try=true; priority=1,duplicate=merge) "$LOCAL_CONFDIR/local.d/worker-controller.inc"
.include(try=true; priority=10) "$LOCAL_CONFDIR/override.d/worker-controller.inc"
}Restart Rspamd:
systemctl restart rspamd
4. Create the Custom Script
- Create the script file:
nano /usr/local/bin/pmg-custom-check - Add the following script to integrate with Rspamd:
Code:
#!/bin/bash
API_URL="http://<your rspamd host>:11334/checkv2"
API_PASSWORD="your-strong-password"
if [ "$#" -ne 2 ]; then
echo "usage: $0 APIVERSION QUEUEFILENAME" 1>&2
exit 1
fi
apiver="$1"
queue_file="$2"
if [ "$apiver" != "v1" ]; then
echo "wrong APIVERSION: $apiver" 1>&2
exit 2
fi
# Call rspamd via HTTP API
rspamd_output=$(curl -s --data-binary @"$queue_file" -H "Password: $API_PASSWORD" "$API_URL")
if [ $? -ne 0 ]; then
echo "Error contacting rspamd" 1>&2
exit 3
fi
# Extract spam score from JSON response
spam_score=$(echo "$rspamd_output" | jq -r '.score')
# Validate spam score
if [[ ! $spam_score =~ ^-?[0-9]+(\.[0-9]+)?$ ]]; then
echo "Error parsing rspamd output" 1>&2
exit 4
fi
# Output for PMG
echo "v1"
if (( $(echo "$spam_score > 0" | bc -l) )); then
echo "SCORE: $spam_score"
else
echo "OK"
fi- Save and make the script executable:
chmod +x /usr/local/bin/pmg-custom-check
5. Testing the Custom Script
Prepare a Test Email File
Create a sample email file (email.eml) in RFC 822 format:
Code:
From: test@example.com
To: recipient@example.com
Subject: Test Email
This is a test email for Rspamd integration.Run the Script Manually
Test the custom script with the email file:
/usr/local/bin/pmg-custom-check v1 email.eml
Expected Output:
- If spam score > 0:
v1
SCORE: 1.1 - If spam score <= 0:
v1
OK
6. Fine-Tuning Rspamd Configuration
Disable Greylisting (Optional)
If greylisting is not needed, disable it in /etc/rspamd/local.d/greylist.conf:
enabled = false;
Restart Rspamd:
systemctl restart rspamd
Conclusion
With this setup, Proxmox Mail Gateway is now integrated with Rspamd for custom spam checking. Rspamd will evaluate emails, assign spam scores, and return results to PMG. Fine-tune Rspamd settings to match your environment, and monitor logs to ensure smooth operation.
I suggest also using a reverse http proxy to upgrade to https if your cluster does not have a secure local network.
Notice: Spam scores are added to the scores calculated by proxmox. Please ensure your filtering can keep up with these added values
Let me know if you encounter issues or need further guidance!
Last edited:
