Skip to main content

Certificates

Instances are served over TLS by the shared ohm-nginx container. Certificates are obtained from Let's Encrypt through a certbot container. When a trusted certificate cannot be issued, the instance keeps the certificate it has while that one is still valid, and gets a self-signed one otherwise.

Requesting​

In the console, the instance's Certificate page. On the command line:

Remote or localagainst pelmo
$ ohm instance certificate request --instance fanes

Before requesting, confirm DNS actually points at this host. A request that fails because of DNS looks identical to one that fails for any other reason:

Remote or localagainst pelmo
$ ohm server config validate-dns

Two things have to be true for a trusted certificate:

  • Every host name on the instance resolves to this server.
  • Inbound TCP 80 is reachable from the internet, because that is how the challenge is answered.

After the instance's host names change, turn on Force beside Request certificate: it reissues a certificate that is still valid, applies to that one request only, is not saved with the options, and is off again after the request.

Every Role offers every mode​

The certificate does not depend on the instance's Role. A development or staging instance offers Self-signed, Let's Encrypt and an uploaded certificate exactly like a production one, subject only to the license. A development instance reached on a public name can therefore get a publicly trusted certificate.

Changing the Role, into or out of Development included, keeps the certificate mode and the certificate the site is served with. No certificate is requested because of a Role change.

A new development copy - one restored, cloned or imported with the Development preset - starts self-signed, from the server's own authority: a copy of a production instance must not ask Let's Encrypt for the production name, and a generated <id>.localhost name cannot get a trusted certificate anyway. Choose another mode on its Certificate tab afterwards, as on any instance. Applying that preset to an existing instance with ohm instance config preset sets Self-signed too.

A saved certificate change is cleared by requesting one​

Certificate options are a configuration change like any other, so saving them puts a row on Pending changes. What clears that row is the certificate request, not the ordinary apply - the row says so, names the request as its action, and links to it.

A successful request records the certificate members as applied and leaves every other pending member its own reason. Two cases deliberately record nothing:

  • a fallback, because what is being served is not what the configured mode produces;
  • a reissued certificate that could not be restarted into service.

In both, the row stays - which is correct, because the change you asked for is not the one in force.

Listing and renewing​

Remote or localagainst pelmo
$ ohm instance certificate list --instance fanes
Remote or localagainst pelmo
$ ohm instance certificate renew --instance fanes

Renewal is one of the operations the maintenance scheduler can run unattended. That is the normal arrangement: a certificate you renew by hand is a certificate that expires on a weekend.

Restores and moves keep the certificate​

An instance's backups carry its certificate, and a restore or a move to another server puts it back when it is still good for the instance's names, so nothing is requested. A Let's Encrypt certificate kept this way is served until its renewal is due; the first renewal on the new server then obtains one of its own. See Restoring.

The fallback is deliberate​

If a trusted certificate cannot be obtained, the instance keeps the certificate it already serves for as long as that certificate is valid for the instance's host names, also in its last 30 days. Only when there is nothing to keep - no certificate, an expired one, or one that does not cover the host names - does the instance get a self-signed one rather than none. A browser warning is a bad outcome; an instance that will not serve HTTPS at all is a worse one.

Because the Developer edition always falls back, a Developer instance ends up on a self-signed certificate rather than on no certificate.

A renewal that falls back, to the kept certificate or to a self-signed one, is reported as a failed renewal and raises its alert, so a fallback never hides behind a green job. Request certificate shows it as a warning that says why, and ohm instance certificate request and renew exit with an error.

An instance on Let's Encrypt that is left on any other certificate is requested again at the next scheduled renewal, whatever that certificate's expiry date, so it returns to Let's Encrypt by itself once the cause is gone.

When the license changes​

When the license stops carrying a certificate feature, every instance using it is put on a self-signed certificate: a Let's Encrypt certificate obtained by DNS-01, an uploaded certificate, or, on a server that moves to the Developer edition, any Let's Encrypt certificate. The DNS provider and its credential, the uploaded pair and the Let's Encrypt settings are kept, the Certificate page says the license switched it, and the instance goes back to its own certificate by itself when the license allows it again.

See When the license changes.

The console's certificate​

The console's own certificate on port 5322 belongs to the server, and the bootstrap agent renews it every day. It is described with the server's other certificate settings in The server's certificate and authority.

Renaming the server​

Renaming the server changes the name the console and its certificate answer to; the instances keep their own names. See Renaming the server.

The console's public name​

The name Let's Encrypt is asked for when the server's own host name is not fully qualified. See The console's public name.

The server's own certificate authority​

An instance's self-signed certificate is signed by an authority of the server's own, the same one that signs the console's. Import that authority once into a browser or an operating system and every self-signed instance on the server is trusted together. The authority is managed on the bootstrap agent: see The server's own certificate authority.

The Self-signed card on an instance's Certificate tab takes a Root CA as its first field, so an instance can be issued under a different authority from the server's default when it needs to be.

The trust kit​

The instance's Certificate tab offers the authority's trust kit for download: the authority in both encodings, a README with the steps for Windows, macOS and Linux, and an installer script for each. See The trust kit.

Last updated on