You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@james.apache.org by bt...@apache.org on 2022/08/10 10:20:33 UTC
[james-project] branch master updated: JAMES-3775 Documentation for RSpamD extension (#1113)
This is an automated email from the ASF dual-hosted git repository.
btellier pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git
The following commit(s) were added to refs/heads/master by this push:
new 3c3f32d707 JAMES-3775 Documentation for RSpamD extension (#1113)
3c3f32d707 is described below
commit 3c3f32d7073509506b0d838c0899fcab733b0f80
Author: vttran <vt...@linagora.com>
AuthorDate: Wed Aug 10 17:20:29 2022 +0700
JAMES-3775 Documentation for RSpamD extension (#1113)
---
.../modules/ROOT/pages/architecture/index.adoc | 4 +-
.../docs/modules/ROOT/pages/configure/index.adoc | 2 +-
.../modules/ROOT/pages/configure/listeners.adoc | 21 ++++++++
.../docs/modules/ROOT/pages/configure/spam.adoc | 60 +++++++++++++++++++---
third-party/rspamd/index.md | 50 ++++++++++++++++++
5 files changed, 127 insertions(+), 10 deletions(-)
diff --git a/server/apps/distributed-app/docs/modules/ROOT/pages/architecture/index.adoc b/server/apps/distributed-app/docs/modules/ROOT/pages/architecture/index.adoc
index 7d767e85a7..a91167e67c 100644
--- a/server/apps/distributed-app/docs/modules/ROOT/pages/architecture/index.adoc
+++ b/server/apps/distributed-app/docs/modules/ROOT/pages/architecture/index.adoc
@@ -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
diff --git a/server/apps/distributed-app/docs/modules/ROOT/pages/configure/index.adoc b/server/apps/distributed-app/docs/modules/ROOT/pages/configure/index.adoc
index 4ea46ef5a0..ed09165bab 100644
--- a/server/apps/distributed-app/docs/modules/ROOT/pages/configure/index.adoc
+++ b/server/apps/distributed-app/docs/modules/ROOT/pages/configure/index.adoc
@@ -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
diff --git a/server/apps/distributed-app/docs/modules/ROOT/pages/configure/listeners.adoc b/server/apps/distributed-app/docs/modules/ROOT/pages/configure/listeners.adoc
index 20974f254c..6bfb45a4a4 100644
--- a/server/apps/distributed-app/docs/modules/ROOT/pages/configure/listeners.adoc
+++ b/server/apps/distributed-app/docs/modules/ROOT/pages/configure/listeners.adoc
@@ -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.
diff --git a/server/apps/distributed-app/docs/modules/ROOT/pages/configure/spam.adoc b/server/apps/distributed-app/docs/modules/ROOT/pages/configure/spam.adoc
index 7a6b240dc4..c7d497eef1 100644
--- a/server/apps/distributed-app/docs/modules/ROOT/pages/configure/spam.adoc
+++ b/server/apps/distributed-app/docs/modules/ROOT/pages/configure/spam.adoc
@@ -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>
-....
\ No newline at end of file
+....
+
+== 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`
\ No newline at end of file
diff --git a/third-party/rspamd/index.md b/third-party/rspamd/index.md
new file mode 100644
index 0000000000..0f1e57e919
--- /dev/null
+++ b/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`
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org