Configuration

The programs and tools shipped in anArangoDB package can be configured with various startup options.

• Startup options you specify on a command line are referred to ascommand line options:

arangosh —server.database myDB

• The same options can also be set viaconfiguration files,using a slightly different syntax:

server.database = myDB

• There are also flags which are for command line usage only,such as ‑‑help and ‑‑version. They don’t take any valuein contrast to options.

Find the available options and flags in the Options sub-chapters of therespective Programs & Tools sub-chapter, like theArangoDB Server Options.

The ArangoDB Starter works differentlyto the other programs and tools. It uses setup.json files for its ownconfigurationand has a fluent command line interface to execute certain actions.If you deploy ArangoDB with the Starter, then custom arangod.conf filesare 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 twodashes (also known as hyphen minus), the name of the option, a space asseparator and the value. You may also use an equals sign = as separatorlike ‑‑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.

Some binaries accept one unnamed argument, which means you can take ashortcut 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 betweenany of the named arguments. For arangod it is the ‑‑database.directoryoption. 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 global options.

To list available options, you can run a binary with the ‑‑help flag:

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‑..

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 tothat 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 easilytranslated 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 morehash symbols # at the beginning of a line. Comments that are placed inother 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.

Only command line options with a value should be set within the configurationfile. Command line options which act as flags should only be entered on thecommand line when starting the server.

Using Configuration Files

For each binary (except arangodb, which is the Starter) there is acorresponding .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 optionavailable to let you specify a path to a .conf file. If you want tocompletely ignore a configuration file (likely the default one) withoutnecessarily 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 tomultiply the value by a certain factor. This can be used to conveniently specifyvalues in megabytes or gigabytes for example.

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 aplaceholder. It can be combined with fixed strings for instance.

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 Servercreate 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 beingvectors 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 atool’s option table (e.g. ArangoDB Server Options)or the type information provided on a command line in the —help output ofan 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 typeinformation (in angled brackets). For log.level you can set one or morestrings for different log levels for example. Simply repeat the option todo so. On a command line:

arangod --log.level 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). The same in a configuration file:

[log]
level = warning
level = queries=trace
level = startup=info

Configuration precedence

There are built-in defaults, with which all configuration variables are firstinitialized. They can be overridden by configuration files and command lineoptions (in this order). Only a fraction of all available options are set inthe configuration files that ArangoDB ships with. Many options will thereforefall back to the built-in defaults unless they are overridden by the user.

It is common to use modified configuration files together with startupoptions on a command line to override specific settings. Command line optionstake 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 optiontakes a single value only (i.e. it is not a vector), the built-in defaultis _system but the configuration file overrules the setting. It gets set tomyDB1 temporarily before it is replaced by myDB2, which in turn getsoverridden by the command line options twice, first to myDB3 and then thefinal value myDB4.

Change configuration at runtime

In general, supplied startup options can not be changed nor can configurationfiles be reloaded once an executable is started, other than by restarting theexecutable with different options. However, some of the startup optionsdefine default values which can be overridden on a per-query basis forinstance, or adjusted at runtime via an API call. Examples:

• Query cache configurationvia JavaScript API
• Change WAL settingsvia an HTTP API request

Fetch Current Configuration Options

To list the configuration options of a running arangod instance, you canconnect with an ArangoShell and invoke aTransaction by calling db._executeTransaction()and providing a JavaScript function to retrieve the server options:

arangosh> db._executeTransaction({ collections: {}, action: function() {return require("internal").options(); } })

Show execution results

Hide execution results

{ 
  "check-configuration" : false, 
  "config" : "/work/ArangoDB/etc/testing/arangod-single.conf", 
  "configuration" : "/work/ArangoDB/etc/testing/arangod-single.conf", 
  "console" : false, 
  "daemon" : false, 
  "default-language" : "en_US", 
  "define" : [ 
    "TOP_DIR=/work/ArangoDB" 
  ], 
  "dump-dependencies" : false, 
  "dump-options" : false, 
  "fortune" : false, 
  "gid" : "", 
  "hund" : false, 
  "log" : [ 
    "info", 
    "info", 
    "replication=warn" 
  ], 
  "pid-file" : "", 
  "supervisor" : false, 
  "uid" : "", 
  "version" : false, 
  "working-directory" : "/var/tmp", 
  "agency.activate" : false, 
  "agency.compaction-keep-size" : 50000, 
  "agency.compaction-step-size" : 1000, 
  "agency.disaster-recovery-id" : "", 
  "agency.election-timeout-max" : 5, 
  "agency.election-timeout-min" : 1, 
  "agency.endpoint" : [ ], 
  "agency.max-append-size" : 250, 
  "agency.my-address" : "", 
  "agency.pool-size" : 1, 
  "agency.size" : 1, 
  "agency.supervision" : false, 
  "agency.supervision-frequency" : 1, 
  "agency.supervision-grace-period" : 10, 
  "agency.wait-for-sync" : true, 
  "arangosearch.threads" : 0, 
  "arangosearch.threads-limit" : 0, 
  "audit.hostname" : "", 
  "audit.output" : [ ], 
  "backup.api-enabled" : "true", 
  "backup.local-path-prefix" : "/", 
  "cache.rebalancing-interval" : 2000000, 
  "cache.size" : 16341597184, 
  "cluster.agency-endpoint" : [ ], 
  "cluster.agency-prefix" : "", 
  "cluster.create-waits-for-sync-replication" : false, 
  "cluster.default-replication-factor" : 1, 
  "cluster.force-one-shard" : false, 
  "cluster.index-create-timeout" : 3600, 
  "cluster.max-number-of-shards" : 1000, 
  "cluster.max-replication-factor" : 10, 
  "cluster.min-replication-factor" : 1, 
  "cluster.my-address" : "", 
  "cluster.my-advertised-endpoint" : "", 
  "cluster.my-role" : "", 
  "cluster.require-persisted-id" : false, 
  "cluster.resign-leadership-on-shutdown" : false, 
  "cluster.synchronous-replication-timeout-factor" : 1, 
  "cluster.synchronous-replication-timeout-minimum" : 30, 
  "cluster.synchronous-replication-timeout-per-4k" : 0.1, 
  "cluster.system-replication-factor" : 2, 
  "cluster.upgrade" : "auto", 
  "cluster.write-concern" : 1, 
  "compaction.db-sleep-time" : 1, 
  "compaction.dead-documents-threshold" : 16384, 
  "compaction.dead-size-percent-threshold" : 0.1, 
  "compaction.dead-size-threshold" : 131072, 
  "compaction.max-file-size-factor" : 3, 
  "compaction.max-files" : 3, 
  "compaction.max-result-file-size" : 134217728, 
  "compaction.min-interval" : 10, 
  "compaction.min-small-data-file-size" : 131072, 
  "database.auto-upgrade" : false, 
  "database.check-version" : false, 
  "database.directory" : "/tmp/arangosh_oLGAal/rocksdb-clusterOrNot/data", 
  "database.force-sync-properties" : false, 
  "database.ignore-datafile-errors" : false, 
  "database.init-database" : false, 
  "database.maximal-journal-size" : 1048576, 
  "database.required-directory-state" : "any", 
  "database.restore-admin" : false, 
  "database.throw-collection-not-loaded-error" : false, 
  "database.upgrade-check" : true, 
  "database.wait-for-sync" : false, 
  "foxx.api" : true, 
  "foxx.queues" : true, 
  "foxx.queues-poll-interval" : 1, 
  "foxx.store" : true, 
  "frontend.proxy-request-check" : true, 
  "frontend.trusted-proxy" : [ ], 
  "frontend.version-check" : true, 
  "http.allow-method-override" : false, 
  "http.hide-product-header" : false, 
  "http.keep-alive-timeout" : 300, 
  "http.trusted-origin" : [ 
    "*" 
  ], 
  "javascript.allow-admin-execute" : true, 
  "javascript.allow-external-process-control" : false, 
  "javascript.allow-port-testing" : false, 
  "javascript.app-path" : "/tmp/arangosh_oLGAal/rocksdb-clusterOrNot/apps", 
  "javascript.copy-installation" : false, 
  "javascript.enabled" : true, 
  "javascript.endpoints-blacklist" : [ ], 
  "javascript.endpoints-whitelist" : [ ], 
  "javascript.environment-variables-blacklist" : [ ], 
  "javascript.environment-variables-whitelist" : [ ], 
  "javascript.files-whitelist" : [ ], 
  "javascript.gc-frequency" : 60, 
  "javascript.gc-interval" : 2000, 
  "javascript.harden" : false, 
  "javascript.module-directory" : [ 
    "/work/ArangoDB/enterprise/js" 
  ], 
  "javascript.script" : [ ], 
  "javascript.script-parameter" : [ ], 
  "javascript.startup-directory" : "/work/ArangoDB/js", 
  "javascript.startup-options-blacklist" : [ ], 
  "javascript.startup-options-whitelist" : [ ], 
  "javascript.v8-contexts" : 16, 
  "javascript.v8-contexts-max-age" : 60, 
  "javascript.v8-contexts-max-invocations" : 0, 
  "javascript.v8-contexts-minimum" : 1, 
  "javascript.v8-max-heap" : 3072, 
  "javascript.v8-options" : [ ], 
  "ldap.async-connect" : false, 
  "ldap.basedn" : "", 
  "ldap.binddn" : "", 
  "ldap.debug" : false, 
  "ldap.enabled" : false, 
  "ldap.network-timeout" : 0, 
  "ldap.port" : 389, 
  "ldap.prefix" : "", 
  "ldap.referrals" : false, 
  "ldap.refresh-rate" : 300, 
  "ldap.restart" : false, 
  "ldap.retries" : 1, 
  "ldap.roles-attribute-name" : "", 
  "ldap.roles-exclude" : "", 
  "ldap.roles-include" : "", 
  "ldap.roles-search" : "", 
  "ldap.roles-transformation" : [ ], 
  "ldap.search-attribute" : "uid", 
  "ldap.search-filter" : "objectClass=*", 
  "ldap.search-scope" : "sub", 
  "ldap.serialize-timeout" : 5, 
  "ldap.serialized" : false, 
  "ldap.server" : "", 
  "ldap.suffix" : "", 
  "ldap.superuser-role" : "", 
  "ldap.timeout" : 0, 
  "ldap.tls" : false, 
  "ldap.tls-cacert-dir" : "", 
  "ldap.tls-cacert-file" : "", 
  "ldap.tls-cert-check-strategy" : "hard", 
  "ldap.tls-version" : "1.2", 
  "ldap.url" : "", 
  "log.color" : true, 
  "log.escape" : true, 
  "log.file" : "/tmp/arangosh_oLGAal/rocksdb-clusterOrNot/log", 
  "log.file-group" : "", 
  "log.file-mode" : "", 
  "log.force-direct" : false, 
  "log.foreground-tty" : false, 
  "log.ids" : true, 
  "log.keep-logrotate" : false, 
  "log.level" : [ 
    "info", 
    "info", 
    "replication=warn" 
  ], 
  "log.line-number" : false, 
  "log.output" : [ 
    "file:///tmp/arangosh_oLGAal/rocksdb-clusterOrNot/log" 
  ], 
  "log.performance" : false, 
  "log.prefix" : "", 
  "log.request-parameters" : true, 
  "log.role" : true, 
  "log.shorten-filenames" : true, 
  "log.thread" : false, 
  "log.thread-name" : false, 
  "log.time-format" : "utc-datestring", 
  "log.use-local-time" : false, 
  "log.use-microtime" : false, 
  "network.idle-connection-ttl" : 60000, 
  "network.io-threads" : 1, 
  "network.max-open-connections" : 1024, 
  "network.verify-hosts" : false, 
  "nonce.size" : 4194304, 
  "query.cache-entries" : 128, 
  "query.cache-entries-max-size" : 268435456, 
  "query.cache-entry-max-size" : 16777216, 
  "query.cache-include-system-collections" : false, 
  "query.cache-mode" : "off", 
  "query.fail-on-warning" : false, 
  "query.memory-limit" : 0, 
  "query.optimizer-max-plans" : 128, 
  "query.optimizer-rules" : [ ], 
  "query.parallelize-gather-writes" : true, 
  "query.registry-ttl" : 30, 
  "query.slow-streaming-threshold" : 10, 
  "query.slow-threshold" : 10, 
  "query.smart-joins" : true, 
  "query.tracking" : true, 
  "query.tracking-with-bindvars" : true, 
  "random.generator" : 1, 
  "rclone.executable" : "rclone-arangodb", 
  "replication.active-failover" : false, 
  "replication.auto-start" : true, 
  "replication.automatic-failover" : false, 
  "replication.connect-timeout" : 10, 
  "replication.max-parallel-tailing-invocations" : 0, 
  "replication.request-timeout" : 600, 
  "rocksdb.allow-fallocate" : true, 
  "rocksdb.block-align-data-blocks" : false, 
  "rocksdb.block-cache-shard-bits" : -1, 
  "rocksdb.block-cache-size" : 19609916620, 
  "rocksdb.compaction-read-ahead-size" : 2097152, 
  "rocksdb.create-sha-files" : true, 
  "rocksdb.debug-logging" : false, 
  "rocksdb.delayed-write-rate" : 0, 
  "rocksdb.dynamic-level-bytes" : true, 
  "rocksdb.enable-pipelined-write" : false, 
  "rocksdb.enable-statistics" : false, 
  "rocksdb.encryption-key-generator" : "", 
  "rocksdb.encryption-keyfile" : "", 
  "rocksdb.enforce-block-cache-size-limit" : false, 
  "rocksdb.exclusive-writes" : false, 
  "rocksdb.intermediate-commit-count" : 1000000, 
  "rocksdb.intermediate-commit-size" : 536870912, 
  "rocksdb.level0-compaction-trigger" : 2, 
  "rocksdb.level0-slowdown-trigger" : 20, 
  "rocksdb.level0-stop-trigger" : 36, 
  "rocksdb.limit-open-files-at-startup" : false, 
  "rocksdb.max-background-jobs" : 8, 
  "rocksdb.max-bytes-for-level-base" : 268435456, 
  "rocksdb.max-bytes-for-level-multiplier" : 10, 
  "rocksdb.max-subcompactions" : 0, 
  "rocksdb.max-total-wal-size" : 83886080, 
  "rocksdb.max-transaction-size" : 18446744073709552000, 
  "rocksdb.max-write-buffer-number" : 9, 
  "rocksdb.min-write-buffer-number-to-merge" : 1, 
  "rocksdb.num-levels" : 7, 
  "rocksdb.num-threads-priority-high" : 4, 
  "rocksdb.num-threads-priority-low" : 4, 
  "rocksdb.num-uncompressed-levels" : 2, 
  "rocksdb.optimize-filters-for-hits" : false, 
  "rocksdb.recycle-log-file-num" : false, 
  "rocksdb.sync-interval" : 100, 
  "rocksdb.table-block-size" : 16384, 
  "rocksdb.throttle" : true, 
  "rocksdb.total-write-buffer-size" : 26146555494, 
  "rocksdb.transaction-lock-timeout" : 1000, 
  "rocksdb.use-direct-io-for-flush-and-compaction" : false, 
  "rocksdb.use-direct-reads" : false, 
  "rocksdb.use-file-logging" : false, 
  "rocksdb.use-fsync" : false, 
  "rocksdb.wal-archive-size-limit" : 0, 
  "rocksdb.wal-directory" : "", 
  "rocksdb.wal-file-timeout" : 10, 
  "rocksdb.wal-file-timeout-initial" : 180, 
  "rocksdb.wal-recovery-skip-corrupted" : false, 
  "rocksdb.write-buffer-size" : 67108864, 
  "server.allow-use-database" : true, 
  "server.authentication" : false, 
  "server.authentication-system-only" : true, 
  "server.authentication-timeout" : 0, 
  "server.authentication-unix-sockets" : true, 
  "server.check-max-memory-mappings" : true, 
  "server.descriptors-minimum" : 0, 
  "server.endpoint" : [ 
    "tcp://127.0.0.1:3492" 
  ], 
  "server.export-metrics-api" : true, 
  "server.flush-interval" : 1000000, 
  "server.gid" : "", 
  "server.harden" : false, 
  "server.io-threads" : 8, 
  "server.local-authentication" : true, 
  "server.maintenance-actions-block" : 2, 
  "server.maintenance-actions-linger" : 3600, 
  "server.maintenance-threads" : 9, 
  "server.maximal-queue-size" : 4096, 
  "server.maximal-threads" : 64, 
  "server.minimal-threads" : 2, 
  "server.prio1-size" : 4096, 
  "server.rest-server" : true, 
  "server.scheduler-queue-size" : 4096, 
  "server.statistics" : true, 
  "server.statistics-history" : true, 
  "server.storage-engine" : "rocksdb", 
  "server.uid" : "", 
  "ssl.cafile" : "", 
  "ssl.cipher-list" : "HIGH:!EXPORT:!aNULL@STRENGTH", 
  "ssl.ecdh-curve" : "prime256v1", 
  "ssl.keyfile" : "/work/ArangoDB/UnitTests/server.pem", 
  "ssl.options" : 2147485780, 
  "ssl.protocol" : 9, 
  "ssl.require-peer-certificate" : false, 
  "ssl.session-cache" : false, 
  "tcp.backlog-size" : 64, 
  "tcp.reuse-address" : true, 
  "temp.path" : "/tmp/arangosh_oLGAal/rocksdb-clusterOrNot/tmp", 
  "ttl.frequency" : 30000, 
  "ttl.max-collection-removes" : 1000000, 
  "ttl.max-total-removes" : 1000000, 
  "ttl.only-loaded-collection" : true, 
  "wal.allow-oversize-entries" : true, 
  "wal.directory" : "", 
  "wal.flush-timeout" : 30000, 
  "wal.historic-logfiles" : 10, 
  "wal.ignore-logfile-errors" : false, 
  "wal.ignore-recovery-errors" : false, 
  "wal.logfile-size" : 33554432, 
  "wal.open-logfiles" : 0, 
  "wal.reserve-logfiles" : 3, 
  "wal.slots" : 1048576, 
  "wal.sync-interval" : 100000, 
  "wal.throttle-wait" : 15000, 
  "wal.throttle-when-pending" : 0, 
  "wal.use-mlock" : false 
}