Certificates - What is the difference between SSL_TYPE=manual vs SSL_TYPE=letsencrypt?

[audioscavenger]

Hi, I see zero difference between those two options, in practice.

• manual:

SSL_TYPE=manual
SSL_CERT_PATH=/certs/cert.pem
SSL_KEY_PATH=/certs/key.pem

      - /docker/swag/config/etc/letsencrypt/live/domain.com/fullchain.pem:/certs/cert.pem:ro
      - /docker/swag/config/etc/letsencrypt/live/domain.com/privkey.pem:/certs/key.pem:ro

• letsencrypt:

SSL_TYPE=letsencrypt

      - /docker/swag/config/etc/letsencrypt/:/etc/letsencrypt/:ro

DMS works exactly the same either way, and in both cases you have to inject a certificate chain+key, or a folder structure that DMS recognizes.

So the question is... why the 2 options? Are you thinking of adding certbot to DMS one day?

[polarathene]

Are you thinking of adding certbot to DMS one day?

No. We have it documented how to do that with their official container.

There's many ways to acquire certs, and you'll find a post a few years back where someone requested certbot integration and I commented with details as to why we'd want to avoid that in DMS I think.

---

I see zero difference between those two options, in practice.

DMS was started back in 2015 by a dev that wanted to share their work. It's been heavily extended and refactored since then.

I think the manual approach might have been what was originally the default. Then someone contributed LetsEncrypt as a convenience.

Around late 2020, I arrived to the project and audited the TLS config and PR'd some improvements.

LetsEncrypt often is provisioned in a structure that uses symlinks, our docs make this rather clear as a caveat to be aware of. Thus you would need to mounot that whole folder for symlinks to resolve correctly IIRC, it may depend how different CRI (podman, k8s, docker) handle that though.

For bind mounts, if you only bind mount a file, it's tied to the inode. Should that file on the host be updated in a way that the inode is modified, the container would no longer receive updates to that file (it'd continue to point to the old inode that is no longer visible as a file on the host filesystem), IIRC this also prevents modifications from within the container should those changes attempt to modify the inode.

Thus folder mounts are often a better choice (but you lose the benefit of remapping the filenames). I can't recall what the behaviour is like when you bind mount symlinks, and it may depend how those symlinks are later updated when the cert is renewed. So that's something you might want to investigate.

---

DMS works exactly the same either way, and in both cases you have to inject a certificate chain+key, or a folder structure that DMS recognizes.

I refactored the scripts in scripts/helpers/ssl.sh to ensure better consistency I think, so sure they work the same way because we ensure that in DMS, but the support to do so under the hood differs:

docker-mailserver/target/scripts/helpers/ssl.sh

Lines 162 to 201 in d0a915b

	# SSL certificate Configuration
	# TODO: Refactor this feature, it's been extended multiple times for specific inputs/providers unnecessarily.
	# NOTE: Some `SSL_TYPE` logic uses mounted certs/keys directly, some make an internal copy either retaining filename or renaming.
	case "${SSL_TYPE}" in
	( "letsencrypt" )
	_log 'debug' "Configuring SSL using 'letsencrypt'"
	# `docker-mailserver` will only use one certificate from an FQDN folder in `/etc/letsencrypt/live/`.
	# We iterate the sequence [SSL_DOMAIN, HOSTNAME, DOMAINNAME] to find a matching FQDN folder.
	# This same sequence is used for the Traefik `acme.json` certificate extraction process, which outputs the FQDN folder.
	#
	# eg: If HOSTNAME (mail.example.test) doesn't exist, try DOMAINNAME (example.test).
	# SSL_DOMAIN if set will take priority and is generally expected to have a wildcard prefix.
	# SSL_DOMAIN will have any wildcard prefix stripped for the output FQDN folder it is stored in.
	# TODO: A wildcard cert needs to be provisioned via Traefik to validate if acme.json contains any other value for `main` or `sans` beyond the wildcard.
	#
	# NOTE: HOSTNAME is set via `helpers/dns.sh`, it is not the original system HOSTNAME ENV anymore.
	# TODO: SSL_DOMAIN is Traefik specific, it no longer seems relevant and should be considered for removal.
	_traefik_support
	# checks folders in /etc/letsencrypt/live to identify which one to implicitly use:
	local LETSENCRYPT_DOMAIN LETSENCRYPT_KEY
	LETSENCRYPT_DOMAIN=$(_find_letsencrypt_domain)
	LETSENCRYPT_KEY=$(_find_letsencrypt_key "${LETSENCRYPT_DOMAIN}")
	# Update relevant config for Postfix and Dovecot
	_log 'trace' "Adding ${LETSENCRYPT_DOMAIN} SSL certificate to the postfix and dovecot configuration"
	# LetsEncrypt `fullchain.pem` and `privkey.pem` contents are detailed here from CertBot:
	# https://certbot.eff.org/docs/using.html#where-are-my-certificates
	# `key.pem` was added for `simp_le` support (2016): https://github.com/docker-mailserver/docker-mailserver/pull/288
	# `key.pem` is also a filename used by the `_extract_certs_from_acme` method (implemented for Traefik v2 only)
	local PRIVATE_KEY="/etc/letsencrypt/live/${LETSENCRYPT_DOMAIN}/${LETSENCRYPT_KEY}.pem"
	local CERT_CHAIN="/etc/letsencrypt/live/${LETSENCRYPT_DOMAIN}/fullchain.pem"
	_set_certificate "${PRIVATE_KEY}" "${CERT_CHAIN}"
	_log 'trace' "SSL configured with 'letsencrypt' certificates"
	;;

docker-mailserver/target/scripts/helpers/ssl.sh

Lines 223 to 269 in d0a915b

	( "manual" ) # (dynamic path via ENV) Use separate private key and cert/chain files (should be PEM encoded)
	_log 'debug' "Configuring certificates using key ${SSL_KEY_PATH} and cert ${SSL_CERT_PATH}"
	# Source files are copied internally to these destinations:
	local PRIVATE_KEY="${DMS_TLS_PATH}/key"
	local CERT_CHAIN="${DMS_TLS_PATH}/cert"
	# Fail early:
	if [[ -z ${SSL_KEY_PATH} ]] && [[ -z ${SSL_CERT_PATH} ]]; then
	_dms_panic__no_env 'SSL_KEY_PATH or SSL_CERT_PATH' "${SCOPE_SSL_TYPE}"
	fi
	if [[ -n ${SSL_ALT_KEY_PATH} ]] \
	&& [[ -n ${SSL_ALT_CERT_PATH} ]] \
	&& [[ ! -f ${SSL_ALT_KEY_PATH} ]] \
	&& [[ ! -f ${SSL_ALT_CERT_PATH} ]]
	then
	_dms_panic__no_file "(ALT) ${SSL_ALT_KEY_PATH} or ${SSL_ALT_CERT_PATH}" "${SCOPE_SSL_TYPE}"
	fi
	if [[ -f ${SSL_KEY_PATH} ]] && [[ -f ${SSL_CERT_PATH} ]]; then
	cp "${SSL_KEY_PATH}" "${PRIVATE_KEY}"
	cp "${SSL_CERT_PATH}" "${CERT_CHAIN}"
	chmod 600 "${PRIVATE_KEY}"
	chmod 644 "${CERT_CHAIN}"
	_set_certificate "${PRIVATE_KEY}" "${CERT_CHAIN}"
	# Support for a fallback certificate, useful for hybrid/dual ECDSA + RSA certs
	if [[ -n ${SSL_ALT_KEY_PATH} ]] && [[ -n ${SSL_ALT_CERT_PATH} ]]; then
	_log 'trace' "Configuring fallback certificates using key ${SSL_ALT_KEY_PATH} and cert ${SSL_ALT_CERT_PATH}"
	_set_alt_certificate "${SSL_ALT_KEY_PATH}" "${SSL_ALT_CERT_PATH}"
	else
	# If the Dovecot settings for alt cert has been enabled (doesn't start with `#`),
	# but required ENV var is missing, reset to disabled state:
	sed -i -r \
	-e 's|^(ssl_alt_key =).*|#\1 </path/to/alternative/key.pem|' \
	-e 's|^(ssl_alt_cert =).*|#\1 </path/to/alternative/cert.pem|' \
	"${DOVECOT_CONFIG_SSL}"
	fi
	_log 'trace' "SSL configured with 'Manual' certificates"
	else
	_dms_panic__no_file "${SSL_KEY_PATH} or ${SSL_CERT_PATH}" "${SCOPE_SSL_TYPE}"
	fi
	;;

---

So the question is... why the 2 options?

We have more than 2 options for this setting, they're just more niche.

As explained above, it's mostly due to how the project evolved.

FWIW: A little over 2 years ago I outlined a way forward to refactor this TLS support into something simpler and more implicit. Doing so would broaden compatibility further as well. I've just not had time to tackle that yet (like with most tasks for DMS) as my time on the project is often invested in support, PR reviews, and general maintenance (with revisions to our docs being rather "expensive" for me to do time-wise).

[audioscavenger]

i figured the folder mount is the way to go, thanks for all the technical explanations

[OrchidLuna]

Chipping in because i thought since nginx v1.28 (deployed either on docker or the host, often with custom repo) adds built in acme support, i wonder if i still can use letsencrypt ssl type. I'll test this on my server with nginx' example config with mounting the state_path directory and see what it's structure looks like.

[polarathene]

• letsencrypt is a convenience and relies on a specific structure. With additional support for Traefik acme.json that extracts cert files into that structure.
• manual presently requires additonal ENV for key and cert paths, and you should mount these both under a common folder, rather than direct file mounts if you want updated certs to propagate to DMS change detection reliably I think.

Others like Caddy (and possibly Nginx now) may differ where neither of those options are as reliable. That requires a refactor to provide a directory that a script would search through for cert files and verify the cert is valid and provisioned for the configured DMS FQDN.