ArangoDB Manual

Command-Line Options

General Options

--help

-h

Prints a list of the most common options available and then exits. In order to see all options use --help-all.

--version

-v

Prints the version of the server and exits.

--configuration filename

-c filename

Specifies the name of the configuration file to use.

If this command is not passed to the server, then by default, the server will attempt to first locate a file named ~/SERVER/SERVER.conf in the user's home directory, where SERVER is the name of the corresponding server.

If no such file is found, the server will proceed to look for a file /etc/SERVER.conf in the system configuration directory. The default installation specifies the system configuration directory as /etc. Therefore, in case that no configuration file is found in the user's home directory, the server will proceed to look for a file named /etc/SERVER.conf.

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

White space is ignored. Each option is specified on a separate line in the form

key = value

Alternatively, a header section can be specified and options pertaining to that section can be specified in a shorter form

[log] 
level = trace

rather than specifying

log.level = trace

Comments can be placed in the configuration file, only if the line begins with one or more hash symbols (#).

There may be occasions where a configuration file exists and the user wishes to override configuration settings stored in a configuration file. Any settings specified on the command line will overwrite the same setting when it appears in a configuration file. If the user wishes to completely ignore configuration files without necessarily deleting the file (or files), then add the command line option

-c none

--configuration none

when starting up the server. Note that, the word none is case-insensitive.

--daemon

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

--supervisor

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

> ./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 supervisor process and the actual database process:

> 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 will start 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/

--uid uid

The name (identity) of the user the server will run as. If this parameter is not specified, the server will not attempt to change its UID, so that the UID used by the server will be the same as the UID of the user who started the server. If this parameter is specified, then the server will change its UID after opening ports and reading configuration files, but before accepting connections or opening other files (such as recovery files). This is useful when the server must be started with raised privileges (in certain environments) but security considerations require that these privileges be dropped once the server has started work.

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

--gid gid

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

This parameter is related to the parameter uid.

--pid-file filename

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

Command-Line Options for the ArangoDB

--server.endpoint endpoint

Specifies an endpoint for HTTP requests by clients. Endpoints have the following pattern:

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 endpoint

If 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 be repeated multiple times.

Examples

> ./arangod --server.endpoint tcp://127.0.0.1:8529 --server.endpoint ssl://127.0.0.1:8530 -server.keyfile server.pem /tmp/vocbase
2012-07-26T07:07:47Z [8161] INFO using SSL protocol version 'TLSv1'
2012-07-26T07:07:48Z [8161] INFO using endpoint 'ssl://127.0.0.1:8530' for http ssl requests
2012-07-26T07:07:48Z [8161] INFO using endpoint 'tcp://127.0.0.1:8529' for http tcp requests
2012-07-26T07:07:49Z [8161] INFO ArangoDB (version 1.1.alpha) is ready for business
2012-07-26T07:07:49Z [8161] INFO Have Fun!

Note that if you are using SSL-encrypted endpoints, you must also supply the path to a server certificate using the --server.keyfile optionn.

--server.disable-authentication value

Setting value to true will turn off authentication on the server side so all clients can execute any action without authorisation and privilege checks.

The default value is false.

--server.keep-alive-timeout

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

--server.keyfile filename

If SSL encryption is used, this option must be used to specify the filename of the server private key. The file must be PEM formatted and contain both the certificate and the server's private key.

The file specified by filename should have the following structure:

-----BEGIN CERTIFICATE-----

(base64 encoded certificate)

-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----

(base64 encoded private key)

-----END RSA PRIVATE KEY-----

You may use certificates issued by a Certificate Authority or self-signed certificates. Self-signed certificates can be created by a tool of your choice. When using OpenSSL for creating the self-signed certificate, the following commands should create a valid keyfile:

# create private key in file "server.key"
openssl genrsa -des3 -out server.key 1024

# create certificate signing request (csr) in file "server.csr"
openssl req -new -key server.key -out server.csr

# copy away original private key to "server.key.org"
cp server.key server.key.org

# remove passphrase from the private key
openssl rsa -in server.key.org -out server.key

# sign the csr with the key, creates certificate PEM file "server.crt"
openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

# combine certificate and key into single PEM file "server.pem"
cat server.crt server.key > server.pem

For further information please check the manuals of the tools you use to create the certificate.

Note: the --server.keyfile option must be set if the server is started with at least one SSL endpoint.

--server.cafile filename

This option can be used to specify a file with CA certificates that are sent to the client whenever the server requests a client certificate. If the file is specified, The server will only accept client requests with certificates issued by these CAs. Do not specify this option if you want clients to be able to connect without specific certificates.

The certificates in filename must be PEM formatted.

Note: this option is only relevant if at least one SSL endpoint is used.

--server.ssl-protocol value

Use this option to specify the default encryption protocol to be used. The following variants are available:

1: SSLv2
2: SSLv23
3: SSLv3
4: TLSv1

The default value is 4 (i.e. TLSv1).

Note: this option is only relevant if at least one SSL endpoint is used.

--server.ssl-cache value

Set to true if SSL session caching should be used.

value has a default value of false (i.e. no caching).

Note: this option is only relevant if at least one SSL endpoint is used, and only if the client supports sending the session id.

--server.ssl-options value

This option can be used to set various SSL-related options. Individual option values must be combined using bitwise OR.

Which options are available on your platform is determined by the OpenSSL version you use. The list of options available on your platform might be retrieved by the following shell command:

> grep "#define SSL_OP_.*" /usr/include/openssl/ssl.h

#define SSL_OP_MICROSOFT_SESS_ID_BUG                    0x00000001L
#define SSL_OP_NETSCAPE_CHALLENGE_BUG                   0x00000002L
#define SSL_OP_LEGACY_SERVER_CONNECT                    0x00000004L
#define SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG         0x00000008L
#define SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG              0x00000010L
#define SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER               0x00000020L
...

A description of the options can be found online in the OpenSSL documentation at: http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html

Note: this option is only relevant if at least one SSL endpoint is used.

--server.ssl-cipher-list cipher-list

This option can be used to restrict the server to certain SSL ciphers only, and to define the relative usage preference of SSL ciphers.

The format of cipher-list is documented in the OpenSSL documentation.

To check which ciphers are available on your platform, you may use the following shell command:

> openssl ciphers -v

ECDHE-RSA-AES256-SHA    SSLv3 Kx=ECDH     Au=RSA  Enc=AES(256)  Mac=SHA1
ECDHE-ECDSA-AES256-SHA  SSLv3 Kx=ECDH     Au=ECDSA Enc=AES(256)  Mac=SHA1
DHE-RSA-AES256-SHA      SSLv3 Kx=DH       Au=RSA  Enc=AES(256)  Mac=SHA1
DHE-DSS-AES256-SHA      SSLv3 Kx=DH       Au=DSS  Enc=AES(256)  Mac=SHA1
DHE-RSA-CAMELLIA256-SHA SSLv3 Kx=DH       Au=RSA  Enc=Camellia(256) Mac=SHA1
...

The default value for cipher-list is "ALL".

Note: this option is only relevant if at least one SSL endpoint is used.

--disable-admin-interface value

If this option is specified and value is true, then the HTML administration interface at URL http://server:port/ will be disabled and cannot used by any user at all.

--database.directory directory

The directory containing the collections and data-files. Defaults to /var/lib/arango.

directory

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

Examples

> ./arangod /tmp/vocbase
2012-05-13T12:37:08Z [8145] INFO using built-in JavaScript startup files
2012-05-13T12:37:08Z [8145] INFO ArangoDB (version 1.x.y) is ready for business
2012-05-13T12:37:08Z [8145] INFO Have Fun!

--database.maximal-journal-size size

Maximal size of journal in bytes. Can be overwritten when creating a new collection. Note that this also limits the maximal size of a single document.

The default is 32MB.

--database.wait-for-sync boolean

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

The default is false.

--database.force-sync-shapes boolean

Force syncing of shape data to disk when writing shape information. If turned off, syncing will still happen for shapes of collections that have a waitForSync value of true. If turned on, syncing of shape data will always happen, regards of the value of waitForSync.

The default is true.

--database.remove-on-drop flag

If true and you drop a collection, then they directory and all associated datafiles will be removed from disk. If false, then they collection directory will be renamed to deleted-..., but remains on hard disk. To restore such a dropped collection, you can rename the directory back to collection-..., but you must also edit the file parameter.json inside the directory.

The default is true.

--javascript.gc-frequency frequency

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

--javascript.gc-interval interval

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

Command-Line Options for Communication

--scheduler.threads arg

An integer argument which sets the number of threads to use in the IO scheduler. The default is 1.

--scheduler.backend arg

The I/O method used by the event handler. The default (if this option is not specified) is to try all recommended backends. This is platform specific. See libev for further details and the meaning of select, poll and epoll.

--show-io-backends

If this option is specified, then the server will list available backends and exit. This option is useful only when used in conjunction with the option scheduler.backend. An integer is returned (which is platform dependent) which indicates available backends on your platform. See libev for further details and for the meaning of the integer returned. This describes the allowed integers for scheduler.backend, see here for details.

Command-Line Options for Logging

There are two different kinds of logs. Human-readable logs and machine-readable logs. The human-readable logs are used to provide an administration with information about the server. The machine-readable logs are used to provide statistics about executed requests and timings about computation steps.

General Logging Options

--log.file filename

This option allows the user to specify the name of a file to which information is logged. By default, if no log file is specified, the standard output is used. Note that if the file named by filename does not exist, it will be created. If the file cannot be created (e.g. due to missing file privileges), the server will refuse to start. If the specified file already exists, output is appended to that file.

Use + to log to standard error. Use - to log to standard output. Use "" to disable logging to file.

--log.severity severity

This parameter provides a set of standard log severities which can be used. The currently accepted severities are:

exception
technical
functional
development
human
all (human and non-human)
non-human (exception, technical, functional, and development)

The default is all.

--log.syslog arg

If this option is set, then in addition to output being directed to the standard output (or to a specified file, in the case that the command line log.file option was set), log output is also sent to the system logging facility. The arg is the system log facility to use. See syslog for further details.

The value of arg depends on your syslog configuration. In general it will be user. Fatal messages are mapped to crit, so if arg is user, these messages will be logged as user.crit. Error messages are mapped to err. Warnings are mapped to warn. Info messages are mapped to notice. Debug messages are mapped to info. Trace messages are mapped to debug.

Human Readable Logging

--log.level level

--log level

Allows the user to choose the level of information which is logged by the server. The argument level is specified as a string and can be one of the values listed below. Note that, fatal errors, that is, errors which cause the server to terminate, are always logged irrespective of the log level assigned by the user. The variant log.level can be used in configuration files, the variant log for command line options.

fatal: Logs errors which cause the server to terminate.

Fatal errors generally indicate some inconsistency with the manner in which the server has been coded. Fatal errors may also indicate a problem with the platform on which the server is running. Fatal errors always cause the server to terminate. For example,

2010-09-20T07:32:12Z [4742] FATAL a http server has already been created

error: Logs errors which the server has encountered.

These errors may not necessarily result in the termination of the server. For example,

2010-09-17T13:10:22Z [13967] ERROR strange log level 'errors', going to 'warning'

warning: Provides information on errors encountered by the server, which are not necessarily detrimental to it's continued operation.

For example,

2010-09-20T08:15:26Z [5533] WARNING got corrupted HTTP request 'POS?'

Note that, setting the log level to warning will also result in all errors to be logged as well.

info: Logs information about the status of the server.

For example,

2010-09-20T07:40:38Z [4998] INFO SimpleVOC ready for business

Note that, setting the log level to info will also result in all errors and warnings to be logged as well.

debug: Logs all errors, all warnings and debug information.

Debug log information is generally useful to find out the state of the server in the case of an error. For example,

2010-09-17T13:02:53Z [13783] DEBUG opened port 7000 for any

Note that, setting the log level to debug will also result in all errors, warnings and server status information to be logged as well.

trace: As the name suggests, logs information which may be useful to trace problems encountered with using the server.

For example,

2010-09-20T08:23:12Z [5687] TRACE trying to open port 8000

Note that, setting the log level to trace will also result in all errors, warnings, status information, and debug information to be logged as well.

--log.line-number

Normally, if an human readable fatal, error, warning or info message is logged, no information about the file and line number is provided. The file and line number is only logged for debug and trace message. This option can be use to always log these pieces of information.

--log.prefix prefix

This option is used specify an prefix to logged text.

--log.thread

Whenever log output is generated, the process ID is written as part of the log information. Setting this option appends the thread id of the calling thread to the process id. For example,

2010-09-20T13:04:01Z [19355] INFO ready for business

when no thread is logged and

2010-09-20T13:04:17Z [19371-18446744072487317056] ready for business

when this command line option is set.

--log.filter arg

For debug and trace messages, only log those messages occurring in the file arg.

Maschine Readable Logging

--log.application name

Specifies the name of the application which should be logged if this item of information is to be logged.

--log.facility name

Specifies the name of the server instance which should be logged if this item of information is to be logged.

--log.format format

If the log output is machine (or machine readable), then this parameter allows you to configure the format of the output. The following placeholders are available:

%A the application name
%C the category which caused the output (e.g. FATAL, ERROR, WARNING etc.)
%E extras
%F facility
%H the host name to log
%K task
%M message identifier
%P peg
%S severity
%T date/time stamp
%U measure unit
%V measure value
%Z date/time stamp in GMT (zulu)
%f source code module
%l source code line
%m source code method
%p pid
%s pthread identifier
%t tid
%u user identifier
%x the actual text

The default format is

%Z;1;%S;%C;%H;%p-%t;%F;%A;%f;%m;%K;%f:%l;%x;%P;%u;%V;%U;%E

--log.hostname name

Specifies the name of the operating environment (the "hostname") which should be logged if this item of information is to be logged. Note that there is no default hostname.

Command-Line Options for Random Numbers

--random.generator arg

The argument is an integer (1,2,3 or 4) which sets the manner in which random numbers are generated. The default method (3) is to use the a non-blocking random (or pseudorandom) number generator supplied by the operating system. Specifying an argument of 2, uses a blocking random (or pseudorandom) number generator. Specifying an argument 1 sets a pseudorandom number generator using an implication of the Mersenne Twister MT19937 algorithm. Algorithm 4 is a combination of the blocking random number generator and the Mersenne Twister.

--random.no-seed

By default, the random generator is seeded. Setting this option causes the random number generator not to be seeded. (Seeding the random number generator only occurs if the generator is set to Mersenne, refer to random.generator for details.)