diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index af72f60c9..4b0a6b97b 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -73,6 +73,7 @@ * xref:configuration/index.adoc[] ** xref:configuration/neo4j-conf.adoc[] +** xref:configuration/command-expansion.adoc[] ** xref:configuration/file-locations.adoc[] //** xref:configuration/network-architecture.adoc[] ** xref:configuration/ports.adoc[] diff --git a/modules/ROOT/pages/configuration/command-expansion.adoc b/modules/ROOT/pages/configuration/command-expansion.adoc new file mode 100644 index 000000000..dcfbf0b82 --- /dev/null +++ b/modules/ROOT/pages/configuration/command-expansion.adoc @@ -0,0 +1,93 @@ +[[neo4j-conf-expand-commands]] += Command expansion +:description: Command expansion provides an additional capability to configure Neo4j by allowing you to specify scripts that set values sourced from external files. +:page-aliases: configuration/neo4j-conf.adoc#neo4j-conf-expand-commands + +Command expansion provides an additional capability to configure Neo4j by allowing you to specify scripts that set values sourced from external files. +This is especially useful for: + +* avoiding setting sensitive information, such as usernames, passwords, keys, etc., in the _neo4j.conf_ file in plain text. +* handling the configuration settings of instances running in environments where the file system is not accessible. + +== How it works + +The scripts are specified in the _neo4j.conf_ file with a `$` prefix and the script to execute within brackets (), i.e., `dbms.setting=$(script_to_execute)`. + +The configuration accepts any command that can be executed within a child process by the user who owns and executes the Neo4j server. +This also means that, in the case of Neo4j set as a service, the commands are executed within the service. + +A generic example would be: + +[source, role=nocopy] +---- +neo4j.configuration.example=$(/bin/bash echo "expanded value") +---- + +By providing such a configuration in the _neo4j.conf_ file upon server start with command expansion enabled, Neo4j evaluates the script and retrieves the value of the configuration settings prior to the instantiation of Neo4j. +The values are then passed to the starting Neo4j instance and kept in memory, in the running instance. + +[NOTE] +==== +You can also use the `curl` (https://curl.se/docs/manpage.html) command to fetch a token or value for a configuration setting. +For example, you can apply an extra level of security by replacing any sensitive information in your _neo4j.conf_ file with a secured reference to a provider of some sort. +==== + +Scripts are run by the Neo4j process and are expected to exit with code `0` within a reasonable time. +The script output should be of a valid type for the setting. +Failure to do so prevents Neo4j from starting. + +[NOTE] +==== +Scripts and their syntax differ between operating systems. +==== + +== Enabling + +The Neo4j startup script and the `neo4j` service can expand and execute the external commands by using the argument `--expand-commands`. + +[source, shell] +---- +bin/neo4j start --expand-commands +---- + +If the startup script does not receive the `--expand-commands` argument, commands in the configuration file are treated as invalid settings. + +Neo4j performs the following basic security checks on the _neo4j.conf_ file. +If they fail, Neo4j does not evaluate the script commands in _neo4j.conf_, and the Neo4j process does not start. + +On Unix (both Linux and Mac OS):: + +* The _neo4j.conf_ file must, at least, be readable by its owner or by the user-group to which the owner belongs. +* The Neo4j process must run as a user who is either the owner of the _neo4j.conf_ file or in the user-group which owns the _neo4j.conf_ file. + +[NOTE] +==== +The Linux permissions bitmask for the least restrictive permissions is `640`. +More restrictive Linux permissions are also allowed. +For example, the _neo4j.conf_ file can have no group permissions and only be readable by its owner (`400` bitmask). +==== + +On Windows:: + +* The _neo4j.conf_ file must, at least, be readable by the user that the Neo4j process runs as. + +== Logging + +The execution of scripts is logged in _neo4j.log_. +For each setting that requires the execution of an external command, Neo4j adds an entry into the log file that contains information, for example: + +[source, role=noheader] +---- +… Executing the external script to retrieve the value of ... +---- + +== Error Handling + +The scripts' execution may generate two types of errors: + +* Errors during the execution -- These errors are reported in the _debug.log_, with a code returned from the external execution. +In this case, the execution stops and the server does not start. + +* Errors for incorrect values -- The returned value is not the one expected for the setting. +In this case, the server does not start. + +For more information, see xref:tools/neo4j-admin/index.adoc#neo4j-admin-exit-codes[Exit codes]. \ No newline at end of file diff --git a/modules/ROOT/pages/kubernetes/operations/maintenance-mode.adoc b/modules/ROOT/pages/kubernetes/operations/maintenance-mode.adoc index ee8af1508..28e0a73ae 100644 --- a/modules/ROOT/pages/kubernetes/operations/maintenance-mode.adoc +++ b/modules/ROOT/pages/kubernetes/operations/maintenance-mode.adoc @@ -20,7 +20,7 @@ kubectl exec -0 -- neo4j-admin store-info --all /var/lib/neo4j/dat [NOTE] ==== All `neo4j-admin` commands need the `--expand-commands` flag to run in the Neo4j container. -This is because the Neo4j Helm chart defines the Neo4j configuration using command expansion to dynamically resolve some configuration parameters at runtime. +This is because the Neo4j Helm chart defines the Neo4j configuration using xref:configuration/command-expansion.adoc[command expansion] to dynamically resolve some configuration parameters at runtime. ==== To run a series of commands, use an interactive shell: diff --git a/modules/ROOT/pages/manage-databases/remote-alias.adoc b/modules/ROOT/pages/manage-databases/remote-alias.adoc index 28267f056..5208da56a 100644 --- a/modules/ROOT/pages/manage-databases/remote-alias.adoc +++ b/modules/ROOT/pages/manage-databases/remote-alias.adoc @@ -139,9 +139,10 @@ The following configuration is necessary for creating a remote database alias: [options="header" cols="m,a"] |=== | Configuration | Description -| <> | The absolute path to the keystore file, including the file name. -| <> | The password to the keystore file. Use xref:configuration/neo4j-conf.adoc#neo4j-conf-expand-commands[Command expansion] to set the password. -| <> | The name of the secret key +| xref:configuration/configuration-settings.adoc#config_dbms.security.keystore.path[`dbms.security.keystore-path`] +| The absolute path to the keystore file, including the file name. +| xref:configuration/configuration-settings.adoc#config_dbms.security.keystore.password[`dbms.security.keystore-password`] | The password to the keystore file. Use xref:configuration/command-expansion.adoc[Command expansion] to set the password. +| xref:configuration/configuration-settings.adoc#config_dbms.security.key.name[`dbms.security.key.name`] | The name of the secret key |=== [CAUTION] diff --git a/modules/ROOT/pages/security/ssl-framework.adoc b/modules/ROOT/pages/security/ssl-framework.adoc index dec887d03..08df0eb80 100644 --- a/modules/ROOT/pages/security/ssl-framework.adoc +++ b/modules/ROOT/pages/security/ssl-framework.adoc @@ -949,7 +949,7 @@ dbms.ssl.policy.bolt.private_key_password=$(openssl aes-256-cbc -a -d -in passwo [NOTE] ==== Using a dynamic command requires Neo4j to be started with the `--expand-commands` option. -For more information, see xref:configuration/neo4j-conf.adoc#neo4j-conf-expand-commands[Command expansion]. +For more information, see xref:configuration/command-expansion.adoc[Command expansion]. ==== ==== Using specific cipher