diff --git a/docs/reverse.rst b/docs/reverse.rst index 56958d9b..b2e3f1f1 100644 --- a/docs/reverse.rst +++ b/docs/reverse.rst @@ -7,10 +7,31 @@ other Web services are available on other FQDNs served from the same IP address. In such a configuration, one would usually run a front-end reverse proxy to serve all Web contents based on criteria like the requested hostname (virtual hosts). +The Mailu team recommends to use Traefik as reverse proxy. This program is solely designed +to act as reverse proxy. It is easy to configure and offers a streamlined experienced when +used with other docker containers on the same host. + +When using a reverse proxy, Mailu should still be used for requesting certificates. +This prevents duplicate certificates. +Other reasons are: + +- Mailu controls the ciphers and keys used for certificates (Mailu has both RSA and ECDSA certs) +- Mailu cerbot client is configured to prevent hitting ratelimits of the CA +- Due to usage of proxy protocol it is less likely that Mailu becomes an open relay due to misconfiguration of special headers. +- No special scripting is required to copy over certs from the proxy to Mailu + +When using Mailu with Traefik as reverse proxy. Traefik is configured to use proxy protocol for all ports, but port 80. +Port 80 is configured to let through the letsencrypt HTTP challenges for Mailu. +This means that if Traefik must request certificates for other services than Mailu, Traefik should use the TLS (TLS-ALPN-01) +challenge method. The HTTP challenge (HTTP-01) cannot be used since this is already used by Mailu. + .. _traefik_proxy: -Traefik as reverse proxy ------------------------- +Traefik as reverse proxy (same host) +------------------------------------ + +This example is for when Traefik (reverse proxy) runs on the same host as Mailu. +It makes use of the docker configuration method for Traefik. In your docker-compose.yml, remove the `ports` section of the `front` container and add a section like follows: @@ -102,7 +123,7 @@ and then add the following to the front section: in mailu.env: -.. code-block:: docker +.. code-block:: bash REAL_IP_FROM=192.168.203.0/24 PROXY_PROTOCOL=25,443,465,993,995,4190 @@ -111,3 +132,164 @@ in mailu.env: WEBROOT_REDIRECT=/sso/login Using the above configuration, Traefik will proxy all the traffic related to Mailu's FQDNs without requiring duplicate certificates. + + +Traefik as reverse proxy (different host) +----------------------------------------- + +This example is for when Traefik (reverse proxy) runs on a different server than the Mailu server. +This example makes use of the File configuration method (File Provider) of Traefik. +It makes use of a single static configuration file and one or more dynamic configuration files. + +This example uses V3 of Traefik. V2 and V3 of Traefik have some differences in the configuration method. + +The contents for the static configuration file. The static configuration file must be provided as argument to Traefik. + +.. code-block:: yaml + + #STATIC CONFIGURATION FILE + #Below value for 'directory' is the location where the dynamic configuration files reside: + #When a change is made in this folder, Traefik automatically loads or reloads it. + providers: + file: + directory: "/etc/traefik/conf" + + entryPoints: + web: + address: :80 + websecure: + address: :443 + mailu-smtp: + address: :25 + mailu-imaps: + address: :993 + mailu-pop3s: + address: :995 + mailu-smtps: + address: :465 + mailu-sieve: + address: :4190 + + #Optional, enables access logging at: + accessLog: + filePath: "/var/log/traefik_access.log" + + #Optional, enables normal logging at: + log: + level: INFO + filePath: "/var/log/traefik.log" + + +This is the contents for the dynamic configuration. You can use and filename you want. +The extension must end with .yml and the file must be placed in the configured directory for +dynamic configuration files. + + +.. code-block:: yaml + + http: + routers: + mailu-web: + entryPoints: + - web + rule: "Host(`mail.example.com) || PathPrefix(`/.well-known/acme-challenge/`))" + service: "mailu-web" + services: + mailu-web: + loadBalancer: + servers: + - url: "http://mailu-server" + + tcp: + routers: + mailu-websecure: + entryPoints: + - websecure + # Add other FQDN's here + rule: "HostSNI(`mail.example.com`) || HostSNI(`autoconfig.example.com`) || HostSNI(`mta-sts.example.com`)" + service: "mailu-websecure" + tls: + passthrough: true + mailu-smtp: + entryPoints: + - mailu-smtp + rule: "HostSNI(`*`)" + service: "mailu-smtp" + mailu-imaps: + entryPoints: + - mailu-imaps + rule: "HostSNI(`*`)" + service: "mailu-imaps" + tls: + passthrough: true + mailu-pop3s: + entryPoints: + - mailu-pop3s + rule: "HostSNI(`*`)" + service: "mailu-pop3s" + tls: + passthrough: true + mailu-smtps: + entryPoints: + - mailu-smtps + rule: "HostSNI(`*`)" + service: "mailu-smtps" + tls: + passthrough: true + mailu-sieve: + entryPoints: + - mailu-sieve + rule: "HostSNI(`*`)" + service: "mailu-sieve" + services: + mailu-websecure: + loadBalancer: + proxyProtocol: + version: 2 + servers: + - address: "mailu-server:443" + mailu-smtp: + loadBalancer: + proxyProtocol: + version: 2 + servers: + - address: "mailu-server:25" + mailu-smtps: + loadBalancer: + proxyProtocol: + version: 2 + servers: + - address: "mailu-server:465" + mailu-imaps: + loadBalancer: + proxyProtocol: + version: 2 + servers: + - address: "mailu-server:993" + mailu-pop3s: + loadBalancer: + proxyProtocol: + version: 2 + servers: + - address: "mailu-server:995" + mailu-sieve: + loadBalancer: + proxyProtocol: + version: 2 + servers: + - address: "mailu-server:4190" + + +In the mailu.env file add the following: + + +.. code-block:: bash + + #Add the IP address of the Traefik server as value for REAL_IP_FROM + REAL_IP_FROM=192.168.2.300/32 + PROXY_PROTOCOL=25,443,465,993,995,4190 + TLS_FLAVOR=letsencrypt + WEBROOT_REDIRECT=/sso/login + + +Using the above configuration, Traefik will proxy all the traffic related to Mailu's FQDNs without requiring duplicate certificates. \ No newline at end of file