GoAdmio

ssl

Issue a Let's Encrypt SSL certificate for one domain, for every domain that has none, or for a subdomain, rebuild the web server configuration, and report likely DNS problems when it fails

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


Overview

/go/ssl gets a free HTTPS certificate from Let's Encrypt for a hosted site using certbot, then rebuilds the site's web server configuration so the certificate is used. Other GoAdmio commands call it for you: create schedules it for each new account, and renew runs it every time.

It works in four modes:

Mode What it does
/go/ssl <domain> Re-issues the certificate for one hosted domain, or issues one for a subdomain.
/go/ssl all Issues certificates for every hosted domain that doesn't have one yet.
/go/ssl bulk Rebuilds the web configuration for all domains with Cloudflare's proxy turned off.
/go/ssl stop Stops any running certbot and clears its lock.

By default a certificate covers the domain and www., go., webmail., smtp., and imap. in front of it. If that fails, the command falls back to smaller sets of names and tells you what the certificate doesn't cover. When it fails altogether, it checks DNS and tells you what points to the wrong place.

[!WARNING] /go/ssl <domain> deletes the domain's current certificate before it requests the new one. If the new request fails, the site is left without HTTPS until a later run succeeds. For a domain with a paid certificate, the Nginx configuration may also be removed and not rebuilt (see Troubleshooting).


Quick start

# Issue or re-issue the certificate for one domain
/go/ssl example.com

# Issue certificates for every domain that has none
/go/ssl all

Syntax

/go/ssl <domain> [options]
/go/ssl all [options]
/go/ssl bulk
/go/ssl stop

The domain, all, bulk, or stop must be the first argument. The options are found anywhere in the command line. The command re-runs itself with sudo when it isn't run as root.

Form Behavior
/go/ssl <domain> If /home/<domain>/www exists, replaces the certificate for that account. Otherwise, if the name is a registered subdomain, issues a certificate for it.
/go/ssl all Goes through every account in /home and requests a certificate where none exists.
/go/ssl bulk or /go/ssl --bulk Turns the Cloudflare proxy off for all domains, rebuilds the web configuration three times, then turns the proxy back on. Exits with status 1.
/go/ssl stop or /go/ssl kill Kills certbot and removes its lock file. Exits with status 1.

Options

Option Applies to Effect
--www One domain, all Names: the domain and www. only.
--limit One domain Same as --www. Used by bulk.
--go One domain, all Names: the domain, www., and go..
--webmail One domain, all Names: the domain, www., and webmail..
--force all Also processes domains that already have a certificate.
--create ssl all When a domain fails, creates the file /home/<domain>/www/ssl, so later all runs skip it.
--zerossl One domain, all Uses ZeroSSL's ACME server instead of Let's Encrypt.
--standalone or --quick One domain, all Uses certbot's own temporary web server, which needs port 80 to be free.
--skipbackupssl Any Skips the daily SSL backup at the end.
--progress One domain Also prints 100 on success and 1 on a failure, for GoAdmio's progress display.

If more than one of --www, --go, and --webmail is given, --www wins, then --go.

Which names are in the certificate

Situation Names
Main domain, no name option The domain, www., go., webmail., smtp., imap.
--www or --limit The domain and www.
--go The domain, www., go.
--webmail The domain, www., webmail.
A subdomain The subdomain only
Alias domains of the account <alias> and www.<alias>, only if their DNS points to this server

A name counts as a main domain when it has one dot, or when it is a known two-part domain such as example.co.uk, or when it has its own zone in your Cloudflare account. Anything else is treated as a subdomain.


Output

Outcome What you get
Success (one domain) SSL Certificate Installed Successfully (<domain> - <N> Months)...
Success (all) [<n>/<total>] SSL Certificate Installed Successfully (<domain> - <N> Months)
Fewer names than usual NOTICE: This certificate will NOT cover (webmail, go, smtp, imap) or NOTICE: This certificate will ONLY cover (webmail.<domain>)
Failure Error: Can not Install SSL Certificate (<domain>)... followed by DNS hints
DNS hint Domain <name> Points To <ip> (Expected <server ip>), or Domain <name> Does Not Resolve
Missing Cloudflare record CNAME Record <name> does not exist, for www, webmail, go, smtp, and imap
Paid certificate present Paid SSL Certificate already installed. and how to delete it with openssl
all skips a domain SKIPPING: SSL certificate installation for <domain> and how to remove the ssl file
Not a hosted domain Domain <name> does not exist...
Daily backup Backup SSL...

Notes on the output:


Examples

# One domain
/go/ssl example.com
# One domain, only the domain and www
/go/ssl example.com --www
# Every domain without a certificate, and mark the ones that fail so they're skipped next time
/go/ssl all --create ssl
# Re-issue every certificate, without the daily backup
/go/ssl all --force --skipbackupssl
# Let a skipped domain be tried again
rm -f /home/example.com/www/ssl
/go/ssl example.com
# Check what certbot has
certbot certificates -d example.com
# Stop a stuck certificate request
/go/ssl stop

Troubleshooting

Symptom Likely cause Fix
Domain <domain> Points To <ip> (Expected <server ip>) The domain's A record doesn't point to this server yet, or points to Cloudflare's proxy. Fix the DNS record. If the Cloudflare proxy is on, see proxy or use /go/ssl bulk.
Domain www.<domain> Points To ... or webmail.<domain> Does Not Resolve The record for that name is missing. Add a record. With Cloudflare, use cname.
CNAME Record <name> does not exist There is no CNAME for that name in the Cloudflare zone. Add it with cname.
NOTICE: This certificate will NOT cover ... The full set of names failed, so a smaller one was used. Fix the DNS for the missing names, then run /go/ssl <domain> again. Mail programs that use smtp. or imap. will show certificate warnings until then.
SKIPPING: ... File "ssl" exists --create ssl or someone created /home/<domain>/www/ssl. Remove the file and run again (see Examples).
Paid SSL Certificate already installed. A certificate from openssl is installed. Remove it with /go/openssl <domain> delete if you want Let's Encrypt.
The site has no HTTPS after a failed run The old certificate was deleted first. Fix the cause (see the DNS hints, and /var/log/letsencrypt/letsencrypt.log), then run the command again. Certificates can also be restored with restore from the daily SSL backup.
An Nginx site's configuration is missing after /go/ssl <domain> for a domain with a paid certificate The command removes the Nginx virtual host before it checks for a paid certificate, and then exits. Run conf for that domain.
A subdomain certificate was issued but isn't used The subdomain path doesn't reload the web server itself. Run reload.
Many failed attempts, then repeated failures Each failing domain makes up to four certbot requests, and Let's Encrypt limits failed validations and repeated identical certificates. Fix DNS first. Wait before trying again, and use --create ssl with all.
certbot seems stuck or says another instance is running A previous request is still running. Run /go/ssl stop, then try again.
--standalone fails Port 80 is in use by the web server. Don't use --standalone, or free the port.
--zerossl fails ZeroSSL's ACME service needs account credentials that this command doesn't pass. Use zerossl.
The "Expected" address is wrong The server IP is read from checkip.amazonaws.com, which can differ behind NAT or on servers with several IPs. Compare with the IP in your DNS manually.
Sites were unproxied after bulk bulk was interrupted before it turned Cloudflare's proxy back on. Run /go/proxy all on.

Details

What happens for /go/ssl <domain>

flowchart TD
    A["ssl domain"] --> B{"/home/domain/www exists?"}
    B -- "No" --> S{"Registered subdomain?"}
    S -- "Yes" --> S1["certbot for the subdomain, then apache-subdomain and nginx-subdomain"]
    S -- "No" --> S2["Print: Domain does not exist"]
    B -- "Yes" --> C["Delete the live and archive certificate files and the SSL virtual hosts"]
    C --> D{"Paid certificate in /etc/ssl?"}
    D -- "Yes" --> X["Print message, exit 1"]
    D -- "No" --> E["Work out the names, add alias domains"]
    E --> F["certbot delete, then certbot certonly"]
    F --> G{"Certificate valid?"}
    G -- "No" --> H["Retry, then domain and www only, then webmail only"]
    G -- "Yes" --> I["Save SSLExpiresOn and SSLDaysLeft in the Site table"]
    H --> I
    I --> J["Rebuild the Apache and Nginx configuration, reload"]
    S1 --> K
    S2 --> K
    J --> K["Daily SSL backup"]

The fallback order

If the first request doesn't produce a valid certificate, the command tries these in turn, stopping at the first one that works:

Attempt Names
1 The full set from Which names are in the certificate
2 The same set again, after deleting any partial certificate
3 The domain and www. only
4 webmail.<domain> only

After a success, the saved expiry date comes from certbot, and the days left are recorded as 89, whatever the real number is.

How all differs

What bulk does

/go/proxy all off
/go/conf --force --skip mailssl
/go/conf --skip mailssl
/go/conf --limit --skip mailssl
/go/proxy all on

It turns Cloudflare's proxy off for all domains while certificates are requested, then on again. Mail server certificates are skipped (see mailssl). Sites are not proxied while it runs.

The daily SSL backup

Unless --skipbackupssl is given, the command ends with /go/backup ssl, at most once every 24 hours. The lock file is /usr/local/goadmio/lock/backup-ssl.lock. The bulk, stop, and paid-certificate exits don't reach this step.

Files and services

Item Purpose
/usr/bin/certbot Requests and removes certificates. It must be installed (see installssl).
/etc/letsencrypt/live/<domain>, /etc/letsencrypt/archive/<domain> The certificate files. Deleted before a re-issue in one-domain mode.
/home/<domain>/www/ssl A marker file. If it exists, all skips the domain.
/etc/ssl/<domain>/cert.pem A paid certificate. If it exists, no Let's Encrypt certificate is requested.
Site table in /var/lib/sqlite/site.db SSLExpiresOn and SSLDaysLeft are updated after each success.
Cloudflare API Used with the saved account ID and API token to find the zone and the CNAME records.

See also

Command Description
checkssl Audit SSL certificates for all hosted domains, renew those close to expiry, and send expiry alerts
installssl Install Let's Encrypt SSL on GoAdmio
zerossl Install a ZeroSSL certificate via the command line
openssl Generate, install, or delete a paid SSL certificate
mailssl Install SSL certificates for SMTP and IMAP
conf Rebuild Apache/Nginx virtual hosts, PHP-FPM pools, and SSL for all accounts
proxy Change Cloudflare's proxy setting
cname Add a CNAME record to a domain's DNS zone on Cloudflare
renew Update the hosting expiry date in GoAdmio
backup Back up one or all GoAdmio accounts