General Options

Database Upgrade

—database.auto-upgrade

Specifying this option will make the server perform a database upgrade insteadof starting the server normally. A database upgrade will first compare theversion number stored in the file VERSION in the database directory with thecurrent server version.

If the version number found in the database directory is higher than the versionnumber the server is running, the server expects this is an unintentionaldowngrade and will warn about this. Using the server in these conditions isneither recommended nor supported.

If the version number found in the database directory is lower than the versionnumber the server is running, the server will check whether there are anyupgrade tasks to perform. It will then execute all required upgrade tasks andprint their statuses. If one of the upgrade tasks fails, the server will exitwith an error. Re-starting the server with the upgrade option will then againtrigger the upgrade check and execution until the problem is fixed.

Whether or not this option is specified, the server will always perform aversion check on startup. Running the server with a non-matching version numberin the VERSION file will make the server refuse to start.

Storage Engine

As of ArangoDB 3.2 two storage engines are supported. The “traditional”engine is called MMFiles, which is also the default storage engine.

An alternative engine based on RocksDB is also provided andcan be turned on manually.

One storage engine type is supported per server per installation. Live switching of storage engines on already installed systems isn’t supported.Configuring the wrong engine (not matching the previously used one) will resultin the server refusing to start. You may however use auto to let ArangoDB choose the previously used one.

—server.storage-engine [auto|mmfiles|rocksdb]

Daemon

—daemon

Runs the server as a daemon (as a background process). This parameter can onlybe set if the pid (process id) file is specified. That is, unless a value to theparameter pid-file is given, then the server will report an error and exit.

Default Language

—default-language default-language

The default language ist used for sorting and comparing strings. The languagevalue is a two-letter language code (ISO-639) or it is composed by a two-letterlanguage code with and a two letter country code (ISO-3166). Valid languages are“de”, “en”, “en_US” or “en_UK”.

The default default-language is set to be the system locale on that platform.

Supervisor

—supervisor

Executes the server in supervisor mode. In the event that the serverunexpectedly terminates due to an internal error, the supervisor willautomatically restart the server. Setting this flag automatically implies thatthe server will run as a daemon. Note that, as with the daemon flag, this flagrequires that the pid-file parameter will set.

unix> ./arangod --supervisor --pid-file /var/run/arangodb.pid /tmp/vocbase/
2012-06-27T15:58:28Z [10133] INFO starting up in supervisor mode

As can be seen (e.g. by executing the ps command), this will start a supervisorprocess and the actual database process:

unix> ps fax | grep arangod
10137 ?        Ssl    0:00 ./arangod --supervisor --pid-file /var/run/arangodb.pid /tmp/vocbase/
10142 ?        Sl     0:00  \_ ./arangod --supervisor --pid-file /var/run/arangodb.pid /tmp/vocbase/

When the database process terminates unexpectedly, the supervisor process willstart up a new database process:

> kill -SIGSEGV 10142
> ps fax | grep arangod
10137 ?        Ssl    0:00 ./arangod --supervisor --pid-file /var/run/arangodb.pid /tmp/vocbase/
10168 ?        Sl     0:00  \_ ./arangod --supervisor --pid-file /var/run/arangodb.pid /tmp/vocbase/

User identity

—uid uid

The name (identity) of the user the server will run as. If this parameter is notspecified, the server will not attempt to change its UID, so that the UID usedby the server will be the same as the UID of the user who started the server. Ifthis parameter is specified, then the server will change its UID after openingports and reading configuration files, but before accepting connections oropening other files (such as recovery files). This is useful when the servermust be started with raised privileges (in certain environments) but securityconsiderations require that these privileges be dropped once the server hasstarted work.

Observe that this parameter cannot be used to bypass operating systemsecurity. In general, this parameter (and its corresponding relative gid) canlower privileges but not raise them.

Group identity

—gid gid

The name (identity) of the group the server will run as. If this parameter isnot specified, then the server will not attempt to change its GID, so that theGID the server runs as will be the primary group of the user who started theserver. If this parameter is specified, then the server will change its GIDafter opening ports and reading configuration files, but before acceptingconnections or opening other files (such as recovery files).

This parameter is related to the parameter uid.

Process identity

—pid-file filename

The name of the process ID file to use when running the server as adaemon. This parameter must be specified if either the flag daemon orsupervisor is set.

Check max memory mappings

—server.check-max-memory-mappings can be used on Linux to make arangod check the number of memory mappings currently used by the process (as reported in/proc//maps) and compare it with the maximum number of allowed mappings as determined by /proc/sys/vm/max_map_count. If the current number of memorymappings gets near the maximum allowed value, arangod will log a warningand disallow the creation of further V8 contexts temporarily until the currentnumber of mappings goes down again.

If the option is set to false, no such checks will be performed. All non-Linuxoperating systems do not provide this option and will ignore it.

Console

—console

Runs the server in an exclusive emergency console mode. Whenstarting the server with this option, the server is started withan interactive JavaScript emergency console, with all networkingand HTTP interfaces of the server disabled.

No requests can be made to the server in this mode, and the onlyway to work with the server in this mode is by using the emergencyconsole.Note that the server cannot be started in this mode if it isalready running in this or another mode.

Random Generator

—random.generator arg

The argument is an integer (1,2,3 or 4) which sets the manner in whichrandom numbers are generated. The default method (3) is to use the anon-blocking random (or pseudorandom) number generator supplied by theoperating system.

Specifying an argument of 2, uses a blocking random (orpseudorandom) number generator. Specifying an argument 1 sets apseudorandomnumber generator using an implication of the Mersenne Twister MT19937algorithm. Algorithm 4 is a combination of the blocking random numbergenerator and the Mersenne Twister.

Enable/disable authentication

—server.authentication

Setting this option to false will turn off authentication on the server sideso all clients can execute any action without authorization and privilegechecks.

The default value is true.

JWT Secret

—server.jwt-secret secret

ArangoDB will use JWTs to authenticate requests. Using this option let’syou specify a JWT. When specified, the JWT secret must be at most 64 byteslong.

In single server setups and when not specifying this secret ArangoDB willgenerate a secret.

In cluster deployments which have authentication enabled a secret mustbe set consistently across all cluster nodes so they can talk to each other.

Enable/disable authentication for UNIX domain sockets

—server.authentication-unix-sockets value

Setting value to true will turn off authentication on the server sidefor requests coming in via UNIX domain sockets. With this flag enabled,clients located on the same host as the ArangoDB server can use UNIX domainsockets to connect to the server without authentication.Requests coming in by other means (e.g. TCP/IP) are not affected by this option.

The default value is false.

Note: this option is only available on platforms that support UNIXdomain sockets.

Enable/disable authentication for system API requests only

—server.authentication-system-only boolean

Controls whether incoming requests need authentication only if they aredirected to the ArangoDB’s internal APIs and features, located at/_api/,/_admin/ etc.

If the flag is set to true, then HTTP authentication is onlyrequired for requests going to URLs starting with /__, but not for otherURLs. The flag can thus be used to expose a user-made API without HTTPauthentication to the outside world, but to prevent the outside world fromusing the ArangoDB API and the admin interface without authentication.Note that checking the URL is performed after any database name prefixhas been removed. That means when the actual URL called is/db/_system/myapp/myaction, the URL /myapp/myaction will be used forauthentication-system-only check.

The default is true.

Note that authentication still needs to be enabled for the server regularly in order for HTTP authentication to be forced for the ArangoDB API and theweb interface. Setting only this flag is not enough.

You can control ArangoDB’s general authentication feature with the—server.authentication flag.

Enable authentication cache timeout

—server.authentication-timeout value

Sets the cache timeout to value (in seconds). This is only necessaryif you use an external authentication system like LDAP.

Enable local authentication

—server.local-authentication value

If set to false only use the external authentication system. Iftrue also use the local _users collections.

The default value is true.

Enable/disable replication applier

—database.replication-applier flag

If false the server will start with replication appliers turned off,even if the replication appliers are configured with the autoStart option.Using the command-line option will not change the value of the _autoStart_option in the applier configuration, but will suppress auto-starting thereplication applier just once.

If the option is not used, ArangoDB will read the applier configurationfrom the file REPLICATION-APPLIER-CONFIG on startup, and use the value of theautoStart attribute from this file.

The default is true.

Keep-alive timeout

—http.keep-alive-timeout

Allows to specify the timeout for HTTP keep-alive connections. The timeoutvalue must be specified in seconds.Idle keep-alive connections will be closed by the server automaticallywhen the timeout is reached. A keep-alive-timeout value 0 will disable the keepalive feature entirely.

Hide Product header

—http.hide-product-header

If true, the server will exclude the HTTP header “Server: ArangoDB” inHTTP responses. If set to false, the server will send the header inresponses.

The default is false.

Allow method override

—http.allow-method-override

When this option is set to true, the HTTP request method will optionallybe fetched from one of the following HTTP request headers if present inthe request:

• x-http-method
• x-http-method-override
• x-method-overrideIf the option is set to true and any of these headers is set, therequest method will be overridden by the value of the header. For example,this allows issuing an HTTP DELETE request which to the outside world willlook like an HTTP GET request. This allows bypassing proxies and tools thatwill only let certain request types pass.

Setting this option to true may impose a security risk so it should onlybe used in controlled environments.

The default value for this option is false.

Server threads

—server.threads number

Specifies the number of threads that are spawned to handle requests.

Toggling server statistics

—server.statistics value

If this option is value is false, then ArangoDB’s statistics gatheringis turned off. Statistics gathering causes regular background CPU activity andmemory usage, so using this option to turn statistics off might relieve heavy-loaded instances a bit.

Session timeout

time to live for server sessions—server.session-timeout value

The timeout for web interface sessions, using for authenticating requeststo the web interface (/_admin/aardvark) and related areas.

Sessions are only used when authentication is turned on.

Foxx queues

enable or disable the Foxx queues feature—foxx.queues flag

If true, the Foxx queues will be available and jobs in the queues willbe executed asynchronously.

The default is true.When set to false the queue manager will be disabled and any jobsare prevented from being processed, which may reduce CPU load a bit.

Foxx queues poll interval

poll interval for Foxx queues—foxx.queues-poll-interval value

The poll interval for the Foxx queues manager. The value is specified inseconds. Lower values will mean more immediate and more frequent Foxxqueue job execution, but will make the queue thread wake up and query thequeues more often. When set to a low value, the queue thread might causeCPU load.

The default is 1 second. If Foxx queues are not used much, then thisvalue may be increased to make the queues thread wake up less.

Directory

—database.directory directory

The directory containing the collections and datafiles. Defaultsto /var/lib/arango. When specifying the database directory, pleasemake sure the directory is actually writable by the arangod process.

You should further not use a database directory which is provided by anetwork filesystem such as NFS. The reason is that networked filesystemsmight cause inconsistencies when there are multiple parallel readers orwriters or they lack features required by arangod (e.g. flock()).

directory

When using the command line version, you can simply supply the databasedirectory as argument.

Examples

> ./arangod --server.endpoint tcp://127.0.0.1:8529 --database.directory
/tmp/vocbase

Database directory state precondition

—database.require-directory-state state

Using this option it is possible to require the database directory to bein a specific state on startup. the options for this value are:

• non-existing: database directory must not exist
• existing: database directory must exist
• empty: database directory must exist but be empty
• populated: database directory must exist and contain specific files already
• any: any directory state allowed

Journal size

—database.maximal-journal-size size

Maximal size of journal in bytes. Can be overwritten when creating a newcollection. Note that this also limits the maximal size of a singledocument.

The default is 32MB.

Wait for sync

default wait for sync behavior—database.wait-for-sync boolean

Default wait-for-sync value. Can be overwritten when creating a newcollection.

The default is false.

Force syncing of properties

force syncing of collection properties to disk—database.force-sync-properties boolean

Force syncing of collection properties to disk after creating a collectionor updating its properties.

If turned off, no fsync will happen for the collection and databaseproperties stored in parameter.json files in the file system. Turningoff this option will speed up workloads that create and drop a lot ofcollections (e.g. test suites).

The default is true.

Limiting memory for AQL queries

—query.memory-limit value

The default maximum amount of memory (in bytes) that a single AQL query can use.When a single AQL query reaches the specified limit value, the query will beaborted with a resource limit exceeded exception. In a cluster, the memoryaccounting is done per shard, so the limit value is effectively a memory limit perquery per shard.

The global limit value can be overriden per query by setting the memoryLimit option value for individual queries when running an AQL query.

The default value is 0, meaning that there is no memory limit.

Turning AQL warnings into errors

—query.fail-on-warning value

When set to true, AQL queries that produce warnings will instantly abort andthrow an exception. This option can be set to catch obvious issues with AQL queries early. When set to false, AQL queries that produce warnings will notabort and return the warnings along with the query results.The option can also be overridden for each individual AQL query.

Enable/disable AQL query tracking

—query.tracking flag

If true, the server’s AQL slow query tracking feature will be enabled bydefault. Tracking of queries can be disabled by setting the option to false.

The default is true.

Enable/disable tracking of bind variables in AQL queries

—query.tracking-with-bindvars flag

If true, then the bind variables will be tracked for all running and slowAQL queries. This option only has an effect if —query.tracking was set totrue. Tracking of bind variables can be disabled by setting the option to false.

The default is true.

Threshold for slow AQL queries

—query.slow-threshold value

By setting value it can be controlled after what execution time an AQL queryis considered “slow”. Any slow queries that exceed the execution time specifiedin value will be logged when they are finished. The threshold value isspecified in seconds. Tracking of slow queries can be turned off entirely bysetting the option —query.tracking to false.

The default value is 10.0.

Query registry timeout

—query.registry-ttl value

The default timeout for AQL query parts to stay alive in the cluster. The defaultvalue is 600 seconds. Query parts that are not used for the configured amount oftime will expire automatically and will be aborted. The value of this option normally only needs to be increased for queries that are running longer than thedefault timeout value (600 seconds) and that time out. The option has no effectin single-server mode.

Limiting the number of query execution plans created by the AQL optimizer

—query.optimizer-max-plans value

By setting value it can be controlled how many different query execution plansthe AQL query optimizer will generate at most for any given AQL query. Normallythe AQL query optimizer will generate a single execution plan per AQL query, butthere are some cases in which it creates multiple competing plans. More planscan lead to better optimized queries, however, plan creation has its costs. Themore plans are created and shipped through the optimization pipeline, the moretime will be spent in the optimizer.Lowering value will make the optimizer stop creating additional plans when ithas already created enough plans.Note that this setting controls the default maximum number of plans to create. Thevalue can still be adjusted on a per-query basis by setting the _maxNumberOfPlans_attribute when running a query.

The default value is 128.

Throw collection not loaded error

—database.throw-collection-not-loaded-error flag

Accessing a not-yet loaded collection will automatically load a collection onfirst access. This flag controls what happens in case an operation would need towait for another thread to finalize loading a collection. If set to true, thenthe first operation that accesses an unloaded collection will load it. Furtherthreads that try to access the same collection while it is still loading willget an error (1238, collection not loaded). When the initial operation hascompleted loading the collection, all operations on the collection can becarried out normally, and error 1238 will not be thrown.

If set to false, the first thread that accesses a not-yet loaded collectionwill still load it. Other threads that try to access the collection whileloading will not fail with error 1238 but instead block until the collection isfully loaded. This configuration might lead to all server threads being blockedbecause they are all waiting for the same collection to completeloading. Setting the option to true will prevent this from happening, butrequires clients to catch error 1238 and react on it (maybe by scheduling aretry for later).

The default value is false.

AQL Query caching mode

—query.cache-mode

Toggles the AQL query cache behavior. Possible values are:

• off: do not use query cache
• on: always use query cache, except for queries that have their cache_attribute set to _false
• demand: use query cache only for queries that have their cache_attribute set to _true

AQL Query cache size

—query.cache-entries

Maximum number of query results that can be stored per database-specific querycache. If a query is eligible for caching and the number of items in thedatabase’s query cache is equal to this threshold value, another cached queryresult will be removed from the cache.

This option only has an effect if the query cache mode is set to either on ordemand.

JavaScript code execution

—javascript.allow-admin-execute

This option can be used to control whether user-defined JavaScript codeis allowed to be executed on server by sending via HTTP to the API endpoint/admin/execute with an authenticated user account. The default value is _false, which disables the execution of user-definedcode. This is also the recommended setting for production. In test environments,it may be convenient to turn the option on in order to send arbitrary setupor teardown commands for execution on the server.

V8 contexts

—javascript.v8-contexts number

Specifies the maximum number of V8 contexts that are created for executing JavaScript code. More contexts allow executing more JavaScript actions in parallel, provided that there are also enough threads available. Please note that each V8 contextwill use a substantial amount of memory and requires periodic CPU processingtime for garbage collection.

Note that this value configures the maximum number of V8 contexts that can beused in parallel. Upon server start only as many V8 contexts will be created as areconfigured in option —javascript.v8-contexts-minimum. The actual number ofavailable V8 contexts may float at runtime between —javascript.v8-contexts-minimumand —javascript.v8-contexts. When there are unused V8 contexts that linger around, the server’s garbage collector thread will automatically delete them.

—javascript.v8-contexts-minimum number

Specifies the minimum number of V8 contexts that will be present at any timethe server is running. The actual number of V8 contexts will never drop below thisvalue, but it may go up as high as specified via the option —javascript.v8-contexts.

When there are unused V8 contexts that linger around and the number of V8 contextsis greater than —javascript.v8-contexts-minimum the server’s garbage collector thread will automatically delete them.

—javascript.v8-contexts-max-invocations

Specifies the maximum number of invocations after which a used V8 context is disposed. The default value of —javascript.v8-contexts-max-invocations is 0, meaning that the maximum number of invocations per context is unlimited.

—javascript.v8-contexts-max-age

Specifies the time duration (in seconds) after which time a V8 context is disposed automatically after its creation. If the time is elapsed, the context will be disposed.The default value for —javascript.v8-contexts-max-age is 60 seconds.

If both —javascript.v8-contexts-max-invocations and —javascript.v8-contexts-max-ageare set, then the context will be destroyed when either of the specified threshold values is reached.

Garbage collection frequency (time-based)

—javascript.gc-frequency frequency

Specifies the frequency (in seconds) for the automatic garbage collection ofJavaScript objects. This setting is useful to have the garbage collection stillwork in periods with no or little numbers of requests.

Garbage collection interval (request-based)

—javascript.gc-interval interval

Specifies the interval (approximately in number of requests) that the garbagecollection for JavaScript objects will be run in each thread.

V8 options

—javascript.v8-options options

Optional arguments to pass to the V8 Javascript engine. The V8 engine will runwith default settings unless explicit options are specified using thisoption. The options passed will be forwarded to the V8 engine which will parsethem on its own. Passing invalid options may result in an error being printed onstderr and the option being ignored.

Options need to be passed in one string, with V8 option names being prefixedwith double dashes. Multiple options need to be separated by whitespace. To geta list of all available V8 options, you can use the value ”—help” as follows:

--javascript.v8-options="--help"

Another example of specific V8 options being set at startup:

--javascript.v8-options="--log"

Names and features or usable options depend on the version of V8 being used, andmight change in the future if a different version of V8 is being used inArangoDB. Not all options offered by V8 might be sensible to use in the contextof ArangoDB. Use the specific options only if you are sure that they are notharmful for the regular database operation.