The neo4j.conf file
The neo4j.conf file is the main source of configuration settings in Neo4j and includes the mappings of configuration setting keys to values. The location of the neo4j.conf file in the different configurations of Neo4j is listed in Default file locations.
Most of the configuration settings in the neo4j.conf file apply directly to Neo4j itself, but there are also other settings related to the Java Runtime (the JVM) on which Neo4j runs.
For more information, see the JVM specific configuration settings.
Many of the configuration settings are also used by neo4j
launcher scripts.
neo4j.conf
conventions
The syntax in the neo4j.conf
file follows the following conventions:
-
The equals sign (
=
) maps configuration setting keys to configuration values. -
Lines that start with the number sign (
#
) are handled as comments. -
Trailing comments are not supported.
-
Empty lines are ignored.
-
Configuring a setting in neo4j.conf overwrites any default values. If you want to amend the default values with custom ones, you must explicitly list the default values along with the new ones.
-
The configuration settings are not ordered.
-
The configuration settings have strict validation enabled by default. It prevents Neo4j from starting if the neo4j.conf file contains typos, incorrect information, or duplicates (except for
server.jvm.additional
). If you set more than one value forserver.jvm.additional
, each setting value adds another custom JVM argument to thejava
launcher.To disable the strict validation, set
server.config.strict_validation.enabled=false
. -
By default, the character encoding is assumed to be ISO 8859-1. From Neo4j 4.8 onwards, this can be overridden by setting the environment variable
NEO4J_CONFIG_FILE_CHARSET
to, for example,utf8
.
Configuration settings
General synopsis
Neo4j configuration settings have the following general synopsis:
<prefix>.<scope>.<component>….<component>.<name>
- Prefix
-
Prefixes are reserved for denoting two special cases (most settings do not have a prefix):
-
initial
— Settings that are only used during the initialization but are ignored thereafter. For example,initial.server.mode_constraint
,initial.dbms.default_database
, etc. -
internal
— The prefix replaces the termsunsupported
andexperimental
used in previous versions. This namespace is dedicated to features that are used internally and may change without notice.
-
- Scope
-
All configuration settings fall into one of the following scopes that behave differently:
-
db
settings can be varied between each database but must be consistent across all configuration files in a cluster/DBMS. -
dbms
settings must be consistent across all configuration files in a cluster/DBMS. -
server
settings apply only to the specific server and can be varied between configuration files across a cluster/DBMS. -
browser
settings apply only to Neo4j Browser. -
client
settings apply only to the client.In Neo4j 5, the
fabric
scope is no longer available. All configuration settings identified by thefabric
namespace in theneo4j.conf
file are moved into thesystem
database. The Cypher surface is extended to support the Fabric configuration.For more information, see Composite databases.
-
- Component
-
Component namespaces are used to group settings that affect similar systems.
- Name
-
The name of the setting. It may contain a common verb and unit patterns, such as
size
,enabled
, etc. Words are separated by an underscore.
For a complete reference of Neo4j configuration settings, see Configuration settings. |
JVM-specific configuration settings
A Java virtual machine (JVM) is a virtual machine that enables a computer to run Java programs and programs written in other languages that are also compiled in Java bytecode. The Java heap is where the objects of a Java program live. Depending on the JVM implementation, the JVM heap size often determines how and for how long time the virtual machine performs garbage collection.
Setting | Description |
---|---|
Sets the initial heap size for the JVM. By default, the JVM heap size is calculated based on the available system resources. |
|
Sets the maximum size of the heap for the JVM. By default, the maximum JVM heap size is calculated based on the available system resources. |
|
Sets additional options for the JVM. The options are set as a string and can vary depending on JVM implementation. |
If you want to have good control of the system behavior, it is recommended to set the heap size parameters to the same value to avoid unwanted full garbage collection pauses. |
List currently active settings
You can use SHOW SETTINGS
to list the currently active configuration settings and their values.
SHOW SETTINGS
YIELD name, value
WHERE name STARTS WITH 'server.default'
RETURN name, value
ORDER BY name
LIMIT 3;
+---------------------------------------------------+ | name | value | +---------------------------------------------------+ | "server.default_advertised_address" | "localhost" | | "server.default_listen_address" | "localhost" | +---------------------------------------------------+
For information about dynamic settings, see Update dynamic settings and Configuration settings reference. |
Command expansion
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:
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.
You can also use the |
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.
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
.
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.
-
The Linux permissions bitmask for the least restrictive permissions is |
- 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:
… Executing the external script to retrieve the value of <setting>...
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 Exit codes.
Was this page helpful?