SSL and certificates

The padlock in the address bar. A certificate encrypts the traffic between your visitor and your site, and lets the browser prove it is really talking to your domain. For most people the good news is that there is nothing to do here. This page explains what happens on its own, and what to do when it does not work.

Screenshot — Panel → Hosting → Accounts → your account → SSL/TLS. At the top is the Certificate for picker: every domain has a certificate of its own. Screenshots are captured with openwolf designqc into .wolf/designqc-captures/.

What happens on its own

Add a domain to your account and the server requests a certificate from Let's Encrypt as soon as the domain points at this server. That usually takes under a minute. After that it is renewed automatically, well before it expires — a certificate is valid for ninety days and is renewed around thirty days before the end.

So there is nothing to do, except one thing: your DNS has to point at this server. As long as your domain still points at your old hosting, Let's Encrypt cannot establish that it is you, and no certificate arrives.

Looking at the status

Under What is there now you see the certificate the web server is currently offering:

• Source — automatic (Let's Encrypt) or a certificate you installed yourself.
• Issued to — the domain names on it.
• Expires — the end date. Inside thirty days that becomes a warning.

corectl ssl list
corectl ssl list | grep yoursite.com

Requesting a certificate yourself

If it went wrong when you added your domain — the DNS pointed nowhere yet, say — simply click Request certificate once it is right.

corectl ssl issue yoursite.com

What happens underneath: the server puts a small file at http://yoursite.com/.well-known/acme-challenge/…, Let's Encrypt fetches it, and if it matches you get your certificate. Which is why your domain has to be reachable on port 80 and must not redirect everything immediately.

Wildcard: one certificate for all your subdomains

If you have many subdomains (shop., blog., customer1., …) you want one certificate covering them all: *.yoursite.com.

That is only possible when the DNS zone of your domain lives on this server, because a wildcard is not proven with a file on your website but with a TXT record in your DNS. The server puts that record down, waits until it is visible, and takes it away again afterwards.

corectl ssl issue yoursite.com --wildcard
corectl ssl issue yoursite.com --no-wildcard   # back to the domain itself only

In the panel this is under Automatic certificate as Subdomains too.

If your DNS lives at your registrar or at Cloudflare a wildcard is not possible from here — request an ordinary certificate per subdomain instead, which works fine.

Extra names: "waiting for DNS"

If your website has extra names (see Extra names and subdomains), they are in the same certificate. There is no second certificate.

Such a name can say waiting for DNS. That means exactly one thing: the name does not point at this server yet, so it could not be checked. It was therefore skipped — deliberately, because a certificate is issued for all of its names at once. Had that one name gone along, the whole request would have failed and you would have been without a certificate for your main domain too.

What is true in the meantime:

• your main domain keeps its valid certificate;
• the extra name is reachable over http://;
• no request was wasted.

As soon as the DNS is right, the next request picks it up — by itself at the nightly renewal, or immediately. If you have only just fixed the DNS, give the server a moment: it remembers an earlier "that name does not exist" for a short while, so a request inside that hour may still skip the name. It corrects itself; all you have to do is request once more.

corectl ssl issue mycompany.com

[corecp] mycompany.co.uk now points here and is included in the certificate
[corecp] certificate active for [mycompany.com www.mycompany.com mycompany.co.uk]

Names you did not ask for: mail, webmail and mta-sts

Three names join your certificate on their own, and none of them is something you have to request:

• mail.<your domain> — the address you type into Outlook, Apple Mail or your phone to collect and send your mail. It is on by default as soon as your domain delivers mail here, exactly as it was in the panel you came from: a mail program that has said mail.yourdomain.com for ten years keeps working.
• webmail.<your domain> — so the webmail link in the panel opens without a browser warning. It appears as soon as your domain delivers mail here.
• mta-sts.<your domain> — the address at which your domain publishes its MTA-STS policy, which tells sending mail servers that mail for you must travel over a verified connection. That policy is only trusted over a certificate that matches this name, so without it in the certificate every sender ignores the policy.

All three follow the same per-name rule as your own extra names: a name whose DNS is not pointing here yet is left out of the certificate rather than failing the whole request, and it is picked up by the next renewal once its DNS is right. Email → Security for the domain says in as many words whether the policy name is covered yet — see Mail security.

Turning the mail name off

If you do not want mail.yourdomain.com — because at your end that name points at another mail provider, say — switch it off with Mail hostname (mail.…) on your website's SSL page. We take the record out of your DNS and stop asking for the name at the next request.

From the command line:

corectl mail hostname set yoursite.com off   # do not publish it
corectl mail hostname set yoursite.com on    # publish it again

Switching it off takes effect in DNS immediately. The certificate keeps the name until it is next renewed, which is harmless: a certificate may name more than what exists.

Why it only appears at the next renewal

If your website has been here a while, mail.yourdomain.com is not on your certificate yet. That will fix itself, but not today: certificates gain the name at their ordinary renewal, and those are spread across the lifetime of every certificate. That is deliberate — Let's Encrypt allows a limited number of certificates per week per domain, and a reseller with a hundred domains would fill that quota in one go.

If you would rather not wait, press Request certificate once on the SSL page. That is one certificate for one website.

Your website gets its certificate even when such a name is not visible yet

A name you created a moment ago is not known everywhere on the internet at once. The party that issues your certificate looks at DNS with its own eyes, and those can be half a minute behind yours. A name like webmail.yoursite.com used to be able to fail the whole request because of that — and then your brand-new website stood there without a certificate, over a name the website itself does not need.

That can no longer happen. If the request fails over such a service name, it is made once more straight away with your website's own names only. Your site is reachable over https:// as normal, and the SSL page shows the skipped name in amber with the reason beside it. It joins the certificate at the next renewal — or sooner, if you press Request certificate yourself.

$ corectl ssl issue yoursite.com
[corecp] the order for yoursite.com failed over a name in it.
         Re-ordering with the website's own names only;
         webmail.yoursite.com is left for the next renewal.
[corecp] certificate active for [yoursite.com]

Where the names in your certificate live

Click the padlock in your browser and follow it through to the certificate details, and you meet two lists that look alike. They are not equally important, and that catches nearly everybody once.

• Subject Alternative Name (SAN) — this is the list that counts. Every name your certificate is valid for is in it: your domain itself, www, your extra names, webmail, and for a wildcard *.yourdomain.com as well. A name that is not in it gets a browser warning, however good the rest looks.
• Subject, usually shown as CN=yourdomain.com — an old field from the days when a certificate could carry only one name. Browsers have ignored it for over a decade. It may be empty, and that says nothing about your certificate.

To read that first list without a browser, from your own machine:

$ openssl s_client -connect mycompany.com:443 -servername mycompany.com </dev/null 2>/dev/null \
    | openssl x509 -noout -ext subjectAltName
X509v3 Subject Alternative Name:
    DNS:mycompany.com, DNS:www.mycompany.com, DNS:mail.mycompany.com, DNS:webmail.mycompany.com

The panel shows the same list under What is there now, as Names on this certificate. Green chips are covered, amber ones are not — and one sentence below the row says why. If one you expected is missing, nine times out of ten that name does not point at this server yet; see Extra names: "waiting for DNS".

One thing matters here: a name that is not covered never costs you the whole certificate. Everything else is still requested and your website keeps working. That is deliberate — a request in which one name fails is rejected in its entirety by the certificate authority, and one wrong DNS record would otherwise take your whole site offline.

Renewing

Renewal happens on its own, from a timer on the server. To force it now — because you just added a subdomain, say:

corectl ssl renew yoursite.com    # this one certificate
corectl ssl renew                 # everything that is due

"The server is busy" — what that means, and why it is good news

At night the server renews every certificate that is due. Each one takes half a minute to a minute and a half, so on a server with a lot of websites that round takes a while.

What you notice: press a button that changes something during it — adding a website, changing a password, a DNS record — and it can take a moment to land. Usually half a minute. You get a yellow message, not a red one:

The server is busy — this node is busy with ssl.renew, 4 of 12 certificates, running for 3m21s. It gives the node up between units, so try again shortly.

That is a wait, not a failure: your action did not go wrong and there is nothing for you to fix. The server hands itself over between two certificates precisely so that your change fits in between. Waiting, or trying again in a moment, are both fine.

It used to do something else, which is why this section exists: your change sat waiting until the end of the whole round and you were eventually shown "something went wrong on our side". Nothing went wrong; the server was working and simply did not say so.

The limits, in plain language

Let's Encrypt keeps a weekly budget, and it is worth knowing how it is counted — because almost everybody guesses it wrong.

• The budget belongs to your domain, not to the server. For yoursite.com and everything under it together that is 50 certificates per 7 days. What other customers on the same server do never comes out of your pot, and your requests never come out of theirs.
• Asking for the same name again is the limit you can actually hit: 5 times per 7 days for exactly the same set of names. Press Request a certificate five times because nothing seems to be happening, and that name cannot get a new certificate for a week. When something does not work, look at why first — the message on the screen says it, and nine times out of ten your DNS does not point here yet.
• Renewals do not count. A renewal tells the certificate authority which certificate it replaces, and that exempts it from the five-per-week. Your automatic renewals can therefore never eat your budget, however many websites you have.
• And if the authority does not accept that statement, you still get your certificate. It happens: the previous certificate was replaced by something else already, or it was ordered before the server re-registered with the authority. The renewal is then simply placed again without naming a predecessor, and the log says so:

[corecp] this order replaces the certificate on disk (ARI wAQTmt….WbqYkSFDsoI)
[corecp] … refused the order over the certificate it names (…); re-ordering
         without the ARI reference
[corecp] certificate active for [yoursite.com www.yoursite.com]

The only thing you lose is the exemption above: that one renewal does count against the five-per-week. Nothing to act on unless you see it on every renewal of the same name.

• A failed attempt costs you no certificate, but it does have a counter of its own: 5 failed checks per name per hour. Another reason to fix the cause before trying again.

Let's Encrypt no longer warns you when a certificate is about to expire

They sent those e-mails until June 2025 and stopped. You do not need them: the panel watches this itself and warns you in good time when a certificate is not renewing. If you see such a notice, do not ignore it — it is now the only one you get.

Why your mail server may hiccup after a new certificate

A new certificate has to be read by your mail server too, so it is nudged to re-read its settings after every request. You will normally notice nothing at all. Very occasionally that nudge can no longer be acted on and the mail server has to be started afresh; the server checks for that itself and does it itself. No mail is lost — anything in flight is simply offered again — but a mail program that was connected at that moment will reconnect.

If you suspect mail is no longer arriving while sending still works, this is the first thing you (or your administrator) check on the server — and also the command that puts it right:

doveadm service status     # silence here means something is wrong
mailq                      # mail piling up here is mail that is not delivered
corectl reconcile          # checks for this and restarts the mail server if needed

Installing a certificate of your own

If you bought a certificate elsewhere (an EV certificate, or one from your employer), install it under Install your own certificate. You need three things:

Paste them, or choose the files. The panel checks before saving that it really is PEM, that the certificate has not already expired, and that the key belongs to the certificate. When the pair matches you see Checked: this pair belongs together.

corectl ssl install yoursite.com \
  --cert-file  ~/yoursite.crt \
  --key-file   ~/yoursite.key \
  --chain-file ~/intermediates.pem

Note that a certificate of your own is not renewed automatically. Set a reminder yourself; the server warns you thirty days ahead, but it cannot solve it for you. To go back to automatic, simply request a Let's Encrypt certificate again — that overwrites your own.

How often the platform tries again

When a request does not work, the server does not keep trying every minute. That is not slowness but necessity: a certificate authority allows only a limited number of requests per domain per week, and a server that keeps hammering a name that does not work yet spends that allowance before the cause has been fixed.

So the server waits a little longer between each automatic attempt:

Two things about it are worth remembering.

A successful request resets the counter. As soon as the certificate is there, the sequence starts at nothing again.

Asking yourself is always allowed. The schedule above only governs what the server does on its own. Press Request a certificate and the order goes out at once, even if the server itself would still be waiting. If you have just fixed your DNS, that is exactly what you want.

Your administrator can see, per name, how often it went wrong, when the server will try again, and the certificate authority's own error message. If a request keeps failing, that message is the fastest answer to why — ask for it.

One more try, when the authority looked too early. A new domain does not become visible to the whole internet at the same moment. The certificate authority asks its own nameserver, and that one can still be unaware of a name your nameservers have been answering for a while. A request that fails on that is placed once more automatically — but only when every nameserver of your domain answers the name at that moment. If your DNS genuinely points nowhere, it stays one failed request and one clear message.

What your administrator can see about one certificate

When your administrator clicks a row in the certificate list, a panel opens with everything the server knows about that one certificate. It is the fastest answer to the question you ask when something goes wrong, and it helps to know what is in there when you ask for it:

Passwords, keys and tokens never appear there: they are taken out at the moment the server writes the message down. What stays is the error itself.

If the software on the server is older than the version that keeps these records, the panel says so in as many words, naming the server. Updating that server makes the history visible.

When it does not work

Checking what the world sees:

echo | openssl s_client -connect yoursite.com:443 -servername yoursite.com 2>/dev/null \
  | openssl x509 -noout -subject -dates

"No website yet" — and what to do about it

A certificate secures a website: it is issued for a domain name, so without a domain there is nothing to secure. On an account with no website, the SSL screen says so, with an Add website button beside it.

1. Go to Accounts → your account → SSL/TLS.
2. Press Add website and add the website on the websites screen.
3. Come back to SSL/TLS. The domain switcher is now above the page, and the certificate is normally requested automatically as soon as the name points at the server.

If you may not add a website yourself you get the same explanation with a View websites link; ask your administrator to create the website.

See also

• Managing DNS records — where the A record and the wildcard validation come from.
• Installing WordPress — install only once https:// works.
• Where a website is served — which server serves your domain.