Change Detection service and SSL

[fawzibr]

I saw this in the SSL configuration page:

Importing Certificates Obtained via Another Source

If you have another source for SSL/TLS certificates you can import them into the server via an external script. The external script can be found here: .

This is a community contributed script, and in most cases you will have better support via our Change Detection service (automatic for SSL_TYPE of manual and letsencrypt) - Unless you're using LDAP which disables the service.

Looked around and didn't find anything about this 'Change Detection Service'. What does it do? How does it work? If I have the config:

volumes:
  - ./ssl/:/tmp/ssl/:ro
environment:
  - SSL_TYPE=manual
  - SSL_CERT_PATH=/tmp/ssl/my_company.crt
  - SSL_KEY_PATH=/tmp/ssl/my_company.key

Does it monitors the if the certificates file date changes and reloads? Do I have to place it in a specific location? Use a specific volume?

[casperklein]

Does it monitors the if the certificates file date changes and reloads?

Almost. The file content is monitored.

These are the involved scripts:

• https://github.com/docker-mailserver/docker-mailserver/blob/master/target/scripts/check-for-changes.sh
• https://github.com/docker-mailserver/docker-mailserver/blob/master/target/scripts/helpers/change-detection.sh

[polarathene]

You can view the links to relevant files provided in the other answer for more insights, but this feature works in the background without any need to configure anything differently.

Looked around and didn't find anything about this 'Change Detection Service'. What does it do? How does it work?

Unfortunately nobody has taken the time to document it officially in our docs.

It monitors some of our supported config files, but not all. It's also used behind the scenes with setup ... commands when you add aliases or accounts, updating configuration and reloading/restarting services in the container to apply that update.

Another feature is the certificates, which is handled in the same way. It should monitor your certificates from a supported location (letsencrypt and manual modes only I think), and when certificates are updated there it'll make sure they're used.

However, this feature presently isn't supported in DMS when LDAP is used. It needs some changes to at least allow for certificate update support, but again nobody has contributed that yet.

[fawzibr]

From what I understand by looking at the scripts:

1. When it starts takes a checksum of the files it monitors saves it to /tmp/docker-mailserver-config-chksum
2. Every once in a while (daily?) Calculates the checksum saves it to /tmp/docker-mailserver-config-chksum.new
3. Compare files reload what's changed

So all I have to do is drop a new certificate and key file replacing the old ones in the same place and thats it? Just want to be sure.

[polarathene]

So all I have to do is drop a new certificate and key file replacing the old ones in the same place and thats it?

Yeah that should work.

docker-mailserver/target/scripts/check-for-changes.sh

Lines 143 to 156 in ee7c4b1

	# _setup_ssl is required for:
	# manual - copy to internal DMS_TLS_PATH (/etc/dms/tls) that Postfix and Dovecot are configured to use.
	# acme.json - presently uses /etc/letsencrypt/live/<FQDN> instead of DMS_TLS_PATH,
	# path may change requiring Postfix/Dovecot config update.
	if [[ ${SSL_TYPE} == 'manual' ]]; then
	# only run the SSL setup again if certificates have really changed.
	if [[ ${CHANGED} =~ ${SSL_CERT_PATH:-${REGEX_NEVER_MATCH}} ]] \
	|| [[ ${CHANGED} =~ ${SSL_KEY_PATH:-${REGEX_NEVER_MATCH}} ]] \
	|| [[ ${CHANGED} =~ ${SSL_ALT_CERT_PATH:-${REGEX_NEVER_MATCH}} ]] \
	|| [[ ${CHANGED} =~ ${SSL_ALT_KEY_PATH:-${REGEX_NEVER_MATCH}} ]]
	then
	_log_with_date 'debug' 'Manual certificates have changed - extracting certificates'
	_setup_ssl
	fi

We copy from the location you provided for SSL_TYPE=manual certs, then restart Postfix and Dovecot to use the new versions. The function call is to the same used when starting the container.

SSL_TYPE=letsencrypt uses the same source location (no internal location to copy to), it just gets detected and reloads, unless acme.json (Traefik) is used then we extract the new certs first.

A future major release may refactor all this if I ever get around to it. So just pay attention to release notes for major versions before updating.

---

2. Every once in a while (daily?)

Every 2 seconds:

docker-mailserver/target/scripts/check-for-changes.sh

Lines 177 to 180 in ee7c4b1

	while true; do
	_check_for_changes
	sleep 2
	done

I'd prefer using better technique than polling, but I just don't haven't found the time to contribute the improvement, nor has anyone else 😅