Merge pull request #228 from mailcow/dmarc_reporting_docs

Add DMARC Reporting Docs

docs/firststeps-dmarc_reporting.md

@@ -0,0 +1,121 @@
+DMARC Reporting done via Rspamd DMARC Module.
+
+Rspamd documentation can be found here: https://rspamd.com/doc/modules/dmarc.html
+
+**Important:**
+
+1. Change `example.com`, `mail.example.com` and `Example` to reflect your setup
+
+2. DMARC reporting requires additional attention, especially over the first few days
+
+3. All receiving domains hosted on mailcow send from one reporting domain. It is recommended to use the parent domain of your `MAILCOW_HOSTNAME`:
+    - If your `MAILCOW_HOSTNAME` is `mail.example.com` change the following config to `domain = "example.com";`
+    - Set `email` equally, e.g. `email = "noreply-dmarc@example.com";`
+
+4. It is optional but recommended to create an email user `noreply-dmarc` in mailcow to handle bounces.
+
+## Enable DMARC reporting
+
+1. Create the file `data/conf/rspamd/local.d/dmarc.conf` and set the following content:
+
+```
+reporting {
+    enabled = true;
+    email = 'noreply-dmarc@example.com';
+    domain = 'example.com';
+    org_name = 'Example';
+    helo = 'rspamd';
+    smtp = 'postfix';
+    smtp_port = 25;
+    from_name = 'Example DMARC Report';
+    msgid_from = 'rspamd.mail.example.com';
+    max_entries = 2k;
+    keys_expire = 2d;
+}
+```
+
+2. Create or modify `docker-compose.override.yml` in the mailcow-dockerized base directory:
+
+```
+version: '2.1'
+
+services:
+  rspamd-mailcow:
+    environment:
+      - MASTER=${MASTER:-y}
+    labels:
+      ofelia.enabled: "true"
+      ofelia.job-exec.rspamd_dmarc_reporting.schedule: "@every 24h"
+      ofelia.job-exec.rspamd_dmarc_reporting.command: "/bin/bash -c \"[[ $${MASTER} == y ]] && /usr/bin/rspamadm dmarc_report > /var/lib/rspamd/dmarc_reports_last_log 2>&1 || exit 0\""
+  ofelia-mailcow:
+    depends_on:
+      - rspamd-mailcow
+```
+
+3. Run `docker-compose up -d`
+
+## Send a copy reports to yourself
+
+To receive a hidden copy of reports generated by Rspamd you can set a `bcc_addrs` list in the `reporting` config section of `data/conf/rspamd/local.d/dmarc.conf`:
+
+```
+reporting {
+    enabled = true;
+    email = 'noreply-dmarc@example.com';
+    bcc_addrs = ["noreply-dmarc@example.com","parsedmarc@example.com"];
+[...]
+```
+
+Rspamd will load changes in real time, so you won't need to restart the container at this point.
+
+This can be useful if you...
+
+- ...want to check that your DMARC reports are sent correctly and authenticated.
+- ...want to analyze your own reports to get statistics, i.e. to use with ParseDMARC or other analytic systems.
+
+## Troubleshooting
+
+Check when the report schedule last ran:
+
+```
+docker-compose exec rspamd-mailcow date -r /var/lib/rspamd/dmarc_reports_last_log
+```
+
+See the latest report output:
+
+```
+docker-compose exec rspamd-mailcow cat /var/lib/rspamd/dmarc_reports_last_log
+```
+
+Manually trigger a DMARC report:
+
+```
+docker-compose exec rspamd-mailcow rspamadm dmarc_report
+```
+
+Validate that Rspamd has recorded data in Redis:
+
+```
+docker-compose exec redis-mailcow redis-cli KEYS 'dmarc;*'
+docker-compose exec redis-mailcow redis-cli HGETALL "dmarc;example.com;20211231"
+```
+
+## Change DMARC reporting frequency
+
+In the example above reports are sent once every 24 hours. You may want to change that interval:
+
+1. Edit `docker-compose.override.yml` and a djust `ofelia.job-exec.rspamd_dmarc_reporting.schedule: "@every 24h"` to a desired value.
+
+2. Run `docker-compose up -d`
+
+3. Run `docker-compose restart ofelia-mailcow`
+
+## Disable DMARC Reporting
+
+To disable reporting:
+
+1. Set `enabled` to `false` in `data/conf/rspamd/local.d/dmarc.conf`
+
+2. Revert changes done to `docker-compose.override.yml`
+
+3. Run `docker-compose up -d`

mkdocs.yml

@@ -40,6 +40,7 @@ nav:
     - 'Logging': 'firststeps-logging.md'
     - 'Reverse Proxy': 'firststeps-rp.md'
     - 'Rspamd UI': 'firststeps-rspamd_ui.md'
+    - 'DMARC Reporting': 'firststeps-dmarc_reporting.md'
     - 'SNAT': 'firststeps-snat.md'
     - 'Sync job migration': 'firststeps-sync_jobs_migration.md'
   - 'Models':