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 4 commits into
base: dev
Choose a base branch
from
Open

Update the ssl config for backup #2610

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ab1f0ce
update the ssl config for backup
renetapopova Sep 18, 2025
5bd7de5
apply suggestions from review
renetapopova Sep 24, 2025
61e7f49
update the note
renetapopova Sep 24, 2025
53d220d
apply suggestions from review
renetapopova Sep 25, 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
27 changes: 25 additions & 2 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 @@ -928,7 +928,7 @@ The owner/group should be configured to the user/group that will be running the
Default user/group is neo4j/neo4j.
====

. Set the backup SSL configuration in _neo4j.conf_.
. Set the backup SSL configuration in the _neo4j.conf_ file.
.. Set the backup SSL policy to `true`:
+
[source, properties]
Expand Down Expand Up @@ -956,6 +956,29 @@ If the certificate is a different path outside of NEO4J_HOME, then set the absol
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, you need to specify the SSL policy to be used by the backup client.
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.

I think this doesn't make it entirely clear that you can back up against the cluster endpoint(6000 default) and its SSL policy dbms.ssl.policy.cluster.*, or the backup endpoint(6362 default) and its SSL policy dbms.ssl.policy.backup.*, but regardless of which you do back up against, the admin client will use the SSL policy specified for backups dbms.ssl.policy.backup.*

You can do this by setting a matching SSL configuration in the _neo4j.conf_ and _neo4j-admin.conf_ files.
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.

It is not entirely true that they must match, but be sympathetic of/mirror one another.
i.e., if they want mutualTLS 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

Copy link

Choose a reason for hiding this comment

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

However, when they use a certificate authority to signs both the client's and server's certificates, the trusted_dir only needs to contain an intermediate CA cert.

This is crucial for the backup to work properly.
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=/path/to/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
----

[NOTE]
====
Keep in mind that if the backup client is on a different machine from the Neo4j server, you must install the same SSL certs and keys on the backup client machine as well, so that the backup client can authenticate the server and vice versa.
====

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

Expand Down Expand Up @@ -1150,7 +1173,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