Wildcard certificates with DNS validation

A normal Let's Encrypt certificate proves that you control a site by serving a small file over HTTP on port 80. That only works for names that already point at your server, and it can never cover "every subdomain". DNS validation proves control a different way: SrvYard adds a temporary TXT record to your domain's DNS zone in Cloudflare, Let's Encrypt looks for it, and the record is removed again.

This is the only way to get a wildcard certificate such as *.acme-shop.example, and it also helps when the site is not reachable yet or port 80 cannot be opened. This article shows how to connect Cloudflare, choose wildcards for a site, issue the certificate and keep it renewing.

Before you begin#

• A domain whose DNS is hosted at Cloudflare. Cloudflare is the only DNS provider SrvYard can use for this. The domain must be a zone in the Cloudflare account you connect. If your DNS lives elsewhere, either move the zone to Cloudflare or use HTTP validation for single names.
• A Cloudflare API token with the permission Zone / DNS / Edit (and Zone / Zone / Read) on the zones you will issue certificates for. Create it in Cloudflare under My Profile > API Tokens.
• A site in the Ready state on a connected server, and the permission to manage its SSL.
• Organisation settings access to connect the integration. Connecting a DNS provider is done once for the whole organisation.

1. Connect Cloudflare#

Open Settings > Integrations in the sidebar and look at the DNS providers card. The card reads DNS providers SrvYard can use to validate domains for certificates, including wildcards.

1. Connect Cloudflare opens the dialog from the next picture.
2. The list of connections. Each row shows the name, the end of the token, the status (Connected, with when it was last checked) and Used by, which tells you whether any certificate depends on it. The token itself is never shown again, and it is stored encrypted.

1. Name. Pre-filled with Cloudflare. Use something that tells accounts apart, for example the company or the domain.
2. API token. Paste the token. The dialog repeats what it must be allowed to do: Zone / DNS / Edit (and Zone / Zone / Read) on the zones you will issue certificates for.
3. Connect. SrvYard asks Cloudflare to confirm the token before it saves it, so a mistyped or under-powered token is rejected straight away.

2. Choose wildcards when you create a site#

A site can be created with wildcards from the start. On the new site form, choose a custom domain and press Configure next to it.

1. Wildcards: On. Support all subdomains, e.g. blog.app.acme-studio.example. Nginx then answers for every subdomain of the name, not only for the name itself. Off supports only the root domain.
2. The note says it plainly: A wildcard certificate needs DNS validation, which you set up later on the site's SSL tab. Creating the site does not issue the certificate.

Wildcards cannot be turned on for the free srvy.sh names, which are a single host each.

3. Issue the certificate with DNS validation#

Open the site, choose SSL, press Get a free certificate and switch to DNS validation.

1. DNS validation. A TXT record is added in Cloudflare. Works for wildcards and for sites that are not reachable yet.
2. DNS integration. Pick the Cloudflare connection from step 1. If the list is empty, connect Cloudflare first.
3. Hostnames. Tick the names for the certificate. The wildcard name *.acme-shop.example is listed with an empty box, next to the bare domain and www.. A wildcard covers one level of subdomains only (blog.acme-shop.example, but not a.b.acme-shop.example) and does not cover the bare domain, so tick both acme-shop.example and *.acme-shop.example when you want both.
4. Get certificate. Starts the request. Validation takes about a minute in the normal case, and a little longer when DNS is slow to answer.

Under the fields, Before you continue explains the rules: the domain must be a zone in the connected Cloudflare account, SrvYard looks the zone up for every name and refuses the request when it is missing, the TXT record is removed afterwards, and the new certificate replaces the one in use only when it was issued and Nginx accepted it.

After the request the output scrolls by line by line. When it ends successfully the certificate is In use, and the card shows Validation: DNS.

4. Use one wildcard on several sites#

A wildcard certificate is useful when several sites on one server share a domain, for example blog. and shop.acme-shop.example. Issue it once on one site. On each of the others, open the SSL tab, press the menu next to Install your own and choose Copy from another site. The list shows installed certificates of other sites on the same server that cover a name of this site.

Be aware that a copy is a copy: SrvYard does not renew it. Renew the original and copy it again is exactly what the panel says. If you have many sites on a domain, it is easier to issue a separate wildcard certificate on each one, and let SrvYard renew every one automatically.

5. Renewal and what can go wrong#

DNS certificates renew themselves, like the others. After the first issue, glance at the certificate card: Validation should say DNS and Renewal should say Automatic. When one has 30 days or less left, SrvYard asks Let's Encrypt again and Cloudflare adds the TXT record again. That means the token must stay valid: if you delete it in Cloudflare, rotate it, or remove the connection from SrvYard, the certificate keeps working until it expires but cannot be renewed. SrvYard then tells you to connect Cloudflare again and request a new certificate. Read How renewals work and what to do when one fails for the whole picture.

Troubleshooting#

• "Choose a connected DNS integration. Connect Cloudflare in the organization settings first." There is no Cloudflare connection yet, or none was selected. Do step 1.
• "… has no zone in the Cloudflare account of this integration". The domain is not a zone of that Cloudflare account. Add the domain to Cloudflare, or connect the account that owns it.
• "Wildcard names … need DNS validation". You asked for a *. name with HTTP validation. Switch to DNS validation, or install your own wildcard certificate.
• The request fails with a validation or permission error. The token lacks Zone / DNS / Edit, or it is limited to other zones. Fix the token in Cloudflare. If you create a new token, connect Cloudflare again with it.
• The wildcard does not cover my bare domain. That is how wildcards work. Request both names on the same certificate.
• Let's Encrypt says too many certificates. The weekly limit for the registered domain is used up. Wait and use Retry now; see the renewals article.

Related#

• Get a free Let's Encrypt certificate: HTTP validation, the usual way.
• How renewals work and what to do when one fails: automatic renewal, alerts and retries.
• Install a custom certificate: a wildcard you bought instead.
• Create a site on your server: the new site form where wildcards are chosen.