GoAdmio

mailssl

Get a free Let's Encrypt certificate for the server's mail hostname (SMTP and IMAP), renew it when 7 days or fewer remain, and rebuild the mail maps

On this page: Overview · Quick start · Syntax · Options · Output · Examples · Troubleshooting · Details · See also


Overview

Mail programs such as Outlook and Thunderbird connect to your server over an encrypted connection and check its SSL certificate. /go/mailssl makes sure the server's mail hostname has a valid certificate. It:

The server hostname must be a full name with at least two dots, such as mail.example.com. Otherwise no certificate is requested.

Certificates for your customers' own domains are handled by ssl and checkssl, not by this command.


Quick start

# Install the certificate, or renew it if it is close to expiry
/go/mailssl

# Replace the existing certificate now
/go/mailssl --force

Syntax

/go/mailssl [--force]
Form Behavior
/go/mailssl Requests a certificate only if there is none, or if the existing one has 7 days or fewer left.
/go/mailssl --force Deletes the existing certificate and requests a new one, even if the current one is valid.

Options

Option Required Notes
--force No Reissue the certificate regardless of how long the current one is valid. Let's Encrypt limits how many certificates can be issued for the same names in a week, so don't use it repeatedly.

Any other argument is ignored.


Output

All certificate messages come from this command. The certificate tool itself runs quietly.

Situation Message
Server and IMAP hostname are the same Installing SSL Certificates on SMTP/IMAP Server Hostname <hostname>...
Two different hostnames Installing SSL Certificates on SMTP/IMAP Server Hostname (<hostname> and <imap-hostname>)...
It worked SSL Certificate Installed Successfully for Hostname (<hostname> - 3 Months)... (or (<hostname> and <imap-hostname> - 3 Months))
It failed Error: Can not Install SSL Certificate for Hostname (<hostname>)... (or with both names)
Nothing to do No output.

After an attempt, a line of dashes is printed.

The exit status doesn't show whether the certificate was installed. Read the message instead.


Examples

# Install or renew the mail certificate
/go/mailssl
# Replace the certificate now
/go/mailssl --force
# Check the certificate that was issued
certbot certificates -d "$(cat /etc/hostname)"
# Check that the mail ports present a valid certificate
/go/checkmail

Troubleshooting

Symptom Likely cause Fix
Nothing is printed The certificate exists and has more than 7 days left, or the hostname (or IMAP hostname) has fewer than two dots. Check cat /etc/hostname. Set a full hostname with hostname. Use --force to reissue.
Error: Can not Install SSL Certificate... Let's Encrypt couldn't verify the hostname. Common reasons: the hostname doesn't point to this server, port 80 is blocked, the web server isn't running, or a rate limit was reached. Check DNS and the firewall with checkfirewall. Read /var/log/letsencrypt/letsencrypt.log.
After an error, no Let's Encrypt certificate exists any more The old certificate is deleted before the new one is requested. See Known limitations. Fix the cause, then run /go/mailssl again.
Mail programs warn about an untrusted certificate The server is using the self-signed fallback because the Let's Encrypt certificate is missing. Run /go/mailssl, then checkmail.
[: =: unary operator expected appears at the start The imap. hostname has no DNS record yet. Harmless. Add the DNS record if you want a separate IMAP hostname.
--force fails after a few runs Let's Encrypt's rate limit for the same names. Wait before trying again.
Reissue fails right after the old certificate was removed The hostname (and not the IMAP name) resolves to this server, but the IMAP name doesn't. Fix the DNS record of the IMAP hostname, or remove /etc/imap.

Details

Which hostnames are covered

Item How it is chosen
Server hostname The contents of /etc/hostname.
IMAP hostname The contents of /etc/imap if that file exists, otherwise the server hostname.
/etc/imap is written automatically If the hostname starts with smtp., the command changes it to imap.. When the DNS record of that imap. name points to this server, it is saved in /etc/imap. Otherwise the server hostname is saved.

If the two names are different, one certificate is issued for both, with the server hostname as the certificate name.

How it works

flowchart TD
    A["mailssl [--force]"] --> B["Find IMAP hostname"]
    B --> C["Create self-signed fallback certificate"]
    C --> D{"Let's Encrypt certificate exists?"}
    D -- "Yes" --> E{"7 days or fewer left?"}
    E -- "Yes" --> F["Delete it"]
    E -- "No" --> G{"--force?"}
    D -- "No" --> H
    F --> H{"Hostnames have 2+ dots?"}
    G -- "Yes" --> H
    G -- "No" --> L
    H -- "No" --> L
    H -- "Yes" --> I["Request certificate with certbot"]
    I --> J{"Issued?"}
    J -- "Yes" --> K["Print success, run go and reload"]
    J -- "No" --> M["Print error"]
    K --> L{"Any hosted accounts?"}
    M --> L
    L -- "Yes" --> N["Run vmail"]
    L -- "No" --> O["Done"]
  1. Logs the call to /var/log/go/mailssl.log.
  2. Reads the web server type, finds this server's public IP, reads the hostname, and counts the hosted accounts.
  3. If the hostname starts with smtp., decides whether imap.<name> points to this server and writes /etc/imap.
  4. Works out the IMAP hostname and counts the dots in both names.
  5. Creates the self-signed fallback certificate in /etc/postfix/ssl.
  6. Chooses the certbot plugin: --nginx on Nginx servers, --apache otherwise.
  7. If a Let's Encrypt certificate for the hostname exists and has 7 days or fewer left, removes /etc/letsencrypt/live/<hostname> (and the IMAP hostname's folder), then runs /go/go.
  8. If the certificate is missing (or --force was given), and both names have at least two dots: deletes any old certificate with that name, requests a new one, and checks that it was issued.
  9. On success, runs /go/go and reload.
  10. If the server hosts any accounts, runs vmail.

Files used

File Purpose
/etc/hostname The server hostname.
/etc/imap The IMAP hostname, if different. Written by this command for smtp. hostnames.
/etc/letsencrypt/live/<hostname>/ The Let's Encrypt certificate.
/etc/postfix/ssl/smtpd.key, smtpd.csr, smtpd.crt The self-signed fallback key, request, and certificate, valid for 365 days.
/etc/postfix/ssl/cakey.pem, cacert.pem A self-signed certificate authority key and certificate, valid for 365 days.
/usr/local/goadmio/linux/ws.db The web server type (Nginx or Apache).
/var/log/go/mailssl.log A log of each call.

The Let's Encrypt registration email is info@<hostname>. Expiry notices go there.

Requirements

Known limitations


See also

Command Description
checkmail Test whether outbound mail port 25 works, and whether the SMTP (465) and IMAP (993) SSL certificates are installed
checkimap Check the IMAP hostname, its DNS record, and the SSL certificate on port 993, and repair the mail SSL setup
doveconf Rebuild the Dovecot configuration, including SSL certificates for the hostname and each domain
vmail Rebuild the Postfix/Dovecot vmail maps
installmail Install and configure webmail services (Postfix and Dovecot)
hostname Change the server hostname and set up GoAdmio, mail, and SSL for it
ssl Install an SSL certificate for a domain in GoAdmio
checkssl Audit SSL certificates for all hosted domains, renew those close to expiry, and send expiry alerts