From: Vsevolod Stakhov <vsevolod@highsecure.ru>
Date: Sat, 5 Sep 2015 16:10:14 +0000 (+0100)
Subject: Add dmarc module documentation.
X-Git-Tag: 1.0.0~83
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=a696faf4490f2a2f698fe9d04d6cfecec52894b6;p=thirdparty%2Frspamd.git

Add dmarc module documentation.
---

diff --git a/doc/markdown/modules/dmarc.md b/doc/markdown/modules/dmarc.md
new file mode 100644
index 0000000000..191e1c2162
--- /dev/null
+++ b/doc/markdown/modules/dmarc.md
@@ -0,0 +1,44 @@
+# 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 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:
+
+~~~nginx
+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:
+
+- `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
+
+When a message violates DMARC policy, rspamd adds the following information to `redis` server:
+
+    unixtime:ip:spf_result:dkim_result
+
+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.
+
+Keys are inserted to redis servers when a server is selected by hash value from sender's domain.
\ No newline at end of file