mirror/docker-mailserver.docker-mailserver
1
0
Fork 0
mirror of https://github.com/docker-mailserver/docker-mailserver.git synced 2025-08-29 22:30:27 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Merge branch 'master' into patch-3

Browse source
This commit is contained in:
Georg Lauterbach 2025-07-30 21:57:58 +02:00 • committed by GitHub
commit ff1a099194
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
61 changed files with 1271 additions and 643 deletions
Download patch file Download diff file Expand all files Collapse all files

3
docs/content/config/advanced/full-text-search.md
View file

@ -141,4 +141,7 @@ While indexing is memory intensive, you can configure the plugin to limit the am
See [#905](https://github.com/docker-mailserver/docker-mailserver/issues/905)
Attempting to enable commented out features in the config example above [may not be functional][gh::xapian-decode2text].
[docs-faq-sa-learn-cron]: ../../faq.md#how-can-i-make-spamassassin-better-recognize-spam
[gh::xapian-decode2text]: https://github.com/orgs/docker-mailserver/discussions/4461#discussioncomment-13002388

2
docs/content/config/advanced/mail-forwarding/relay-hosts.md
View file

@ -151,6 +151,6 @@ We provide this support via two config files:
[wikipedia::smarthost]: https://en.wikipedia.org/wiki/Smart_host
[docs::env-relay]: ../../environment.md#relay-host
[dms-repo::helpers-relay]: https://github.com/docker-mailserver/docker-mailserver/blob/v14.0.0/target/scripts/helpers/relay.sh
[dms-repo::helpers-relay]: https://github.com/docker-mailserver/docker-mailserver/blob/v15.0.0/target/scripts/helpers/relay.sh
[dms-gh::pr-3607]: https://github.com/docker-mailserver/docker-mailserver/issues/3607
[dms-gh::relay-example]: https://github.com/docker-mailserver/docker-mailserver/issues/3842#issuecomment-1913380639

8
docs/content/config/advanced/mail-getmail.md
View file

@ -108,3 +108,11 @@ It is possible to utilize the `getmail-gmail-xoauth-tokens` helper to provide au
[getmail-docs]: https://getmail6.org/configuration.html
[getmail-docs-xoauth-12]: https://github.com/getmail6/getmail6/blob/1f95606156231f1e074ba62a9baa64f892a92ef8/docs/getmailrc-examples#L286
[getmail-docs-xoauth-13]: https://github.com/getmail6/getmail6/blob/1f95606156231f1e074ba62a9baa64f892a92ef8/docs/getmailrc-examples#L351
## Debugging
To debug your `getmail` configurations, run this `setup debug` command:
```sh
docker exec -it dms-container-name setup debug getmail
```

2
docs/content/config/advanced/mail-sieve.md
View file

@ -94,7 +94,7 @@ When mail is delivered to your account, it is possible to organize storing mail
# Check if the mail recipient address has a tag (:detail)
if envelope :detail :matches "to" "*" {
# Create a variable `tag`, with the the captured `to` value normalized (SoCIAL => Social)
# Create a variable `tag`, with the captured `to` value normalized (SoCIAL => Social)
set :lower :upperfirst "tag" "${1}";
# Store the mail into a folder with the tag name, nested under your inbox folder:

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

@ -29,7 +29,7 @@ Cloudflare has written an [article about DKIM, DMARC and SPF][cloudflare-dkim-dm
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_)
2. Outbound mail is signed (_when your 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.
@ -54,7 +54,7 @@ You'll need to repeat this process if you add any new domains.
You should have:
- At least one [email account setup][docs-accounts-add]
- At least one [email account setup][docs-accounts]
- Attached a [volume for config][docs-volumes-config] to persist the generated files to local storage
!!! example "Creating DKIM Keys"
@ -76,7 +76,7 @@ You should have:
??? info "Changing the key size"
The keypair generated for using with DKIM presently defaults to RSA-2048. This is a good size but you can lower the security to `1024-bit`, or increase it to `4096-bit` (_discouraged as that is excessive_).
To generate a key with different size (_for RSA 1024-bit_) run:
```sh
@ -137,7 +137,7 @@ DKIM is currently supported by either OpenDKIM or Rspamd:
If you have multiple domains, you need to:
- Create a key wth `docker exec -it <CONTAINER NAME> setup config dkim domain <DOMAIN>` for each domain DMS should sign outgoing mail for.
- Create a key with `docker exec -it <CONTAINER NAME> setup config dkim domain <DOMAIN>` for each domain DMS should sign outgoing mail for.
- Provide a custom `dkim_signing.conf` (for which an example is shown below), as the default config only supports one domain.
!!! info "About the Helper Script"

2
docs/content/config/debugging.md
View file

@ -111,7 +111,7 @@ This could be from outdated software, or running a system that isn't able to pro
- **Container runtime:** Docker and Podman for example have subtle differences. DMS docs are primarily focused on Docker, but we try to document known issues where relevant.
- **Rootless containers:** Introduces additional differences in behavior or requirements:
- cgroup v2 is required for supporting rootless containers.
- Differences such as for container networking which may further affect support for IPv6 and preserving the client IP (Remote address). Example with Docker rootless are [binding a port to a specific interface][docker-rootless-interface] and the choice of [port forwarding driver][docs-rootless-portdriver].
- Differences such as for container networking which may further affect support for IPv6 and preserving the client IP (Remote address). Example with Docker rootless are [binding a port to a specific interface][docker-rootless-interface] and the choice of [port forwarding driver][docs::fail2ban::rootless-portdriver].
[network::docker-userlandproxy]: https://github.com/moby/moby/issues/44721
[network::docker-nftables]: https://github.com/moby/moby/issues/26824

62
docs/content/config/environment.md
View file

@ -6,15 +6,31 @@ title: Environment Variables
Values in **bold** are the default values. If an option doesn't work as documented here, check if you are running the latest image. The current `master` branch corresponds to the image `ghcr.io/docker-mailserver/docker-mailserver:edge`.
!!! tip
If an environment variable `<VAR>__FILE` is set with a valid file path as the value, the content of that file will become the value for `<VAR>` (_provided `<VAR>` has not already been set_).
#### General
##### OVERRIDE_HOSTNAME
If you can't set your hostname (_eg: you're in a container platform that doesn't let you_) specify it via this environment variable. It will have priority over `docker run --hostname`, or the equivalent `hostname:` field in `compose.yaml`.
If you cannot set your DMS FQDN as your hostname (_eg: you're in a container runtime lacks the equivalent of Docker's `--hostname`_), specify it via this environment variable.
- **empty** => Uses the `hostname -f` command to get canonical hostname for DMS to use.
- **empty** => Internally uses the `hostname --fqdn` command to get the canonical hostname assigned to the DMS container.
- => Specify an FQDN (fully-qualified domain name) to serve mail for. The hostname is required for DMS to function correctly.
!!! info
`OVERRIDE_HOSTNAME` is checked early during DMS container setup. When set it will be preferred over querying the containers hostname via the `hostname --fqdn` command (_configured via `docker run --hostname` or the equivalent `hostname:` field in `compose.yaml`_).
!!! warning "Compatibility may differ"
`OVERRIDE_HOSTNAME` is not a complete replacement for adjusting the containers configured hostname. It is a best effort workaround for supporting deployment environments like Kubernetes or when using Docker with `--network=host`.
Typically this feature is only useful when software supports configuring a specific hostname to use, instead of a default fallback that infers the hostname (such as retrieving the hostname via libc / NSS). [Fetchmail is known to be incompatible][gh--issue::hostname-compatibility] with this ENV, requiring manual workarounds.
Compatibility differences are being [tracked here][gh-issue::dms-fqdn] as they become known.
##### LOG_LEVEL
Set the log level for DMS. This is mostly relevant for container startup scripts and change detection event feedback.
@ -194,15 +210,23 @@ Please read [the SSL page in the documentation][docs-tls] for more information.
##### TLS_LEVEL
- **empty** => modern
- modern => Enables TLSv1.2 and modern ciphers only. (default)
- intermediate => Enables TLSv1, TLSv1.1 and TLSv1.2 and broad compatibility ciphers.
- `modern` => Limits the cipher suite to secure ciphers only.
- `intermediate` => Relaxes security by adding additional ciphers for broader compatibility.
!!! info
In both cases TLS v1.2 is the minimum protocol version supported.
!!! note
Prior to DMS v12.0, `TLS_LEVEL=intermediate` additionally supported TLS versions 1.0 and 1.1. If you still have legacy devices that can only use these versions of TLS, please follow [this workaround advice][gh-issue::tls-legacy-workaround].
##### SPOOF_PROTECTION
Configures the handling of creating mails with forged sender addresses.
- **0** => (not recommended) Mail address spoofing allowed. Any logged in user may create email messages with a [forged sender address](https://en.wikipedia.org/wiki/Email_spoofing).
- 1 => Mail spoofing denied. Each user may only send with his own or his alias addresses. Addresses with [extension delimiters](http://www.postfix.org/postconf.5.html#recipient_delimiter) are not able to send messages.
- 1 => Mail spoofing denied. Each user may only send with their own or their alias addresses. Addresses with [extension delimiters](http://www.postfix.org/postconf.5.html#recipient_delimiter) are not able to send messages.
##### ENABLE_SRS
@ -247,6 +271,12 @@ Set the mailbox size limit for all users. If set to zero, the size will be unlim
See [mailbox quota][docs-accounts-quota].
!!! info "Compatibility"
This feature is presently only compatible with `ACCOUNT_PROVISIONER=FILE`.
When using a different provisioner (or `SMTP_ONLY=1`) this ENV will instead default to `0`.
##### POSTFIX_MESSAGE_SIZE_LIMIT
Set the message size limit for all users. If set to zero, the size will be unlimited (not recommended!). Size is in bytes.
@ -295,7 +325,7 @@ Customize the update check interval. Number + Suffix. Suffix must be 's' for sec
- sdbox => (experimental) uses Dovecot high-performance mailbox format, one file contains one message
- mdbox ==> (experimental) uses Dovecot high-performance mailbox format, multiple messages per file and multiple files per box
This option has been added in November 2019. Using other format than Maildir is considered as experimental in docker-mailserver and should only be used for testing purpose. For more details, please refer to [Dovecot Documentation](https://wiki2.dovecot.org/MailboxFormat).
This option has been added in November 2019. Using other format than Maildir is considered as experimental in docker-mailserver and should only be used for testing purpose. For more details, please refer to [Dovecot Documentation](https://doc.dovecot.org/admin_manual/mailbox_formats/#mailbox-formats).
##### POSTFIX_REJECT_UNKNOWN_CLIENT_HOSTNAME
@ -360,6 +390,23 @@ Default: empty (no prefix will be added to e-mails)
Add trailing white-space by quote wrapping the value: `SPAM_SUBJECT='[SPAM] '`
##### DMS_CONFIG_POLL
Defines how often DMS polls [monitored config files][gh::monitored-configs] for changes in the DMS Config Volume. This also includes TLS certificates and is often relied on for applying changes managed via `setup` CLI commands.
- **`2`** => How often (in seconds) [change detection][gh::check-for-changes] is performed.
!!! note "Decreasing the frequency of polling for changes"
Raising the value will delay how soon a change is detected which may impact UX expectations for responsiveness, but reduces resource usage when changes are rare.
!!! info
When using `ACCOUNT_PROVISIONER=LDAP`, the change detection feature is presently disabled.
[gh::check-for-changes]: https://github.com/docker-mailserver/docker-mailserver/blob/v15.0.0/target/scripts/check-for-changes.sh#L37
[gh::monitored-configs]: https://github.com/docker-mailserver/docker-mailserver/blob/v15.0.0/target/scripts/helpers/change-detection.sh#L30-L42
#### Rspamd
##### ENABLE_RSPAMD
@ -1147,3 +1194,6 @@ Provide the credentials to use with `RELAY_HOST` or `DEFAULT_RELAY_HOST`.
[postfix-config::relayhost]: https://www.postfix.org/postconf.5.html#relayhost
[postfix-config::relayhost_maps]: https://www.postfix.org/postconf.5.html#sender_dependent_relayhost_maps
[postfix-config::sasl_passwd]: https://www.postfix.org/postconf.5.html#smtp_sasl_password_maps
[gh-issue::tls-legacy-workaround]: https://github.com/docker-mailserver/docker-mailserver/pull/2945#issuecomment-1949907964
[gh-issue::hostname-compatibility]: https://github.com/docker-mailserver/docker-mailserver-helm/issues/168#issuecomment-2911782106
[gh-issue::dms-fqdn]: https://github.com/docker-mailserver/docker-mailserver/issues/3520#issuecomment-1700191973

44
docs/content/config/security/fail2ban.md
View file

@ -14,18 +14,48 @@ hide:
## Configuration
!!! warning
Enabling Fail2Ban support can be done via ENV, but also requires granting at least the `NET_ADMIN` capability to interact with the kernel and ban IP addresses.
DMS must be launched with the `NET_ADMIN` capability in order to be able to install the NFTables rules that actually ban IP addresses. Thus, either include `--cap-add=NET_ADMIN` in the `docker run` command, or the equivalent in the `compose.yaml`:
!!! example
```yaml
cap_add:
- NET_ADMIN
```
=== "Docker Compose"
```yaml title="compose.yaml"
services:
mailserver:
environment:
- ENABLE_FAIL2BAN=1
cap_add:
- NET_ADMIN
```
=== "Docker CLI"
```bash
docker run --rm -it \
--cap-add=NET_ADMIN \
--env ENABLE_FAIL2BAN=1
```
!!! warning "Security risk of adding non-default capabilties"
DMS bundles F2B into the image for convenience to simplify integration and deployment.
The [`NET_ADMIN`][security::cap-net-admin] and [`NET_RAW`][security::cap-net-raw] capabilities are not granted by default to the container root user, as they can be used to compromise security.
If this risk concerns you, it may be wiser to instead prefer only granting these capabilities to a dedicated Fail2Ban container ([example][lsio:f2b-image]).
!!! bug "Running Fail2Ban on Older Kernels"
DMS configures F2B to use NFTables, not IPTables (legacy). We have observed that older systems, for example NAS systems, do not support the modern NFTables rules. You will need to configure F2B to use legacy IPTables again, for example with the [``fail2ban-jail.cf``][github-file-f2bjail], see the [section on configuration further down below](#custom-files).
DMS configures F2B to use [NFTables][network::nftables], not [IPTables (legacy)][network::iptables-legacy].
We have observed that older systems (for example NAS systems), do not support the modern NFTables rules. You will need to configure F2B to use legacy IPTables again, for example with the [`fail2ban-jail.cf`][github-file-f2bjail], see the [section on configuration further down below](#custom-files).
[security::cap-net-admin]: https://0xn3va.gitbook.io/cheat-sheets/container/escaping/excessive-capabilities#cap_net_admin
[security::cap-net-raw]: https://0xn3va.gitbook.io/cheat-sheets/container/escaping/excessive-capabilities#cap_net_raw
[lsio:f2b-image]: https://docs.linuxserver.io/images/docker-fail2ban
[network::nftables]: https://en.wikipedia.org/wiki/Nftables
[network::iptables-legacy]: https://developers.redhat.com/blog/2020/08/18/iptables-the-two-variants-and-their-relationship-with-nftables#two_variants_of_the_iptables_command
### DMS Defaults

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

@ -6,34 +6,60 @@ title: 'Security | Rspamd'
Rspamd is a ["fast, free and open-source spam filtering system"][rspamd-web]. DMS integrates Rspamd like any other service. We provide a basic but easy to maintain setup of Rspamd.
If you want to take a look at the default configuration files for Rspamd that DMS packs, navigate to [`target/rspamd/` inside the repository][dms-repo::default-rspamd-configuration]. Please consult the [section "The Default Configuration"](#the-default-configuration) section down below for a written overview.
If you want to take a look at the default configuration files for Rspamd that DMS adds, navigate to [`target/rspamd/` inside the repository][dms-repo::default-rspamd-configuration]. Please consult the [section "The Default Configuration"](#the-default-configuration) section down below for a written overview.
## Related Environment Variables
### Enable Rspamd
The following environment variables are related to Rspamd:
Rspamd is presently opt-in for DMS, but intended to become the default anti-spam service in a future release.
1. [`ENABLE_RSPAMD`](../environment.md#enable_rspamd)
2. [`ENABLE_RSPAMD_REDIS`](../environment.md#enable_rspamd_redis)
3. [`RSPAMD_CHECK_AUTHENTICATED`](../environment.md#rspamd_check_authenticated)
4. [`RSPAMD_GREYLISTING`](../environment.md#rspamd_greylisting)
5. [`RSPAMD_HFILTER`](../environment.md#rspamd_hfilter)
6. [`RSPAMD_HFILTER_HOSTNAME_UNKNOWN_SCORE`](../environment.md#rspamd_hfilter_hostname_unknown_score)
7. [`RSPAMD_LEARN`](../environment.md#rspamd_learn)
8. [`SPAM_SUBJECT`](../environment.md#spam_subject)
9. [`MOVE_SPAM_TO_JUNK`][docs::spam-to-junk]
10. [`MARK_SPAM_AS_READ`](../environment.md#mark_spam_as_read)
DMS offers two anti-spam solutions:
With these variables, you can enable Rspamd itself, and you can enable / disable certain features related to Rspamd.
- Legacy (_Amavis, SpamAssassin, OpenDKIM, OpenDMARC_)
- Rspamd (_Provides equivalent features of software from the legacy solution_)
## The Default Configuration
While you could configure Rspamd to only replace some of the legacy services, it is advised to only use Rspamd with the legacy services disabled.
### Other Anti-Spam-Services
!!! example "Switch to Rspamd"
DMS packs other anti-spam services, like SpamAssassin or Amavis, next to Rspamd. There exist services, like ClamAV (`ENABLE_CLAMAV`), that Rspamd can utilize to improve the scanning. Except for ClamAV, we recommend disabling **all other** anti-spam services when using Rspamd. The [basic configuration shown below](#a-very-basic-configuration) provides a good starting point.
To use Rspamd add the following ENV config changes:
```env
ENABLE_RSPAMD=1
# Rspamd replaces the functionality of all these anti-spam services, disable them:
ENABLE_OPENDKIM=0
ENABLE_OPENDMARC=0
ENABLE_POLICYD_SPF=0
ENABLE_AMAVIS=0
ENABLE_SPAMASSASSIN=0
# Greylisting is opt-in, if you had enabled Postgrey switch to the Rspamd equivalent:
ENABLE_POSTGREY=0
RSPAMD_GREYLISTING=1
# Optional: Add anti-virus support with ClamAV (compatible with Rspamd):
ENABLE_CLAMAV=1
```
!!! info "Relevant Environment Variables"
The following environment variables are related to Rspamd:
1. [`ENABLE_RSPAMD`](../environment.md#enable_rspamd)
2. [`ENABLE_RSPAMD_REDIS`](../environment.md#enable_rspamd_redis)
3. [`RSPAMD_CHECK_AUTHENTICATED`](../environment.md#rspamd_check_authenticated)
4. [`RSPAMD_GREYLISTING`](../environment.md#rspamd_greylisting)
5. [`RSPAMD_HFILTER`](../environment.md#rspamd_hfilter)
6. [`RSPAMD_HFILTER_HOSTNAME_UNKNOWN_SCORE`](../environment.md#rspamd_hfilter_hostname_unknown_score)
7. [`RSPAMD_LEARN`](../environment.md#rspamd_learn)
8. [`SPAM_SUBJECT`](../environment.md#spam_subject)
9. [`MOVE_SPAM_TO_JUNK`][docs::spam-to-junk]
10. [`MARK_SPAM_AS_READ`](../environment.md#mark_spam_as_read)
## Overview of Rspamd support
### Mode of Operation
!!! tip "Attention"
!!! note "Attention"
Read this section carefully if you want to understand how Rspamd is integrated into DMS and how it works (on a surface level).
@ -79,13 +105,16 @@ DMS does not set a default password for the controller worker. You may want to d
When Rspamd is enabled, we implicitly also start an instance of Redis in the container:
- Redis is configured to persist its data via RDB snapshots to disk in the directory `/var/lib/redis` (_or the [`/var/mail-state/`][docs::dms-volumes-state] volume when present_).
- With the volume mount, the snapshot will restore the Redis data across container restarts, and provide a way to keep backup.
- With the volume mount, the snapshot will restore the Redis data across container updates, and provide a way to keep a backup.
- Without a volume mount a containers internal state will persist across restarts until the container is recreated due to changes like ENV or upgrading the image for the container.
Redis uses `/etc/redis/redis.conf` for configuration:
- We adjust this file when enabling the internal Redis service.
- If you have an external instance of Redis to use, the internal Redis service can be opt-out via setting the ENV [`ENABLE_RSPAMD_REDIS=0`][docs::env::enable-redis] (_link also details required changes to the DMS Rspamd config_).
If you are interested in using Valkey instead of Redis, please refer to [this guidance][gh-dms::guide::valkey].
### Web Interface
Rspamd provides a [web interface][rspamd-docs::web-ui], which contains statistics and data Rspamd collects. The interface is enabled by default and reachable on port 11334.
@ -96,7 +125,7 @@ To use the web interface you will need to configure a password, [otherwise you w
??? example "Set a custom password"
Add this line to [your rspamd `custom-commands.conf` config](#with-the-help-of-a-custom-file) which sets the `password` option of the _controller worker_:
Add this line to [your Rspamd `custom-commands.conf` config](#with-the-help-of-a-custom-file) which sets the `password` option of the _controller worker_:
```
set-option-for-controller password "your hashed password here"
@ -108,9 +137,13 @@ To use the web interface you will need to configure a password, [otherwise you w
docker exec -it <CONTAINER_NAME> rspamadm pw
```
---
**Related:** A minimal Rspamd `compose.yaml` [example with a reverse-proxy for web access][gh-dms::guide::rspamd-web].
### DNS
DMS does not supply custom values for DNS servers (to Rspamd). If you need to use custom DNS servers, which could be required when using [DNS-based deny/allowlists](#rbls-real-time-blacklists-dnsbls-dns-based-blacklists), you need to adjust [`options.inc`][rspamd-docs::basic-options] yourself. Make sure to also read our [FAQ page on DNS servers][docs::faq::dns-servers].
DMS does not supply custom values for DNS servers (to Rspamd). If you need to use custom DNS servers, which could be required when using [DNS-based deny/allowlists](#rbls-real-time-blacklists-dnsbls-dns-based-blacklists), you need to adjust [`options.inc`][rspamd-docs::config::global] yourself. Make sure to also read our [FAQ page on DNS servers][docs::faq::dns-servers].
!!! warning
@ -142,7 +175,7 @@ You can choose to enable ClamAV, and Rspamd will then use it to check for viruse
#### RBLs (Real-time Blacklists) / DNSBLs (DNS-based Blacklists)
The [RBL module][rspamd-docs::modules::rbl] is enabled by default. As a consequence, Rspamd will perform DNS lookups to various blacklists. Whether an RBL or a DNSBL is queried depends on where the domain name was obtained: RBL servers are queried with IP addresses extracted from message headers, DNSBL server are queried with domains and IP addresses extracted from the message body \[[source][www::rbl-vs-dnsbl]\].
The [RBL module][rspamd-docs::modules::rbl] is enabled by default. As a consequence, Rspamd will perform DNS lookups to various blacklists. Whether an RBL or a DNSBL is queried depends on where the domain name was obtained: RBL servers are queried with IP addresses extracted from message headers, DNSBL server are queried with domains and IP addresses extracted from the message body ([source][www::rbl-vs-dnsbl]).
!!! danger "Rspamd and DNS Block Lists"
@ -152,106 +185,141 @@ The [RBL module][rspamd-docs::modules::rbl] is enabled by default. As a conseque
## Providing Custom Settings & Overriding Settings
DMS brings sane default settings for Rspamd. They are located at `/etc/rspamd/local.d/` inside the container (or `target/rspamd/local.d/` in the repository).
!!! info "Rspamd config overriding precedence"
### Manually
Rspamd has a layered approach for configuration with [`local.d` and `override.d` config directories][rspamd-docs::config-directories].
!!! question "What is [`docker-data/dms/config/`][docs::dms-volumes-config]?"
- DMS [extends the Rspamd default configs via `/etc/rspamd/local.d/`][dms-repo::default-rspamd-configuration].
- User config changes should be handled separately as overrides via the [DMS Config Volume][docs::dms-volumes-config] (`docker-data/dms/config/`) with either:
- `./rspamd/override.d/` - Config files placed here are copied to `/etc/rspamd/override.d/` during container startup.
- [`./rspamd/custom-commands.conf`](#with-the-help-of-a-custom-file) - Applied after copying any provided configs from `rspamd/override.d/` (DMS Config volume) to `/etc/rspamd/override.d/`.
If you want to overwrite the default settings or provide your settings, you can place files at `docker-data/dms/config/rspamd/override.d/`. Files from this directory are copied to `/etc/rspamd/override.d/` during startup. These files [forcibly override][rspamd-docs::override-dir] Rspamd and DMS default settings.
!!! abstract "Reference docs for Rspamd config"
!!! question "What is the [`local.d` directory and how does it compare to `override.d`][rspamd-docs::config-directories]?"
- [Config Overview][rspamd-docs::config::overview], [Quickstart guide][rspamd-docs::config::quickstart], and [Config Syntax (UCL)][rspamd-docs::config::ucl-syntax]
- Global Options ([`options.inc`][rspamd-docs::config::global])
- [Workers][rspamd-docs::config::workers] ([`worker-controller.inc`][rspamd-docs::config::worker-controller], [`worker-proxy.inc`][rspamd-docs::config::worker-proxy])
- [Modules][rspamd-docs::modules] (_view each module page for their specific config options_)
!!! warning "Clashing Overrides"
!!! tip "View rendered config"
Note that when also [using the `custom-commands.conf` file](#with-the-help-of-a-custom-file), files in `override.d` may be overwritten in case you adjust them manually and with the help of the file.
`rspamadm configdump` will output the full rspamd configuration that is used should you need it for troubleshooting / inspection.
### With the Help of a Custom File
- You can also see which modules are enabled / disabled via `rspamadm configdump --modules-state`
- Specific config sections like `dkim` or `worker` can also be used to filter the output to just those sections: `rspamadm configdump dkim worker`
- Use `--show-help` to include inline documentation for many settings.
DMS provides the ability to do simple adjustments to Rspamd modules with the help of a single file. Just place a file called `custom-commands.conf` into `docker-data/dms/config/rspamd/`. If this file is present, DMS will evaluate it. The structure is simple, as each line in the file looks like this:
### Using `custom-commands.conf` { #with-the-help-of-a-custom-file }
```txt
COMMAND ARGUMENT1 ARGUMENT2 ARGUMENT3
```
For convenience DMS provides a single config file that will directly create or modify multiple configs at `/etc/rspamd/override.d/`. This is handled as the final rspamd configuration step during container startup.
where `COMMAND` can be:
DMS will apply this config when you provide `rspamd/custom-commands.conf` in your DMS Config volume. Configure it with directive lines as documented below.
1. `disable-module`: disables the module with name `ARGUMENT1`
2. `enable-module`: explicitly enables the module with name `ARGUMENT1`
3. `set-option-for-module`: sets the value for option `ARGUMENT2` to `ARGUMENT3` inside module `ARGUMENT1`
4. `set-option-for-controller`: set the value of option `ARGUMENT1` to `ARGUMENT2` for the controller worker
5. `set-option-for-proxy`: set the value of option `ARGUMENT1` to `ARGUMENT2` for the proxy worker
6. `set-common-option`: set the option `ARGUMENT1` that [defines basic Rspamd behavior][rspamd-docs::basic-options] to value `ARGUMENT2`
7. `add-line`: this will add the complete line after `ARGUMENT1` (with all characters) to the file `/etc/rspamd/override.d/<ARGUMENT1>`
!!! note "Only use this feature for `option = value` changes"
!!! example "An Example Is [Shown Down Below](#adjusting-and-extending-the-very-basic-configuration)"
`custom-commands.conf` is only suitable for adding or replacing simple `option = value` settings for configs at `/etc/rspamd/override.d/`.
- New settings are appended to the associated config file.
- When replacing an existing setting in an override config, that setting may be any matching line (_allowing for nested scopes, instead of only top-level keys_).
Any changes involving more advanced [UCL config syntax][rspamd-docs::config::ucl-syntax] should instead add UCL config files directly to `rspamd/override.d/` (_in the DMS Config volume_).
!!! note "File Names & Extensions"
!!! info "`custom-commands.conf` syntax"
For command 1 - 3, we append the `.conf` suffix to the module name to get the correct file name automatically. For commands 4 - 6, the file name is fixed (you don't even need to provide it). For command 7, you will need to provide the whole file name (including the suffix) yourself!
There are 7 directives available to manage custom Rspamd configurations. Add these directive lines into `custom-commands.conf`, they will be processed sequentially.
You can also have comments (the line starts with `#`) and blank lines in `custom-commands.conf` - they are properly handled and not evaluated.
**Directives:**
!!! tip "Adjusting Modules This Way"
```txt
# For /etc/rspamd/override.d/{options.inc,worker-controller.inc,worker-proxy}.inc
set-common-option <OPTION NAME> <OPTION VALUE>
set-option-for-controller <OPTION NAME> <OPTION VALUE>
set-option-for-proxy <OPTION NAME> <OPTION VALUE>
These simple commands are meant to give users the ability to _easily_ alter modules and their options. As a consequence, they are not powerful enough to enable multi-line adjustments. If you need to do something more complex, we advise to do that [manually](#manually)!
# For /etc/rspamd/override.d/<MODULE NAME>.conf
enable-module <MODULE NAME>
disable-module <MODULE NAME>
set-option-for-module <MODULE NAME> <OPTION NAME> <OPTION VALUE>
## Examples & Advanced Configuration
# For /etc/rspamd/override.d/<FILENAME>
add-line <FILENAME> <CONTENT>
```
### A Very Basic Configuration
**Syntax:**
Do you want to start using Rspamd? Rspamd is disabled by default, so you need to set the following environment variables:
- Blank lines are ok.
- `#` at the start of a line represents a comment for adding notes.
- `<OPTION VALUE>` and `<CONTENT>` will contain the remaining content of their line, any preceding inputs are delimited by white-space.
```env
ENABLE_RSPAMD=1
# ClamAV is compatible with Rspamd. Optionally enable it for anti-virus support:
ENABLE_CLAMAV=1
---
# Rspamd replaces the functionality of all these anti-spam services, disable them:
ENABLE_OPENDKIM=0
ENABLE_OPENDMARC=0
ENABLE_POLICYD_SPF=0
ENABLE_AMAVIS=0
ENABLE_SPAMASSASSIN=0
??? note "`<MODULE NAME>` can also target non-module configs"
# Provided you've set `RSPAMD_GREYLISTING=1`, also disable Postgrey:
ENABLE_POSTGREY=0
```
An example is the `statistics` module, which has config to import a separate file (`classifier-bayes.conf`) for easier overrides to this section of the module config.
This will enable Rspamd and disable services you don't need when using Rspamd.
??? example
### Adjusting and Extending The Very Basic Configuration
Rspamd is running, but you want or need to adjust it? First, create a file named `custom-commands.conf` under `docker-data/dms/config/rspamd` (which translates to `/tmp/docker-mailserver/rspamd/` inside the container). Then add your changes:
1. Say you want to be able to easily look at the frontend Rspamd provides on port 11334 (default) without the need to enter a password (maybe because you already provide authorization and authentication). You will have to adjust the controller worker: `set-option-for-controller secure_ip "0.0.0.0/0"`.
2. Do you additionally want to enable the auto-spam-learning for the Bayes module? No problem: `set-option-for-module classifier-bayes autolearn true`.
3. But the chartable module gets on your nerves? Easy: `disable-module chartable`.
??? example "What Does the Result Look Like?"
Here is what the file looks like in the end:
```bash
# See 1.
# ATTENTION: this disables authentication on the website - make sure you know what you're doing!
```conf title="rspamd/custom-commands.conf"
# If you're confident you've properly secured access to the rspamd web service/API (Default port: 11334)
# with your own auth layer (eg: reverse-proxy) you can bypass rspamd requiring credentials:
# https://rspamd.com/doc/workers/controller.html#controller-configuration
set-option-for-controller secure_ip "0.0.0.0/0"
# See 2.
# Some settings aren't documented well, you may find them in snippets or Rspamds default config files:
# https://rspamd.com/doc/tutorials/quickstart.html#using-of-milter-protocol-for-rspamd--16
# /etc/rspamd/worker-proxy.inc
set-option-for-proxy reject_message "Rejected - Detected as spam"
# Equivalent to the previous example, but `add-line` is more verbose:
add-line worker-proxy.inc reject_message = "Rejected - Detected as spam"
# Enable Bayes auto-learning feature to classify spam based on Rspamd action/score results:
# NOTE: The statistics module imports a separate file for classifier-bayes config
# https://rspamd.com/doc/configuration/statistic.html#autolearning
set-option-for-module classifier-bayes autolearn true
# See 3.
# Disable the `chartable` module:
# https://rspamd.com/doc/modules/chartable.html
disable-module chartable
```
## Advanced Configuration
### DKIM Signing
There is a dedicated [section for setting up DKIM with Rspamd in our documentation][docs::dkim-with-rspamd].
### ARC (Authenticated Received Chain)
[ARC][wikipedia::arc] support in DMS is opt-in via config file. [Enable the ARC Rspamd module][rspamd-docs::arc] by creating a config file at `docker-data/dms/config/rspamd/override.d/arc.conf`.
!!! example
For each mail domain you have DMS manage, add the equivalent `example.com` sub-section to `domain` and adjust the `path` + `selector` fields as necessary.
```conf title="rspamd/override.d/arc.conf"
sign_local = true;
sign_authenticated = true;
domain {
example.com {
path = "/tmp/docker-mailserver/rspamd/dkim/rsa-2048-mail-example.private.txt";
selector = "mail";
}
}
```
!!! tip "Using a common keypair"
As with DKIM, the keypair can be shared across your configured domains.
Your ARC config can share the same DKIM private key + selector (_with associated DNS record for the public key_).
### _Abusix_ Integration
This subsection provides information about the integration of [Abusix][abusix-web], "a set of blocklists that work as an additional email security layer for your existing mail environment". The setup is straight-forward and well documented:
1. [Create an account](https://app.abusix.com/)
1. [Create an account][abusix-web::register]
2. Retrieve your API key
3. Navigate to the ["Getting Started" documentation for Rspamd][abusix-docs::rspamd-integration] and follow the steps described there
4. Make sure to change `<APIKEY>` to your private API key
@ -267,17 +335,28 @@ While _Abusix_ can be integrated into Postfix, Postscreen and a multitude of oth
[rspamd-docs::web-ui::password]: https://www.rspamd.com/doc/tutorials/quickstart.html#setting-the-controller-password
[rspamd-docs::modules]: https://rspamd.com/doc/modules/
[rspamd-docs::modules::rbl]: https://rspamd.com/doc/modules/rbl.html
[rspamd-docs::override-dir]: https://www.rspamd.com/doc/faq.html#what-are-the-locald-and-overrided-directories
[rspamd-docs::config-directories]: https://rspamd.com/doc/faq.html#what-are-the-locald-and-overrided-directories
[rspamd-docs::basic-options]: https://rspamd.com/doc/configuration/options.html
[rspamd-docs::config::ucl-syntax]: https://rspamd.com/doc/configuration/ucl.html
[rspamd-docs::config::overview]: https://rspamd.com/doc/configuration/index.html
[rspamd-docs::config::quickstart]: https://rspamd.com/doc/tutorials/quickstart.html#configuring-rspamd
[rspamd-docs::config::global]: https://rspamd.com/doc/configuration/options.html
[rspamd-docs::config::workers]: https://rspamd.com/doc/workers/
[rspamd-docs::config::worker-controller]: https://rspamd.com/doc/workers/controller.html
[rspamd-docs::config::worker-proxy]: https://rspamd.com/doc/workers/rspamd_proxy.html
[www::rbl-vs-dnsbl]: https://forum.eset.com/topic/25277-dnsbl-vs-rbl-mail-security/?do=findComment&comment=119818
[wikipedia::arc]: https://en.wikipedia.org/wiki/Authenticated_Received_Chain
[rspamd-docs::arc]: https://rspamd.com/doc/modules/arc.html
[www::rbl-vs-dnsbl]: https://forum.eset.com/topic/25277-dnsbl-vs-rbl-mail-security/#comment-119818
[abusix-web]: https://abusix.com/
[abusix-web::register]: https://app.abusix.com/
[abusix-docs::rspamd-integration]: https://abusix.com/docs/rspamd/
[spamhaus::faq::dnsbl-usage]: https://www.spamhaus.org/faq/section/DNSBL%20Usage#365
[dms-repo::rspamd-actions-config]: https://github.com/docker-mailserver/docker-mailserver/blob/v14.0.0/target/rspamd/local.d/actions.conf
[dms-repo::default-rspamd-configuration]: https://github.com/docker-mailserver/docker-mailserver/tree/v14.0.0/target/rspamd
[dms-repo::rspamd-actions-config]: https://github.com/docker-mailserver/docker-mailserver/tree/v15.0.0/target/rspamd/local.d/actions.conf
[dms-repo::default-rspamd-configuration]: https://github.com/docker-mailserver/docker-mailserver/tree/v15.0.0/target/rspamd
[gh-dms::guide::valkey]: https://github.com/docker-mailserver/docker-mailserver/issues/4001#issuecomment-2652596692
[gh-dms::guide::rspamd-web]: https://github.com/orgs/docker-mailserver/discussions/4269#discussioncomment-11329588
[docs::env::enable-redis]: ../environment.md#enable_rspamd_redis
[docs::spam-to-junk]: ../environment.md#move_spam_to_junk

38
docs/content/config/security/ssl.md
View file

@ -13,7 +13,7 @@ There are multiple options to enable SSL (via [`SSL_TYPE`][docs-env::ssl-type]):
After installation, you can test your setup with:
- [`checktls.com`](https://www.checktls.com/TestReceiver)
- [`testssl.sh`](https://github.com/drwetter/testssl.sh)
- [`testssl.sh`](https://github.com/testssl/testssl.sh)
!!! warning "Exposure of DNS labels through Certificate Transparency"
@ -485,6 +485,8 @@ DSM-generated letsencrypt certificates get auto-renewed every three months.
!!! example
While DMS does not need a webserver to work, this workaround will provision a TLS certificate for DMS to use by adding a dummy site block to trigger cert provisioning.
```yaml title="compose.yaml"
services:
# Basic Caddy service to provision certs:
@ -510,9 +512,12 @@ DSM-generated letsencrypt certificates get auto-renewed every three months.
- ${CADDY_DATA_DIR}/certificates/acme-v02.api.letsencrypt.org-directory/mail.example.com/mail.example.com.key:/etc/letsencrypt/live/mail.example.com/privkey.pem
```
An explicit entry in your `Caddyfile` config will have Caddy provision and renew a certificate for your DMS FQDN:
```caddyfile title="Caddyfile"
mail.example.com {
tls internal {
# Optionally provision RSA 2048-bit certificate instead of ECDSA P-256:
tls {
key_type rsa2048
}
@ -522,10 +527,12 @@ DSM-generated letsencrypt certificates get auto-renewed every three months.
}
```
While DMS does not need a webserver to work, this workaround will provision a TLS certificate for DMS to use.
!!! info
- [`tls internal`][caddy-docs::tls-internal] will create a local self-signed cert for testing. This targets only the site-address, unlike the global `local_certs` option.
- [`key_type`][caddy-docs::key-type] can be used in the `tls` block if you need to enforce RSA as the key type for certificates provisioned. The default is currently ECDSA (P-256).
An explicit `tls` directive affects only the site-address block it's used in:
- Use [`tls internal { ... }`][caddy-docs::tls-internal] if wanting to create a local self-signed cert, which may be useful for testing. This allows opt-in to use self-signed certs unlike the global `local_certs` option.
- [`key_type`][caddy-docs::key-type] can be used in the `tls` block if you need to enforce RSA as the key type for certificates provisioned. The default is currently ECDSA (P-256). This may improve compatibility with legacy clients.
??? example "With `caddy-docker-proxy`"
@ -558,9 +565,9 @@ DSM-generated letsencrypt certificates get auto-renewed every three months.
labels:
# Set your DMS FQDN here to add the site-address into the generated Caddyfile:
caddy_0: mail.example.com
# Add a dummy directive is required:
# Adding a dummy directive is required:
caddy_0.respond: "Hello DMS"
# Uncomment to make a proxy for Rspamd
# Uncomment to make a proxy for Rspamd:
# caddy_1: rspamd.example.com
# caddy_1.reverse_proxy: "{{upstreams 11334}}"
```
@ -571,6 +578,23 @@ DSM-generated letsencrypt certificates get auto-renewed every three months.
This can make the volume mounting for DMS to find the certificates non-deterministic, but you can [restrict provisioning to single service via the `acme_ca` setting][caddy::restrict-acme-provisioner].
---
**NOTE:** Bind mounting a file directly instead of a directory will mount by inode. If the file is updated at renewal and this modifies the inode on the host system, then the container will still point to the old certificate.
If this happens, consider using our manual TLS type instead:
```yaml title="compose.yaml"
services:
mailserver:
environment:
SSL_TYPE: manual
SSL_CERT_PATH: /srv/tls/mail.example.com/mail.example.com.crt
SSL_KEY_PATH: /srv/tls/mail.example.com/mail.example.com.key
volumes:
- ${CADDY_DATA_DIR}/certificates/acme-v02.api.letsencrypt.org-directory/mail.example.com/:/srv/tls/mail.example.com/:ro
```
### Traefik
[Traefik][traefik::github] is an open-source application proxy using the [ACME protocol][ietf::rfc::acme]. Traefik can request certificates for domains and subdomains, and it will take care of renewals, challenge negotiations, etc.

11
docs/content/contributing/general.md
View file

@ -15,13 +15,20 @@ When refactoring, writing or altering scripts or other files, adhere to these ru
Make sure to select `edge` in the dropdown menu at the top. Navigate to the page you would like to edit and click the edit button in the top right. This allows you to make changes and create a pull-request.
Alternatively you can make the changes locally. For that you'll need to have Docker installed. Navigate into the `docs/` directory. Then run:
Alternatively you can make the changes locally. For that you'll need to have Docker installed and run:
```sh
docker run --rm -it -p 8000:8000 -v "${PWD}:/docs" squidfunk/mkdocs-material
# From the root directory of the git clone:
docker run --rm -it -p 8000:8000 -v "./docs:/docs" squidfunk/mkdocs-material
```
This serves the documentation on your local machine on port `8000`. Each change will be hot-reloaded onto the page you view, just edit, save and look at the result.
!!! note
The container logs will inform you of invalid links detected, but a [few are false-positives][gh-dms::mkdocs-link-error-false-positives] due to our usage of linking to specific [content tabs][mkdocs::content-tabs].
[get-docker]: https://docs.docker.com/get-docker/
[docs-bats-parallel]: https://bats-core.readthedocs.io/en/v1.8.2/usage.html#parallel-execution
[gh-dms::mkdocs-link-error-false-positives]: https://github.com/docker-mailserver/docker-mailserver/pull/4366
[mkdocs::content-tabs]: https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#anchor-links

5
docs/content/contributing/tests.md
View file

@ -35,6 +35,10 @@ There are many functions that aid in writing tests. **We urge you to use them!**
We encourage you to try both of the approaches mentioned above. To make understanding and using the helper functions easy, every function contains detailed documentation comments. Read them carefully!
!!! tip
If your test needs to add or create additional files, our helpers will [manage a disposable config directory per container][technical-guide::test-tmp-config] for you with the path stored in the `TEST_TMP_CONFIG` ENV (outside the container, `/tmp/docker-mailserver` within the container).
### How Are Tests Run?
Tests are split into two categories:
@ -141,3 +145,4 @@ $ make clean tests
[testing-prs]: https://github.com/docker-mailserver/docker-mailserver/blob/master/.github/workflows/test_merge_requests.yml
[get-docker]: https://docs.docker.com/get-docker/
[docs-bats-parallel]: https://bats-core.readthedocs.io/en/v1.8.2/usage.html#parallel-execution
[technical-guide::test-tmp-config]: https://github.com/docker-mailserver/docker-mailserver/pull/4359#issuecomment-2817591085

50
docs/content/examples/tutorials/dovecot-solr.md
View file

@ -24,39 +24,41 @@ As the official DMS image does not provide `dovecot-solr`, you'll need to includ
!!! quote ""
=== "`user-patches.sh`"
If you'd prefer to avoid a custom image build. This approach is simpler but with the caveat that any time the container is restarted, you'll have a delay as the package is installed each time.
```bash
#!/bin/bash
apt-get update && apt-get install dovecot-solr
```
=== "`compose.yaml`"
A custom DMS image does not add much friction. You do not need a separate `Dockerfile` as Docker Compose supports building from an inline `Dockerfile` in your `compose.yaml`.
The `image` key of the service is swapped for the `build` key instead, as shown below:
```yaml
services:
mailserver:
hostname: mail.example.com
# The `image` setting now represents the tag for the local build configured below:
image: local/dms:14.0
image: local/dms:${DMS_TAG?Must set DMS image tag}
# Local build (no need to try pull `image` remotely):
pull_policy: build
# Add this `build` section to your real `compose.yaml` for your DMS service:
build:
dockerfile_inline: |
FROM docker.io/mailserver/docker-mailserver:14.0
FROM docker.io/mailserver/docker-mailserver:${DMS_TAG?Must set DMS image tag}
RUN apt-get update && apt-get install dovecot-solr
```
- Just run `docker compose up` and it will pull DMS and build your custom image to run a container.
- Updating to a new DMS release is straight-forward, just adjust the version tag as you normally would. If you make future changes that don't apply, you may need to force a rebuild.
- This approach only needs to install the package once with the image build itself. This minimizes delay of container startup.
This approach only needs to install the package once with the image build itself which minimizes the delay of container startup.
- Just run `DMS_TAG='14.0' docker compose up` and it will pull the DMS image, then build your custom DMS image to run a new container instance.
- Updating to a new DMS release is straight-forward, just adjust the `DMS_TAG` ENV value or change the image tag directly in `compose.yaml` as you normally would to upgrade an image.
- If you make future changes to the `dockerfile_inline` that don't seem to be applied, you may need to force a rebuild with `DMS_TAG='14.0' docker compose up --build`.
!!! note "Why doesn't DMS include `dovecot-solr`?"
@ -144,6 +146,25 @@ docker compose exec mailserver doveadm fts rescan -A
Usually within 15 minutes or so, you should be able to search your mail using the Dovecot FTS feature! :tada:
### Compatibility
Since Solr 9.8.0 was released (Jan 2025), a breaking change [deprecates support for `<lib>` directives][solr::9.8::lib-directive] which is presently used by the Dovecot supplied Solr config (`solr-config-9.xml`) to automatically load additional jars required.
To enable support for `<lib>` directives, add the following ENV to your `solr` container:
```yaml
services:
solr:
environment:
SOLR_CONFIG_LIB_ENABLED: true
```
!!! warning "Solr 10"
From the Solr 10 release onwards, this opt-in ENV will no longer be available.
If Dovecot has not updated their example Solr config ([upstream PR][dovecot::pr::solr-config-lib]), you will need to manually modify the Solr XML config to remove the `<lib>` directives and replace the suggested ENV `SOLR_CONFIG_LIB_ENABLED=true` with `SOLR_MODULES=analysis-extras`.
[docs::user-patches]: ../../config/advanced/override-defaults/user-patches.md
[docs::dovecot::full-text-search]: ../../config/advanced/full-text-search.md
[gh-dms::feature-request::dovecot-solr-package]: https://github.com/docker-mailserver/docker-mailserver/issues/4052
@ -152,3 +173,6 @@ docker compose exec mailserver doveadm fts rescan -A
[dockerfile-solr-uidgid]: https://github.com/apache/solr-docker/blob/9cd850b72309de05169544395c83a85b329d6b86/9.6/Dockerfile#L89-L92
[github-solr]: https://github.com/apache/solr
[github-dovecot::core-docs]: https://github.com/dovecot/core/tree/main/doc
[solr::9.8::lib-directive]: https://issues.apache.org/jira/browse/SOLR-16781
[dovecot::pr::solr-config-lib]: https://github.com/dovecot/core/pull/238

20
docs/content/examples/tutorials/mailserver-behind-proxy.md
View file

@ -114,15 +114,15 @@ The below guidance is focused on configuring [Traefik][traefik-web], but the adv
# These are examples, configure the equivalent for any additional ports you proxy.
# Explicit TLS (STARTTLS):
- traefik.tcp.routers.mail-smtp.rule=HostSNI(`*`)
- traefik.tcp.routers.mail-smtp.entrypoints=smtp
- traefik.tcp.routers.mail-smtp.service=smtp
- traefik.tcp.routers.mail-smtp.entrypoints=mail-smtp
- traefik.tcp.routers.mail-smtp.service=mail-smtp
- traefik.tcp.services.mail-smtp.loadbalancer.server.port=25
- traefik.tcp.services.mail-smtp.loadbalancer.proxyProtocol.version=2
# Implicit TLS is no different, except for optional HostSNI support:
- traefik.tcp.routers.mail-submissions.rule=HostSNI(`*`)
- traefik.tcp.routers.mail-submissions.entrypoints=smtp-submissions
- traefik.tcp.routers.mail-submissions.service=smtp-submissions
- traefik.tcp.routers.mail-submissions.entrypoints=mail-submissions
- traefik.tcp.routers.mail-submissions.service=mail-submissions
- traefik.tcp.services.mail-submissions.loadbalancer.server.port=465
- traefik.tcp.services.mail-submissions.loadbalancer.proxyProtocol.version=2
# NOTE: Optionally match by SNI rule, this requires TLS passthrough (not compatible with STARTTLS):
@ -258,7 +258,7 @@ The below guidance is focused on configuring [Traefik][traefik-web], but the adv
# Create a variant for port 25 too (NOTE: Port 10025 is already assigned in DMS to Amavis):
postconf -Mf smtp/inet | sed -e s/^smtp/12525/ >> /etc/postfix/master.cf
# Enable PROXY Protocol support (different setting as port 25 is handled via postscreen), optionally configure a `syslog_name` to distinguish in logs:
postconf -P 12525/inet/postscreen_upstream_proxy_protocol=haproxy 12525/inet/syslog_name=smtp-proxyprotocol
postconf -P 12525/inet/postscreen_upstream_proxy_protocol=haproxy 12525/inet/syslog_name=postfix/smtpd-proxyprotocol
```
Supporting port 25 with an additional PROXY protocol port will also require a `postfix-main.cf` override line for `postscreen` to work correctly:
@ -279,12 +279,12 @@ The below guidance is focused on configuring [Traefik][traefik-web], but the adv
haproxy_trusted_networks = 172.16.42.2
service imap-login {
inet_listener imap-proxied {
inet_listener imap-proxyprotocol {
haproxy = yes
port = 10143
}
inet_listener imaps-proxied {
inet_listener imaps-proxyprotocol {
haproxy = yes
port = 10993
ssl = yes
@ -292,12 +292,12 @@ The below guidance is focused on configuring [Traefik][traefik-web], but the adv
}
service pop3-login {
inet_listener pop3-proxied {
inet_listener pop3-proxyprotocol {
haproxy = yes
port = 10110
}
inet_listener pop3s-proxied {
inet_listener pop3s-proxyprotocol {
haproxy = yes
port = 10995
ssl = yes
@ -305,7 +305,7 @@ The below guidance is focused on configuring [Traefik][traefik-web], but the adv
}
service managesieve-login {
inet_listener sieve-proxied {
inet_listener sieve-proxyprotocol {
haproxy = yes
port = 14190
}

50
docs/content/examples/use-cases/bind-smtp-network-interface.md
View file

@ -21,10 +21,6 @@ This can be configured by [overriding the default Postfix configurations][docs::
In `postfix-main.cf` you'll have to set the [`smtp_bind_address`][postfix-docs::smtp-bind-address-ipv4] and [`smtp_bind_address6`][postfix-docs::smtp-bind-address-ipv6]
to the respective IP-address on the server you want to use.
[docs::overrides-postfix]: ../../config/advanced/override-defaults/postfix.md
[postfix-docs::smtp-bind-address-ipv4]: https://www.postfix.org/postconf.5.html#smtp_bind_address
[postfix-docs::smtp-bind-address-ipv6]: https://www.postfix.org/postconf.5.html#smtp_bind_address6
!!! example
=== "Contributed solution"
@ -55,14 +51,56 @@ to the respective IP-address on the server you want to use.
```
If that avoids the concern with `smtp-amavis`, you may still need to additionally override for the [`relay` transport][gh-src::postfix-master-cf::relay-transport] as well if you have configured DMS to relay mail.
=== "Bridged Networks"
When your DMS container is using a bridge network, you'll instead need to restrict which IP address inbound and outbound traffic is routed through via the bridged interface.
For **inbound** traffic, you may configure this at whatever scope is most appropriate for you:
- **Daemon:** Change the [default bind address][inbound-ip::docker-docs::daemon] configured in `/etc/docker/daemon.json` (default `0.0.0.0`)
- **Network:** Assign the [`host_binding_ipv4` bridge driver option][inbound-ip::docker-docs::network] as shown in the below `compose.yaml` snippet.
- **Container:** Provide an explicit host IP address when [publishing a port][inbound-ip::docker-docs::container].
For **outbound** traffic, the bridge network will use the default route. You can change this by either:
- [Manually routing networks][outbound-ip::route-manually] on the host.
- Use the [`host_ipv4` driver option][outbind-ip::host-ipv4] for Docker networks to force the SNAT (source IP) that the bridged network will route outbound traffic through.
- This IP address must belong to a network interface to be routed through it.
- IPv6 support via `host_ipv6` [requires at least Docker v25][outbind-ip::host-ipv6].
---
Here is a `compose.yaml` snippet that applies the inbound + outbound settings to the default bridge network Docker Compose creates (_if it already exists, you will need to ensure it's re-created to apply the updated settings_):
```yaml title="compose.yaml"
networks:
default:
driver_opts:
# Inbound IP (sets the host IP that published ports receive traffic from):
com.docker.network.bridge.host_binding_ipv4: 198.51.100.42
# Outbound IP (sets the host IP that external hosts will receive connections from):
com.docker.network.host_ipv4: 198.51.100.42
```
!!! note "IP addresses for documentation"
IP addresses shown in above examples are placeholders, they are IP addresses reserved for documentation by IANA (_[RFC-5737 (IPv4)][rfc-5737] and [RFC-3849 (IPv6)][rfc-3849]_). Replace them with the IP addresses you want DMS to send mail through.
IP addresses shown in above examples (`198.51.100.42` + `2001:DB8::42`) are placeholders, they are IP addresses reserved for documentation by IANA (_[RFC-5737 (IPv4)][rfc-5737] and [RFC-3849 (IPv6)][rfc-3849]_). Replace them with the IP addresses you want DMS to send mail through.
[docs::overrides-postfix]: ../../config/advanced/override-defaults/postfix.md
[postfix-docs::smtp-bind-address-ipv4]: https://www.postfix.org/postconf.5.html#smtp_bind_address
[postfix-docs::smtp-bind-address-ipv6]: https://www.postfix.org/postconf.5.html#smtp_bind_address6
[rfc-5737]: https://datatracker.ietf.org/doc/html/rfc5737
[rfc-3849]: https://datatracker.ietf.org/doc/html/rfc3849
[gh-pr::3465::comment-restrictions]: https://github.com/docker-mailserver/docker-mailserver/pull/3465#discussion_r1458114528
[gh-pr::3465::alternative-solution]: https://github.com/docker-mailserver/docker-mailserver/pull/3465#issuecomment-1678107233
[gh-src::postfix-master-cf::relay-transport]: https://github.com/docker-mailserver/docker-mailserver/blob/9cdbef2b369fb4fb0f1b4e534da8703daf92abc9/target/postfix/master.cf#L65
[inbound-ip::docker-docs::daemon]: https://docs.docker.com/reference/cli/dockerd/#default-network-options
[inbound-ip::docker-docs::network]: https://docs.docker.com/engine/network/drivers/bridge/#default-host-binding-address
[inbound-ip::docker-docs::container]: https://docs.docker.com/reference/compose-file/services/#ports
[outbound-ip::route-manually]: https://github.com/moby/moby/issues/30053#issuecomment-1077041045
[outbind-ip::host-ipv4]: https://github.com/moby/libnetwork/pull/2454
[outbind-ip::host-ipv6]: https://github.com/moby/moby/issues/46469

2
docs/content/usage.md
View file

@ -48,7 +48,7 @@ We will later dig into DKIM, DMARC & SPF, but for now, these are the records tha
- The **MX record** tells everyone which (DNS) name is responsible for e-mails on your domain.
Because you want to keep the option of running another service on the domain name itself, you run your mail server on `mail.example.com`.
This does not imply your e-mails will look like `test@mail.example.com`, the DNS name of your mail server is decoupled of the domain it serves e-mails for.
In theory, you mail server could even serve e-mails for `test@some-other-domain.com`, if the MX record for `some-other-domain.com` points to `mail.example.com`.
Your mail server could also handle emails for `test@some-other-domain.com`, if the MX record for `some-other-domain.com` points to `mail.example.com`.
- The **A record** tells everyone which IP address the DNS name `mail.example.com` resolves to.
- The **PTR record** is the counterpart of the A record, telling everyone what name the IP address `11.22.33.44` resolves to.