From: Andrew Lewis Date: Wed, 6 Jul 2016 19:40:29 +0000 (+0200) Subject: [Doc] Update & rework DMARC module docs X-Git-Tag: 1.3.0~151^2 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=0fa9a9b37364ad21549efc21f47261d3ea80b760;p=rspamd.git [Doc] Update & rework DMARC module docs --- 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_"; +} +~~~