Update firststeps-dmarc_reporting.md

docs/firststeps-dmarc_reporting.md

@@ -1,62 +1,77 @@
 DMARC Reporting done via Rspamd DMARC Module.
 
-Offical configuration options and documentation can be found here: https://rspamd.com/doc/modules/dmarc.html
+Rspamd documentation can be found here: https://rspamd.com/doc/modules/dmarc.html
 
 **Important:**
-1. Before use config examples from this document please adjust them, change `example.com` and `Example` to your actual data
+1. Before use examples bellow, change `example.com`, `mail.example.com` and `Example` to your actual data
 2. DMARC reporting require additional attention, especially at first days
 3. Your reports for all server will be send from one reporting domain. Recommended to use parent domain of your `MAILCOW_HOSTNAME`, f.e:
     - if your `MAILCOW_HOSTNAME=mail.example.com` then Reporting `domain = "example.com";`
     - set `email` from same domain also, `email = "noreply-dmarc@example.com";`
-4. This optional, but recomended step: create `noreply-dmarc` email user in mailcow to handle bounces.
+4. This optional, but recommended step: create `noreply-dmarc` email user in mailcow to handle bounces.
     - Go to mailcow admin UI → Configuration → Mail Setup → Mailboxes → Add mailbox → Create mailbox `noreply-dmarc`, please choose correct domain
     - In case you want silently discard bounces: login in SOGo from this account and go to Preferences → Mail → Filters → Create Filter → Add action → Provide name, f.e: `noreply` and add action: Discard the message and save filter
     - In case you plan to resend a copy of reports to yourself: you need add condition to previous filter example `From is not noreply-dmarc@example.com`
 
-## Enable DMARC Reports
+## Enable DMARC Reporting
 1. Create or edit file in `data/conf/rspamd/local.d/dmarc.conf` and set content to:
 ```
-reporting = true;
+reporting {
-send_reports = true;
+    enabled = true;
-report_settings {
+    email = 'noreply-dmarc@example.com';
-    org_name = "Example";
+    domain = 'example.com';
-    domain = "example.com";
+    org_name = 'Example';
-    email = "noreply-dmarc@example.com";
+    helo = 'rspamd';
-    from_name = "Example DMARC Report";
+    smtp = 'postfix';
-    smtp = "postfix";
     smtp_port = 25;
-    helo = "rspamd";
+    from_name = 'Example DMARC Report';
-    retries = 3;
+    msgid_from = 'rspamd.mail.example.com';
-    hscan_count = 1500
+    max_entries = 2k;
+    keys_expire = 2d;
 }
 ```
-2. Create required `dmarc_reports_last_sent` file:
+2. Create `docker-compose.override.yml` or merge with your existing one:
-`docker-compose exec rspamd-mailcow bash -c "touch /var/lib/rspamd/dmarc_reports_last_sent; chown 101:101 /var/lib/rspamd/dmarc_reports_last_sent; chmod 644 /var/lib/rspamd/dmarc_reports_last_sent"`
+```
-3. Restart rspamd container:
+version: '2.1'
-`docker-compose restart rspamd-mailcow`
 
-## Disable DMARC Reports
+services:
-To disable reporting set `send_reports` to `false` and restart rspamd container
+  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 get copy of own generated reports you can add `additional_address = "noreply-dmarc@pnnsoft.com";` in `report_settings` section.
+To recieve a hidden copy of reports generated by Rspamd you can set a list of comma-separated emails via `bcc_addrs = ["noreply-dmarc@example.com","parsedmarc@example.com"];` in `reporting` section.
+
+Rspamd will load changes in runtime, no need to restart it.
+
 This useful in case:
 - you want to check that your DMARC Reports send correctly, e.g.: check that they signed by DKIM, etc.
 - you want to analyze own reports to get statics data, f.e: use with ParseDMARC or other analytic system
 
-**Important:**
+## Troubleshooting
+You can check:
+1. Run `docker-compose exec rspamd-mailcow ls -lah /var/lib/rspamd/dmarc_reports_last_log` to check when file was been modified last time
+2. Do `docker-compose exec rspamd-mailcow cat /var/lib/rspamd/dmarc_reports_last_log` to check last report output
+3. Manually trigger sending of DMARC reports via `rspamd-mailcow rspamadm dmarc_report` and check the output
+4. Validate that Rspamd has recorded data in Redis via `docker-compose exec redis-mailcow redis-cli KEYS 'dmarc;*'` and then run `docker-compose exec redis-mailcow redis-cli HGETALL "dmarc;example.com;date"`
 
-Future `additional_address_bcc` is broken, lead to not sending reports to `additional_address` even while it `false`.
+## Change DMARC Reporting Frequency
-Do not add this option to `dmarc.conf` till bug https://github.com/rspamd/rspamd/issues/3465 will be resolved and fixed version will be used in mailcow.
+In the example above reports are send once a 24 hours. To change this behaviour:
+1. Adjust `ofelia.job-exec.rspamd_dmarc_reporting.schedule: "@every 24h"` to desired value in `docker-compose.override.yml`
+2. Run `docker-compose up -d`
+3. Run `docker-compose restart ofelia-mailcow`
 
-## DMARC Force actions 
+## Disable DMARC Reporting
-This module also allows to enable force actions based on sender DMARC policy to reject or quarantine emails which has failed policy.
+To disable reporting:
-This good from security point, but it can lead of rejecting of forwarded email and not allow whitelist broken senders. Better **avoid** using this option.
+1. Set `enabled` to `false` in `data/conf/rspamd/local.d/dmarc.conf`
-
+2. Revert changes done to `docker-compose.override.yml`
-If you still want to enable it, add to end of `data/conf/rspamd/local.d/dmarc.conf`:
+3. Run `docker-compose up -d`
-```
-actions {
-    quarantine = "add_header";
-    reject = "reject";
-}
-```