Issue a wildcard certificate

A wildcard certificate covers example.com and *.example.com. Let’s Encrypt validates wildcards only over DNS, and Hyperion holds no DNS credentials. You have two ways: publish TXT records yourself each time (about every 60 days), or delegate a small DNS zone to the panel once so renewals run unattended.

Before you start

• Your account has the Manage TLS certificates permission. Setting up the delegated zone needs the Owner role, like every other Settings form.
• You can edit the domain’s DNS records.
• A real Let’s Encrypt contact address is set under Settings, HTTPS & previews, Let’s Encrypt contact.
• The certificate covers the primary domain and *.<domain> only. Aliases are not added to it.

Steps

Option A: publish TXT records by hand

1. Open the site, then the Domains & SSL tab.
2. Open Need a wildcard (*.example.com)? DNS-01 issuance… and click Start wildcard issuance.
3. The Wildcard certificate — DNS-01 page lists TXT records (type, name, value). Add each at your DNS provider, then wait a minute or two. The domain and its wildcard share one name, _acme-challenge.example.com, so it gets two TXT values.
4. Click I’ve published the records, validate now.

Before it contacts Let’s Encrypt, Hyperion queries the domain’s own nameservers for every value. If one is missing, the page returns with Not validated yet — the records below are still the right ones. and the same values stay valid. Wait and click again. Asking to start again while the order is pending shows the same values.

Wildcards issued this way do not renew themselves. You get notifications as expiry nears; repeat the steps before it. The page then shows “Wildcard certificate issued.”

Option B: delegate a zone for automatic renewal

Do the one-time setup first, on the master.

1. Open Settings, then HTTPS & previews, and find Delegated acme zone.
2. Fill in:
   • Zone, a name under your panel’s, for example acme.panel.example.com.
   • Name server host, outside the zone and in the parent zone, for example ns-acme.example.com.
   • Public IPv4, this server’s address, for example 203.0.113.10, and optionally Public IPv6.
   • Tick Answer for this zone (opens port 53 in the firewall).
3. Click Save. Saving with the box ticked checks that nothing else listens on port 53 and opens it in the firewall.
4. Add the records the page lists at the DNS provider of the parent zone: an NS record for the zone, and A (and AAAA) for the name server host.
5. Click Check delegation. A pill reads working, delegation missing, points elsewhere or could not be checked.

Then, for each domain:

1. Open the site’s Domains & SSL tab and find the Wildcard renewal card.
2. Click Set up automatic renewal. The card shows a Name (_acme-challenge.example.com) and a CNAME target.
3. Create that CNAME at the DNS provider of example.com.
4. Click Check the CNAME until the pill reads CNAME verified.
5. Click Issue the wildcard now and confirm. A job runs the issuance.

From then on the master renews the certificate once a day when it is within 30 days of expiry. It confirms the CNAME, serves the TXT values itself, waits until public resolvers see them, and withdraws them afterwards. The certificate list on Certificates shows auto-renew on beside it. Settings, HTTPS & previews lists Delegated wildcards with their state.

Before you turn the responder off

Unticking Answer for this zone stops the master from answering for the zone. Delegated wildcards then fall back to manual renewal and can expire. Check Certificates for wildcards with auto-renew on first. You can turn it back on at any time.

For a test node’s preview addresses, the same page issues one *.<base> certificate per node under Preview certificates.

Check that it worked

Open Certificates. The domain is listed with issuer letsencrypt, a date about 90 days away and, for Option B, auto-renew on. The site’s Certificate card lists *.example.com under Covers.

If it fails

• Not validated yet — the records below are still the right ones. The nameservers do not serve all values yet. Check each record’s name and value and wait for propagation.
• CNAME not verified with a note: the record is missing or points elsewhere. The note is the checker’s own text.
• The delegated zone is off: turn it on under Settings → HTTPS. Tick Answer for this zone.
• Set up the delegated acme zone under Settings → HTTPS first. Complete the one-time setup.
• automatic renewal is not set up for example.com: click Set up automatic renewal first.
• Port 53 is held by another service: saving the zone is refused with a message. Free the port and save again.