Configuration
The programs and tools shipped in an ArangoDB package can be configured with various startup options.
-
Startup options you specify on a command line are referred to as command line options:
arangosh --server.database myDB --server.username Jay -
The same options can also be set via configuration files, using a slightly different syntax:
server.database = myDB server.username = JayOr more compact like this:
[server] database = myDB username = Jay -
There are also commands that are intended for command line usage only, such as
‑‑helpand‑‑version.
Available startup options
Find the available options and commands in the Options sub-chapters of the respective Programs & Tools sub-chapter, like the ArangoDB Server Options.
The ArangoDB Starter works differently
to the other programs and tools. It uses setup.json files for its own
configuration
and has a fluent command line interface to execute certain actions.
If you deploy ArangoDB with the Starter, then custom arangod.conf files
are generated by this tool and are used instead of the default configuration.
Command line options
Command line options can be supplied in the style ‑‑option value with two
dashes (also known as hyphen minus), the name of the option, a space as
separator and the value. You may also use an equals sign = as separator
like ‑‑option=value.
The value can be surrounded with double quote marks " like
‑‑option="value". This is mandatory if the value contains spaces,
but it is optional otherwise.
Boolean options that you want to enable do not need to be set to true
explicitly. For example, --log.role is equivalent to --log.role true.
Some binaries accept one unnamed argument, which means you can take a
shortcut and leave out the ‑‑option part and supply the value directly.
It does not matter if you supply it as first or last argument, or between
any of the named arguments. For arangod it is the ‑‑database.directory
option. The following commands are identical:
arangod my_data_dir
arangod "my_data_dir"
arangod --database.directory my_data_dir
arangod --database.directory=my_data_dir
arangod --database.directory "my_data_dir"
arangod --database.directory="my_data_dir"
Many options belong to a section as in ‑‑section.param, e.g.
‑‑server.database, but there can also be options without any section.
These options are referred to as general options.
To list available options, you can run a binary with the ‑‑help command:
arangosh --help
To list the options of a certain section only, use ‑‑help‑{section},
like ‑‑help‑server. To list all options including hidden ones use
--help-all.
Configuration file format
.conf files for ArangoDB binaries are in a simple key-value pair format.
Each option is specified on a separate line in the form:
key = value
It may look like this:
server.endpoint = tcp://127.0.0.1:8529
server.authentication = true
Alternatively, a header section can be specified and options pertaining to that section can be specified in a shorter form:
[server]
endpoint = tcp://127.0.0.1:8529
authentication = true
So you see, a command line option ‑‑section.param value can be easily
translated to an option in a configuration file:
[section]
param = value
Whitespace around = is ignored in configuration files.
This includes whitespace around equality signs in the parameter value:
log.level = startup = trace
It is the same as without whitespace:
log.level=startup=trace
Comments can be placed in the configuration file by placing one or more
hash symbols # at the beginning of a line. Comments that are placed in
other places (i.e. not at the beginning of a line) are unsupported and should
be avoided to ensure correct parsing of the startup options as intended.
Commands like --version should not be used in configuration files
(version = true) because the process will terminate after executing the
command, potentially giving the impression that it failed to start.
Using Configuration Files
For each binary (except arangodb, which is the Starter) there is a
corresponding .conf file that an ArangoDB package ships with.
arangosh.conf contains the default ArangoShell configuration for instance.
The configuration files can be adjusted or new ones be created.
To load a particular configuration file, there is a ‑‑configuration option
available to let you specify a path to a .conf file. If you want to
completely ignore a configuration file (likely the default one) without
necessarily deleting the file, then add the command line option
-c none
or
--configuration none
The value none is case-insensitive.
Suffixes for Numeric Options
It is possible to add suffixes to numeric options that will cause ArangoDB to multiply the value by a certain factor. This can be used to conveniently specify values in megabytes or gigabytes for example.
| Suffix | Factor | Example |
|---|---|---|
kib, KiB |
1024 | 512KiB |
mib, MiB |
1024 ^ 2 | 64mib |
gib, GiB |
1024 ^ 3 | 3gib |
k, K, kb, KB |
1000 | 3k |
m, M, mb, MB |
1000 ^ 2 | 3mb |
g, G, gb, GB |
1000 ^ 3 | 3GB |
% |
0.01 | 5% |
Suffix could be used like this in a configuration file:
[rocksdb]
write-buffer-size=512KiB
block-cache-size=512MiB
total-write-buffer-size=2GiB
max-bytes-for-level-multiplier=1K
[cache]
size=2G
Environment variables as parameters
If you want to use an environment variable in a value of a startup option,
write the name of the variable wrapped in at signs @. It acts as a
placeholder. It can be combined with fixed strings for instance.
For literal at signs in startup option arguments, escape them like @@.
Command line example:
arangod --temp.path @TEMP@/arango_tmp
In a configuration file:
[temp]
path = @TEMP@/arango_tmp
On a Windows system, above setting would typically make the ArangoDB Server
create its folder for temporary files in %USERPROFILE%\AppData\Local\Temp,
i.e. C:\Users\xxx\AppData\Local\Temp\arango_tmp.
Options with multiple values
Certain startup options accept multiple values. In case of parameters being
vectors you can specify one or more times the option with varying values.
Whether this is the case can be seen by looking at the Type column of a
tool’s option table (e.g. ArangoDB Server Options)
or the type information provided on a command line in the --help output of
an ArangoDB binary:
--log.level <string...> the global or topic-specific log level
Vectors can be identified by the three dots ... at the end of the data type
information (in angled brackets). For log.level you can set one or more
strings for different log levels for example. Simply repeat the option to
do so. On a command line:
arangod --log.level all=warning --log.level queries=trace --log.level startup=info
This sets a global log level of warning and two topic-specific levels
(trace for queries and info for startup). Note that --log.level warning
does not set a log level globally for all existing topics, but only the
general topic.
The same in a configuration file:
[log]
level = all=warning
level = queries=trace
level = startup=info
Configuration precedence
There are built-in defaults, with which all configuration variables are first initialized. They can be overridden by configuration files and command line options (in this order). Only a fraction of all available options are set in the configuration files that ArangoDB ships with. Many options will therefore fall back to the built-in defaults unless they are overridden by the user.
It is common to use modified configuration files together with startup options on a command line to override specific settings. Command line options take precedence over values set in a configuration file.
If the same option is set multiple times, but only supports a single value,
then the last occurrence of the option will become the final value.
For example, if you edit arangosh.conf to set:
server.database = myDB1
server.database = myDB2
… and start ArangoShell like:
arangosh --server.database myDB3 --server.database myDB4
… then the database it will connect to is myDB4, because this startup option
takes a single value only (i.e. it is not a vector), the built-in default
is _system but the configuration file overrules the setting. It gets set to
myDB1 temporarily before it is replaced by myDB2, which in turn gets
overridden by the command line options twice, first to myDB3 and then the
final value myDB4.
Change configuration at runtime
In general, supplied startup options can not be changed nor can configuration files be reloaded once an executable is started, other than by restarting the executable with different options. However, some of the startup options define default values which can be overridden on a per-query basis for instance, or adjusted at runtime via an API call. Examples:
- Query cache configuration via JavaScript API
Fetch Current Configuration Options
To list the configuration options of a running arangod instance, you can
connect with an ArangoShell and invoke a
Transaction by calling db._executeTransaction()
and providing a JavaScript function to retrieve the server options: