Skip to content
Permalink
Browse files
JAMES-3775 Documentation for RSpamD extension (#1113)
  • Loading branch information
vttranlina committed Aug 10, 2022
1 parent 2c786d7 commit 3c3f32d7073509506b0d838c0899fcab733b0f80
Show file tree
Hide file tree
Showing 5 changed files with 127 additions and 10 deletions.
@@ -19,7 +19,7 @@ patterns. ElasticSearch throughtput do not however match the one of Cassandra th
* *RabbitMQ* enables James nodes of a same cluster to collaborate together. It is used to implement connected protocols,
notification patterns as well as distributed resilient work queues and mail queue.
* *Tika* (optional) enables text extraction from attachments, thus improving full text search results.
* *SpamAssassin* (optional) can be used for Spam detection and user feedback is supported.
* *link:https://spamassassin.apache.org/[SpamAssassin] or link:https://rspamd.com/[RSpamD]* (optional) can be used for Spam detection and user feedback is supported.

xref:architecture/consistency-model.adoc[This page] further details Distributed James consistency model.

@@ -206,7 +206,7 @@ operations on the system, like:
* Current quota calculation
* Message indexation with ElasticSearch
* Mailbox annotations cleanup
* Ham/spam reporting to SpamAssassin
* Ham/spam reporting to Spam filtering system
* …

==== Deleted Messages Vault
@@ -60,7 +60,7 @@ By omitting these files, no extra behaviour is added.
** xref:configure/listeners.adoc[*listeners.xml*] enables configuration of Mailbox Listeners link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/listeners.xml[example]
** xref:configure/extensions.adoc[*extensions.properties*] allows to extend James behaviour by loading your extensions in it link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/extensions.properties[example]
** xref:configure/jvm.adoc[*jvm.properties*] lets you specify additional system properties without cluttering your command line
** xref:configure/spam.adoc[This page] documents Anti-Spam setup with SpamAssassin.
** xref:configure/spam.adoc[This page] documents Anti-Spam setup with SpamAssassin, RSpamD.
** xref:configure/remote-delivery-error-handling.adoc[This page] proposes a simple strategy for RemoteDelivery error handling.
** xref:configure/collecting-contacts.adoc[This page] documents contact collection
** xref:configure/collecting-events.adoc[This page] documents event collection
@@ -52,6 +52,27 @@ Example:
Please note that a `spamassassin.properties` file is needed. Read also
xref:configure/spam.adoc[this page] for extra configuration required to support this feature.

=== RSpamDListener

Provides HAM/SPAM feedback to a RSpamD server depending on user actions.

This MailboxListener is supported.

Example:

....
<listeners>
<!-- ... -->
<listener>
<class>org.apache.james.rspamd.RSpamDListener</class>
</listener>
</listeners>
....

Please note that a `rspamd.properties` file is needed. Read also
xref:configure/spam.adoc[this page] for extra configuration required to support this feature.


=== MailboxOperationLoggingListener

Provides more insights on mailbox operationsby logging them.
@@ -9,23 +9,27 @@ Anti-Spam system can be configured via two main different mechanisms:
== AntiSpam SMTP Hooks

"FastFail" SMTP Hooks acts to reject before spooling
on the SMTP level. SpamAssasin hook can be used as a fastfail hook, therefore
SpamAssassin must run as a server on the same machine as the Apache James Server.
on the SMTP level. The Spam detector hook can be used as a fastfail hook, therefore
Spam filtering system must run as a server on the same machine as the Apache James Server.

SMTP Hooks for non-existent users, DSN filter, domains with invalid MX record,
can also be configured.

*SpamAssassinHandler* (experimental) also enables to classify the messages as spam or not
with an configurable score threshold (`0.0`, non configurable). Only a global database is supported. Per user spam
with a configurable score threshold (`0.0`, non-configurable). Only a global database is supported. Per user spam
detection is not supported by this hook.

== AntiSpam Mailets

* *SpamAssassin* Mailet is designed to classify the messages as spam or not
with an configurable score threshold. Usually a message will only be
James' repository provide two AntiSpam mailets: SpamAssassin and RSpamDScanner.
We can select one in them for filtering spam mail.

* *SpamAssassin and RSpamDScanner* Mailet is designed to classify the messages as spam or not
with a configurable score threshold. Usually a message will only be
considered as spam if it matches multiple criteria; matching just a single test
will not usually be enough to reach the threshold. Note that this mailet is executed on a per-user basis.

=== SpamAssassin
Here is an example of mailet pipeline conducting out SpamAssassin execution:

....
@@ -55,7 +59,7 @@ the table. Also, the correct approach is to send the original spam or non-spam
as an attachment to another message sent to the feeder in order to avoid bias from the
current sender's email header.

== Feedback for SpamAssassin
=== Feedback for SpamAssassin

If enabled, the `SpamAssassinListener` will asynchronously report users mails moved to the `Spam` mailbox as Spam,
and other mails as `Ham`, effectively populating the user database for per user spam detection. This enables a per-user
@@ -87,4 +91,46 @@ Example:
<async>true</async>
</listener>
</listeners>
....
....

== RSpamD

The RSpamD extension (optional) requires an extra configuration file `rspamd.properties` to configure RSpamd connection

.rspamd.properties content
|===
| Property name | explanation

| rSpamDUrl
| URL defining the RSpamD's server. Eg: http://rspamd:11334

| rSpamDPassword
| Password for pass authentication when request to RSpamD's server. Eg: admin
|===


Here is an example of mailet pipeline conducting out RSpamDScanner execution:

....
<mailet match="All" class="org.apache.james.rspamd.RSpamDScanner">
</mailet>
<mailet match="IsMarkedAsSpam=org.apache.james.rspamd.status" class="WithStorageDirective">
<targetFolderName>Spam</targetFolderName>
</mailet>
....

=== Feedback for RSpamD
If enabled, the `RSpamDListener` will base on the Mailbox event to detect the message is a spam or not, then James will send report `spam` or `ham` to RSpamD
The RSpamD listener needs to explicitly be registered with xref:configure/listeners.adoc[listeners.xml].

Example:

....
<listeners>
<listener>
<class>org.apache.james.rspamd.RSpamDListener</class>
</listener>
</listeners>
....

For more detail about how to use RSpamD's extension: `third-party/rspamd/index.md`
@@ -0,0 +1,50 @@
# James' extensions for RSpamD

This module is for developing and delivering extensions to James for the [RSpamD](https://rspamd.com/) (the spam filtering system)

## How to run

- The RSpamD extension requires an extra configuration file `rspamd.properties` to configure RSpamd connection
Configuration parameters:
- `rSpamDUrl` : URL defining the RSpamD's server. Eg: http://rspamd:11334
- `rSpamDPassword` : Password for pass authentication when request to RSpamD's server. Eg: admin

- Declare the `extensions.properties` for this module.

```
guice.extension.module=org.apache.james.rspamd.module.RSpamDModule
guice.extension.task=org.apache.james.rspamd.module.RSpamDTaskExtensionModule
```

- Declare the RSpamD mailbox listeners in `listeners.xml`. Eg:

```
<listener>
<class>org.apache.james.rspamd.RSpamDListener</class>
</listener>
```

- Declare the RSpamD mailet for custom mail processing. Mailet pipeline Eg:

```
<mailet match="All" class="org.apache.james.rspamd.RSpamDScanner"></mailet>
<mailet match="IsMarkedAsSpam=org.apache.james.rspamd.status" class="WithStorageDirective">
<targetFolderName>Spam</targetFolderName>
</mailet>
```

- Declare the webadmin for RSpamD in `webadmin.properties`

```
extensions.routes=org.apache.james.rspamd.route.FeedMessageRoute
```
How to use admin endpoint, see more at [Additional webadmin endpoints](README.md)

- Docker compose file example: [docker-compose.yml](docker-compose.yml) or [docker-compose-distributed.yml](docker-compose-distributed.yml)
- The sample-configuration: [sample-configuration](sample-configuration)
- For running docker-compose, first compile this project

```
mvn clean install -DskipTests
```
then run it: `docker-compose up`

0 comments on commit 3c3f32d

Please sign in to comment.