ArangoDB Server Server Options

Managing Endpoints

The ArangoDB server can listen for incoming requests on multiple endpoints.

The endpoints are normally specified either in ArangoDB’s configuration file oron the command-line like —server.endpoint. ArangoDB supports differenttypes of endpoints:

• tcp://ipv4-address:port - TCP/IP endpoint, using IPv4
• tcp://[ipv6-address]:port - TCP/IP endpoint, using IPv6
• ssl://ipv4-address:port - TCP/IP endpoint, using IPv4, SSL encryption
• ssl://[ipv6-address]:port - TCP/IP endpoint, using IPv6, SSL encryption
• unix:///path/to/socket - Unix domain socket endpointIf a TCP/IP endpoint is specified without a port number, then the default port(8529) will be used. If multiple endpoints need to be used, the option can berepeated multiple times.

The default endpoint for ArangoDB is tcp://127.0.0.1:8529 ortcp://localhost:8529.

Examples

unix> ./arangod --server.endpoint tcp://127.0.0.1:8529
                --server.endpoint ssl://127.0.0.1:8530
                --ssl.keyfile server.pem /tmp/vocbase
2019-05-06T07:30:42Z [9228] INFO ArangoDB 3.4.5 [linux] 64bit, using jemalloc, build tags/v3.4.5-0-g648fbb8191, VPack 0.1.33, RocksDB 5.16.0, ICU 58.1, V8 5.7.492.77, OpenSSL 1.1.0j  20 Nov 2018
2019-05-06T07:30:43Z [9228] INFO {authentication} Jwt secret not specified, generating...
2019-05-06T07:30:43Z [9228] INFO using storage engine rocksdb
2019-05-06T07:30:43Z [9228] INFO {cluster} Starting up with role SINGLE
2019-05-06T07:50:53Z [9228] INFO {syscall} file-descriptors (nofiles) hard limit is 1048576, soft limit is 1048576
2019-05-06T07:50:53Z [9228] INFO {authentication} Authentication is turned on (system only), authentication for unix sockets is turned on
2019-05-06T07:30:43Z [9228] INFO using endpoint 'http+tcp://127.0.0.1:8529' for non-encrypted requests
2019-05-06T07:30:43Z [9228] INFO using endpoint 'http+ssl://127.0.0.1:8530' for ssl-encrypted requests
2019-05-06T07:30:44Z [9228] INFO ArangoDB (version 3.4.5 [linux]) is ready for business. Have fun!

Given a hostname:

—server.endpoint tcp://hostname:port

Given an IPv4 address:

—server.endpoint tcp://ipv4-address:port

Given an IPv6 address:

—server.endpoint tcp://[ipv6-address]:port

On one specific ethernet interface each port can only be bound exactlyonce. You can look up your available interfaces using the ifconfig commandon Linux / macOS - the Windows equivalent is ipconfig (seeWikipedia for more details).The general names of the interfaces differ on OS’s and hardwares they run on.However, typically every host has a so calledloopback interface,which is a virtual interface. By convention it always has the address127.0.0.1 or ::1 (ipv6), and can only be reached from exactly the very samehost. Ethernet interfaces usually have names like eth0, wlan0, eth1:17,le0 or a plain text name in Windows.

To find out which services already use ports (so ArangoDB can’t bind themanymore), you can use thenetstat command(it behaves a little different on each platform, run it with -lnpt on Linux,-p tcp on macOS or with -an on windows for valuable information).

ArangoDB can also do a so called broadcast bind usingtcp://0.0.0.0:8529. This way it will be reachable on all interfaces of thehost. This may be useful on development systems that frequently change theirnetwork setup like laptops.

Special note on IPv6 link-local addresses

ArangoDB can also listen to IPv6 link-local addresses via adding the zone IDto the IPv6 address in the form [ipv6-link-local-address%zone-id]. However,what you probably instead want is to bind to a local IPv6 address. Local IPv6addresses start with fd. If you only see a fe80: IPv6 address in yourinterface configuration but no IPv6 address starting with fd your interfacehas no local IPv6 address assigned. You can read more about IPv6 link-localaddresses here.

Example

Bind to a link-local and local IPv6 address.

unix> ifconfig

This command lists all interfaces and assigned ip addresses. The link-localaddress may be fe80::6257:18ff:fe82:3ec6%eth0 (IPv6 address plus interface name).A local IPv6 address may be fd12:3456::789a. To bind ArangoDB to it startarangod with —server.endpoint tcp://[fe80::6257:18ff:fe82:3ec6%eth0]:8529.Use telnet to test the connection.

unix> telnet fe80::6257:18ff:fe82:3ec6%eth0 8529
Trying fe80::6257:18ff:fe82:3ec6...
Connected to my-machine.
Escape character is '^]'.
GET / HTTP/1.1
HTTP/1.1 301 Moved Permanently
Location: /_db/_system/_admin/aardvark/index.html
Content-Type: text/html
Server: ArangoDB
Connection: Keep-Alive
Content-Length: 197
<html><head><title>Moved</title></head><body><h1>Moved</h1><p>This page has moved to <a href="/_db/_system/_admin/aardvark/index.html">/_db/_system/_admin/aardvark/index.html</a>.</p></body></html>

Reuse address

—tcp.reuse-address

If this boolean option is set to true then the socket option SOREUSEADDR isset on all server endpoints, which is the default. If this option is set to_false it is possible that it takes up to a minute after a server hasterminated until it is possible for a new server to use the same endpointagain. This is why this is activated by default.

Please note however that under some operating systems this can be a securityrisk because it might be possible for another process to bind to the sameaddress and port, possibly hijacking network traffic. Under Windows, ArangoDBadditionally sets the flag SO_EXCLUSIVEADDRUSE as a measure to alleviate thisproblem.

Backlog size

—tcp.backlog-size

Allows to specify the size of the backlog for the listen system call Thedefault value is 10. The maximum value is platform-dependent. Specifying ahigher value than defined in the system header’s SOMAXCONN may result in awarning on server start. The actual value used by listen may also be silentlytruncated on some platforms (this happens inside the listen system call).

Maximal queue size

Maximum size of the queue for requests: —server.maximal-queue-sizesize

Specifies the maximum size of the queue for asynchronous taskexecution. If the queue already contains size tasks, new tasks willbe rejected until other tasks are popped from the queue. Setting thisvalue may help preventing from running out of memory if the queue isfilled up faster than the server can process requests.

Storage engine

ArangoDB’s “traditional” storage engine is called MMFiles, which also was thedefault storage engine up to including ArangoDB 3.3.

Since ArangoDB 3.2, an alternative engine based on RocksDBis also provided and could be turned on manually. Since ArangoDB 3.4, the RocksDBstorage engine is the default storage engine for new installations.

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 choosethe previously used one.

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

Note that auto will default to rocksdb starting with ArangoDB 3.4, but inprevious versions it defaulted to mmfiles.

Check max memory mappings

—server.check-max-memory-mappings can be used on Linux to make arangodcheck the number of memory mappings currently used by the process (as reported in/proc/<pid>/maps) and compare it with the maximum number of allowed mappings asdetermined 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.

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.

Server threads

—server.minimal-threads number

—server.maximal-threads number

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

The actual number of request processing threads is adjusted dynamically at runtimeand will float between —server.minimal-threads and —server.maximal-threads.

—server.minimal-threads determines the minimum number of request processingthreads the server will start and that will always be kept around. The defaultvalue is 2.

—server.maximal-threads determines the maximum number of request processingthreads the server is allowed to start for request handling. If that number ofthreads is already running, arangod will not start further threads for requesthandling. The default value is

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 heavily-loaded instances a bit.

Data source flush synchronization

—server.flush-interval

ArangoDB will periodically ensure that all data sources (databases, views, etc.)have flushed all committed data to disk and write some checkpoint data to aid infuture recovery. Increasing this value will result in fewer, larger writebatches, while decreasing it will result in more, smaller writes. Setting thevalue too low can easily overwhelm the server, while setting the value too highmay result in high memory usage and periodic slowdowns. Value is given inmicroseconds, with a typical range of 100000 (100ms) to 10000000 (10s) and adefault of 1000000 (1s). Use caution when changing from the default.