Merge d7e92b6953 into df360516ff

Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
Co-authored-by: Casper <casperklein@users.noreply.github.com>

CHANGELOG.md

@@ -70,6 +70,8 @@ The most noteworthy change of this release is the update of the container's base
 
 ### Added
 
+- **Docs:**
+  - A guide for configuring a public server to relay inbound and outbound mail from DMS on a private server ([#3973](https://github.com/docker-mailserver/docker-mailserver/pull/3973))
 - **Environment Variables:**
   - `LOGROTATE_COUNT` defines the number of files kept by logrotate ([#3907](https://github.com/docker-mailserver/docker-mailserver/pull/3907))
     - The fail2ban log file is now also taken into account by `LOGROTATE_COUNT` and `LOGROTATE_INTERVAL` ([#3915](https://github.com/docker-mailserver/docker-mailserver/pull/3915), [#3919](https://github.com/docker-mailserver/docker-mailserver/pull/3919))
@@ -94,7 +96,9 @@ The most noteworthy change of this release is the update of the container's base
 
 ### Fixes
 
-- DMS config files that are parsed line by line are now more robust to parse by detecting and fixing line-endings ([#3819](https://github.com/docker-mailserver/docker-mailserver/pull/3819))
+- DMS config:
+  - Files that are parsed line by line are now more robust to parse by detecting and fixing line-endings ([#3819](https://github.com/docker-mailserver/docker-mailserver/pull/3819))
+  - The override config `postfix-main.cf` now retains custom parameters intended for use with `postfix-master.cf` ([#3880](https://github.com/docker-mailserver/docker-mailserver/pull/3880))
 - Variables related to Rspamd are declared as `readonly`, which would cause warnings in the log when being re-declared; we now guard against this issue ([#3837](https://github.com/docker-mailserver/docker-mailserver/pull/3837))
 - Relay host feature refactored ([#3845](https://github.com/docker-mailserver/docker-mailserver/pull/3845))
   - `DEFAULT_RELAY_HOST` ENV can now also use the `RELAY_USER` + `RELAY_PASSWORD` ENV for supplying credentials.

compose.yaml

@@ -7,7 +7,6 @@ services:
     env_file: mailserver.env
     # More information about the mail-server ports:
     # https://docker-mailserver.github.io/docker-mailserver/latest/config/security/understanding-the-ports/
-    # To avoid conflicts with yaml base-60 float, DO NOT remove the quotation marks.
     ports:
       - "25:25"    # SMTP  (explicit TLS => STARTTLS, Authentication is DISABLED => use port 465/587 instead)
       - "143:143"  # IMAP4 (explicit TLS => STARTTLS)

docs/content/config/security/ssl.md

@@ -481,113 +481,108 @@ DSM-generated letsencrypt certificates get auto-renewed every three months.
 
 ### Caddy
 
-For Caddy v2 you can specify the `key_type` in your server's global settings, which would end up looking something like this if you're using a `Caddyfile`:
+[Caddy][web::caddy] is an open-source web server with built-in TLS certificate generation. You can use the [official Docker image][dockerhub::caddy] and write your own `Caddyfile`.
 
-```caddyfile
-{
-  debug
-  admin localhost:2019
-  http_port 80
-  https_port 443
-  default_sni example.com
-  key_type rsa2048
-}
-```
+!!! example
 
-If you are instead using a json config for Caddy v2, you can set it in your site's TLS automation policies:
+    ```yaml title="compose.yaml"
+    services:
+      # Basic Caddy service to provision certs:
+      reverse-proxy:
+        image: caddy:2.7
+        ports:
+          - 80:80
+          - 443:443
+        volumes:
+          - ./Caddyfile:/etc/caddy/Caddyfile:ro
+          - ${CADDY_DATA_DIR}:/data
 
-??? example "Caddy v2 JSON example snippet"
+      # Share the Caddy data volume for certs and configure SSL_TYPE to `letsencrypt`
+      mailserver:
+        image: ghcr.io/docker-mailserver/docker-mailserver:latest
+        hostname: mail.example.com
+        environment:
+          SSL_TYPE: letsencrypt
+        # While you could use a named data volume instead of a bind mount volume, it would require the long-syntax to rename cert files:
+        # https://docs.docker.com/compose/compose-file/05-services/#volumes
+        volumes:
+          - ${CADDY_DATA_DIR}/certificates/acme-v02.api.letsencrypt.org-directory/mail.example.com/mail.example.com.crt:/etc/letsencrypt/live/mail.example.com/fullchain.pem
+          - ${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
+    ```
 
-    ```json
-    {
-      "apps": {
-        "http": {
-          "servers": {
-            "srv0": {
-              "listen": [
-                ":443"
-              ],
-              "routes": [
-                {
-                  "match": [
-                    {
-                      "host": [
-                        "mail.example.com",
-                      ]
-                    }
-                  ],
-                  "handle": [
-                    {
-                      "handler": "subroute",
-                      "routes": [
-                        {
-                          "handle": [
-                            {
-                              "body": "",
-                              "handler": "static_response"
-                            }
-                          ]
-                        }
-                      ]
-                    }
-                  ],
-                  "terminal": true
-                },
-              ]
-            }
-          }
-        },
-        "tls": {
-          "automation": {
-            "policies": [
-              {
-                "subjects": [
-                  "mail.example.com",
-                ],
-                "key_type": "rsa2048",
-                "issuer": {
-                  "email": "admin@example.com",
-                  "module": "acme"
-                }
-              },
-              {
-                "issuer": {
-                  "email": "admin@example.com",
-                  "module": "acme"
-                }
-              }
-            ]
-          }
-        }
+    ```caddyfile title="Caddyfile"
+    mail.example.com {
+      tls internal {
+        key_type rsa2048
       }
+
+      # Optional, can be useful for troubleshooting
+      # connection to Caddy with correct certificate:
+      respond "Hello DMS"
     }
     ```
 
-The generated certificates can then be mounted:
+    While DMS does not need a webserver to work, this workaround will provision a TLS certificate for DMS to use.
 
-```yaml
-volumes:
-  - ${CADDY_DATA_DIR}/certificates/acme-v02.api.letsencrypt.org-directory/mail.example.com/mail.example.com.crt:/etc/letsencrypt/live/mail.example.com/fullchain.pem
-  - ${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
-```
+    - [`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).
 
-### Traefik v2
+??? example "With `caddy-docker-proxy`"
 
-[Traefik][traefik::github] is an open-source application proxy using the [ACME protocol][ietf::rfc::acme]. [Traefik][traefik::github] can request certificates for domains and subdomains, and it will take care of renewals, challenge negotiations, etc. We strongly recommend to use [Traefik][traefik::github]'s major version 2.
+    Using [`lucaslorentz/caddy-docker-proxy`][github::caddy-docker-proxy] allows you to generate a `Caddyfile` by adding labels to your services in `compose.yaml`:
 
-[Traefik][traefik::github]'s storage format is natively supported if the `acme.json` store is mounted into the container at `/etc/letsencrypt/acme.json`. The file is also monitored for changes and will trigger a reload of the mail services (Postfix and Dovecot).
+    ```yaml title="compose.yaml"
+    services:
+      reverse-proxy:
+        image: lucaslorentz/caddy-docker-proxy:2.8
+        ports:
+          - 80:80
+          - 443:443
+        volumes:
+          - /var/run/docker.sock:/var/run/docker.sock
+          - ${CADDY_DATA_DIR}:/data
+        labels:
+          # Set global config here, this option has an empty value to enable self-signed certs for local testing:
+          # NOTE: Remove this label when going to production.
+          caddy.local_certs: ""
 
-Wildcard certificates are supported. If your FQDN is `mail.example.com` and your wildcard certificate is `*.example.com`, add the ENV: `#!bash SSL_DOMAIN=example.com`.
+      # Use labels to configure Caddy to provision DMS certs
+      mailserver:
+        image: ghcr.io/docker-mailserver/docker-mailserver:latest
+        hostname: mail.example.com
+        environment:
+          SSL_TYPE: letsencrypt
+        volumes:
+          - ${CADDY_DATA_DIR}/certificates/acme-v02.api.letsencrypt.org-directory/mail.example.com/mail.example.com.crt:/etc/letsencrypt/live/mail.example.com/fullchain.pem
+          - ${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
+        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:
+          caddy_0.respond: "Hello DMS"
+          # Uncomment to make a proxy for Rspamd
+          # caddy_1: rspamd.example.com
+          # caddy_1.reverse_proxy: "{{upstreams 11334}}"
+    ```
 
-DMS will select it's certificate from `acme.json` checking these ENV for a matching FQDN (_in order of priority_):
+!!! warning "Caddy certificate location varies"
 
-1. `#!bash ${SSL_DOMAIN}`
-2. `#!bash ${HOSTNAME}`
-3. `#!bash ${DOMAINNAME}`
+    The path contains the certificate provisioner used. This path may be different from the example above for you and may change over time when multiple provisioner services are used][dms-pr-feedback::caddy-provisioning-gotcha].
 
-This setup only comes with one caveat: The domain has to be configured on another service for [Traefik][traefik::github] to actually request it from _Let's Encrypt_, i.e. [Traefik][traefik::github] will not issue a certificate without a service / router demanding it.
+    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].
+
+### 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.
+
+Traefik's storage format is natively supported if the `acme.json` store is mounted into the container at `/etc/letsencrypt/acme.json`. The file is also monitored for changes and will trigger a reload of the mail services (Postfix and Dovecot).
+
+DMS will select it's certificate from `acme.json` prioritizing a match for the DMS FQDN (hostname), while also checking one DNS level up (_eg: `mail.example.com` => `example.com`_). Wildcard certificates are supported.
+
+This setup only comes with one caveat - The domain has to be configured on another service for Traefik to actually request it from _Let's Encrypt_ (_i.e. Traefik will not issue a certificate without a service / router demanding it_).
 
 ???+ example "Example Code"
+
     Here is an example setup for [`docker-compose`](https://docs.docker.com/compose/):
 
     ```yaml
@@ -716,7 +711,7 @@ The local and internal paths may be whatever you prefer, so long as both `SSL_CE
 
 ## Testing a Certificate is Valid
 
-- From your host:
+!!! example "Connect to DMS on port 25"
 
     ```sh
     docker exec mailserver openssl s_client \
@@ -725,26 +720,42 @@ The local and internal paths may be whatever you prefer, so long as both `SSL_CE
       -CApath /etc/ssl/certs/
     ```
 
-- Or:
+    The response should show the certificate chain with a line further down: `Verify return code: 0 (ok)`
+
+    ---
+
+    This example runs within the DMS container itself to verify the cert is working locally.
+
+    - Adjust the `-connect` IP if testing externally from another system. Additionally testing for port 143 (Dovecot IMAP) is encouraged (_change the protocol for `-starttls` from `smtp` to `imap`_).
+    - `-CApath` will help verify the certificate chain, provided the location contains the root CA that signed your TLS cert for DMS.
+
+??? example "Verify certificate dates"
 
     ```sh
     docker exec mailserver openssl s_client \
-      -connect 0.0.0.0:143 \
-      -starttls imap \
-      -CApath /etc/ssl/certs/
+      -connect 0.0.0.0:25 \
+      -starttls smtp \
+      -CApath /etc/ssl/certs/ \
+      2>/dev/null | openssl x509 -noout -dates
     ```
 
-And you should see the certificate chain, the server certificate and: `Verify return code: 0 (ok)`
+!!! tip "Testing and troubleshooting"
 
-In addition, to verify certificate dates:
+    If you need to test a connection without resolving DNS, `curl` can connect with `--resolve` option to map an FQDN + Port to an IP address, instead of the request address provided.
 
-```sh
-docker exec mailserver openssl s_client \
-  -connect 0.0.0.0:25 \
-  -starttls smtp \
-  -CApath /etc/ssl/certs/ \
-  2>/dev/null | openssl x509 -noout -dates
-```
+    ```bash
+    # NOTE: You may want to use `--insecure` if the cert was provisioned with a private CA not present on the curl client:
+    # Use `--verbose` for additional insights on the connection.
+    curl --resolve mail.example.com:443:127.0.0.1 https://mail.example.com
+    ```
+
+    Similarly with `openssl` you can connect to an IP as shown previously, but provide an explicit SNI if necessary with `-servername mail.example.com`.
+
+    ---
+
+    Both `curl` and `openssl` also support `-4` and `-6` for enforcing IPv4 or IPv6 lookup.
+
+    This can be useful, such as when [DNS resolves the IP to different servers leading to different certificates returned][dms-discussion::gotcha-fqdn-bad-dns]. As shown in that link, `step certificate inspect` is also handy for viewing details of the cert returned or on disk.
 
 ## Plain-Text Access
 
@@ -919,3 +930,13 @@ Despite this, if you must use non-standard DH parameters or you would like to sw
 [acme-companion::standalone]: https://github.com/nginx-proxy/acme-companion/blob/main/docs/Standalone-certificates.md
 [acme-companion::standalone-changes]: https://github.com/nginx-proxy/acme-companion/blob/main/docs/Standalone-certificates.md#picking-up-changes-to-letsencrypt_user_data
 [acme-companion::service-loop]: https://github.com/nginx-proxy/acme-companion/blob/main/docs/Container-utilities.md
+
+[web::caddy]: https://caddyserver.com
+[dockerhub::caddy]: https://hub.docker.com/_/caddy
+[github::caddy-docker-proxy]: https://github.com/lucaslorentz/caddy-docker-proxy
+[dms-pr-feedback::caddy-provisioning-gotcha]: https://github.com/docker-mailserver/docker-mailserver/pull/3485/files#r1297512818
+[caddy-docs::tls-internal]: https://caddyserver.com/docs/caddyfile/directives/tls#syntax
+[caddy-docs::key-type]: https://caddyserver.com/docs/caddyfile/options#key-type
+[caddy::restrict-acme-provisioner]: https://caddy.community/t/is-there-a-way-on-a-caddyfile-to-force-a-specific-acme-ca/14506
+
+[dms-discussion::gotcha-fqdn-bad-dns]: https://github.com/docker-mailserver/docker-mailserver/issues/3955#issuecomment-2027882633

docs/content/examples/use-cases/external-relay-only-mailserver.md

@@ -0,0 +1,233 @@
+---
+title: 'Use Cases | Relay inbound and outbound mail for an internal DMS'
+hide:
+  - toc
+---
+
+## Introduction
+
+!!! info "Community contributed guide"
+
+    Adapted into a guide from [this discussion](https://github.com/orgs/docker-mailserver/discussions/3965).
+
+    **Requirements:**
+
+    - A _public server_ with a static IP, like many VPS providers offer. It will only relay mail to DMS, no mail is stored on this system.
+    - A _private server_ (e.g.: a local system at home) that will run DMS.
+    - Both servers are connected to the same network via a VPN (_optional convenience for trust via the `mynetworks` setting_).
+
+    ---
+
+    The guide below will assume the VPN is setup on `192.168.2.0/24` with:
+
+    - The _public server_ is using `192.168.2.2`
+    - The _private server_ is using `192.168.2.3`
+
+The goal of this guide is to configure a _public server_ that can receive inbound mail and relay that over to DMS on a _private server_, which can likewise submit mail outbound through a _public server_ or service.
+
+The primary motivation is to keep your mail storage private instead of storing it to disk unencrypted on a VPS host.
+
+## DNS setup
+
+Follow our [standard guidance][docs::usage-dns-setup] for DNS setup.
+
+Set your A, MX and PTR records for the _public server_ as if it were running DMS.
+
+!!! example "DNS Zone file example"
+    
+    For this guide, we assume DNS is configured with:
+
+    - A public reachable IP address of `11.22.33.44`
+    - Mail for `@example.com` addresses must have an MX record pointing to `mail.example.com`.
+    - An A record for `mail.example.com` pointing to the IP address of your _public server_.
+
+    ```txt
+    $ORIGIN example.com
+    @     IN  A      11.22.33.44
+    mail  IN  A      11.22.33.44
+
+    ; mail server for example.com
+    @     IN  MX  10 mail.example.com.
+    ```
+
+    SPF records should also be set up as you normally would for `mail.example.com`.
+
+## Public Server (Basic Postfix setup)
+
+You will need to install Postfix on your _public server_. The functionality that is needed for this setup is not yet implemented in DMS, so a vanilla Postfix will probably be easier to work with, especially since this server will only be used as an inbound and outbound relay.
+
+It's necessary to adjust some settings afterwards.
+
+<!-- This empty quote block is purely for a visual border -->
+!!! quote ""
+
+    === "Postfix main config"
+
+        ??? example "Create or replace `/etc/postfix/main.cf`"
+
+            ```cf
+            # See /usr/share/postfix/main.cf.dist for a commented, more complete version
+
+            smtpd_banner = $myhostname ESMTP $mail_name (Debian/GNU)
+            biff = no
+
+            # appending .domain is the MUA's job.
+            append_dot_mydomain = no
+
+            # Uncomment the next line to generate "delayed mail" warnings
+            #delay_warning_time = 4h
+
+            # See http://www.postfix.org/COMPATIBILITY_README.html -- default to 3.6 on
+            # fresh installs.
+            compatibility_level = 3.6
+
+            # TLS parameters
+            smtpd_tls_cert_file=/etc/postfix/certificates/mail.example.com.crt
+            smtpd_tls_key_file=/etc/postfix/certificates/mail.example.com.key
+            smtpd_tls_security_level=may
+            smtp_tls_CApath=/etc/ssl/certs
+            smtp_tls_security_level=may
+            smtp_tls_session_cache_database = btree:${data_directory}/smtp_scache
+
+            alias_database = hash:/etc/aliases
+            alias_maps = hash:/etc/aliases
+            maillog_file = /var/log/postfix.log
+            mailbox_size_limit = 0
+            inet_interfaces = all
+            inet_protocols = ipv4
+            readme_directory = no
+            recipient_delimiter = +
+
+            # Customizations relevant to this guide:
+            myhostname = mail.example.com
+            myorigin = example.com
+            mydestination = localhost
+            mynetworks = 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.2.0/24
+            smtpd_relay_restrictions = permit_mynetworks permit_sasl_authenticated defer_unauth_destination
+            transport_maps = hash:/etc/postfix/transport
+            relay_domains = $mydestination, hash:/etc/postfix/relay
+
+            # Disable local system accounts and delivery:
+            local_recipient_maps =
+            local_transport = error:local mail delivery is disabled
+            ```
+
+        Let's highlight some of the important parts:
+
+        - Avoid including `mail.example.com` in `mydestination`, in fact you can just set `localhost` or nothing at all here as we want all mail to be relayed to our _private server_ (DMS).
+        - `mynetworks` should contain your VPN network (_eg: `192.168.2.0/24` subnet_).
+        - Important are `transport_maps = hash:/etc/postfix/transport` and `relay_domains = $mydestination, hash:/etc/postfix/relay`, with their file contents covered below.
+        - For good measure, also disable `local_recipient_maps`.
+        - You should have a valid certificate configured for `mail.example.com`.
+
+        !!! warning "Open relay"
+
+            Please be aware that setting `mynetworks` to a public CIDR will leave you with an open relay. **Only** set it to the CIDR of your VPN beyond the localhost ranges.
+
+    === "Route outbound mail through a separate transport"
+
+        When mail arrives to the _public server_ for an `@example.com` address, we want to send it via the `relay` transport to our _private server_ over port 25 for delivery to DMS.
+
+        [`transport_maps`][postfix-docs::transport_maps] is configured with a [`transport` table][postfix-docs::transport_table] file that matches recipient addresses and assigns a non-default transport. This setting has priority over [`relay_transport`][postfix-docs::relay_transport].
+
+        !!! example "Create `/etc/postfix/transport`"
+
+            ```txt
+            example.com relay:[192.168.2.3]:25
+            ```
+
+            **Other considerations:**
+
+            - If you have multiple domains, you can add them here too (on separate lines).
+            - If you use a smarthost add `* relay:[X.X.X.X]:port` to the bottom (eg: `* relay:[relay1.org]:587`), which will relay everything outbound via this relay host.
+
+        !!! tip
+
+            Instead of a file, you could alternatively configure `main.cf` with `transport_maps = inline:{ example.com=relay:[192.168.2.3]:25 }`
+
+    === "Configure recipient domains to relay mail"
+
+        We want `example.com` to be relayed inbound and everything else relayed outbound.
+
+        [`relay_domains`][postfix-docs::relay_domains] is configured with a file with a list of domains that should be relayed (one per line), the 2nd value is required but can be anything.
+
+        !!! example "Create `/etc/postfix/relay`"
+
+            ```txt
+            example.com   OK
+            ```
+
+        !!! tip
+
+            Instead of a file, you could alternatively configure `main.cf` with `relay_domains = example.com`.
+
+!!! note "Files configured with `hash:` table type must run `postmap` to apply changes"
+
+    Run `postmap /etc/postfix/transport` and `postmap /etc/postfix/relay` after creating or updating either of these files, this processes them into a separate file for Postfix to use.
+
+## Private Server (Running DMS)
+
+You can set up your DMS instance as you normally would.
+
+- Be careful not to give it a hostname of `mail.example.com`. Instead, use `internal-mail.example.com` or something similar.
+- DKIM can be setup as usual since it considers checks whether the message body has been tampered with, which our public relay doesn't do. Set DKIM up for `mail.example.com`.
+
+Next, we need to configure our _private server_ to relay all outbound mail through the _public server_ (or a separate smarthost service). The setup is [similar to the default relay setup][docs::relay-host-details].
+
+<!-- This empty quote block is purely for a visual border -->
+!!! quote ""
+
+    === "Configure the relay host"
+
+        !!! example "Create `postfix-relaymap.cf`"
+
+            ```txt
+            @example.com  [192.168.2.2]:25
+            ```
+
+        Meaning all mail sent outbound from `@example.com` addresses will be relayed through the _public server_ at that VPN IP.
+
+        The _public server_ `mynetworks` setting from earlier trusts any mail received on port 25 from the VPN network, which is what allows the mail to be sent outbound when it'd otherwise be denied.
+
+    === "Trust the _public server_"
+
+        !!! example "Create `postfix-main.cf`"
+
+            ```txt
+            mynetworks = 192.168.2.0/24
+            ```
+
+        This will trust any connection from the VPN network to DMS, such as from the _public server_ when relaying mail over to DMS at the _private server_.
+
+        This step is necessary to skip some security measures that DMS normally checks for, like verifying DNS records like SPF are valid. As the mail is being relayed, those checks would fail otherwise as the IP of your _public server_ would not be authorized to send mail on behalf of the sender address in mail being relayed.
+
+        ??? tip "Alternative to `mynetworks` setting"
+
+            Instead of trusting connections by their IP with the `mynetworks` setting, those same security measures can be skipped for any authenticated deliveries to DMS over port 587 instead.
+
+            This is a bit more work. `mynetworks` on the _public server_ `main.cf` Postfix config is for trusting DMS when it sends mail from the _private server_, thus you'll need to have that public Postfix service configured with a login account that DMS can use.
+
+            On the _private server_, DMS needs to know the credentials for that login account, that is handled with `postfix-sasl-password.cf`:
+
+            ```txt
+            @example.com user:secret
+            ```
+
+            You could also relay mail through SendGrid, AWS SES or similar instead of the _public server_ you're running to receive mail from. Login credentials for those relay services are provided via the same `postfix-sasl-password.cf` file.
+
+            ---
+
+            Likewise for the _public server_ to send mail to DMS, it would need to be configured to relay mail with credentials too, removing the need for `mynetworks` on the DMS `postfix-main.cf` config.
+
+            The extra effort to require authentication instead of blind trust of your private subnet can be beneficial at reducing the impact of a compromised system or service on that network that wasn't expected to be permitted to send mail.
+
+## IMAP / POP3
+
+IMAP and POP3 need to point towards your _private server_, since that is where the mailboxes are located, which means you need to have a way for your MUA to connect to it.
+
+[docs::usage-dns-setup]: ../../usage.md#minimal-dns-setup
+[docs::relay-host-details]: ../../config/advanced/mail-forwarding/relay-hosts.md#technical-details
+[postfix-docs::relay_domains]: https://www.postfix.org/postconf.5.html#relay_domains
+[postfix-docs::relay_transport]: https://www.postfix.org/postconf.5.html#relay_transport
+[postfix-docs::transport_maps]: https://www.postfix.org/postconf.5.html#transport_maps
+[postfix-docs::transport_table]: https://www.postfix.org/transport.5.html

docs/mkdocs.yml

@@ -180,6 +180,7 @@ nav:
       - 'iOS Mail Push Support': examples/use-cases/ios-mail-push-support.md
       - 'Lua Authentication': examples/use-cases/auth-lua.md
       - 'Bind outbound SMTP to a specific network': examples/use-cases/bind-smtp-network-interface.md
+      - 'Relay inbound and outbound mail for an internal DMS': examples/use-cases/external-relay-only-mailserver.md
   - 'FAQ' : faq.md
   - 'Contributing':
     - 'General Information': contributing/general.md

target/scripts/startup/setup.d/postfix.sh

@@ -109,21 +109,6 @@ function _setup_postfix_late() {
 function __postfix__setup_override_configuration() {
   __postfix__log 'debug' 'Overriding / adjusting configuration with user-supplied values'
 
-  local OVERRIDE_CONFIG_POSTFIX_MAIN='/tmp/docker-mailserver/postfix-main.cf'
-  if [[ -f ${OVERRIDE_CONFIG_POSTFIX_MAIN} ]]; then
-    cat "${OVERRIDE_CONFIG_POSTFIX_MAIN}" >>/etc/postfix/main.cf
-    _adjust_mtime_for_postfix_maincf
-
-    # do not directly output to 'main.cf' as this causes a read-write-conflict
-    postconf -n >/tmp/postfix-main-new.cf 2>/dev/null
-
-    mv /tmp/postfix-main-new.cf /etc/postfix/main.cf
-    _adjust_mtime_for_postfix_maincf
-    __postfix__log 'trace' "Adjusted '/etc/postfix/main.cf' according to '${OVERRIDE_CONFIG_POSTFIX_MAIN}'"
-  else
-    __postfix__log 'trace' "No extra Postfix settings loaded because optional '${OVERRIDE_CONFIG_POSTFIX_MAIN}' was not provided"
-  fi
-
   local OVERRIDE_CONFIG_POSTFIX_MASTER='/tmp/docker-mailserver/postfix-master.cf'
   if [[ -f ${OVERRIDE_CONFIG_POSTFIX_MASTER} ]]; then
     while read -r LINE; do
@@ -131,7 +116,23 @@ function __postfix__setup_override_configuration() {
     done < <(_get_valid_lines_from_file "${OVERRIDE_CONFIG_POSTFIX_MASTER}")
     __postfix__log 'trace' "Adjusted '/etc/postfix/master.cf' according to '${OVERRIDE_CONFIG_POSTFIX_MASTER}'"
   else
-    __postfix__log 'trace' "No extra Postfix settings loaded because optional '${OVERRIDE_CONFIG_POSTFIX_MASTER}' was not provided"
+    __postfix__log 'trace' "No extra Postfix master settings loaded because optional '${OVERRIDE_CONFIG_POSTFIX_MASTER}' was not provided"
+  fi
+
+  # NOTE: Must come after postfix-master.cf as custom parameter support only works provided either config references it.
+  local OVERRIDE_CONFIG_POSTFIX_MAIN='/tmp/docker-mailserver/postfix-main.cf'
+  if [[ -f ${OVERRIDE_CONFIG_POSTFIX_MAIN} ]]; then
+    cat "${OVERRIDE_CONFIG_POSTFIX_MAIN}" >>/etc/postfix/main.cf
+    _adjust_mtime_for_postfix_maincf
+
+    # Do not directly output to 'main.cf' as this causes a read-write-conflict
+    postconf -n >/tmp/postfix-main-new.cf 2>/dev/null
+
+    mv /tmp/postfix-main-new.cf /etc/postfix/main.cf
+    _adjust_mtime_for_postfix_maincf
+    __postfix__log 'trace' "Adjusted '/etc/postfix/main.cf' according to '${OVERRIDE_CONFIG_POSTFIX_MAIN}'"
+  else
+    __postfix__log 'trace' "No extra Postfix main settings loaded because optional '${OVERRIDE_CONFIG_POSTFIX_MAIN}' was not provided"
   fi
 }