[Solution] Per-Domain Mail SSL/TLS SNI for Dovecot & Postfix on ISPConfig 3.x

Hi everyone,

I've been running ISPConfig 3.3.0p3 with 38 mail domains on a single server and ran into the well-known issue where all mail clients receive the same SSL certificate regardless of which domain they connect to. If a client connects to mail.example.com but the server certificate is for mail.server.com, users see SSL hostname mismatch warnings.

This is tracked in the ISPConfig GitLab as:
- #3794 — Dovecot SNI support
- #6074 — Postfix 3.4 TLS SNI Mapping
- #6075 — Dovecot local_name for individual SSL certificates

Since ISPConfig doesn't natively support this yet, I've built a solution that works alongside ISPConfig using its own database and Let's Encrypt certificates. I've published it on GitHub for the community:

https://github.com/bosspacific/ispconfig-mail-sni

**How it works:**

1. You create a "mail.<domain>" website in ISPConfig for each mail domain with SSL + Let's Encrypt enabled. ISPConfig handles the certificate issuance and renewal as normal.

2. The script reads active mail domains from ISPConfig's MySQL database, finds the matching Let's Encrypt certificates, and generates:
- Dovecot local_name SNI blocks (so each domain gets its own cert on IMAP/POP3)
- Postfix tls_server_sni_maps entries (so each domain gets its own cert on SMTP)

3. A systemd timer runs daily to pick up new domains, and a path watcher triggers on certificate renewals.

**What's included:**

- **update-mail-sni.sh** — Main script with --check, --status, --dry-run options
- **create-mail-sites.sh** — Bulk creation of mail.<domain> sites via ISPConfig's JSON API (useful if you have many domains)
- **install.sh** — One-command installer with uninstall option
- **systemd units** — Timer, service, and path watcher for automation

**Requirements:**

- ISPConfig 3.x (tested on 3.3.0p3)
- Dovecot 2.3+ (for local_name SNI support)
- Postfix 3.4+ (for tls_server_sni_maps support)
- DNS A records for mail.<domain> pointing to the server

**Key design decisions:**

- Works WITH ISPConfig, not around it. Uses ISPConfig's database and certificate paths.
- Idempotent — only restarts services when configuration actually changes.
- The Dovecot SNI config is loaded via ISPConfig's own custom config include (99-ispconfig-custom-config.conf), so ISPConfig updates won't break it.
- The bulk site creation tool uses ISPConfig's JSON API properly, so all sites are created with correct permissions, vhosts, and directory structures.

**Quick start for a single domain:**

1. Create website "mail.example.com" in ISPConfig → Sites, with SSL + Let's Encrypt
2. Ensure DNS: mail.example.com → your server IP
3. Clone and install:
git clone https://github.com/bosspacific/ispconfig-mail-sni.git
cd ispconfig-mail-sni
sudo ./install.sh

**Quick start for many domains:**

1. Create a Remote API user in ISPConfig (System → Remote Users, tick "Sites Domain functions")
2. Run: ./create-mail-sites.sh --api-user <user> --api-pass <pass>
3. Wait for ISPConfig to issue all certificates
4. Run: sudo ./install.sh
5. Delete the Remote API user

I've been running this in production with 38 domains and all IMAP and SMTP connections now receive the correct per-domain certificate. No more SSL warnings for any mail client.

Hope this helps others facing the same issue. Feedback and contributions welcome on GitHub.

Tested on: Debian 12 (Bookworm), ISPConfig 3.3.0p3, Dovecot 2.3.19.1, Postfix 3.7

=== GitLab Issues #3794, #6074, #6075 ===

https://git.ispconfig.org/ispconfig/ispconfig3/-/issues/3794
https://git.ispconfig.org/ispconfig/ispconfig3/-/issues/6074
https://git.ispconfig.org/ispconfig/ispconfig3/-/issues/6075 (closed)

Cheers,
Haluk
BOSS Pacific

 

i assume you're running a single ispconfig server, or at least, multi-server with postfix and webserver on the same server.
that, or you're running a central, dedicated email server and are also creating the sites like mail.example.com on that email server.

not looked at the actual scripts yet, but i'm assuning that as is, it wouldn't work on systems where the admin is keeping websites and email completely separated and will not run mailservers with ports 80/443 open.

an alternative is to create mail.example.com as an alias to the website (www.)example.com, which also helps keep the number of unnecessary vhosts down.. and have the certificates inserted into the database, and allow the mailserver access to that database.
this would allow the cert details to traverse servers ( or network file sync / shared filesystem are alternative options)

also should be minimal work to create a similar script to configure SNI for pure-ftpd.

 

Very interesting.
Not quite sutable for me but it could be a great startingpoint for something similar I wanted to create for some time but didn't get around to yet.

I've been running that for ages. It's somewhere here on the forum.

 

Thanks for the thoughtful feedback!

You're correct — this was built for a single-server ISPConfig setup (web + mail + DNS on the same box), which is a common deployment for small-to-medium hosting. All 38 domains run on one server, so the mail.<domain> websites and Let's Encrypt validation happen locally.

You raise a valid point about multi-server setups where mail and web are separated. A few thoughts:

1. For separated mail servers without ports 80/443, DNS-01 validation would be the way to go instead of HTTP-01. The script could be extended to support acme.sh DNS API plugins — the cert issuance happens elsewhere, but the SNI configuration logic (Dovecot local_name + Postfix tls_server_sni_maps) would still apply.

2. Your suggestion of creating mail.<domain> as an alias/subdomain of the main website is a cleaner approach for keeping vhost count down. In my case I went with separate sites because ISPConfig issues individual Let's Encrypt certs per site, and I wanted each mail.<domain> cert to be independently managed. But the alias approach would work well if you're using a wildcard or SAN cert.

3. Storing certs in the database for cross-server access is interesting — essentially what ISPConfig would need to do natively to support this in a multi-server setup. Shared filesystem (NFS/GlusterFS) for the cert directory would be simpler to implement as an interim solution.

4. Good call on pure-ftpd SNI — the same pattern would work. Read domains from the database, map to certs, generate the pure-ftpd TLS config. Happy to add that if there's interest.

The script is intentionally simple and focused on the single-server use case since that's what most ISPConfig admins asking about this in the GitLab issues seem to be running. But PRs for multi-server support would be welcome.

Cheers,
Haluk