SSL certificates

WardPane gets and renews HTTPS certificates from Let’s Encrypt on its own. Once a domain points to the server, the site has a certificate within a minute or two; there is nothing to run by hand and no cron job to set up. The panel at https://<IP>:1500 gets a certificate for the server’s IP address too.

What you need

• An email address for the Let’s Encrypt account. install.sh --email sets it, and you can change it in Settings > Certificates (ACME_EMAIL). Without it no certificates are issued.
• DNS records of the domain and every alias pointing to the server: an A record to its IPv4 address and, if you have AAAA records, every one of them to its IPv6 address. See DNS.
• Ports 80 and 443 open to the internet, including in your VPS provider’s own firewall.

How it works

Each site has one certificate for the main domain and all its aliases, up to 100 names in total. Renewal starts when a third of the lifetime is left, so a 90-day certificate is renewed about 30 days before it expires.

Before ordering, the panel checks DNS. A name that does not point to the server yet is skipped and gets added to the certificate later, once its record is fixed. The SSL tab of the site lists the missing names with the reason for each.

AAAA records are checked as well. Let’s Encrypt tries IPv6 first and may pick any AAAA record of a name, so every one of them must point to this server: to PUBLIC_IPV6, or to one of the server’s global IPv6 addresses. If one points elsewhere, the name is left out, and the panel shows the reason along with the current value of PUBLIC_IPV6.

When Let’s Encrypt cannot validate some aliases, the certificate is issued straight away without them, and they are tried again later. The panel reports all failed names of an order in a single message. The main domain cannot be dropped this way: if it fails, there is no certificate.

If the names left after this are exactly the ones the current certificate already has, nothing new is ordered, because Let’s Encrypt allows only 5 duplicate certificates per week. After an error the panel waits longer before each new attempt and writes every step to the panel log.

Broken certificate files

If the certificate files of a site are damaged or cannot be read, the panel serves a self-signed certificate and orders a new one. It does this at most once a day, since a disk that keeps failing will break new files too.

Certificates are stored in /var/lib/wardpane/certs/<id>/bundle.pem. The key and the chain share one file, so after a power failure they cannot end up from different orders.

The ACME account

If Let’s Encrypt reports that the ACME account is deactivated, the panel creates a new account key and keeps the old one next to it as account-*.key.old. On any other refusal the key is not changed.

Staging

For tests you can use the Let’s Encrypt staging environment: ACME_STAGING=true in Settings > Certificates or install.sh --staging. Staging certificates are not trusted by browsers. When you switch back to production, staging certificates are replaced automatically. The setting applies after the panel restarts.

The certificate for the server IP

The server’s IP address gets its own certificate from Let’s Encrypt with the shortlived profile: it is valid for about 6 days and renewed about every 4 days. The panel uses it on port 1500, and it is also served for https://<IP>. Right after installation, until it is issued, the browser may warn about a self-signed certificate.

You can turn it off with IP_CERT in Settings > Certificates (applies after restart). PUBLIC_IP and PUBLIC_IPV6 are detected automatically and can be set there if the detection is wrong.

The SSL tab of a site

Open a site and go to SSL. The Certificate card shows the state of the certificate (names, expiry, missing names and why) and has these controls:

• Check DNS checks what the names of the site point to, without ordering anything.
• Issue SSL orders a certificate now instead of waiting for the next automatic run.
• Auto SSL issues and renews the certificate automatically. On by default.
• Redirect HTTP to HTTPS sends visitors who open http:// to the secure address. On by default.

While a certificate is being issued, the page refreshes every 3 seconds.

The SSL certificates section

Version 2.4 is planned to add an SSL certificates section with the certificates of all sites on one page, including self-signed ones, your own certificates and CSRs; see the roadmap. In 2.0 each site’s certificate is on its SSL tab, and the dashboard counts the sites with certificate problems. Warnings about certificates that expire soon, with a button to fix them, arrive with the health checks in 2.3.

Sites behind Cloudflare

Certificates are issued even when the DNS of a site points to Cloudflare. Turn on Behind Cloudflare on the SSL tab. For the very first certificate, set the SSL/TLS mode in Cloudflare to Full or Flexible; switch to Full (strict) once the certificate is issued. With a Cloudflare API token the panel can also check the zone and create the rule that keeps the ACME challenge path out of Cloudflare’s checks, including “I’m Under Attack” mode. See Cloudflare.

Typical errors

The panel log (Activity in the menu) shows every order, every failed name and the answer from Let’s Encrypt. From the server:

journalctl -u wardpane -f