Skip to content

Issue a wildcard certificate (DNS-01)

What you'll have at the end: a wildcard certificate (*.example.com) issued, installed, and covering every host under that zone that presents it — issued the same way any DNS-01 certificate is, with one extra rule: a wildcard can only be validated by proving control of the DNS zone, never by answering a challenge on a specific host.

Prerequisites:

  • A renewal profile whose Validation Method is a DNS-01 variant — DNS-01 (Automatic via API) with a configured DNS provider, or DNS-01 (Manual TXT) if you'll publish the record yourself. HTTP-01 and the internal CA cannot validate a wildcard at all; a wildcard endpoint is refused off any other lane before an order is ever opened.
  • Hub admin access, and an active Scout on the host you want the wildcard certificate delivered to.

Time: 10–15 minutes on the automatic lane; the manual lane adds however long it takes you to publish a DNS record.

Step 1 — Add the endpoint with a leading *.

On Manage, click + Add endpoint. Fill in the form exactly as for any other endpoint, with the wildcard as the hostname:

Field Value
Hostname *.example.com
Port 443 (unused for the wildcard row itself, but still required)
Scout the Scout that should hold and deliver this certificate
Renewal profile a DNS-01 profile — automatic or manual

Click Add endpoint.

You should now see one of two things:

  • The endpoint created and a first issuance queued — proceed to Step 2 (or Step 3 on the manual lane).
  • A refusal naming wildcard_requires_dns01 if the profile you picked isn't DNS-01. Pick a DNS-01 profile and try again — there is no override, because no other lane can validate a wildcard at all.

The hostname is validated as a single leading *. label: *.example.com is accepted; a remainder with no dot at all (*.com, for instance — there has to be something beneath the wildcard to cover) and anything carrying a second * are both refused with a 400, before the form even reaches the renewal profile check.

Step 2 — Automatic lane: nothing else to do

If the profile's DNS provider can publish the challenge itself, the order runs the same way any automatic DNS-01 renewal does: the Hub opens the order, publishes the TXT record, waits for it to become visible, lets the CA validate, and the Scout installs the result. Skip to Step 4.

⚠️ If a later renewal of this certificate also covers the bare apex (example.com alongside *.example.com — see the box in Step 3 for how that happens), the automatic lane needs a DNS provider that can hold two TXT values at one name at once. Route 53 and Cloudflare can; Google Cloud DNS cannot yet, and that renewal is refused pre-flight (wildcard_txt_collision) rather than silently publishing only one value. Split the apex and wildcard into separate certificates, or switch that profile to manual TXT.

Step 3 — Manual lane: publish the TXT record(s)

On DNS-01 (Manual TXT), the renewal parks and the drawer shows the record to publish: _acme-challenge.example.com.

If this certificate also covers the bare apex, publish BOTH values

A wildcard's challenge record and its zone apex's challenge record are the same DNS name — _acme-challenge.example.com either way, because the literal * label is not something a DNS name can carry. A fresh + Add endpoint order for *.example.com alone only proves the wildcard, so this doesn't come up on Step 1's first issuance — but a renewal of a certificate that already covers both *.example.com and its bare example.com (common on a certificate adopted or taken over from certbot, which carried both names already) plans both, and the CA needs to see two different TXT values at that one name simultaneously — one proving the apex, one proving the wildcard. Publishing only the value you were shown for the wildcard silently leaves the apex's authorization unproven, and the order times out on it.

Most DNS consoles let you add a second TXT record at an existing name without disturbing the first — add both and leave both until the renewal closes.

The Hub's check is a membership test, not an exact match: as long as your zone answers with a value containing each expected string among however many TXT records are at that name, both authorizations validate. Leftover records from a previous attempt don't need cleaning up first.

Step 4 — Verify the result

The renewal is closed — drawer → Renewals tab: newest entry Closed.

A covered host proves it — the wildcard hostname itself is never dialed or scanned; nothing can open a TLS connection to the literal name *.example.com. The Hub instead treats the wildcard as proven once a concrete host under it (app.example.com, shop.example.com, ...) is observed actually serving a certificate whose subject or SAN list contains the wildcard name — not merely because such a host exists or is otherwise managed. Point a Scout at one of the covered hosts (see Track a new endpoint) if you want the wildcard row itself to show served proof.

The world sees it — from any covered host:

$ echo | openssl s_client -connect app.example.com:443 -servername app.example.com 2>/dev/null | openssl x509 -noout -subject -ext subjectAltName
subject=CN=*.example.com
X509v3 Subject Alternative Name:
    DNS:*.example.com, DNS:example.com

Autopilot is not available on a wildcard certificate

Autopilot refuses to enable on a wildcard group at every point that would otherwise turn it on — the enable action itself, the scheduled sweep, and the offer rendered on the row. The attempt fails with a distinct wildcard_group refusal, separate from the ordinary fleet-state refusals. Renew a wildcard certificate with Renew Now instead; there is no unattended path for it today.

Where the certificate lives on the Scout

The Scout cannot use the literal * in a filesystem path — it is a shell glob metacharacter, and an unquoted path in an operator-authored hook would silently expand it. Wildcard certificate files are stored under a directory named for the zone with _wildcard. prefixed instead of the *. label: *.example.com lives at {data-dir}/certs/_wildcard.example.com/ (fullchain.pem, cert.pem, chain.pem, privkey.pem — same shape as any other managed certificate). The certificate itself still names *.example.com in its subject and SANs; only the on-disk directory is encoded this way. If you write a pre/deploy/post hook that reads the managed directory for this certificate, use the _wildcard. path, not the literal name.