Update Caddy docs

[mholt]

Someone in our community noted that the Caddy docs on Stalwart's website were a bit old or unclear/inaccurate.

I am not a Stalwart user but wanted to check if Stalwart does in fact use HTTP? The suggested Caddyfiles proxy HTTP, not raw TCP.

Also, Caddy does support the PROXY protocol as of a while ago: https://caddyserver.com/docs/caddyfile/directives/reverse_proxy#proxy_protocol

For proxying TCP, there's a layer 4 plugin that does this: https://github.com/mholt/caddy-l4

And instead of copying certs with a cron job, Caddy has an eventing system that can be utilized more appropriately. For example: https://github.com/mholt/caddy-events-exec (formal documentation is still forthcoming so it's understandable that this was missed; it's also new).

[mdecimus]

Hi,

Thank you for pointing this out.

Yes, Stalwart uses HTTP for multiple purposes (JMAP, REST API, ACME, MTA-STS, etc) in addition to the traditional email protocols.

The Caddy configuration file in our documentation was a user contribution and I haven't personally tested it. I assumed that the proxy protocol was not supported by Caddy because multiple Stalwart users reported having problems configuring/using the L4 plugin (they couldn't find examples on the Caddy website I believe) and, in addition to this, there were some (probably old?) posts around the internet mentioning that Caddy did not support the proxy protocol.

I will ask around in our Discord community to see if any of our users has the L4 plugin working with Stalwart and can contribute their Caddy configuration file to the Stalwart docs.

Thanks.

[MarcA711]

Hey,
I am currently trying to configure caddy for stalwart. Once I get it up and running I can gladly share my configuration. However, I have two questions and hope that someone can help me:

1. If Caddy handles the secure (encrypted) connections to the client, can Caddy establish insecure (unencrypted) connections to stalwart? For example, the client connects to caddy via https (443) or imaps (993), can caddy then connect unencrypted via http (8080) or imap (143) to stalwart or should an encrypted connection still be established here to avoid security vulnerabilities?
2. If caddy handles all outgoing connections, does stalwart need access to the certificate of mail.example.com? Or can stalwart use a self-signed certificate for encrypted connections to caddy/ no certificate at all if caddy only connects unencrypted?

[mholt]

should an encrypted connection still be established here to avoid security vulnerabilities?

Reverse-proxying to plaintext endpoints is totally normal and acceptable if the network is trusted; i.e. the loopback interface or a private network that you trust/control. A common use case is to terminate TLS for backend apps.

Or can stalwart use a self-signed certificate for encrypted connections to caddy/ no certificate at all if caddy only connects unencrypted?

I can't answer about Stalwart, but Caddy can be configured to accept self-signed certificates to backends. However, again, if the internal network is trusted/private, no cert may be required at all.

[MarcA711]

Thank you really much for answering my questions @mholt!

Then the only remaining question is whether stalwart needs access to the certificate for mail.example.com for another reason than handling TLS. I hope @mdecimus or another stalwart expert can help me here.

[mdecimus]

does stalwart need access to the certificate of mail.example.com?

Yes, the TLS certificates are needed for plain-text connections that are upgraded to TLS with the STARTTLS SMTP or IMAP command.

[MarcA711]

@mdecimus Thank you for you answer. I am working on it and will share my config once everything is running.

However, one other thing that I noticed: The docs for setting up traefik suggest that you mount the docker sock into the traefik container. This is questionable in terms of security. The docs should mention that this configuration is just an insecure example. Or even better, the configuration could be improved. Traefik can be configured using a config file instead of docker labels, which requires no access to the docker sock. As an alternative, there a docker sockets proxies, for example https://github.com/wollomatic/socket-proxy and https://github.com/Tecnativa/docker-socket-proxy.

If you want, I can open a separate issue for easier issue tracking

[mdecimus]

If you want, I can open a separate issue for easier issue tracking

Sure, thank you. Or if you are planning to submit a patch to the documentation, you can include both updated configurations in the same PR.

[MarcA711]

Hey,

@mdecimus I am no traefik user so I have no idea how to fix or improve the configuration myself. But once I submit a PR for caddy I can add a warning for traefik.

So far I didn't use caddy l4 for handling tcp traffic on other ports. Caddy l4 can't handle STARTTLS (afaik), so stalwart will need access to the certificate in any case. It will also break certain stalwart features. For example, if caddy l4 terminates tls traffic on 993 and proxies it to stalwarts 143, stalwart thinks that imap runs on 143 without implicit tls. This results in wrong configuration in autoconfig/autodiscover and wrong entries in "view dns records".
I think using caddy l4 for stalwart is not useful as long as you don't need loadbalancing. Otherwise it is just additional configuration. Or am I missing any advantage?

Below is my Caddyfile. Any feedback is very welcome. It handles http requests and certificates for stalwart. It will also use the API to reload stalwart after a new certificate was obtained. I am currently very busy myself, but I would like submit a PR and explain the configuration a bit. But it will maybe take a couple of weeks until I can do this.

Caddyfile:

{
	email [email protected]
	admin off
	log {
		output file /data/log/error.log
		level ERROR
	}
	events {
		on cert_obtained exec /bin/sh -c <<RENEW_CERT
			[[ {event.data.identifier} == mail.example.com ]] &&
			cp -rf /data/caddy/{event.data.storage_path} /cert/ &&
			wget --header="Accept: application/json" --header="Authorization: Bearer {$STALWART_API}" -qO- http://stalwart:8081/api/reload/
			RENEW_CERT
	}
}

mail.example.com, autodiscover.example.com, autoconfig.example.com, mta-sts.example.com {
	log {
		output file /data/log/access-stalwart.log
		level INFO
		format json
	}
	tls {
		reuse_private_keys
	}
	reverse_proxy http://stalwart:8080 {
		transport http {
			proxy_protocol v2
		}
	}
}

Stalwart config.toml:

certificate.default.cert = "%{file:/cert/mail.example.com/mail.example.com.crt}%"
certificate.default.default = true
certificate.default.private-key = "%{file:/cert/mail.example.com/mail.example.com.key}%"


server.listener.http.bind = "[::]:8080"
server.listener.http.protocol = "http"
server.listener.http.proxy.override = true
server.listener.http.proxy.trusted-networks.0 = "172.10.0.10/32"

server.listener.api.bind = "[::]:8081"
server.listener.api.protocol = "http"

Additional configuration: Pass an API key as environment variable STALWART_API to caddy. Mount a directory to both stalwart and caddy under /cert. Give caddy a static IP like "172.10.0.10".

[MarcA711]

@mdecimus Sorry to bother you with another question, but is there another way to get an API key with just "Refresh system settings" and "Authenticate" permissions set to yes (everything else set to no)? I went through the whole list and selected "no" for every other permission which was kind of tedious.