Documentation for TLS certificate rotation feature #2165
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -1108,6 +1108,44 @@ Beware that the SSL debug option logs a new statement every time a client connec | |
| To avoid that scenario, make sure this setting is only enabled for a short term duration. | ||
| ==== | ||
|
|
||
| [role=label--new-2025.03] | ||
| [[certificate-rotation]] | ||
| == Certificates rotation | ||
|
|
||
| It is considered best practice to use certificates with reasonably short duration. | ||
| This, however, requires the periodic rotation of certificates whereby old certificates are removed and the new ones are installed. | ||
| Previous versions of Neo4j required a database restart for changes to be applied. | ||
| Starting from 2025.03, new certificates can be rotated in, and SSL configuration can be updated without requiring a restart. | ||
| This reduces undesirable effects of transient loss of cluster members. | ||
|
|
||
| Following are the steps of newly introduced certificates rotation. | ||
tonbut marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| . Enable the dynamic reloading of certificates on all cluster members. | ||
| It is best to do this when the cluster is deployed as changing this configuration requires a restart: | ||
|
|
||
| [source, properties] | ||
| ---- | ||
| dbms.security.tls_reload=true (default is false) | ||
|
There was a problem hiding this comment. if this setting needs to be set up to There was a problem hiding this comment. One more question: Do we need to mention this setting above https://neo4j.com/docs/operations-manual/current/security/ssl-framework/#ssl-configuration? where we talk about SSL configuration settings There was a problem hiding this comment. We could mention it on https://neo4j.com/docs/operations-manual/current/clustering/setup/deploy/ but I don't think we should - it's an optional feature and we don't mention SSL setup anywhere else on that page. I guess same applies to Docker and Kubernetes sections. I don't think it needs to go above the other settings - again this is an optional feature and isn't required knowledge to fully understand and deploy the SSL configuration |
||
| ---- | ||
|
|
||
| . Replace old certificates either by overwriting on the filesystem or by copying them to a new location and updating the required SSL configuration for each effected scope. | ||
| Both certificates may exist on the filesystem but only one can be referenced in the configuration. | ||
tonbut marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| New certificates need to be copied to all cluster members as required. | ||
|
|
||
| . Make necessary changes to any of the SSL configuration and/or replace certificates for effected scopes. | ||
|
|
||
| . Connect to each cluster member in turn with Cypher Shell using a <<ssl-bolt-connect,`bolt` URI scheme>> and run the reload procedure: | ||
|
|
||
| [source] | ||
| ---- | ||
| dbms.reloadTLSCertificates() | ||
|
There was a problem hiding this comment. Is this a new procedure? Our test didn't show yet that we miss a procedure on our page https://neo4j.com/docs/operations-manual/current/procedures/. But looks like we need to add in this procedure there There was a problem hiding this comment. Yes it's a new procedure but not merged yet. I'll add it to this page too once we agree the name. |
||
| ---- | ||
|
|
||
| . New settings will take effect immediately, however existing connections will not be pre-emptively terminated. | ||
|
There was a problem hiding this comment. I think I need more details here. Does this mean that new connections will use new certificates, but the existing connections (established before the update) will continue using the old certificates until they expire? There was a problem hiding this comment. Yes exactly. It will not terminate existing connection. But any new connections will use the new certificates There was a problem hiding this comment. Even expired certificates won't cause a connection to terminate. The certificates are only used during the connection negotiation stage |
||
|
|
||
| . Verify that the intra-cluster communication is still encrypted using external tooling, such as Nmap, described in <<ssl-cluster-config, Configuring SSL for intra-cluster communications>>. | ||
|
|
||
|
|
||
| [[ssl-terminology]] | ||
| == Terminology | ||
|
|
||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do we need to specify here: TLS certificates rotation?