mailcow-dockerized-docs/docs/firststeps-dmarc_reporting.md

DMARC Reporting done via Rspamd DMARC Module.

Rspamd documentation can be found here: https://rspamd.com/doc/modules/dmarc.html

**Important:**
1. Before you use the examples below, 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. Recommended to use parent domain of your `MAILCOW_HOSTNAME`, for example:
    - if your `MAILCOW_HOSTNAME=mail.example.com` then change your reporting config to match `domain = "example.com";`
    - set `email` from the same domain also, `email = "noreply-dmarc@example.com";`
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, enter `noreply` and add action: Discard the message and save filter
    - In case you plan to resend a copy of reports to yourself, you need to add a condition to previous filter example `From is not noreply-dmarc@example.com`

## Enable DMARC Reporting
1. Create or edit file in `data/conf/rspamd/local.d/dmarc.conf` and set contents to:
```
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 `docker-compose.override.yml` or merge with your existing one:
```
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 `reporting` section.

```
reporting {
    enabled = true;
    email = 'noreply-dmarc@example.com';
    bcc_addrs = ["noreply-dmarc@example.com","parsedmarc@example.com"];
...
```

Rspamd will load changes in real time, no need to restart it.

This useful in case:
- you want to check that your DMARC Reports send correctly, check that they signed by DKIM, etc.
- you want to analyze own reports to get statics data, for example use with ParseDMARC or other analytic system

## Troubleshooting

Check when the report schedule last ran
```
docker-compose exec rspamd-mailcow date -r /var/lib/rspamd/dmarc_reports_last_log
```

See last report output
```
docker-compose exec rspamd-mailcow cat /var/lib/rspamd/dmarc_reports_last_log
```

Manually Trigger 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 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`

## 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`