You've already forked docker-mailserver
mirror of
https://github.com/docker-mailserver/docker-mailserver.git
synced 2025-08-07 23:03:10 +02:00
docs: Complete rewrite of Relay Host pages (#3861)
* docs: Complete rewrite on relay host docs - Both relay docs pages have had heavy refactor / rewrite. - ENV docs page relay host section revised. * docs: Revise relay host page with technical details section * docs: Add LDAP compatibility caveat for `RELAY_HOST`
This commit is contained in:
Brennan Kinney
GitHub
@ -1014,13 +1014,19 @@ you to replace both instead of just the envelope sender.
|
||||
|
||||
#### Relay Host
|
||||
|
||||
!!! tip "`RELAY_HOST` vs `DEFAULT_RELAY_HOST`"
|
||||
Supported ENV for the [Relay Host][docs::relay-host] feature.
|
||||
|
||||
`DEFAULT_RELAY_HOST` is encouraged, but presently does not support sender domain opt-out (`setup relay exclude-domain`).
|
||||
!!! note "Prefer `DEFAULT_RELAY_HOST` instead of `RELAY_HOST`"
|
||||
|
||||
This is advised unless you need support for sender domain opt-out (via `setup relay exclude-domain`).
|
||||
|
||||
The implementation for `RELAY_HOST` is not compatible with LDAP.
|
||||
|
||||
!!! tip "Opt-in for relay host support"
|
||||
|
||||
If you only want to enable relay for specific sender domains, use can use opt-in via `setup relay add-domain`.
|
||||
Enable relaying only for specific sender domains instead by using `setup relay add-domain`.
|
||||
|
||||
**NOTE:** Presently there is a caveat when relay host credentials are configured (_which is incompatible with opt-in_).
|
||||
|
||||
##### DEFAULT_RELAY_HOST
|
||||
|
||||
@ -1033,22 +1039,24 @@ Configures a default relay host.
|
||||
|
||||
!!! abstract "Technical Details"
|
||||
|
||||
Configures the Postfix `main.cf` setting: [`relayhost`][postfix-config::relayhost]
|
||||
This ENV internally configures the Postfix `main.cf` setting: [`relayhost`][postfix-config::relayhost]
|
||||
|
||||
##### RELAY_HOST
|
||||
|
||||
Configures a default relay host.
|
||||
|
||||
!!! info
|
||||
|
||||
- This is a legacy ENV. It is however required for the opt-out feature of `postfix-relaymap.cf` to work.
|
||||
- When configured, all known mail domains managed by DMS will be configured to relay outbound mail, just like `DEFAULT_RELAY_HOST`.
|
||||
|
||||
!!! note
|
||||
|
||||
Expects a value like `mail.example.com`. Internally this will be wrapped to `[mail.example.com]`, so it should resolve to the MTA directly.
|
||||
|
||||
Do not use with `DEFAULT_RELAY_HOST`. `RELAY_HOST` has precedence as it is configured with `sender_dependent_relayhost_maps`.
|
||||
!!! warning "Do not use with `DEFAULT_RELAY_HOST`"
|
||||
|
||||
`RELAY_HOST` has precedence as it is configured with `sender_dependent_relayhost_maps`.
|
||||
|
||||
!!! info
|
||||
|
||||
- This is a legacy ENV. It is however required for the opt-out feature of `postfix-relaymap.cf` to work.
|
||||
- Internal configuration however differs from `DEFAULT_RELAY_HOST`.
|
||||
|
||||
!!! abstract "Technical Details"
|
||||
|
||||
@ -1057,6 +1065,8 @@ Configures a default relay host.
|
||||
- Postfix setting with config: [`sender_dependent_relayhost_maps = texthash:/etc/postfix/relayhost_map`][postfix-config::relayhost_maps]
|
||||
- DMS Config volume support via: `postfix-relaymap.cf` (_generates `/etc/postfix/relayhost_map`_)
|
||||
|
||||
All known mail domains managed by DMS will be configured to relay outbound mail to `RELAY_HOST` by adding them implicitly to `/etc/postfix/relayhost_map`, except for domains using the opt-out feature of `postfix-relaymap.cf`.
|
||||
|
||||
##### RELAY_PORT
|
||||
|
||||
Default => 25
|
||||
@ -1069,10 +1079,10 @@ Support for configuring a different port than 25 for `RELAY_HOST` to use.
|
||||
|
||||
#### Relay Host Credentials
|
||||
|
||||
!!! warning "Configuring relay host credentials make outbound authentication mandatory"
|
||||
!!! warning "Configuring relay host credentials enforces outbound authentication"
|
||||
|
||||
Presently when `RELAY_USER` + `RELAY_PASSWORD` or `postfix-sasl-password.cf` are configured, all outbound mail traffic is configured to require a secure connection established and forbids the omission of credentials.
|
||||
|
||||
|
||||
Additional feature work is required to only enforce these requirements on mail sent through a configured relay host.
|
||||
|
||||
##### RELAY_USER
|
||||
@ -1083,10 +1093,10 @@ Provide the credentials to use with `RELAY_HOST` or `DEFAULT_RELAY_HOST`.
|
||||
|
||||
!!! tip "Alternative credentials config"
|
||||
|
||||
You may prefer to use `setup relay add-auth` to avoid exposure of secrets in ENV.
|
||||
You may prefer to use `setup relay add-auth` to avoid risking ENV exposing secrets.
|
||||
|
||||
- With the CLI command you must provide each sender domain relay credentials.
|
||||
- Alternatively manually edit `postfix-sasl-password.cf` with the correct relayhost entry (_`DEFAULT_RELAY_HOST` value or as defined in `/etc/postfix/relayhost_map`_) to provide credentials per relayhost configured.
|
||||
- With the CLI command, you must provide relay credentials for each of your sender domains.
|
||||
- Alternatively manually edit `postfix-sasl-password.cf` with the correct relayhost entry (_`DEFAULT_RELAY_HOST` value, or as defined in `/etc/postfix/relayhost_map`_) to provide credentials per relayhost configured.
|
||||
|
||||
!!! abstract "Technical Details"
|
||||
|
||||
@ -1095,7 +1105,16 @@ Provide the credentials to use with `RELAY_HOST` or `DEFAULT_RELAY_HOST`.
|
||||
- Postfix setting with config: [`smtp_sasl_password_maps = texthash:/etc/postfix/sasl_passwd`][postfix-config::sasl_passwd]
|
||||
- DMS Config volume support via: `postfix-sasl-password.cf` (_generates `/etc/postfix/sasl_passwd`_)
|
||||
|
||||
This file has relay hosts that must match the `host:port` of `/etc/postfix/relayhost_map` or `main.cf:relayhost`. DMS support handles this for you.
|
||||
---
|
||||
|
||||
When `postfix-sasl-password.cf` is present, DMS will copy it internally to `/etc/postfix/sasl_passwd`.
|
||||
|
||||
- DMS provides support for mapping credentials by sender domain:
|
||||
- Explicitly via `setup relay add-auth` (_creates / updates `postfix-sasl-password.cf`_).
|
||||
- Implicitly via the relay ENV support (_configures all known DMS managed domains to use the relay ENV_).
|
||||
- Credentials can be explicitly configured for specific relay hosts instead of sender domains:
|
||||
- Add the exact relayhost value (`host:port` / `[host]:port`) from the generated `/etc/postfix/relayhost_map`, or `main.cf:relayhost` (`DEFAULT_RELAY_HOST`).
|
||||
- `setup relay ...` is missing support, you must instead add these manually to `postfix-sasl-password.cf`.
|
||||
|
||||
[docs-rspamd]: ./security/rspamd.md
|
||||
[docs-tls]: ./security/ssl.md
|
||||
@ -1103,6 +1122,7 @@ Provide the credentials to use with `RELAY_HOST` or `DEFAULT_RELAY_HOST`.
|
||||
[docs-tls-manual]: ./security/ssl.md#bring-your-own-certificates
|
||||
[docs-tls-selfsigned]: ./security/ssl.md#self-signed-certificates
|
||||
[docs-accounts-quota]: ./user-management.md#quotas
|
||||
[docs::relay-host]: ./advanced/mail-forwarding/relay-hosts.md
|
||||
[docs::dms-volumes-state]: ./advanced/optional-config.md#volumes-state
|
||||
[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
|
||||
|
||||
Reference in New Issue
Block a user