# SpamAssassin Milter
This milter applies mail filtering through SpamAssassin server using the spamc
client.
This program is intended as a replacement for [spamass-milt].
Status: **EXPERIMENTAL/IN DEVELOPMENT**
[spamass-milt]: https://savannah.nongnu.org/projects/spamass-milt/
## Operation
SpamAssassin Milter filters email messages through the SpamAssassin server. By
default it applies the following modifications to messages:
* Always: Rewrite SpamAssassin headers
* Spam only: Rewrite ‘rewrite’ headers Subject From To if necessary
* Spam only: Replace message body (and rewrite related headers MIME-Version
Content-Type if necessary)
TODO describe --reject-spam
## Building
This project uses Cargo as usual. If your distribution does not install a
pkg-config metadata file for the milter library used by SpamAssassin Milter, you
can use the provided milter.pc file. Put it on the pkg-config path as follows:
```
PKG_CONFIG_PATH=. cargo build
```
## Usage
**This program is in development.** (I do already use it to filter mail on my
own domain, though.)
The easiest way of setting up SpamAssassin Milter is to edit the provided
systemd service file spamassassin-milter.service, and install it in
/etc/systemd/system.
There is one required argument, the milter listening socket.
TODO
### ‘dry-run’
For first-time users, before deploying SpamAssassin Milter on your mail server,
you may wish to run it with the ‘dry-run’ option. Combined with the verbose
logging option, this gives good insight in the log about the changes that
SpamAssassin Milter would apply.
```
/usr/sbin/spamassassin-milter --dry-run --verbose inet:3001@localhost
```
```
spamassassin-milter[8604]: AD3F03F1F3: rewriting header: add header "X-Spam-Checker-Version" [dry-run, not done]
spamassassin-milter[8604]: AD3F03F1F3: rewriting header: add header "X-Spam-Level" [dry-run, not done]
spamassassin-milter[8604]: AD3F03F1F3: rewriting header: add header "X-Spam-Status" [dry-run, not done]
spamassassin-milter[8604]: AD3F03F1F3: finished processing
spamassassin-milter[8604]: 112D03F1F3: rewriting header: replace header "X-Spam-Checker-Version" [dry-run, not done]
spamassassin-milter[8604]: 112D03F1F3: rewriting header: replace header "X-Spam-Status" [dry-run, not done]
spamassassin-milter[8604]: 112D03F1F3: finished processing
```
## Integration with SpamAssassin
Integration with SpamAssassin has two components: the SpamAssassin server,
called spamd, running as a daemonised service, and the SpamAssassin client
spamc. SpamAssassin Milter uses spamc to communicate with the SpamAssassin
server.
### SpamAssassin configuration
The main SpamAssassin configuration file is /etc/spamassassin/local.conf.
By default, SpamAssassin creates ‘reports’ for messages it recognises as spam.
These reports replace the message body, that is, the message body is rewritten
to present a report instead of the original message, and the original message is
relegated to a MIME attachment. SpamAssassin Milter by default applies reports.
If the reports behaviour is not desired, they may be disabled by setting the
parameter `report_safe 0` in the SpamAssassin configuration.
TODO describe reports and disabling reports with report_safe 0
### spamc configuration
To integrate with spamc, it is recommended to set spamc configuration options in
the spamc configuration file /etc/spamassassin/spamc.conf.
For example, the following is the content of a minimal spamc.conf file:
```
--socket=/run/spamassassin/spamd.sock
```
This configuration instructs spamc to connect to spamd on a UNIX domain socket
at /run/spamassassin/spamd.sock.
When reports are disabled, the following is a reasonable configuration:
```
--socket=/run/spamassassin/spamd.sock
--headers
```
The `--headers` option is just a shortcut that tells spamd not to transmit the
body back to spamc. This option obviously only makes sense and should only be
used when SpamAssassin reports are disabled.
## Integration with Postfix
To integrate with Postfix, ensure the SpamAssassin Milter service is up and
running, and then configure its listening socket in /etc/postfix/main.cf as
follows:
```
smtpd_milters = inet:localhost:3001
non_smtpd_milters = $smtpd_milters
```
After reloading the Postfix configuration, mail will be processed by
SpamAssassin Milter.
By default, SpamAssassin Milter will accept, that is, won’t check messages
coming from connections from localhost, and messages from authenticated senders.
## Licence
Copyright © 2020 David Bürgin
This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.