Obsidian SuiteDocumentation
Obsidian Mail Server: all chapters

Docs / Obsidian Mail Server / Start here

Certificates

Every connection to the server is encrypted: webmail, phones, Macs, IMAP, and mail between servers. For apps to trust the connection, the server needs a certificate for its name from a certificate authority.

On first start the server makes a self-signed certificate for mail.example.com. It encrypts, but no app trusts it: browsers warn, iPhones ask the user to accept it, and some apps refuse outright. Replace it before people start using the server. The certificate box at the bottom of the sidebar shows which certificate is in use and when it expires.

Which names the certificate needs

  • mail.example.com: the server's own name. Always required.
  • autodiscover.<domain> for each of your email domains, for example autodiscover.example.com. iPhones, Macs and Outlook look up the server at that name when someone adds an account, and check the certificate for it.

Let's Encrypt

Let's Encrypt certificates are free and renew automatically every 60 to 90 days. The server answers Let's Encrypt's check on port 80 by itself, so nothing has to stop while a certificate is issued or renewed.

Before you start: the DNS names above must already point at this server, and port 80 must reach it from the internet (see DNS and Installing).

1. Install certbot and request the certificate. Sign in to the server (console or SSH) and run, listing every name the certificate needs:

sudo apt install certbot
sudo certbot certonly --webroot -w /var/lib/obsidian-mailserver/acme -d mail.example.com -d autodiscover.example.com

2. Let the mail server read it. Certbot keeps its files readable only by root. This hook copies them to the mail server's folder now and after every renewal:

sudo install -d -m 750 -o root -g omsd /etc/obsidian-mailserver/tls
sudo tee /etc/letsencrypt/renewal-hooks/deploy/obsidian-mailserver > /dev/null << 'EOF'
#!/bin/sh
set -e
install -m 640 -o root -g omsd "$RENEWED_LINEAGE/privkey.pem" /etc/obsidian-mailserver/tls/privkey.pem
install -m 640 -o root -g omsd "$RENEWED_LINEAGE/fullchain.pem" /etc/obsidian-mailserver/tls/fullchain.pem
EOF
sudo chmod 755 /etc/letsencrypt/renewal-hooks/deploy/obsidian-mailserver
sudo RENEWED_LINEAGE=/etc/letsencrypt/live/mail.example.com /etc/letsencrypt/renewal-hooks/deploy/obsidian-mailserver

3. Point the server at it. Open the configuration file:

sudo nano /etc/obsidian-mailserver/appsettings.json

and add a Tls section inside "Oms" (mind the commas between sections):

"Tls": {
  "CertificatePath": "/etc/obsidian-mailserver/tls/fullchain.pem",
  "KeyPath": "/etc/obsidian-mailserver/tls/privkey.pem"
}

4. Restart once.

sudo systemctl restart obsidian-mailserver

Reload this admin center: the certificate box in the sidebar should show the new issuer. From now on certbot renews by itself and the server picks up each renewed certificate without a restart.

If a domain is added later, request the certificate again with its autodiscover name added (step 1 with one more -d); the hook and settings stay the same.

A certificate you already have

Any certificate from a public authority works, including wildcard certificates (*.example.com covers mail.example.com when it is in example.com, but not autodiscover. names of other domains).

  • PEM files (fullchain.pem + privkey.pem, or .crt + .key): copy them to /etc/obsidian-mailserver/tls/, make them readable by the server with sudo chown root:omsd <files> and sudo chmod 640 <files>, and set CertificatePath (the certificate followed by its intermediate certificates) and KeyPath as in step 3 above.
  • A PFX / PKCS#12 file: set CertificatePath to the .pfx file and add "PfxPassword": "...".

Restart once after changing the settings. Later replacements of the same file are picked up automatically: copy the new key first, then the new certificate.

Certificates behind a proxy or gateway

If a reverse proxy or load balancer in front of the server handles HTTPS, it needs the certificate too, and the server's own certificate only matters for the connection between the two. Mail ports (25, 465, 587, 993, 995) are always encrypted by the server itself, so it still needs a certificate its clients trust.