Skip to main content

Recover from an expired certificate

What happens when the server certificate expires​

A secure RavenDB server uses a single server certificate, which it presents on every encrypted connection.

Once the certificate expires, every connection to the server fails:

  • You cannot open Studio, because the browser rejects the expired certificate during the TLS handshake.
  • Client applications can no longer connect to the server.
  • In a cluster, the nodes share the certificate that is now expired, and cannot authenticate to each other and elect a leader.

Restarting the server does not help on its own. As the server loads, it rejects the expired certificate and fails to start, logging an error such as:

The provided certificate '<name>' from <source> is expired! Thumbprint: <thumbprint>, Expired on: <date>

Normally you would replace the certificate using Studio, but Studio cannot be reached in this situation. The recovery is therefore done directly on the server machine, at the file level, as described below.

Recover the server​

Obtain a valid certificate​

Before access can be restored, you need a valid certificate to replace the expired one. The replacement can be a certificate that is still valid, a new one from your certificate authority, or one issued through Let's Encrypt.

The replacement must meet the same requirements as any RavenDB server certificate: a .pfx file that contains the private key, has not expired, and carries the required Key Usage and Enhanced Key Usage fields. See certificate requirements for the full list.

Install the new certificate​

Install the new certificate on the server machine in one of two ways:

  • Overwrite the existing certificate file.
    Replace the current .pfx file with the new one, keeping the same path. The server will detect the change and load the new certificate within an hour, or immediately on a restart.
  • Point the server at the new file.
    Set Security.Certificate.Path in the server's settings.json file to the new .pfx, add Security.Certificate.Password if the file has one, and restart the server.

Once a valid certificate is loaded, the server resumes serving over HTTPS, and clients and cluster nodes can connect again.

Recover a cluster​

In a cluster, the same certificate is installed on every node, so an expired certificate must be replaced on each node, using either method above.

Replacing the certificate file does not depend on the cluster, so it works even while the cluster has no leader. The cluster elects a leader again once a majority of its nodes have loaded a valid certificate.

If Studio still cannot be reached with an administrator certificate, or the nodes still don't trust each other after the change, register a trusted certificate on each node locally using rvn admin-channel (see emergency access for a secure cluster for the procedure), which connects to the running server without TLS.

Once the cluster is reachable again, see certificate renewal and rotation to learn how to replace certificates across the cluster using Studio.

Prevent recurrence​

Renew your certificates well before they expire.

RavenDB provides warnings in advance, in the following ways:

  • Notifications are raised in Studio's Notification Center as the expiration date nears, first as a warning and in the final days as an error.
  • RavenDB also publishes the certificate's expiration over SNMP, which an external monitoring tool can poll.
    The certificate is marked as expiring once its remaining validity falls below the number of days set by Security.Certificate.ExpiringThresholdInDays (14 days by default).

If you install the server using the Setup Wizard and Let's Encrypt, RavenDB renews the certificate automatically.
See automatic Let's Encrypt renewals.

If you provide your own certificate, renewing it before it expires is your responsibility.
See certificate renewal and rotation.

In this article