From 614042344db14ea91262056ed2af09dcd0796495 Mon Sep 17 00:00:00 2001 From: Florent Daigniere Date: Mon, 8 Apr 2024 09:46:39 +0200 Subject: [PATCH] document --- core/nginx/conf/nginx.conf | 4 ++-- core/nginx/config.py | 2 +- docs/compose/setup.rst | 12 ++++------- docs/configuration.rst | 30 ++++++++++++++++++---------- docs/reverse.rst | 28 ++------------------------ towncrier/newsfragments/3061.feature | 7 ++++++- 6 files changed, 35 insertions(+), 48 deletions(-) diff --git a/core/nginx/conf/nginx.conf b/core/nginx/conf/nginx.conf index d67ce65a..bbd86fdc 100644 --- a/core/nginx/conf/nginx.conf +++ b/core/nginx/conf/nginx.conf @@ -310,7 +310,7 @@ mail { resolver {{ RESOLVER }} valid=30s; error_log /dev/stderr info; - {% if TLS_25 and not TLS_ERROR %} + {% if TLS and not TLS_ERROR %} include /etc/nginx/tls.conf; ssl_session_cache shared:SSLMAIL:3m; {% endif %} @@ -328,7 +328,7 @@ mail { {% if SUBNET6 %} listen [::]:25{% if PROXY_PROTOCOL_25 %} proxy_protocol{% endif %}; {% endif %} - {% if TLS_25 and not TLS_ERROR %} + {% if TLS and not TLS_ERROR %} {% if TLS_FLAVOR in ['letsencrypt','mail-letsencrypt'] %} ssl_certificate /certs/letsencrypt/live/mailu/DANE-chain.pem; ssl_certificate /certs/letsencrypt/live/mailu-ecdsa/DANE-chain.pem; diff --git a/core/nginx/config.py b/core/nginx/config.py index 3d92d1b9..1f06424b 100755 --- a/core/nginx/config.py +++ b/core/nginx/config.py @@ -89,7 +89,7 @@ for item in args.get('PROXY_PROTOCOL', '').split(','): log.error(f'Not sure what to do with {item} in PROXY_PROTOCOL ({args.get("PROXY_PROTOCOL")})') PORTS_REQUIRING_TLS=['443', '465', '993', '995'] -ALL_PORTS='25,80,443,465,587,993,995,4190' +ALL_PORTS='25,80,443,465,993,995,4190' for item in args.get('PORTS', ALL_PORTS).split(','): if item in PORTS_REQUIRING_TLS and args['TLS_FLAVOR'] == 'notls': continue diff --git a/docs/compose/setup.rst b/docs/compose/setup.rst index 81433ba3..ae1a6387 100644 --- a/docs/compose/setup.rst +++ b/docs/compose/setup.rst @@ -31,18 +31,14 @@ Sets the ``TLS_FLAVOR`` to one of the following values: - ``cert`` is the default and requires certificates to be setup manually; -- ``letsencrypt`` will use the *Letsencrypt!* CA to generate automatic certificates; -- ``mail`` is similar to ``cert`` except that TLS will only be served for - emails (IMAP and SMTP), not HTTP (use it behind reverse proxies); -- ``mail-letsencrypt`` is similar to ``letsencrypt`` except that TLS will only be served for - emails (IMAP and SMTP), not HTTP (use it behind reverse proxies); +- ``letsencrypt`` will use the *Letsencrypt!* CA to obtain certificates automatically; - ``notls`` will disable TLS, this is not recommended except for testing. .. note:: When using *Letsencrypt!* you have to make sure that the DNS ``A`` and ``AAAA`` records for the - all hostnames mentioned in the ``HOSTNAMES`` variable match with the ip addresses of you server. - Or else certificate generation will fail! See also: :ref:`dns_setup`. + all hostnames mentioned in the ``HOSTNAMES`` variable match with the ip addresses of you server + or else certificate generation will fail! See also: :ref:`dns_setup`. Bind address ```````````` @@ -91,7 +87,7 @@ Finish setting up TLS Mailu relies heavily on TLS and must have a key pair and a certificate available, at least for the hostname configured in the ``mailu.env`` file. -If you set ``TLS_FLAVOR`` to ``cert`` or ``mail`` then you must create a ``certs`` directory +If you set ``TLS_FLAVOR`` to ``cert`` then you must create a ``certs`` directory in your root path and setup a key-certificate pair there: - ``cert.pem`` contains the certificate (override with ``TLS_CERT_FILENAME``), diff --git a/docs/configuration.rst b/docs/configuration.rst index 50a576fd..f5818509 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -62,8 +62,7 @@ The ``AUTH_RATELIMIT_EXEMPTION`` (default: '') is a comma separated list of netw CIDRs that won't be subject to any form of rate limiting. Specifying ``0.0.0.0/0, ::/0`` there is a good way to disable rate limiting altogether. -The ``TLS_FLAVOR`` sets how Mailu handles TLS connections. Setting this value to -``notls`` will cause Mailu not to serve any web content! More on :ref:`tls_flavor`. +The ``TLS_FLAVOR`` sets how Mailu obtains a x509 certificate. More on :ref:`tls_flavor`. The ``DEFAULT_SPAM_THRESHOLD`` (default: 80) is the default spam tolerance used when creating a new user. @@ -248,9 +247,20 @@ but slows down the performance of modern devices. .. _`android handsets older than 7.1.1`: https://community.letsencrypt.org/t/production-chain-changes/150739 -The ``TLS_PERMISSIVE`` (default: true) setting controls whether ciphers and protocols offered on port 25 for STARTTLS are optimized for maximum compatibility. We **strongly recommend** that you do **not** change this setting on the basis that any encryption beats no encryption. If you are subject to compliance requirements and are not afraid of losing emails as a result of artificially reducing compatibility, set it to 'false'. Keep in mind that servers that are running a software stack old enough to not be compatible with the current TLS requirements will either a) deliver in plaintext b) bounce emails c) silently drop emails; moreover, modern servers will benefit from various downgrade protections (DOWNGRD, RFC7507) making the security argument mostly a moot point. +The ``TLS_PERMISSIVE`` (default: true) setting controls whether ciphers and protocols offered on port 25 +for STARTTLS are optimized for maximum compatibility. We **strongly recommend** that you do **not** change +this setting on the basis that any encryption beats no encryption. If you are subject to compliance +requirements and are not afraid of losing emails as a result of artificially reducing compatibility, +set it to 'false'. Keep in mind that servers that are running a software stack old enough to not be +compatible with the current TLS requirements will either a) deliver in plaintext b) bounce emails +c) silently drop emails; moreover, modern servers will benefit from various downgrade protections +(DOWNGRD, RFC7507) making the security argument mostly a moot point. -The ``COMPRESSION`` (default: unset) setting controls whether emails are stored compressed at rest on disk. Valid values are ``gz``, ``bz2`` or ``zstd`` and additional settings can be configured via ``COMPRESSION_LEVEL``, see `zlib_save_level`_ for accepted values. If the underlying filesystem supports compression natively you should use it instead of this setting as it will be more efficient and will improve compatibility with 3rd party tools. +The ``COMPRESSION`` (default: unset) setting controls whether emails are stored compressed at rest on disk. +Valid values are ``gz``, ``bz2`` or ``zstd`` and additional settings can be configured via +``COMPRESSION_LEVEL``, see `zlib_save_level`_ for accepted values. If the underlying filesystem +supports compression natively you should use it instead of this setting as it will be more efficient +and will improve compatibility with 3rd party tools. .. _`zlib_save_level`: https://doc.dovecot.org/settings/plugin/zlib-plugin/#plugin_setting-zlib-zlib_save_level @@ -267,13 +277,13 @@ The ``TZ`` sets the timezone Mailu will use. The timezone naming convention usua .. _`TZ database name`: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones -The ``PROXY_PROTOCOL`` (default: unset) allows the the front container to receive TCP and HTTP connections with -the `PROXY protocol`_ (originally introduced in HAProxy, now also configurable in other proxy servers). -It can be set to: -* ``http`` to accept the ``PROXY`` protocol on nginx's HTTP proxy ports -* ``mail`` to accept the ``PROXY`` protocol on nginx's mail proxy ports -* ``all`` to accept the ``PROXY`` protocol on all nginx's HTTP and mail proxy ports +The ``PORTS`` (default: '25,80,443,465,993,995,4190') setting determines which services should be enabled. It is a comma delimited list of ports numbers. +If you need to re-enable IMAP, POP3 and Submission, you can append '110,143,587' to that list. + +The ``PROXY_PROTOCOL`` (default: unset) setting allows the the front container to receive TCP and HTTP connections with +the `PROXY protocol`_ (originally introduced in HAProxy, now also configurable in other proxy servers). +It can be set to a comma delimited list of ports on which it should be enabled. .. _`PROXY protocol`: https://github.com/haproxy/haproxy/blob/master/doc/proxy-protocol.txt diff --git a/docs/reverse.rst b/docs/reverse.rst index de427d5d..56958d9b 100644 --- a/docs/reverse.rst +++ b/docs/reverse.rst @@ -28,11 +28,8 @@ and add a section like follows: - "--entrypoints.web.address=:http" - "--entrypoints.websecure.address=:https" - "--entrypoints.smtp.address=:smtp" - - "--entrypoints.submission.address=:submission" - "--entrypoints.submissions.address=:submissions" - - "--entrypoints.imap.address=:imap" - "--entrypoints.imaps.address=:imaps" - - "--entrypoints.pop3.address=:pop3" - "--entrypoints.pop3s.address=:pop3s" - "--entrypoints.sieve.address=:sieve" # - "--api.insecure=true" @@ -42,11 +39,8 @@ and add a section like follows: - "80:80" - "443:443" - "465:465" - - "587:587" - "993:993" - "995:995" - - "110:110" - - "143:143" - "4190:4190" # The Web UI (enabled by --api.insecure=true) # - "8080:8080" @@ -80,36 +74,18 @@ and then add the following to the front section: - "traefik.tcp.services.smtp.loadbalancer.server.port=25" - "traefik.tcp.services.smtp.loadbalancer.proxyProtocol.version=2" - - "traefik.tcp.routers.submission.rule=HostSNI(`*`)" - - "traefik.tcp.routers.submission.entrypoints=submission" - - "traefik.tcp.routers.submission.service=submission" - - "traefik.tcp.services.submission.loadbalancer.server.port=587" - - "traefik.tcp.services.submission.loadbalancer.proxyProtocol.version=2" - - "traefik.tcp.routers.submissions.rule=HostSNI(`*`)" - "traefik.tcp.routers.submissions.entrypoints=submissions" - "traefik.tcp.routers.submissions.service=submissions" - "traefik.tcp.services.submissions.loadbalancer.server.port=465" - "traefik.tcp.services.submissions.loadbalancer.proxyProtocol.version=2" - - "traefik.tcp.routers.imap.rule=HostSNI(`*`)" - - "traefik.tcp.routers.imap.entrypoints=imap" - - "traefik.tcp.routers.imap.service=imap" - - "traefik.tcp.services.imap.loadbalancer.server.port=143" - - "traefik.tcp.services.imap.loadbalancer.proxyProtocol.version=2" - - "traefik.tcp.routers.imaps.rule=HostSNI(`*`)" - "traefik.tcp.routers.imaps.entrypoints=imaps" - "traefik.tcp.routers.imaps.service=imaps" - "traefik.tcp.services.imaps.loadbalancer.server.port=993" - "traefik.tcp.services.imaps.loadbalancer.proxyProtocol.version=2" - - "traefik.tcp.routers.pop3.rule=HostSNI(`*`)" - - "traefik.tcp.routers.pop3.entrypoints=pop3" - - "traefik.tcp.routers.pop3.service=pop3" - - "traefik.tcp.services.pop3.loadbalancer.server.port=110" - - "traefik.tcp.services.pop3.loadbalancer.proxyProtocol.version=2" - - "traefik.tcp.routers.pop3s.rule=HostSNI(`*`)" - "traefik.tcp.routers.pop3s.entrypoints=pop3s" - "traefik.tcp.routers.pop3s.service=pop3s" @@ -129,9 +105,9 @@ in mailu.env: .. code-block:: docker REAL_IP_FROM=192.168.203.0/24 - PROXY_PROTOCOL=all-but-http + PROXY_PROTOCOL=25,443,465,993,995,4190 TRAEFIK_VERSION=v2 - TLS_FLAVOR=mail-letsencrypt + 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. diff --git a/towncrier/newsfragments/3061.feature b/towncrier/newsfragments/3061.feature index 66b6e669..b8f3e4cd 100644 --- a/towncrier/newsfragments/3061.feature +++ b/towncrier/newsfragments/3061.feature @@ -1 +1,6 @@ -Introduce new settings for configuring proxying and TLS. Drop TLS_FLAVOR=mail-letsencrypt +Introduce new settings for configuring proxying and TLS. Disable POP3, IMAP and SUBMISSION by default, see https://nostarttls.secvuln.info/ +- Drop TLS_FLAVOR=mail-* +- Change the meaning of PROXY_PROTOCOL, introduce PORTS +- Disable POP3, IMAP and SUBMISSION ports by default, to re-enable ensure PORTS include 110, 143 and 587 + +MANAGESIEVE with implicit TLS is not a thing clients support... so 4190 is enabled by default.