[Doc] Update & rework DMARC module docs

1 files changed, 31 insertions, 27 deletions

diff --git a/doc/markdown/modules/dmarc.md b/doc/markdown/modules/dmarc.md
index f71eb6f91..7bec587ec 100644
--- a/doc/markdown/modules/dmarc.md
+++ b/doc/markdown/modules/dmarc.md
@@ -1,44 +1,48 @@
 # DMARC module
 
-DMARC is a special technology that allows domains to define theirs `SPF` and `DKIM` policies. For example, a domain
-might define that all messages sent must have valid DKIM signature and permissive SPF policies. That is useful for
-domains that deal with payments or other confidential stuff (such as e-banking). Conjunction of SPF, DKIM and DMARC
-allows to avoid or filter fraud for such domains.
-
-Moreover, DMARC allows to set a specific address to collect abused messages. This can be useful for fraud prevention as well.
-DMARC is set using DNS `TXT` record, called `_dmarc.domain.com`. It's format is standartized and here is, for example a record
-that specifies strict policy for SPF and DKIM:
-
-    v=DMARC1; p=reject; rua=mailto:d@rua.agari.com; ruf=mailto:dk@bounce.paypal.com,mailto:d@ruf.agari.com
-
-This record also specifies email addresses for abuse reports (for realtime and archives).
+DMARC is a technology leveraging SPF & DKIM which allows domain owners to publish policies regarding how messages bearing
+their domain in the RFC5322.From field should be handled (for example to quarantine or reject messages which do not have an
+aligned DKIM or SPF identifier) and to elect to receive reporting information about such messages (to help them identify
+abuse and/or misconfiguration and make informed decisions about policy application).
 
 ## DMARC in rspamd
 
-Rspamd supports DMARC policies and also can store information about mails that have violated policies for collecting statistics and sending reports.
-Please mention, that rspamd itself cannot send reports, it merely stores sufficient data in `redis` that could be used for generating DMARC reports by an external tool (not shipped with rspamd now).
-
-DMARC configuration is very simple:
+The default configuration for the DMARC module in rspamd is an empty collection:
 
 ~~~ucl
 dmarc {
-    servers = "localhost:6390";
-    key_prefix = "dmarc_"; # Keys would have format of dmarc_domain.com
 }
 ~~~
 
-When you have this module enabled, it also adds symbols:
+This is enough to enable the module and check/apply DMARC policies.
+
+Symbols added by the module are as follows:
+
+- `DMARC_POLICY_ALLOW`: Message was authenticated & allowed by DMARC policy
+- `DMARC_POLICY_REJECT`: Authentication failed- rejection suggested by DMARC policy
+- `DMARC_POLICY_QUARANTINE`: Authentication failed- quarantine suggested by DMARC policy
+- `DMARC_POLICY_SOFTFAIL`: Authentication failed- no action suggested by DMARC policy
 
-- `DMARC_POLICY_ALLOW`: SPF **and** DKIM policies are satisfied
-- `DMARC_POLICY_REJECT`: SPF **or** DKIM policies are violated
-- `DMARC_POLICY_QUARANTINE`: Message is suggested to be quarantined by DMARC policy
-- `DMARC_POLICY_SOFTFAIL`: DNS or other temporary error
+Rspamd is able to store records in `redis` which could be used to generate DMARC aggregate reports but there is as of yet no available tool to generate such reports from these. Format of the records stored in `redis` is as follows:
 
-When a message violates DMARC policy, rspamd adds the following information to `redis` server:
+    unixtime,ip,spf_result,dkim_result,dmarc_disposition
 
-    unixtime,ip,spf_result,dkim_result
+where spf and dkim results are `true` or `false` indicating wether an aligned spf/dkim identifier was found and dmarc_disposition is one of `none`/`quarantine`/`reject` indicating policy applied to the message.
 
-where results are `true` or `false` meaning allow and reject values accordingly.
-Unixtime and IP are inserted in text form. Keys are therefore `lists` in redis terminology.
+These records are added to a list named $prefix$domain where $domain is the domain which defined policy for the message being reported on and $prefix is the value of the `key_prefix` setting (or "dmarc_" if this isn't set).
 
 Keys are inserted to redis servers when a server is selected by hash value from sender's domain.
+
+To enable storing of report information, `reporting` must be set to `true`.
+
+~~~ucl
+dmarc {
+	# Enables storing reporting information to redis
+	reporting = true;
+	# If Redis server is not configured below, settings from redis {} will be used
+	#servers = "127.0.0.1:6379"; # Servers to use for reads and writes (can be a list)
+	# Alternatively set read_servers / write_servers to split reads and writes
+	# To set custom prefix for redis keys:
+	#key_prefix = "dmarc_";
+}
+~~~