github-com-docker-mailserver/docker-mailserver
1
0
Fork 0
mirror of https://github.com/docker-mailserver/docker-mailserver.git synced 2024-01-19 02:48:50 +00:00
Code Issues Projects Releases Wiki Activity

docs: Combine DKIM/DMARC/SPF pages (#3231)

Browse source 
Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
This commit is contained in:
Georg Lauterbach 2023-04-10 12:08:58 +02:00 committed by GitHub
parent ff087837bd
commit 34a1fd613f
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
10 changed files with 362 additions and 334 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docs/content/config/advanced/optional-config.md
View file

@ -4,7 +4,7 @@ hide:
- toc # Hide Table of Contents for this page - toc # Hide Table of Contents for this page
--- ---
This is a list of all configuration files and directories which are optional or automatically generated in your `docker-data/dms/config/` directory. This is a list of all configuration files and directories which are optional or automatically generated in your `docker-data/dms/config/` directory. We use this path to reference the local config directory in our docs, which you should attach a volume into the container at `/tmp/docker-mailserver`.
## Directories ## Directories
@ -43,7 +43,7 @@ This is a list of all configuration files and directories which are optional or
[docs-accounts-quota]: ../../config/user-management.md#quotas [docs-accounts-quota]: ../../config/user-management.md#quotas
[docs-aliases-regex]: ../../config/user-management.md#configuring-regexp-aliases [docs-aliases-regex]: ../../config/user-management.md#configuring-regexp-aliases
[docs-dkim]: ../../config/best-practices/dkim.md [docs-dkim]: ../../config/best-practices/dkim_dmarc_spf.md#dkim
[docs-fail2ban]: ../../config/security/fail2ban.md [docs-fail2ban]: ../../config/security/fail2ban.md
[docs-faq-spamrules]: ../../faq.md#how-can-i-manage-my-custom-spamassassin-rules [docs-faq-spamrules]: ../../faq.md#how-can-i-manage-my-custom-spamassassin-rules
[docs-faq-userpatches]: ../../faq.md#how-to-adjust-settings-with-the-user-patchessh-script [docs-faq-userpatches]: ../../faq.md#how-to-adjust-settings-with-the-user-patchessh-script

2
docs/content/config/best-practices/autodiscover.md
View file

@ -4,6 +4,8 @@ hide:
- toc # Hide Table of Contents for this page - toc # Hide Table of Contents for this page
--- ---
# Auto-Discovery of Services
Email auto-discovery means a client email is able to automagically find out about what ports and security options to use, based on the mail-server URI. It can help simplify the tedious / confusing task of adding own's email account for non-tech savvy users. Email auto-discovery means a client email is able to automagically find out about what ports and security options to use, based on the mail-server URI. It can help simplify the tedious / confusing task of adding own's email account for non-tech savvy users.
Email clients will search for auto-discoverable settings and prefill almost everything when a user enters its email address :heart: Email clients will search for auto-discoverable settings and prefill almost everything when a user enters its email address :heart:

123
docs/content/config/best-practices/dkim.md
View file

@ -1,123 +0,0 @@
---
title: 'Best Practices | DKIM'
---
DKIM is a security measure targeting email spoofing. It is greatly recommended one activates it.
!!! note
See [the Wikipedia page](https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail) for more details on DKIM.
## Enabling DKIM Signature
To enable DKIM signature, **you must have created at least one email account**. Once its done, just run the following command to generate the signature:
```sh
./setup.sh config dkim
```
After generating DKIM keys, you should restart `docker-mailserver`. DNS edits may take a few minutes to hours to propagate.
The script should ideally be run with a volume for _config_ attached (eg: `./docker-data/dms/config/:/tmp/docker-mailserver/`), otherwise by default it will mount `./config/:/tmp/docker-mailserver/`.
The default keysize when generating the signature is 4096 bits for now. If you need to change it (e.g. your DNS provider limits the size), then provide the size as the first parameter of the command:
```sh
./setup.sh config dkim keysize <keysize>
```
For LDAP systems that do not have any directly created user account you can run the following command (since `8.0.0`) to generate the signature by additionally providing the desired domain name (if you have multiple domains use the command multiple times or provide a comma-separated list of domains):
```sh
./setup.sh config dkim keysize <key-size> domain <example.com>[,<not-example.com>]
```
Now the keys are generated, you can configure your DNS server with DKIM signature, simply by adding a TXT record. If you have direct access to your DNS zone file, then it's only a matter of pasting the content of `docker-data/dms/config/opendkim/keys/example.com/mail.txt` in your `example.com.hosts` zone.
```console
$ dig mail._domainkey.example.com TXT
---
;; ANSWER SECTION
mail._domainkey.<DOMAIN> 300 IN TXT "v=DKIM1; k=rsa; p=AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN"
```
## Configuration using a Web Interface
1. Generate a new record of the type `TXT`.
2. Paste `mail._domainkey` the `Name` txt field.
3. In the `Target` or `Value` field fill in `v=DKIM1; k=rsa; p=AZERTYUGHJKLMWX...`.
4. In `TTL` (time to live): Time span in seconds. How long the DNS server should cache the `TXT` record.
5. Save.
!!! note
Sometimes the key in `docker-data/dms/config/opendkim/keys/example.com/mail.txt` can be on multiple lines. If so then you need to concatenate the values in the TXT record:
```console
$ dig mail._domainkey.example.com TXT
---
;; ANSWER SECTION
mail._domainkey.<DOMAIN> 300 IN TXT "v=DKIM1; k=rsa; "
"p=AZERTYUIOPQSDF..."
"asdfQWERTYUIOPQSDF..."
```
The target (or value) field must then have all the parts together: `v=DKIM1; k=rsa; p=AZERTYUIOPQSDF...asdfQWERTYUIOPQSDF...`
## Verify-Only
If you want DKIM to only _verify_ incoming emails, the following version of `/etc/opendkim.conf` may be useful (right now there is no easy mechanism for installing it other than forking the repo):
```conf
# This is a simple config file verifying messages only
#LogWhy yes
Syslog yes
SyslogSuccess yes
Socket inet:12301@localhost
PidFile /var/run/opendkim/opendkim.pid
ReportAddress postmaster@example.com
SendReports yes
Mode v
```
## Switch Off DKIM
Simply remove the DKIM key by recreating (not just relaunching) the `docker-mailserver` container.
## Debugging
- [DKIM-verifer](https://addons.mozilla.org/en-US/thunderbird/addon/dkim-verifier): A add-on for the mail client Thunderbird.
- You can debug your TXT records with the `dig` tool.
```console
$ dig TXT mail._domainkey.example.com
---
; <<>> DiG 9.10.3-P4-Debian <<>> TXT mail._domainkey.example.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 39669
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 512
;; QUESTION SECTION:
;mail._domainkey.example.com. IN TXT
;; ANSWER SECTION:
mail._domainkey.example.com. 3600 IN TXT "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCxBSjG6RnWAdU3oOlqsdf2WC0FOUmU8uHVrzxPLW2R3yRBPGLrGO1++yy3tv6kMieWZwEBHVOdefM6uQOQsZ4brahu9lhG8sFLPX4MaKYN/NR6RK4gdjrZu+MYSdfk3THgSbNwIDAQAB"
;; Query time: 50 msec
;; SERVER: 127.0.1.1#53(127.0.1.1)
;; WHEN: Wed Sep 07 18:22:57 CEST 2016
;; MSG SIZE rcvd: 310
```
---
!!! warning "Key sizes >=4096-bit"
Keys of 4096 bits could de denied by some mail-servers. According to https://tools.ietf.org/html/rfc6376 keys are preferably between 512 and 2048 bits. See issue [#1854][github-issue-1854].
[github-issue-1854]: https://github.com/docker-mailserver/docker-mailserver/issues/1854

346
docs/content/config/best-practices/dkim_dmarc_spf.md Normal file
View file

@ -0,0 +1,346 @@
# DKIM, DMARC & SPF
Cloudflare has written an [article about DKIM, DMARC and SPF][cloudflare-dkim-dmarc-spf] that we highly recommend you to read to get acquainted with the topic.
!!! note "Rspamd vs Individual validators"
With v12.0.0, Rspamd was integrated into DMS. It can perform validations for DKIM, DMARC and SPF as part of the `spam-score-calculation` for an email. DMS provides individual alternatives for each validation that can be used instead of deferring to Rspamd:
- DKIM: `opendkim` is used as a milter (like Rspamd)
- DMARC: `opendmarc` is used as a milter (like Rspamd)
- SPF: `policyd-spf` is used in Postfix's `smtpd_recipient_restrictions`
In a future release Rspamd will become the default for these validations, with a deprecation notice issued prior to the removal of the above alternatives.
We encourage everyone to prefer Rspamd via `ENABLE_RSPAMD=1`.
!!! warning "DNS Caches & Propagation"
While modern DNS providers are quick, it may take minutes or even hours for new DNS records to become available / propagate.
## DKIM
!!! quote "What is DKIM"
DomainKeys Identified Mail (DKIM) is an email authentication method designed to detect forged sender addresses in email (email spoofing), a technique often used in phishing and email spam.
[Source][wikipedia-dkim]
When DKIM is enabled:
1. Inbound mail will verify any included DKIM signatures
2. Outbound mail is signed (_when you're sending domain has a configured DKIM key_)
DKIM requires a public/private key pair to enable **signing (_via private key_)** your outgoing mail, while the receiving end must query DNS to **verify (_via public key_)** that the signature is trustworthy.
### Generating Keys
You should have:
- At least one [email account setup][docs-accounts-add]
- Attached a [volume for config][docs-volumes-config] to persist the generated files to local storage
DKIM is currently supported by either OpenDKIM or Rspamd:
=== "OpenDKIM"
OpenDKIM is currently [enabled by default][docs-env-opendkim].
The command `docker exec <CONTAINER NAME> setup config dkim help` details supported config options, along with some examples.
!!! example "Create a DKIM key"
Generate the DKIM files with:
```sh
docker exec -ti <CONTAINER NAME> setup config dkim
```
Your new DKIM key(s) and OpenDKIM config files have been added to `/tmp/docker-mailserver/opendkim/`.
??? note "LDAP accounts need to specify domains explicitly"
The command is unable to infer the domains from LDAP user accounts, you must specify them:
```sh
setup config dkim domain 'example.com,example.io'
```
??? tip "Changing the key size"
The private key presently defaults to RSA-4096. To create an RSA 2048-bit key run:
```sh
setup config dkim keysize 2048
```
=== "Rspamd"
Opt-in via [`ENABLE_RSPAMD=1`][docs-env-rspamd] (_and disable the default OpenDKIM: `ENABLE_OPENDKIM=0`_).
Rspamd provides DKIM support through two separate modules:
1. [Verifying DKIM signatures from inbound mail][rspamd-docs-dkim-checks] is enabled by default.
2. [Signing outbound mail with your DKIM key][rspamd-docs-dkim-signing] needs additional setup (key + dns + config).
!!! example "Create a DKIM key"
Presently only OpenDKIM is supported with `setup config dkim`. To generate your DKIM key and DNS files you'll need to specify:
- `-s` The DKIM selector (_eg: `mail`, it can be anything you like_)
- `-d` The sender address domain (_everything after `@` from the email address_)
See `rspamadm dkim_keygen -h` for an overview of the supported options.
---
1. Go inside the container with `docker exec -ti <CONTAINER NAME> bash`
2. Add `rspamd/dkim/` folder to your config volume and switch to it: `cd /tmp/docker-mailserver/rspamd/dkim`
3. Run: `rspamadm dkim_keygen -s mail -b 2048 -d example.com -k mail.private > mail.txt` (_change `-d` to your domain-part_)
4. Presently you must ensure Rspamd can read the `<selector>.private` file, run:
-`chgrp _rspamd mail.private`
-`chmod g+r mail.private`
---
!!! bug inline end "DMS config volume support is not ready for Rspamd"
Presently you'll need to [explicitly mount `rspamd/modules/override.d/`][docs-rspamd-config-dropin] as an additional volume; do not use [`rspamd-modules.conf`][docs-rspamd-config-declarative] for this purpose.
Create a configuration file for the DKIM signing module at `rspamd/modules/override.d/dkim_signing.conf` and populate it with config as shown in the example below:
??? example "DKIM Signing Module Configuration Examples"
A simple configuration could look like this:
```cf
# documentation: https://rspamd.com/doc/modules/dkim_signing.html
enabled = true;
sign_authenticated = true;
sign_local = true;
use_domain = "header";
use_redis = false; # don't change unless Redis also provides the DKIM keys
use_esld = true;
check_pubkey = true; # you wan't to use this in the beginning
domain {
example.com {
path = "/tmp/docker-mailserver/rspamd/dkim/mail.private";
selector = "mail";
}
}
```
As shown next, you can:
- You can add more domains into the `domain { ... }` section.
- A domain can also be configured with multiple selectors and keys within a `selectors [ ... ]` array.
```cf
# ...
domain {
example.com {
selectors [
{
path = "/tmp/docker-mailserver/rspamd/dkim/example.com/rsa.private";
selector = "dkim-rsa";
},
{
path = /tmp/docker-mailserver/rspamd/example.com/ed25519.private";
selector = "dkim-ed25519";
}
]
}
example.org {
selectors [
{
path = "/tmp/docker-mailserver/rspamd/dkim/example.org/rsa.private";
selector = "dkim-rsa";
},
{
path = "/tmp/docker-mailserver/rspamd/dkim/example.org/ed25519.private";
selector = "dkim-ed25519";
}
]
}
}
```
!!! warning "Support for DKIM keys using Ed25519"
This modern elliptic curve is supported by Rspamd, but support by third-parties for [verifying Ed25519 DKIM signatures is unreliable][dkim-ed25519-support].
If you sign your mail with this key type, you should include RSA as a fallback, like shown in the above example.
!!! tip "DKIM Signing config: `check_pubkey = true;`"
This setting will have Rspamd query the DNS record for each DKIM selector, verifying each public key matches the private key configured.
If there is a mismatch, a warning will be omitted to the Rspamd log (`/var/log/supervisor/rspamd.log`).
!!! info "Restart required"
After restarting `docker-mailserver`, outgoing mail will now be signed with your new DKIM key(s) :tada:
You'll need to repeat this process if you add any new domains.
!!! warning "RSA Key Sizes >= 4096 Bit"
Keys of 4096 bits could denied by some mail servers. According to [RFC 6376][rfc-6376] keys are [preferably between 512 and 2048 bits][github-issue-dkimlength].
### DNS Record { #dkim-dns }
When mail signed with your DKIM key is sent from your mail server, the receiver needs to check a DNS `TXT` record to verify the DKIM signature is trustworthy.
!!! example "Configuring DNS - DKIM record"
When you generated your key in the previous step, the DNS data was saved into a file `<selector>.txt` (default: `mail.txt`). Use this content to update your [DNS via Web Interface][dns::example-webui] or directly edit your [DNS Zone file][dns::wikipedia-zonefile]:
=== "Web Interface"
Create a new record:
| Field | Value |
| ----- | ------------------------------------------------------------------------------ |
| Type | `TXT` |
| Name | `<selector>._domainkey` (_default: `mail._domainkey`_) |
| TTL | Use the default (_otherwise [3600 seconds is appropriate][dns::digicert-ttl]_) |
| Data | File content within `( ... )` (_formatted as advised below_) |
=== "DNS Zone file"
`<selector>.txt` is already formatted as a snippet for adding to your [DNS Zone file][dns::wikipedia-zonefile].
Just copy/paste the file contents into your existing DNS zone. The `TXT` value has been split into separate strings every 255 characters for compatibility.
??? info "`<selector>.txt` - Formatting the `TXT` record value correctly"
This file was generated for use within a [DNS zone file][dns::wikipedia-zonefile]. DNS `TXT` records values that are longer than 255 characters need to be split into multiple parts. This is why the public key has multiple parts wrapped within double-quotes between `(` and `)`.
A DNS web-interface may handle this internally instead, while [others may not, but expect the input as a single line][dns::webui-dkim]_). You'll need to manually format the value as described below.
Your DNS record file (eg: `mail.txt`) should look similar to this:
```txt
mail._domainkey IN TXT ( "v=DKIM1; k=rsa; "
"p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqQMMqhb1S52Rg7VFS3EC6JQIMxNDdiBmOKZvY5fiVtD3Z+yd9ZV+V8e4IARVoMXWcJWSR6xkloitzfrRtJRwOYvmrcgugOalkmM0V4Gy/2aXeamuiBuUc4esDQEI3egmtAsHcVY1XCoYfs+9VqoHEq3vdr3UQ8zP/l+FP5UfcaJFCK/ZllqcO2P1GjIDVSHLdPpRHbMP/tU1a9mNZ"
"5QMZBJ/JuJK/s+2bp8gpxKn8rh1akSQjlynlV9NI+7J3CC7CUf3bGvoXIrb37C/lpJehS39KNtcGdaRufKauSfqx/7SxA0zyZC+r13f7ASbMaQFzm+/RRusTqozY/p/MsWx8QIDAQAB"
) ;
```
Take the content between `( ... )`, and combine all the quote wrapped content and remove the double-quotes including the white-space between them. That is your `TXT` record value, the above example would become this:
```txt
v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqQMMqhb1S52Rg7VFS3EC6JQIMxNDdiBmOKZvY5fiVtD3Z+yd9ZV+V8e4IARVoMXWcJWSR6xkloitzfrRtJRwOYvmrcgugOalkmM0V4Gy/2aXeamuiBuUc4esDQEI3egmtAsHcVY1XCoYfs+9VqoHEq3vdr3UQ8zP/l+FP5UfcaJFCK/ZllqcO2P1GjIDVSHLdPpRHbMP/tU1a9mNZ5QMZBJ/JuJK/s+2bp8gpxKn8rh1akSQjlynlV9NI+7J3CC7CUf3bGvoXIrb37C/lpJehS39KNtcGdaRufKauSfqx/7SxA0zyZC+r13f7ASbMaQFzm+/RRusTqozY/p/MsWx8QIDAQAB
```
To test that your new DKIM record is correct, query it with the `dig` command. The `TXT` value response should be a single line split into multiple parts wrapped in double-quotes:
```console
$ dig +short TXT dkim-rsa._domainkey.example.com
"v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqQMMqhb1S52Rg7VFS3EC6JQIMxNDdiBmOKZvY5fiVtD3Z+yd9ZV+V8e4IARVoMXWcJWSR6xkloitzfrRtJRwOYvmrcgugOalkmM0V4Gy/2aXeamuiBuUc4esDQEI3egmtAsHcVY1XCoYfs+9VqoHEq3vdr3UQ8zP/l+FP5UfcaJFCK/ZllqcO2P1GjIDVSHLdPpRHbMP/tU1a9mNZ5QMZBJ/JuJK/s+2bp8gpxKn8rh1akSQjlynlV9NI+7J3CC7CUf3bGvoXIrb37C/lpJehS39" "KNtcGdaRufKauSfqx/7SxA0zyZC+r13f7ASbMaQFzm+/RRusTqozY/p/MsWx8QIDAQAB"
```
### Troubleshooting { #dkim-debug }
[MxToolbox has a DKIM Verifier][mxtoolbox-dkim-verifier] that you can use to check your DKIM DNS record(s).
When using Rspamd, we recommend you turn on `check_pubkey = true;` in `dkim_signing.conf`. Rspamd will then check whether your private key matches your public key, and you can check possible mismatches by looking at `/var/log/supervisor/rspamd.log`.
## DMARC
With DMS, DMARC is pre-configured out of the box. You may disable extra and excessive DMARC checks when using Rspamd via `ENABLE_OPENDMARC=0`.
The only thing you need to do in order to enable DMARC on a "DNS-level" is to add new `TXT`. In contrast to [DKIM](#dkim), DMARC DNS entries do not require any keys, but merely setting the [configuration values][dmarc-howto-configtags]. You can either handcraft the entry by yourself or use one of available generators (like [this one][dmarc-tool-gca]).
Typically something like this should be good to start with:
```txt
_dmarc.example.com. IN TXT "v=DMARC1; p=none; sp=none; fo=0; adkim=4; aspf=r; pct=100; rf=afrf; ri=86400; rua=mailto:dmarc.report@example.com; ruf=mailto:dmarc.report@example.com"
```
Or a bit more strict policies (_mind `p=quarantine` and `sp=quarantine`_):
```txt
_dmarc.example.com. IN TXT "v=DMARC1; p=quarantine; sp=quarantine; fo=0; adkim=r; aspf=r; pct=100; rf=afrf; ri=86400; rua=mailto:dmarc.report@example.com; ruf=mailto:dmarc.report@example.com"
```
The DMARC status may not be displayed instantly due to delays in DNS (caches). Dmarcian has [a few tools][dmarcian-tools] you can use to verify your DNS records.
## SPF
!!! quote "What is SPF"
Sender Policy Framework (SPF) is a simple email-validation system designed to detect email spoofing by providing a mechanism to allow receiving mail exchangers to check that incoming mail from a domain comes from a host authorized by that domain's administrators.
[Source][wikipedia-spf]
!!! note "Disabling `policyd-spf`?"
As of now, `policyd-spf` cannot be disabled. This is WIP.
### Adding an SPF Record
To add a SPF record in your DNS, insert the following line in your DNS zone:
```txt
example.com. IN TXT "v=spf1 mx ~all"
```
This enables the _Softfail_ mode for SPF. You could first add this SPF record with a very low TTL. _SoftFail_ is a good setting for getting started and testing, as it lets all email through, with spams tagged as such in the mailbox.
After verification, you _might_ want to change your SPF record to `v=spf1 mx -all` so as to enforce the _HardFail_ policy. See <http://www.open-spf.org/SPF_Record_Syntax> for more details about SPF policies.
In any case, increment the SPF record's TTL to its final value.
### Backup MX & Secondary MX for `policyd-spf`
For whitelisting an IP Address from the SPF test, you can create a config file (see [`policyd-spf.conf`](https://www.linuxcertif.com/man/5/policyd-spf.conf)) and mount that file into `/etc/postfix-policyd-spf-python/policyd-spf.conf`.
**Example:** Create and edit a `policyd-spf.conf` file at `docker-data/dms/config/postfix-policyd-spf.conf`:
```conf
debugLevel = 1
#0(only errors)-4(complete data received)
skip_addresses = 127.0.0.0/8,::ffff:127.0.0.0/104,::1
# Preferably use IP-Addresses for whitelist lookups:
Whitelist = 192.168.0.0/31,192.168.1.0/30
# Domain_Whitelist = mx1.not-example.com,mx2.not-example.com
```
Then add this line to `docker-compose.yml`:
```yaml
volumes:
- ./docker-data/dms/config/postfix-policyd-spf.conf:/etc/postfix-policyd-spf-python/policyd-spf.conf
```
[docs-accounts-add]: ../user-management.md#adding-a-new-account
[docs-volumes-config]: ../advanced/optional-config.md
[docs-env-opendkim]: ../environment.md#enable_opendkim
[docs-env-rspamd]: ../environment.md#enable_rspamd
[docs-rspamd-config-dropin]: ../security/rspamd.md#manually
[docs-rspamd-config-declarative]: ../security/rspamd.md#with-the-help-of-a-custom-file
[cloudflare-dkim-dmarc-spf]: https://www.cloudflare.com/learning/email-security/dmarc-dkim-spf/
[rfc-6376]: https://tools.ietf.org/html/rfc6376
[github-issue-dkimlength]: https://github.com/docker-mailserver/docker-mailserver/issues/1854
[rspamd-docs-dkim-checks]: https://www.rspamd.com/doc/modules/dkim.html
[rspamd-docs-dkim-signing]: https://www.rspamd.com/doc/modules/dkim_signing.html
[dns::example-webui]: https://www.vultr.com/docs/introduction-to-vultr-dns/
[dns::digicert-ttl]: https://www.digicert.com/faq/dns/what-is-ttl
[dns::wikipedia-zonefile]: https://en.wikipedia.org/wiki/Zone_file
[dns::webui-dkim]: https://serverfault.com/questions/763815/route-53-doesnt-allow-adding-dkim-keys-because-length-is-too-long
[dkim-ed25519-support]: https://serverfault.com/questions/1023674/is-ed25519-well-supported-for-the-dkim-validation/1074545#1074545
[mxtoolbox-dkim-verifier]: https://mxtoolbox.com/dkim.aspx
[dmarc-howto-configtags]: https://github.com/internetstandards/toolbox-wiki/blob/master/DMARC-how-to.md#overview-of-dmarc-configuration-tags
[dmarc-tool-gca]: https://dmarcguide.globalcyberalliance.org
[dmarcian-tools]: https://dmarcian.com/dmarc-tools/
[wikipedia-dkim]: https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail
[wikipedia-spf]: https://en.wikipedia.org/wiki/Sender_Policy_Framework

36
docs/content/config/best-practices/dmarc.md
View file

@ -1,36 +0,0 @@
---
title: 'Best Practices | DMARC'
hide:
- toc # Hide Table of Contents for this page
---
More information at [DMARC Guide][dmarc-howto].
## Enabling DMARC
In `docker-mailserver`, DMARC is pre-configured out of the box. The only thing you need to do in order to enable it, is to add new `TXT` entry to your DNS.
In contrast with [DKIM][docs-dkim], the DMARC DNS entry does not require any keys, but merely setting the [configuration values][dmarc-howto::configtags]. You can either handcraft the entry by yourself or use one of available generators (like [this one][dmarc-tool::gca]).
Typically something like this should be good to start with (_don't forget to replace `@example.com` to your actual domain_):
```
_dmarc.example.com. IN TXT "v=DMARC1; p=none; rua=mailto:dmarc.report@example.com; ruf=mailto:dmarc.report@example.com; sp=none; ri=86400"
```
Or a bit more strict policies (_mind `p=quarantine` and `sp=quarantine`_):
```
_dmarc IN TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc.report@example.com; ruf=mailto:dmarc.report@example.com; fo=0; adkim=r; aspf=r; pct=100; rf=afrf; ri=86400; sp=quarantine"
```
DMARC status is not being displayed instantly in Gmail for instance. If you want to check it directly after DNS entries, you can use some services around the Internet such as from [Global Cyber Alliance][dmarc-tool::gca] or [RedSift][dmarc-tool::redsift]. In other cases, email clients will show "DMARC: PASS" in ~1 day or so.
Reference: [#1511][github-issue-1511]
[docs-dkim]: ./dkim.md
[github-issue-1511]: https://github.com/docker-mailserver/docker-mailserver/issues/1511
[dmarc-howto]: https://github.com/internetstandards/toolbox-wiki/blob/master/DMARC-how-to.md
[dmarc-howto::configtags]: https://github.com/internetstandards/toolbox-wiki/blob/master/DMARC-how-to.md#overview-of-dmarc-configuration-tags
[dmarc-tool::gca]: https://dmarcguide.globalcyberalliance.org
[dmarc-tool::redsift]: https://ondmarc.redsift.com

59
docs/content/config/best-practices/spf.md
View file

@ -1,59 +0,0 @@
---
title: 'Best Practices | SPF'
hide:
- toc # Hide Table of Contents for this page
---
From [Wikipedia](https://en.wikipedia.org/wiki/Sender_Policy_Framework):
!!! quote
Sender Policy Framework (SPF) is a simple email-validation system designed to detect email spoofing by providing a mechanism to allow receiving mail exchangers to check that incoming mail from a domain comes from a host authorized by that domain's administrators. The list of authorized sending hosts for a domain is published in the Domain Name System (DNS) records for that domain in the form of a specially formatted TXT record. Email spam and phishing often use forged "from" addresses, so publishing and checking SPF records can be considered anti-spam techniques.
!!! note
For a more technical review: https://github.com/internetstandards/toolbox-wiki/blob/master/SPF-how-to.md
## Add a SPF Record
To add a SPF record in your DNS, insert the following line in your DNS zone:
```txt
; MX record must be declared for SPF to work
example.com. IN MX 1 mail.example.com.
; SPF record
example.com. IN TXT "v=spf1 mx ~all"
```
This enables the _Softfail_ mode for SPF. You could first add this SPF record with a very low TTL.
_SoftFail_ is a good setting for getting started and testing, as it lets all email through, with spams tagged as such in the mailbox.
After verification, you _might_ want to change your SPF record to `v=spf1 mx -all` so as to enforce the _HardFail_ policy. See http://www.open-spf.org/SPF_Record_Syntax for more details about SPF policies.
In any case, increment the SPF record's TTL to its final value.
## Backup MX, Secondary MX
For whitelisting an IP Address from the SPF test, you can create a config file (see [`policyd-spf.conf`](https://www.linuxcertif.com/man/5/policyd-spf.conf)) and mount that file into `/etc/postfix-policyd-spf-python/policyd-spf.conf`.
**Example:**
Create and edit a `policyd-spf.conf` file at `docker-data/dms/config/postfix-policyd-spf.conf`:
```conf
debugLevel = 1
#0(only errors)-4(complete data received)
skip_addresses = 127.0.0.0/8,::ffff:127.0.0.0/104,::1
# Preferably use IP-Addresses for whitelist lookups:
Whitelist = 192.168.0.0/31,192.168.1.0/30
# Domain_Whitelist = mx1.not-example.com,mx2.not-example.com
```
Then add this line to `docker-compose.yml`:
```yaml
volumes:
- ./docker-data/dms/config/postfix-policyd-spf.conf:/etc/postfix-policyd-spf-python/policyd-spf.conf
```

78
docs/content/config/security/rspamd.md
View file

@ -78,7 +78,7 @@ DMS brings sane default settings for Rspamd. They are located at `/etc/rspamd/lo
### With the Help of a Custom File ### With the Help of a Custom File
DMS provides the ability to do simple adjustments to Rspamd modules with the help of a single file. Just place a file called `rspamd-modules.conf` into the directory `docker-data/dms/config/` (which translates to `/tmp/docker-mailserver/` in the container). If this file is present, DMS will evaluate it. The structure is _very_ simple. Each line in the file looks like this: DMS provides the ability to do simple adjustments to Rspamd modules with the help of a single file. Just place a file called `rspamd-modules.conf` into the [local config directory `docker-data/dms/config/`][docs-volumes-config]. If this file is present, DMS will evaluate it. The structure is _very_ simple. Each line in the file looks like this:
```txt ```txt
COMMAND ARGUMENT1 ARGUMENT2 ARGUMENT3 COMMAND ARGUMENT1 ARGUMENT2 ARGUMENT3
@ -133,80 +133,9 @@ Rspamd is running, but you want or need to adjust it?
### DKIM Signing ### DKIM Signing
By default, DMS offers no option to generate and configure signing e-mails with DKIM. This is because the parsing would be difficult. But don't worry: the process is relatively straightforward nevertheless. The [official Rspamd documentation for the DKIM signing module][dkim-signing-module] is pretty good. Basically, you need to There is a dedicated [section for setting up DKIM with Rspamd in our documentation][docs-dkim-with-rspamd].
1. `exec` into the container [docs-dkim-with-rspamd]: ../best-practices/dkim_dmarc_spf.md#dkim
2. Run a command similar to `rspamadm dkim_keygen -s 'woosh' -b 2048 -d example.com -k example.private > example.txt`, adjusted to your needs
3. Make sure to then persists the files `example.private` and `example.txt` (created in step 2) in the container (for example with a Docker bind mount)
4. Create a configuration for the DKIM signing module, i.e. a file called `dkim_signing.conf` that you mount to `/etc/rspamd/local.d/` or `/etc/rspamd/override.d/`. We provide example configurations down below. We recommend mounting this file into the container as well (as described [here](#manually)); do not use [`rspamd-modules.conf`](#with-the-help-of-a-custom-file) for this purpose.
??? example "DKIM Signing Module Configuration Examples"
A simple configuration could look like this:
```cf
# documentation: https://rspamd.com/doc/modules/dkim_signing.html
enabled = true;
sign_authenticated = true;
sign_local = true;
use_domain = "header";
use_redis = false; # don't change unless Redis also provides the DKIM keys
use_esld = true;
check_pubkey = true;
domain {
example.com {
path = "/path/to/example.private";
selector = "woosh";
}
}
```
If you have multiple domains and you want to sign with the modern ED25519 elliptic curve but also with RSA (you will likely want to have RSA as a fallback!):
```cf
# documentation: https://rspamd.com/doc/modules/dkim_signing.html
enabled = true;
sign_authenticated = true;
sign_local = true;
use_domain = "header";
use_redis = false; # don't change unless Redis also provides the DKIM keys
use_esld = true;
check_pubkey = true;
domain {
example.com {
selectors [
{
path = "/path/to/com.example.rsa.private";
selector = "dkim-rsa";
},
{
path = /path/to/com.example.ed25519.private";
selector = "dkim-ed25519";
}
]
}
example.org {
selectors [
{
path = "/path/to/org.example.rsa.private";
selector = "dkim-rsa";
},
{
path = "/path/to/org.example.ed25519.private";
selector = "dkim-ed25519";
}
]
}
}
```
### _Abusix_ Integration ### _Abusix_ Integration
@ -226,6 +155,7 @@ While _Abusix_ can be integrated into Postfix, Postscreen and a multitude of oth
[//]: # (General Links) [//]: # (General Links)
[docs-volumes-config]: ../advanced/optional-config.md
[homepage]: https://rspamd.com/ [homepage]: https://rspamd.com/
[modules]: https://rspamd.com/doc/modules/ [modules]: https://rspamd.com/doc/modules/
[proxy-self-scan-mode]: https://rspamd.com/doc/workers/rspamd_proxy.html#self-scan-mode [proxy-self-scan-mode]: https://rspamd.com/doc/workers/rspamd_proxy.html#self-scan-mode

4
docs/content/examples/tutorials/basic-installation.md
View file

@ -218,8 +218,8 @@ In this setup `docker-mailserver` is not intended to receive email from the outs
[docs-ports]: ../../config/security/understanding-the-ports.md [docs-ports]: ../../config/security/understanding-the-ports.md
[docs-environment]: ../../config/environment.md [docs-environment]: ../../config/environment.md
[docs-spf]: ../../config/best-practices/spf.md [docs-spf]: ../../config/best-practices/dkim_dmarc_spf.md#spf
[docs-dkim]: ../../config/best-practices/dkim.md [docs-dkim]: ../../config/best-practices/dkim_dmarc_spf.md#dkim
[docs-ssl]: ../../config/security/ssl.md#lets-encrypt-recommended [docs-ssl]: ../../config/security/ssl.md#lets-encrypt-recommended
[docs-usage]: ../../usage.md#get-up-and-running [docs-usage]: ../../usage.md#get-up-and-running
[github-issue-ufw]: https://github.com/docker-mailserver/docker-mailserver/issues/3151 [github-issue-ufw]: https://github.com/docker-mailserver/docker-mailserver/issues/3151

38
docs/content/usage.md
View file

@ -159,44 +159,12 @@ You should add at least one [alias][docs-aliases], the [_postmaster alias_][docs
docker exec -ti <CONTAINER NAME> setup alias add postmaster@example.com user@example.com docker exec -ti <CONTAINER NAME> setup alias add postmaster@example.com user@example.com
``` ```
### DKIM Keys ### Advanced DNS Setup - DKIM, DMARC & SPF
You can (_and you should_) generate DKIM keys. For more information: You will very likely want to configure your DNS with these TXT records: [SPF, DKIM, and DMARC][cloudflare-spf-dkim-dmarc]. We also ship a [dedicated page in our documentation][docs-dkim-dmarc-spf] about the setup of DKIM, DMARC & SPF.
- DKIM [with OpenDKIM][docs-dkim-opendkim] (_enabled by default_)
- DKIM [with Rspamd][docs-dkim-rspamd] (_when using `ENABLE_RSPAMD=1`_)
When keys are generated, you can configure your DNS server by just pasting the content of `config/opendkim/keys/domain.tld/mail.txt` to [set up DKIM][dkim-signing-setup]. See the [documentation][docs-dkim-dns] for more details.
!!! note
In case you're using LDAP, the setup looks a bit different as you do not add user accounts directly. Postfix doesn't know your domain(s) and you need to provide it when configuring DKIM:
``` BASH
docker exec -ti <CONTAINER NAME> setup config dkim domain '<domain.tld>[,<domain2.tld>]'
```
[dkim-signing-setup]: https://mxtoolbox.com/dmarc/dkim/setup/how-to-setup-dkim
[docs-dkim-dns]: ./config/best-practices/dkim.md#configuration-using-a-web-interface
[docs-dkim-opendkim]: ./config/best-practices/dkim.md#enabling-dkim-signature
[docs-dkim-rspamd]: ./config/security/rspamd.md#dkim-signing
### Advanced DNS Setup
You will very likely want to configure your DNS with these TXT records: [SPF, DKIM, and DMARC][cloudflare-spf-dkim-dmarc].
The following illustrates what a (rather strict) set of records could look like:
```console
$ dig @1.1.1.1 +short TXT example.com
"v=spf1 mx -all"
$ dig @1.1.1.1 +short TXT dkim-rsa._domainkey.example.com
"v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQ..."
$ dig @1.1.1.1 +short TXT _dmarc.example.com
"v=DMARC1; p=reject; sp=reject; pct=100; adkim=s; aspf=s; fo=1"
```
[cloudflare-spf-dkim-dmarc]: https://www.cloudflare.com/learning/email-security/dmarc-dkim-spf/ [cloudflare-spf-dkim-dmarc]: https://www.cloudflare.com/learning/email-security/dmarc-dkim-spf/
[docs-dkim-dmarc-spf]: ./config/best-practices/dkim_dmarc_spf.md
### Custom User Changes & Patches ### Custom User Changes & Patches

6
docs/mkdocs.yml
View file

@ -78,6 +78,8 @@ markdown_extensions:
- name: mermaid - name: mermaid
class: mermaid class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.tabbed:
alternate_style: true
- pymdownx.magiclink - pymdownx.magiclink
- pymdownx.inlinehilite - pymdownx.inlinehilite
- pymdownx.tilde - pymdownx.tilde
@ -116,9 +118,7 @@ nav:
- 'Environment Variables': config/environment.md - 'Environment Variables': config/environment.md
- 'User Management': config/user-management.md - 'User Management': config/user-management.md
- 'Best Practices': - 'Best Practices':
- 'DKIM': config/best-practices/dkim.md - 'DKIM, DMARC & SPF': config/best-practices/dkim_dmarc_spf.md
- 'DMARC': config/best-practices/dmarc.md
- 'SPF': config/best-practices/spf.md
- 'Auto-discovery': config/best-practices/autodiscover.md - 'Auto-discovery': config/best-practices/autodiscover.md
- 'Security': - 'Security':
- 'Understanding the Ports': config/security/understanding-the-ports.md - 'Understanding the Ports': config/security/understanding-the-ports.md