Request a certificate from an ACME server#

You will end up with a certificate that the router requests from an ACME server, such as Let's Encrypt, and renews by itself. It is held in the router's certificate store, listed on System → Certificates, and available to the router's services that use certificates, such as OpenVPN.

Before you start#

• The operator role or higher, and a licence: the request is a change that has to be applied.
• A DNS name for each name the certificate is to cover, resolving from the internet to this router.
• Port 80 on this router reachable from the internet, on the address those names resolve to. The ACME server checks each name by connecting to it on port 80.
• An email address for expiry notices.
• The router's clock right: Time synchronisation.

Step 1 — Let port 80 in#

A router with a default-drop firewall does not admit port 80 from the internet, and the check fails without it. On Protect → Firewall, add a rule to the input ruleset, which holds the rules for traffic addressed to the router itself: action accept, protocol tcp, destination port 80, and the internet uplink as the inbound interface. A default-drop ruleset that admits what you meant explains the rulesets.

Apply it before you request the certificate, because the ACME server checks the names as soon as the request is applied. Firewall changes are marked as able to cut you off, so choose Apply with auto-revert on the bar at the bottom of the page, and press Keep changes once the page still responds.

Leave the rule in place afterwards: the router renews the certificate by itself, and every renewal is checked the same way.

Step 2 — Open the request form#

System → Certificates → Add certificate, then Request from an ACME server: The router requests the certificate, from Let’s Encrypt for example, and renews it.

The form, Request a certificate from an ACME server, begins with the rule it depends on: The ACME server checks each name on port 80, so every name must resolve to this router and port 80 must reach it.

Step 3 — Fill it in#

Press Request certificate. The request joins the pending changes, described as, for example, Request certificate “router” from an ACME server — router.example.com, contact admin@example.com.

Step 4 — Apply#

Apply the pending changes from the bar at the bottom of the page. The bar marks every change to the certificate store as able to cut you off, because a service may be using the certificate: Apply with auto-revert, followed by Keep changes once the page still responds, is the careful choice.

The router requests the certificate when the change is applied, so applying takes longer than usual. If the ACME server refuses — a name that does not resolve to the router, port 80 closed — applying fails with the ACME server's reason. The pending changes stay pending: fix the cause and apply again.

Step 5 — Check it#

The Certificates table lists the new entry with an ACME badge:

The tiles above count Requested by ACME and Expiring within 30 days; a certificate whose renewal keeps failing shows up in the second.

Select the entry for its details: Subject, Names, Issued by, Valid from, Expires, Key, Private key (Held by the router; the key itself is never shown), SHA-256 fingerprint, and an ACME request section with the Domain names, Contact email, ACME server, Answers on and RSA key size. Edit request changes the request.

From outside, against a service that uses the certificate:

openssl s_client -connect router.example.com:443 -servername router.example.com </dev/null 2>/dev/null \
  | openssl x509 -noout -issuer -subject -dates

Using it#

Other settings refer to a certificate by its name. The OpenVPN page, for example, offers the certificates and certificate authorities on the router in its Certificate authority and Certificate fields. Once something uses the certificate, the Used by column says what.

A certificate you already have, or one the router generates#

Add certificate offers two other ways in. Both are checked by the agent before anything is added, and both add to the pending changes.

Import — for a certificate issued elsewhere. Enter a Name, an optional Description, the Certificate (PEM, beginning -----BEGIN CERTIFICATE-----.) and its Private key (PEM. It is stored on the router and not shown again.), then press Check certificate. The agent refuses a private key that does not belong to the certificate, and a key protected by a passphrase (remove the passphrase and paste it again). It warns when no private key was pasted, when several certificates were pasted (only the first is imported), and when the certificate expires within 30 days. It then shows what the entry will be — Subject, Names, Issued by, Expires, Key, Private key — and Add certificate adds it.

To renew an imported certificate, open it and press Replace certificate. Leave Private key empty to keep the key the router holds; the new certificate must then have been issued for that key. A certificate requested from an ACME server is not replaced this way: the router replaces it itself.

Generate — for a certificate the router creates. Enter a Name, a Common name, and optionally an Organisation; the Names it is valid for (host names, wildcards and IP addresses; The common name when empty.); whether it Identifies A server, A client or A server and a client; Valid for (365 days by default, at most 3650); the Key (EC P-256 by default, EC P-384, RSA 2048 or RSA 4096); and Signed by: Itself (self-signed), or a certificate authority on the router that holds its key. Press Generate, read the result, and press Add certificate. A self-signed certificate, or one signed by the router's own authority, is trusted only by clients told to trust it.

Deleting one#

Open the entry and press Delete certificate, then Delete name? to go ahead. The button is disabled while anything uses the certificate, and says what: Used by … Remove it from there first. Deleting an ACME certificate stops its renewal; remove the port 80 rule too if nothing else needs it.

The web interface's certificate#

The agent serves the web interface with the certificate named by its --tls-cert and --tls-key start-up options. The shipped service passes neither, and has the agent generate a self-signed certificate in its data directory instead: an EC P-256 certificate for the host name, the host name under .local, localhost and the router's addresses at the time, valid for 398 days. Browsers warn about it until you add an exception for this host. It still encrypts the session, so session cookies cannot be captured passively on the network.

The agent replaces that certificate by itself, and logs why, when it is unreadable, when it has expired or expires within 30 days, or when it was generated as a certificate authority, as early builds did. If you ever added one of those early certificates to a browser's or a system's trust store, remove it: a certificate authority there is trusted for every site.

A backup carries the agent's certificate and its key, so a restored router keeps presenting the certificate browsers already accept.

To serve the web interface with another certificate, point the two options at its files with a systemd drop-in, at the console. This is not a setting in the web interface:

[Service]
ExecStart=
ExecStart=/usr/bin/wheelhouse-agent … --tls-cert <path> --tls-key <path>

Then sudo systemctl daemon-reload and sudo systemctl restart wheelhouse-agent. Two things follow:

• The agent reads the files when it starts. A renewal that rewrites them reaches the web interface only after the agent restarts: Restart agent under Admin → Agent settings does it.
• A drop-in survives an image upgrade; an edit to the packaged service does not. Copy the full ExecStart line from the packaged service into the drop-in, changing only the certificate options.

Where the router keeps the files of an ACME certificate is not documented here; find them on your own router before pointing the agent at them.

Undoing it#

Remove the certificate from whatever uses it, delete it on the Certificates page, apply, and remove the firewall rule that admitted port 80 if nothing else needs it.

See also#

• Certificates — the page, field by field
• Harden a router that faces the internet
• A default-drop ruleset that admits what you meant — the rule that lets the check in
• Time synchronisation — a wrong clock fails issuance and validation