Skip to content

Update the ssl config for backup #2610

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: dev
Choose a base branch
from
+94 −40
Open

Update the ssl config for backup #2610

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1cfc0bf
update the ssl config for backup
renetapopova Sep 18, 2025
daf91b0
apply suggestions from review
renetapopova Sep 24, 2025
56d6369
update the note
renetapopova Sep 24, 2025
df84034
apply suggestions from review
renetapopova Sep 25, 2025
8130ff3
apply suggestions from review
renetapopova Sep 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions modules/ROOT/pages/backup-restore/online-backup.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -317,12 +317,22 @@ The SSL configuration policy has the key of `dbms.ssl.policy.backup`.

As an example, add the following content to your _neo4j.conf_ and _neo4j-admin.conf_ files:

.Server configuration in _neo4j.conf_
[source, properties]
----
dbms.ssl.policy.backup.enabled=true
dbms.ssl.policy.backup.tls_versions=TLSv1.2
dbms.ssl.policy.backup.ciphers=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
dbms.ssl.policy.backup.client_auth=REQUIRE
dbms.ssl.policy.backup.tls_versions=TLSv1.2,TLSv1.3
dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
----

.Client configuration in _neo4j-admin.conf_
[source, properties]
----
dbms.ssl.policy.backup.enabled=true
dbms.ssl.policy.backup.client_auth=REQUIRE
dbms.ssl.policy.backup.tls_versions=TLSv1.2,TLSv1.3
dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
----

[TIP]
Expand Down
120 changes: 82 additions & 38 deletions modules/ROOT/pages/security/ssl-framework.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,7 +180,7 @@ You can identify them by the line `-----BEGIN RSA PRIVATE KEY-----` at the begin
While Neo4j 5.0 can load and use those keys, they are considered deprecated and will be removed in a future version.
====


[[ssl-validate-certs]]
=== Validate the key and the certificate

If you need, you can validate the key file and the certificate as follows:
Expand Down Expand Up @@ -655,22 +655,23 @@ openssl s_client -connect my_domain.com:7473
Intra-cluster encryption is the security solution for the cluster communication.
The Neo4j cluster communicates on 3 ports:

* 6000 - Transactions
* 7000 - Raft communications
* 7688 - Server side routing
* `6000` - Transactions
* `7000` - Raft communications
* `7688` - Server side routing

To configure SSL for intra-cluster communication, create the folder structure and place the key and certificate files under it.
Then, configure the SSL cluster policies in the _neo4j.conf_ file and test that the intra-cluster communication is encrypted.

To set up intra-cluster encryption, on each server create the folder structure and place the key file and the certificates under those.
Then, you need to configure the SSL cluster policies in the _neo4j.conf_ file and test that the intra-cluster communication is encrypted.
==== Set up SSL certificates for intra-cluster communications

. Set up the _cluster_ folder under _certificates_.
.. Create a directory _cluster_ under_<NEO4J_HOME>/certificates_ folder:
. Create a directory _cluster_ under _<NEO4J_HOME>/certificates_ folder:
+
[source, shell]
----
mkdir certificates/cluster
----

.. Create a directory _trusted_ and _revoked_ under _<NEO4J_HOME>/certificates/cluster_ folder:
. Create a directory _trusted_ and _revoked_ under _<NEO4J_HOME>/certificates/cluster_ folder:
+
[source, shell]
----
Expand Down Expand Up @@ -703,9 +704,11 @@ Thus, the servers are able to establish trust relationships with each other.
----
cp /path/to/certs/public.crt certificates/cluster/revoked
----
+

==== Verify the folder structure and permissions

The folder structure should look like this with the right file permissions and the groups and ownerships:
+

[options="header", cols="3,1,4*m"]
|===
| Path
Expand Down Expand Up @@ -757,21 +760,22 @@ The folder structure should look like this with the right file permissions and t
| 0755
| drwxr-xr-x
|===
+

[TIP]
====
The owner/group should be configured to the user/group that will be running the `neo4j` service.
Default user/group is neo4j/neo4j.
====

. Set the cluster SSL configuration in _neo4j.conf_.
.. Set the cluster SSL policy to `true`:
==== Set the cluster SSL configuration in _neo4j.conf_

. Set the cluster SSL policy to `true`:
+
[source, properties]
----
dbms.ssl.policy.cluster.enabled=true
----
.. Set the appropriate certificates path and the right key and cert files:
. Set the appropriate certificates path and the right key and cert files:
+
[source, properties]
----
Expand All @@ -785,7 +789,7 @@ dbms.ssl.policy.cluster.public_certificate=public.crt
If the certificate is a different path outside of NEO4J_HOME, then set the absolute path for the certificates directory.
====

.. Set the cluster client authentication to `REQUIRE` to enable the mutual authentication, which means that both ends of a channel have to authenticate:
. Set the cluster client authentication to `REQUIRE` to enable the mutual authentication, which means that both ends of a channel have to authenticate:
+
[source, properties]
----
Expand All @@ -799,14 +803,16 @@ The actual xref:security/ssl-framework.adoc#term-ssl-cryptographic-objects[crypt
The trusted CA certificate will be shared however.
====

.. Verify that the intra-cluster communication is encrypted.
==== Verify that the intra-cluster communication is encrypted

Once the intra-cluster encryption is enabled, you can verify that the communication is encrypted.
You may use an external tooling, such as Nmap (https://nmap.org/download.html):
+

[source, shell]
----
nmap --script ssl-enum-ciphers -p <port> <hostname>
----
+

[NOTE]
====
The hostname and port have to be adjusted according to your configuration.
Expand All @@ -823,24 +829,28 @@ For more details on securing the comunication between the cluster servers, see x
[[ssl-backup-config]]
=== Configure SSL for backup communication

In a single instance, by default the backup communication happens on port `6362`.
In a cluster topology, it is possible to take a backup from any server, and each server has two configurable ports capable of serving a backup.
These ports are configured by `dbms.backup.listen.address` (port `6362`) and `server.cluster.listen_address` (port `6000`) respectively.
If the intra-cluster encryption is enabled and the backup communication is using port `6000`, then your communication channels are already encrypted.
The following steps assumes that your backup is set up on a different port.
In a single instance, the backup communication happens on port `6362` by default. +
In a cluster topology, it is possible to take a backup from any server, and each server has two configurable ports capable of serving a backup:

* `dbms.backup.listen.address` (port `6362`)
* `server.cluster.listen_address` (port `6000`)

If the <<ssl-cluster-config, intra-cluster encryption>> is enabled and the backup communication uses port `6000`, then the communication channels are already encrypted.
The following steps assume that your backup is set up on a different port.

==== Set up SSL certificates for backup

To set up SSL for backup communication, create the folder structure and place the key file and the certificates under those.
Then, you need to configure the SSL backup policies in the _neo4j.conf_ file.
Create the folder structure and place the key and certificate files under it.
Then, configure the SSL backup policies in the _neo4j.conf_ file.

. Set up the _backup_ folder under _certificates_.
.. Create a directory _backup_ under _<NEO4J_HOME>/certificates_ folder:
. Create a directory _backup_ under _<NEO4J_HOME>/certificates_ folder:
+
[source, shell]
----
mkdir certificates/backup
----

.. Create a directory _trusted_ and _revoked_ under _<NEO4J_HOME>/certificates/backup_ folder:
. Create a directory _trusted_ and _revoked_ under _<NEO4J_HOME>/certificates/backup_ folder:
+
[source, shell]
----
Expand All @@ -867,9 +877,11 @@ cp /path/to/certs/public.crt certificates/backup/trusted
----
cp /path/to/certs/public.crt certificates/backup/revoked
----
+
The folder structure should look like this with the right file permissions and the groups and ownerships:
+

==== Verify the backup folder structure and permissions

The folder structure should look like this with the right file permissions and the groups and ownerships, assuming the `neo4j` user runs the service:

[options="header", cols="3,1,4*m"]
|===
| Path
Expand Down Expand Up @@ -921,21 +933,22 @@ The folder structure should look like this with the right file permissions and t
| 0755
| drwxr-xr-x
|===
+

[TIP]
====
The owner/group should be configured to the user/group that will be running the `neo4j` service.
Default user/group is neo4j/neo4j.
====

. Set the backup SSL configuration in _neo4j.conf_.
.. Set the backup SSL policy to `true`:
==== Set the backup SSL configuration in the _neo4j.conf_ file.

. Set the backup SSL policy to `true`:
+
[source, properties]
----
dbms.ssl.policy.backup.enabled=true
----
.. Set the appropriate certificates path and the right key and cert files:
. Set the appropriate certificates path and the right key and cert files:
+
[source, properties]
----
Expand All @@ -949,13 +962,44 @@ dbms.ssl.policy.backup.public_certificate=public.crt
If the certificate is a different path outside of NEO4J_HOME, then set the absolute path for the certificates directory.
====

.. Set the backup client authentication to `REQUIRE` to enable the mutual authentication, which means that both ends of a channel have to authenticate:
. Set the backup client authentication to `REQUIRE` to enable the mutual authentication, which means that both ends of a channel have to authenticate:
+
[source, properties]
----
dbms.ssl.policy.backup.client_auth=REQUIRE
----

=== Configure the backup client for SSL
Copy link

@thelonelyvulpes thelonelyvulpes Sep 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

bit of a meta comment, but it might be worth including in the documentation, we do not the validate the keys of ssl policy values so
dbms.ssl.policy.backup.foo will parse happily but will not help, so it is important that users validate the config keys when configuring SSL, dbms.ssl.policy.backup.trusted_directory got me as it must be dbms.ssl.policy.backup.trusted_dir which is inconsistent with *.base_directory


When using `neo4j-admin backup` command, the backup client needs to be configured to use SSL as well.
Regardless of which backup port you are targeting (see <<ssl-backup-config>>), the backup client uses the SSL policy specified in `dbms.ssl.policy.backup.*`, given the same SSL policy name matches between server and client.

[NOTE]
====
If the backup client is on a different machine from the Neo4j server, you must install sympathetic SSL certificates and keys on the backup client machine as well, so that the backup client can authenticate the server and vice versa.
If you want mutual TLS with self-signed certificates, the server must have the client's certificate in its _trusted_dir_, and the client must have the server's certificate in its _trusted_dir_.
If you use a certificate authority (CA) to signs both the client's and server's certificates, the _trusted_dir_ must contain only the CA or intermediate certificates.

Furthermore, Neo4j does not validate the certificates.
It is your responsibility to ensure that the certificates are valid.
See <<ssl-certificates>> for details.
====

Configure the SSL backup policies in the _neo4j-admin.conf_ file on the backup client machine.

For example, if you have set up the backup SSL policy described in section <<ssl-backup-config>>, then you need to set the following in the _neo4j-admin.conf_ file:

[source, properties]
----
dbms.ssl.policy.backup.enabled=true
dbms.ssl.policy.backup.base_directory=certificates/backup
dbms.ssl.policy.backup.private_key=private.key
dbms.ssl.policy.backup.public_certificate=public.crt
dbms.ssl.policy.backup.client_auth=REQUIRE
dbms.ssl.policy.backup.tls_versions=TLSv1.2,TLSv1.3
dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
----

[[ssl-other-configs]]
=== Other configurations for SSL

Expand Down Expand Up @@ -1150,7 +1194,7 @@ This means that while new connections will use new certificates, the existing co
Even if a certificate expires, active connections remain unaffected because the certificates are only used during the initial connection handshake.

. 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
Expand Down