Hostnames and certificates
Your own hostname on a zone is a CNAME to the zone's default hostname, plus a certificate we issue once that CNAME is live. In that order: point the DNS first, then switch SSL on, and the certificate arrives within a minute or two. Every hostname on a zone has a certificate of its own: the default hostname always has one from Let's Encrypt, and a hostname you add gets one from Let's Encrypt, or you upload your own.
The name#
A hostname is a full name of at least two labels, at most 253 characters, made of letters, digits and hyphens with a last label of letters only: cdn.example.com, or the bare domain example.com. No wildcard, no underscore, no port and no IP address. A name containing cachegenie.com or cg-cdn.com anywhere is refused, and so is a name already on a zone, yours or anyone else's. It is added with SSL off. The default hostname's SSL is always on, it always uses Let's Encrypt, and it cannot be deleted; deleting any other hostname removes it and its certificates at once, with no confirmation step.
The DNS#
A CNAME from your hostname to the zone's default hostname, which the hostname table shows:
cdn.example.com. CNAME myzone.zone.cg-cdn.com.That is the whole of it. The default hostname resolves to our network and follows it as it changes, so never copy our addresses into A or AAAA records of your own: they change without notice, and a name that stops resolving to us stops being served. A bare domain cannot carry a CNAME under the DNS rules, so for example.com itself use a provider that offers an ALIAS, ANAME or flattened CNAME record at the apex, or put the site on a subdomain such as www.
SSL and Force SSL#
Once the name resolves to us, switch SSL on. We check that the name's DNS resolves to our network, order a certificate from Let's Encrypt, and every location is serving it a few seconds after it is issued; the whole thing takes a minute or two, and the certificate renews itself 30 days before it expires. If the name does not resolve to us yet, the Certificate column reads waiting for DNS to point here and the name is checked again an hour later; switching SSL off and on does not bring that forward, which is why the DNS goes first.
Until a certificate exists, an HTTPS connection to the hostname fails at the handshake: no certificate is presented, so a browser shows a connection or protocol error rather than a page. HTTP works throughout. Switching SSL off stops HTTPS for the name and turns Force SSL off with it.
Force SSL becomes available once SSL is on and a certificate exists. On, a request over HTTP is answered with a 301 to the same URL over HTTPS, path and query included, and every response that carries your content adds Strict-Transport-Security: max-age=31536000, without includeSubDomains. That header tells browsers to use HTTPS for this hostname for a year without asking, so switch it on only when everything served under the name works over HTTPS.
Moving a hostname that is already live#
There is a gap between the moment your DNS starts sending visitors to us and the moment the certificate exists: a minute or two in which HTTPS on that name fails. HTTP is unaffected. Two ways to handle it:
- Upload your own certificate first. Add the hostname, use Use own certificate to upload the certificate and key your current server uses, then move the DNS: HTTPS works from the first visitor. The gap moves to the moment you press Remove, which deletes the upload at once while Let's Encrypt takes a minute or two to issue, so do that at a quiet moment, or keep your own certificate and renew it yourself.
- Accept the gap. Move the DNS at a quiet moment with a short TTL in place, and switch SSL on the moment the name resolves to us. Visitors who arrive over HTTPS in that minute or two see a connection error and can retry.
What the Certificate column says#
| The column reads | Meaning | What to do |
|---|---|---|
| Let's Encrypt | A certificate is in place and renewing itself. The same bare text shows while the SSL switch is off, so read the switch with it | Nothing |
| Let's Encrypt, being issued | SSL was switched on and the order is in progress | Wait a minute or two |
| Let's Encrypt, waiting for DNS to point here | The name did not resolve to us when it was last checked. The tooltip says what it resolved to instead | Fix the CNAME. The name is checked again an hour later, and the line clears once a certificate has been issued |
| Let's Encrypt, issuance failed, retrying | Let's Encrypt refused the order or could not validate it. The tooltip carries the reason | The usual causes are a CAA record on your domain that does not allow letsencrypt.org, and DNS that changed during the order. It is retried after an hour, then 2, 4 and 8, then every 16 hours |
| Let's Encrypt, renewal failed, retrying | The same, for a renewal. The current certificate keeps serving until it expires | As above |
| Let's Encrypt, expired, reissuing | The certificate expired before a renewal succeeded and a new one is being ordered | Check the tooltip for what stopped the renewal |
| Own certificate (issuer), expires 3 Mar 2027 | You uploaded a certificate. Inside 30 days of expiry the line reads expires in N days as a warning, and once it has expired, expired 3 Mar 2027 | Replace it, or remove it to hand over to Let's Encrypt |
| certificate status unavailable, please refresh | The page could not read the certificate's state | Refresh the page |
Your own certificate#
Use own certificate, on a hostname you added, takes the certificate and its private key in PEM form. What is accepted:
- The certificate first, followed by any intermediate certificates, each as a
-----BEGIN CERTIFICATE-----block. The chain is stored as pasted. - An unencrypted private key: RSA of 2048 bits or longer, or EC on P-256, P-384 or P-521 with a named curve. A key with a passphrase, or an EC key exported with explicit curve parameters, is refused with a message saying so.
- A certificate issued for the hostname, by its common name or a subject alternative name. A wildcard covers one label, so
*.example.comcoverscdn.example.comand nota.b.example.com. - One that has not expired, and does not start more than a day in the future.
Saving switches the hostname's SSL on, replaces any certificate uploaded before, and puts the new one on every location within seconds. Remove deletes it at once, switches Force SSL off, and starts a Let's Encrypt issuance for the name, which takes a minute or two, so HTTPS on the name fails in between. The key is stored with the zone and sent only to our edge. We email everyone ticked for Technical emails under the account's Email contacts 30 days and 7 days before an uploaded certificate expires, and again when it has expired; an expired upload is taken over by Let's Encrypt automatically, so a lapsed one costs an HTTPS outage for as long as the issuance takes rather than for good.
Several hostnames on one zone#
A zone can carry as many hostnames as you need, each with its own certificate. Whether they share one cached copy of each file or hold one copy per name depends on the Forward Host Header switch: off, one folder of files is served under every name from one copy; on, each name is cached separately, because your origin is told which name was asked for and may answer differently. A full site needs it on; a library of files under several names wants it off. A purge clears every hostname's copy either way.
If it does not work#
- HTTPS to the hostname fails to connect: the SSL switch is off for it (the Certificate column still reads Let's Encrypt), the name does not resolve to us yet (waiting for DNS to point here), or the certificate is still being issued (being issued).
- A page saying No site is configured here: the name resolves to us but is not on any zone, or the zone it was on has been deleted.
- The default hostname works and yours does not: check the CNAME with
dig cdn.example.com CNAME; it should answer with the default hostname.
Error pages and status codes covers everything a visitor can be shown.