Hawkin
/
arangodb
mirror of https://gitee.com/bigwinds/arangodb
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Changed documentation code in configure chapter

This commit is contained in:
Thomas Schmidts 2014-07-02 14:08:41 +02:00
parent 804099aa1a
commit e46d87f23c
28 changed files with 724 additions and 1260 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

443
Documentation/Books/Users/ConfigureArango/Arangod.mdpp
View File

@ -1,305 +1,74 @@
!CHAPTER Command-Line Options for arangod
`--server.endpoint endpoint`
!SUBSECTION Endpoint
<!-- lib/HttpServer/ApplicationEndpointServer.h -->
@startDocuBlock serverEndpoint
Specifies an endpoint for HTTP requests by clients. Endpoints have the following pattern:
!SUBSECTION Reuse address
<!-- lib/HttpServer/ApplicationEndpointServer.h -->
@startDocuBlock serverReuseAddress
* 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.
!SUBSECTION Disable authentication
<!-- arangod/RestServer/ArangoServer.h -->
@startDocuBlock server_authentication
*Examples*
!SUBSECTION Disable authentication-unix-sockets
<!-- arangod/RestServer/ArangoServer.h -->
@startDocuBlock serverAuthenticationDisable
unix> ./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!
!SUBSECTION Authenticate system only
<!-- arangod/RestServer/ArangoServer.h -->
@startDocuBlock serverAuthenticateSystemOnly
Note that if you are using SSL-encrypted endpoints, you must also supply the path to a server certificate using the `--server.keyfile` option.
!SUBSECTION Disable replication-logger
<!-- arangod/RestServer/ArangoServer.h -->
@startDocuBlock serverDisableReplicationLogger
Endpoints can also be changed at runtime. Please refer to HTTP Interface for Endpoints for more details.
!SUBSECTION Disable replication-applier
<!-- arangod/RestServer/ArangoServer.h -->
@startDocuBlock serverDisableReplicationApplier
!SUBSECTION Timeout
<!-- lib/HttpServer/ApplicationEndpointServer.h -->
@startDocuBlock keep_alive_timeout
`--server.reuse-address`
!SUBSECTION Default Api
<!-- lib/HttpServer/ApplicationEndpointServer.h -->
@startDocuBlock serverDefaultApi
If this boolean option is set to true then the socket option SO_REUSEADDR is set 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 has terminated until it is possible for a new server to use the same endpoint again. This is why this is activated by default.
!SUBSECTION Allow method arrive
<!-- lib/HttpServer/ApplicationEndpointServer.h -->
@startDocuBlock serverAllowMethod
Please note however that under some operating systems this can be a security risk because it might be possible for another process to bind to the same address and port, possibly hijacking network traffic. Under Windows, ArangoDB additionally sets the flag SO_EXCLUSIVEADDRUSE as a measure to alleviate this problem.
!SUBSECTION Keyfile
<!-- lib/HttpServer/ApplicationEndpointServer.h -->
@startDocuBlock serverKeyfile
!SUBSECTION Cafile
<!-- lib/HttpServer/ApplicationEndpointServer.h -->
@startDocuBlock serverCafile
`--server.disable-authentication value`
!SUBSECTION SSL protocol
<!-- lib/HttpServer/ApplicationEndpointServer.h -->
@startDocuBlock serverSSLProtocol
Setting value to true will turn off authentication on the server side so all clients can execute any action without authorisation and privilege checks.
!SUBSECTION SSL Cache
<!-- lib/HttpServer/ApplicationEndpointServer.h -->
@startDocuBlock serverSSLCache
The default value is false.
!SUBSECTION SSL options
<!-- lib/HttpServer/ApplicationEndpointServer.h -->
@startDocuBlock serverSSLOptions
!SUBSECTION SSL Cipher
<!-- lib/HttpServer/ApplicationEndpointServer.h -->
@startDocuBlock serverSSLCipher
`--server.disable-authentication-unix-sockets value`
Setting value to true will turn off authentication on the server side for requests coming in via UNIX domain sockets. With this flag enabled, clients located on the same host as the ArangoDB server can use UNIX domain sockets to connect to the server without authentication. Requests coming in by other means (e.g. TCP/IP) are not affected by this option.
!SUBSECTION Backlog
<!-- lib/HttpServer/ApplicationEndpointServer.h -->
@startDocuBlock serverBacklog
The default value is false.
Note: this option is only available on platforms that support UNIX domain sockets.
`--server.authenticate-system-only boolean`
Controls whether incoming requests need authentication only if they are directed to the ArangoDB's internal APIs and features, located at /_api/, /_admin/ etc.
IF the flag is set to true, then HTTP authentication is only required for requests going to URLs starting with /_, but not for other URLs. The flag can thus be used to expose a user-made API without HTTP authentication to the outside world, but to prevent the outside world from using the ArangoDB API and the admin interface without authentication. Note that checking the URL is performed after any database name prefix has been removed. That means when the actual URL called is /_db/_system/myapp/myaction, the URL /myapp/myaction will be used for authenticate-system-only check.
The default is false.
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 the web interface. Setting only this flag is not enough.
You can control ArangoDB's general authentication feature with the --server.disable-authentication flag.
`--server.disable-replication-logger flag`
If true the server will start with the replication logger turned off, even if the replication logger is configured with the autoStart option. Using this option will not change the value of the autoStart option in the logger configuration, but will suppress auto-starting the replication logger just once.
If the option is not used, ArangoDB will read the logger configuration from the file REPLICATION-LOGGER-CONFIG on startup, and use the value of the autoStart attribute from this file.
The default is false.
`--server.disable-replication-applier flag`
If true the server will start with the replication applier turned off, even if the replication applier is 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 the replication applier just once.
If the option is not used, ArangoDB will read the applier configuration from the file REPLICATION-APPLIER-CONFIG on startup, and use the value of the autoStart attribute from this file.
The default 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.default-api-compatibility`
This option can be used to determine the API compatibility of ArangoDB in both the HTTP interface and the JavaScript libraries. Deprecated features that haven't been deprecated in that version will no longer show warnings when being used.
The commandline option expects an ArangoDB version number as an integer, calculated as follows:
10000 * major + 100 * minor (example: 10400 for ArangoDB 1.4)
In most cases it will be sufficient to not set this option explicitly but to keep the default value. However, in case an "old" ArangoDB client is used that does not send any compatibility information and that cannot handle the responses of the current version of ArangoDB, it might be reasonable to set the option to an old version number to improve compatibility with older clients.
`--server.allow-method-override`
When this option is set to true, the HTTP request method will optionally be fetched from one of the following HTTP request headers if present in the request:
* x-http-method
* x-http-method-override
* x-method-override
If the option is set to true and any of these headers is set, the request method will be overriden by the value of the header. For example, this allows issuing an HTTP DELETE request which to the outside world will look like an HTTP GET request. This allows bypassing proxies and tools that will only let certain request types pass.
Setting this option to true may impose a security risk so it should only be used in controlled environments.
The default value for this option is false.
`--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.
`--server.backlog-size`
Allows to specify the size of the backlog for the listen system call The default value is 10. The maximum value is platform-dependent.
<!--
@anchor CommandLineArangoEndpoint
@copydetails triagens::rest::ApplicationEndpointServer::_endpoints
@CLEARPAGE
@anchor CommandLineArangoReuseAddress
@copydetails triagens::rest::ApplicationEndpointServer::_reuseAddress
@CLEARPAGE
@anchor CommandLineArangoDisableAuthentication
@copydetails triagens::arango::ArangoServer::_disableAuthentication
@CLEARPAGE
@anchor CommandLineArangoDisableAuthenticationUnixSockets
@copydetails triagens::arango::ArangoServer::_disableAuthenticationUnixSockets
@CLEARPAGE
@anchor CommandLineArangoAuthenticateSystemOnly
@copydetails triagens::arango::ArangoServer::_authenticateSystemOnly
@CLEARPAGE
@anchor CommandLineArangoDisableReplicationLogger
@copydetails triagens::arango::ArangoServer::_disableReplicationLogger
@CLEARPAGE
@anchor CommandLineArangoDisableReplicationApplier
@copydetails triagens::arango::ArangoServer::_disableReplicationApplier
@CLEARPAGE
@anchor CommandLineArangoKeepAliveTimeout
@copydetails triagens::rest::ApplicationEndpointServer::_keepAliveTimeout
@CLEARPAGE
@anchor CommandLineArangoDefaultApiCompatibility
@copydetails triagens::rest::ApplicationEndpointServer::_defaultApiCompatibility
@CLEARPAGE
@anchor CommandLineArangoAllowMethodOverride
@copydetails triagens::rest::ApplicationEndpointServer::_allowMethodOverride
@CLEARPAGE
@anchor CommandLineArangoKeyFile
@copydetails triagens::rest::ApplicationEndpointServer::_httpsKeyfile
@CLEARPAGE
@anchor CommandLineArangoCaFile
@copydetails triagens::rest::ApplicationEndpointServer::_cafile
@CLEARPAGE
@anchor CommandLineArangoSslProtocol
@copydetails triagens::rest::ApplicationEndpointServer::_sslProtocol
@CLEARPAGE
@anchor CommandLineArangoSslCacheMode
@copydetails triagens::rest::ApplicationEndpointServer::_sslCache
@CLEARPAGE
@anchor CommandLineArangoSslOptions
@copydetails triagens::rest::ApplicationEndpointServer::_sslOptions
@CLEARPAGE
@anchor CommandLineArangoSslCipherList
@copydetails triagens::rest::ApplicationEndpointServer::_sslCipherList
@CLEARPAGE
@anchor CommandLineArangoBacklogSize
@copydetails triagens::rest::ApplicationEndpointServer::_backlogSize
-->
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.
!SUBSECTION Disable statics
`--disable-statistics value`
@ -309,97 +78,31 @@ option to turn it off might relieve heavy-loaded instances.
Note: this option is only available when ArangoDB has not been compiled with
the option *--disable-figures*.
`--database.directory directory`
!SUBSECTION Directory
<!-- lib/HttpServer/ApplicationEndpointServer.h -->
@startDocuBlock DatabaseDirectory
The directory containing the collections and datafiles. Defaults to /var/lib/arango. When specifying the database directory, please make sure the directory is actually writable by the arangod process.
!SUBSECTION Journal size
<!-- lib/HttpServer/ApplicationEndpointServer.h -->
@startDocuBlock databaseMaximalJournalSize
You should further not use a database directory which is provided by a network filesystem such as NFS. The reason is that networked filesystems might cause inconsistencies when there are multiple parallel readers or writers or they lack features required by arangod (e.g. flock()).
`directory`
When using the command line version, you can simply supply the database directory as argument.
*Examples*
> ./arangod --server.endpoint tcp://127.0.0.1:8529 --database.directory /tmp/vocbase
`--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.
!SUBSECTION Wait for sync
<!-- lib/HttpServer/ApplicationEndpointServer.h -->
@startDocuBlock databaseWaitForSync
`--database.wait-for-sync boolean`
!SUBSECTION Sync properties
<!-- lib/HttpServer/ApplicationEndpointServer.h -->
@startDocuBlock databaseForceSync
Default wait-for-sync value. Can be overwritten when creating a new collection.
!SUBSECTION Frequency
<!-- arangod/V8Server/ApplicationV8.h -->
@startDocuBlock jsGcFrequency
The default is false.
!SUBSECTION Startup gc-interval
<!-- arangod/V8Server/ApplicationV8.h -->
@startDocuBlock jsStartupGcInterval
`--database.force-sync-properties boolean`
Force syncing of collection properties to disk after creating a collection or updating its properties.
If turned off, syncing will still happen for collection that have a waitForSync value of true. If turned on, syncing of properties will always happen, regardless of the value of waitForSync.
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.
`--javascript.v8-options options`
Optional arguments to pass to the V8 Javascript engine. The V8 engine will run with default settings unless explicit options are specified using this option. The options passed will be forwarded to the V8 engine which will parse them on its own. Passing invalid options may result in an error being printed on stderr and the option being ignored.
Options need to be passed in one string, with V8 option names being prefixed with double dashes. Multiple options need to be separated by whitespace. To get a list of all available V8 options, you can use the value "&ndash;help" as follows:
`--javascript.v8-options "--help"`
Another example of specific V8 options being set at startup:
`--javascript.v8-options "--harmony --log"`
Names and features or usable options depend on the version of V8 being used, and might change in the future if a different version of V8 is being used in ArangoDB. Not all options offered by V8 might be sensible to use in the context of ArangoDB. Use the specific options only if you are sure that they are not harmful for the regular database operation.
<!--
@CLEARPAGE
@anchor CommandLineArangoDirectory
@copydetails triagens::arango::ArangoServer::_databasePath
@CLEARPAGE
@anchor CommandLineArangoMaximalJournalSize
@copydetails triagens::arango::ArangoServer::_defaultMaximalSize
@CLEARPAGE
@anchor CommandLineArangoWaitForSync
@copydetails triagens::arango::ArangoServer::_defaultWaitForSync
@CLEARPAGE
@anchor CommandLineArangoForceSyncProperties
@copydetails triagens::arango::ArangoServer::_forceSyncProperties
@CLEARPAGE
@anchor CommandLineArangoRemoveOnDrop
@copydetails triagens::arango::ArangoServer::_removeOnDrop
@CLEARPAGE
@anchor CommandLineArangoJsGcFrequency
@copydetails triagens::arango::ApplicationV8::_gcFrequency
@CLEARPAGE
@anchor CommandLineArangoJsGcInterval
@copydetails triagens::arango::ApplicationV8::_gcInterval
@CLEARPAGE
@anchor CommandLineArangoJsV8Options
@copydetails triagens::arango::ApplicationV8::_v8Options
-->
!SUBSECTION V8 options
<!-- arangod/V8Server/ApplicationV8.h -->
@startDocuBlock jsV8Options

95
Documentation/Books/Users/ConfigureArango/Authentication.mdpp
View File

@ -8,37 +8,26 @@ will allow the administrator to restrict access to collections and queries to
certain users, given them either read or write access.
Currently, you can only secure the access to ArangoDB in an all-or-nothing
fashion. The collection `_users` contains all users and a salted SHA256 hash
fashion. The collection *_users* contains all users and a salted SHA256 hash
of their passwords. A user can be active or inactive. A typical document of this
collection is
{
"_id" : "_users/1172449",
"_rev" : "1172449",
"_key" : "1172449",
"active" : true,
"changePassword" : false,
"user" : "root",
"password" : "$1$bd5458a8$8b23e2e1a762f75001ab182235b8ab1b8665bc572b0734a042a501b3c34e567a"
}
<!--
@EXAMPLE_ARANGOSH_OUTPUT{AuthenticationExample1}
db._users.firstExample("user", "root")
@END_EXAMPLE_ARANGOSH_OUTPUT
-->
```js
{
"_id" : "_users/1172449",
"_rev" : "1172449",
"_key" : "1172449",
"active" : true,
"changePassword" : false,
"user" : "root",
"password" : "$1$bd5458a8$8b23e2e1a762f75001ab182235b8ab1b8665bc572b0734a042a501b3c34e567a"
}
```
!SUBSECTION Command-Line Options for the Authentication and Authorization
`--server.disable-authentication value`
Setting value to true will turn off authentication on the server side so all clients can execute any action without authorization and privilege checks.
The default value is false.
<!--@copydetails triagens::arango::ArangoServer::_disableAuthentication-->
<!-- arangod/RestServer/ArangoServer.h -->
@startDocuBlock server_authentication
!SECTION Introduction to User Management
@ -46,9 +35,11 @@ ArangoDB provides basic functionality to add, modify and remove database users
programmatically. The following functionality is provided by the *users* module
and can be used from inside arangosh and arangod.
Please note that this functionality is not available from within the web
**Note**: This functionality is not available from within the web
interface.
!SUBSECTION Save
`users.save(user, passwd, active, extra, changePassword)`
This will create a new ArangoDB user. The username must be specified in
@ -70,11 +61,15 @@ name.
The new user account can only be used after the server is either restarted or
the server authentication cache is [reloaded](#examples_reload).
Note: this function will not work from within the web interface
**Note**: this function will not work from within the web interface
!SUBSUBSECTION EXAMPLES
*Examples*
arangosh> require("org/arangodb/users").save("my-user", "my-secret-password");
```js
arangosh> require("org/arangodb/users").save("my-user", "my-secret-password");
```
!SUBSECTION Document
`users.document(user)`
@ -84,7 +79,9 @@ The username must be specified in *user*.
This method will fail if the user cannot be found in the database.
Note: this function will not work from within the web interface
**Note**: this function will not work from within the web interface
!SUBSECTION Replace
`users.replace(user, passwd, active, extra, changePassword)`
@ -106,11 +103,15 @@ This method will fail if either the username or the passwords are not specified
or given in a wrong format, or if the specified user cannot be found in the
database.
Note: this function will not work from within the web interface
**Note**: this function will not work from within the web interface
!SUBSUBSECTION EXAMPLES Update
*Examples*
arangosh> require("org/arangodb/users").replace("my-user", "my-changed-password");
```js
arangosh> require("org/arangodb/users").replace("my-user", "my-changed-password");
```
!SUBSECTION Update
`users.update(user, passwd, active, extra, changePassword)`
@ -129,11 +130,15 @@ This method will fail if either the username or the passwords are not specified
or given in a wrong format, or if the specified user cannot be found in the
database.
Note: this function will not work from within the web interface
**Note**: this function will not work from within the web interface
!SUBSUBSECTION EXAMPLES Remove
*Examples*
arangosh> require("org/arangodb/users").update("my-user", "my-secret-password");
```js
arangosh> require("org/arangodb/users").update("my-user", "my-secret-password");
```
!SUBSECTION Remove
`users.remove(user)`
@ -144,11 +149,15 @@ the database.
This method will fail if the user cannot be found in the database.
Note: this function will not work from within the web interface
**Note**: this function will not work from within the web interface
!SUBSUBSECTION EXAMPLES Reload
*Examples*
arangosh> require("org/arangodb/users").remove("my-user");
```js
arangosh> require("org/arangodb/users").remove("my-user");
```
!SUBSECTION Reload
`users.reload()`
@ -158,7 +167,9 @@ All user authentication data is loaded by the server once on startup only and is
cached after that. When users get added or deleted, a cache flush is required,
and this can be performed by called this method.
Note: this function will not work from within the web interface
**Note**: this function will not work from within the web interface
!SUBSECTION isValid
`users.isvalid(user, password)`
@ -169,7 +180,9 @@ is valid.
Each call to this function is penalized by the server sleeping a random
amount of time.
Note: this function will not work from within the web interface
**Note**: this function will not work from within the web interface
!SUBSECTION all()
`users.all()`

107
Documentation/Books/Users/ConfigureArango/Cluster.mdpp
View File

@ -1,96 +1,25 @@
!CHAPTER Command-Line Options for Clusters
`--cluster.agency-endpoint endpoint`
!SUBSECTION Agency endpoint
<!-- arangod/Cluster/ApplicationCluster.h -->
@startDocuBlock clusterAgencyEndpoint
An agency endpoint the server can connect to. The option can be specified multiple times so the server can use a cluster of agency servers. Endpoints have the following pattern:
!SUBSECTION Agency prefix
<!-- arangod/Cluster/ApplicationCluster.h -->
@startDocuBlock clusterAgencyPrefix
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
!SUBSECTION MyId
<!-- arangod/Cluster/ApplicationCluster.h -->
@startDocuBlock clusterMyId
At least one endpoint must be specified or ArangoDB will refuse to start. It is recommended to specify at least two endpoints so ArangoDB has an alternative endpoint if one of them becomes unavailable.
!SUBSECTION MyAddress
<!-- arangod/Cluster/ApplicationCluster.h -->
@startDocuBlock clusterMyAddress
*Examples*
!SUBSECTION Username
<!-- arangod/Cluster/ApplicationCluster.h -->
@startDocuBlock clusterUsername
--cluster.agency-endpoint tcp://192.168.1.1:4001 --cluster.agency-endpoint tcp://192.168.1.2:4002
`--cluster.agency-prefix prefix`
The global key prefix used in all requests to the agency. The specified prefix will become part of each agency key. Specifying the key prefix allows managing multiple ArangoDB clusters with the same agency server(s).
prefix must consist of the letters a-z, A-Z and the digits 0-9 only. Specifying a prefix is mandatory.
Examples
`--cluster.prefix mycluster`
`--cluster.my-id id`
The local server's id in the cluster. Specifying id is mandatory on startup. Each server of the cluster must have a unique id.
Specifying the id is very important because the server id is used for determining the server's role and tasks in the cluster.
id must be a string consisting of the letters a-z, A-Z or the digits 0-9 only.
`--cluster.my-address endpoint`
The server's endpoint for cluster-internal communication. If specified, it must 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
If no endpoint is specified, the server will look up its internal endpoint address in the agency. If no endpoint can be found in the agency for the server's id, ArangoDB will refuse to start.
*Examples*
--cluster.my-address tcp://192.168.1.1:8530
`--cluster.username username`
The username used for authorization of cluster-internal requests. This username will be used to authenticate all requests and responses in cluster-internal communication, i.e. requests exchanged between coordinators and individual database servers.
This option is used for cluster-internal requests only. Regular requests to coordinators are authenticated normally using the data in the _users collection.
If coordinators and database servers are run with authentication turned off, (e.g. by setting the --server.disable-authentication option to true), the cluster-internal communication will also be unauthenticated.
`--cluster.password password`
The password used for authorization of cluster-internal requests. This password will be used to authenticate all requests and responses in cluster-internal communication, i.e. requests exchanged between coordinators and individual database servers.
This option is used for cluster-internal requests only. Regular requests to coordinators are authenticated normally using the data in the _users collection.
If coordinators and database servers are run with authentication turned off, (e.g. by setting the --server.disable-authentication option to true), the cluster-internal communication will also be unauthenticated.
<!--
@anchor CommandLineArangoClusterHeartbeatInterval
@copydetails triagens::arango::ApplicationCluster::_heartbeatInterval
@CLEARPAGE
@anchor CommandLineArangoClusterAgencyEndpoint
@copydetails triagens::arango::ApplicationCluster::_agencyEndpoints
@CLEARPAGE
@anchor CommandLineArangoClusterAgencyPrefix
@copydetails triagens::arango::ApplicationCluster::_agencyPrefix
@CLEARPAGE
@anchor CommandLineArangoClusterMyId
@copydetails triagens::arango::ApplicationCluster::_myId
@CLEARPAGE
@anchor CommandLineArangoClusterMyAddress
@copydetails triagens::arango::ApplicationCluster::_myAddress
@CLEARPAGE
@anchor CommandLineArangoClusterUsername
@copydetails triagens::arango::ApplicationCluster::_username
@CLEARPAGE
@anchor CommandLineArangoClusterPassword
@copydetails triagens::arango::ApplicationCluster::_password
-->
!SUBSECTION Password
<!-- arangod/Cluster/ApplicationCluster.h -->
@startDocuBlock clusterPassword

33
Documentation/Books/Users/ConfigureArango/Communication.mdpp
View File

@ -1,33 +1,20 @@
!CHAPTER 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.
!SUBSECTION Scheduler threads
<!-- lib/Scheduler/ApplicationScheduler.h -->
@startDocuBlock schedulerThreads
`--scheduler.maximal-queue-size size`
Specifies the maximum size of the dispatcher queue for asynchronous task execution. If the queue already contains size tasks, new tasks will be rejected until other tasks are popped from the queue. Setting this value may help preventing from running out of memory if the queue is filled up faster than the server can process requests.
`--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.
!SUBSECTION Scheduler maximal queue size
<!-- arangod/RestServer/ArangoServer.h -->
@startDocuBlock serverAuthenticationDisable
!SUBSECTION Scheduler backend
<!-- lib/Scheduler/ApplicationScheduler.h -->
@startDocuBlock schedulerBackend
!SUBSECTION Io backends
`--show-io-backends`
<!--
@anchor CommandLineSchedulerThreads
@copydetails triagens::rest::ApplicationScheduler::_nrSchedulerThreads
@CLEARPAGE
@anchor CommandLineSchedulerMaximalQueueSize
@copydetails triagens::arango::ArangoServer::_dispatcherQueueSize
@CLEARPAGE
@anchor CommandLineSchedulerBackend
@copydetails triagens::rest::ApplicationScheduler::_backend
-->
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

14
Documentation/Books/Users/ConfigureArango/Development.mdpp
View File

@ -1,14 +0,0 @@
!CHAPTER Command-Line Options for Development
`--development-mode`
Specifying this option will start the server in development mode. The development mode forces reloading of all actions and Foxx applications on every HTTP request. This is very resource-intensive and slow, but makes developing server-side actions and Foxx applications much easier.
Never use this option in production.
<!--
@anchor CommandLineArangoDevelopmentMode
@copydetails triagens::arango::ArangoServer::_developmentMode
-->

23
Documentation/Books/Users/ConfigureArango/EmergencyConsole.mdpp
View File

@ -4,19 +4,20 @@
The following command starts a emergency console.
*Note:* Never start the emergency console for a database which also has a
**Note**: Never start the emergency console for a database which also has a
server attached to it. In general the ArangoDB shell is what you want.
> ./arangod --console --log error /tmp/vocbase
ArangoDB shell [V8 version 3.9.4, DB version 1.x.y]
arango> 1 + 2;
3
arango> db.geo.count();
703
<!--@EXAMPLE{start-emergency-console,emergency console} -->
```
> ./arangod --console --log error /tmp/vocbase
ArangoDB shell [V8 version 3.9.4, DB version 1.x.y]
arango> 1 + 2;
3
arango> db.geo.count();
703
```
The emergency console disables the HTTP interface of the server and
opens a JavaScript console on standard output instead. This allows you

50
Documentation/Books/Users/ConfigureArango/Endpoint.mdpp
View File

@ -3,7 +3,7 @@
The ArangoDB server can listen for incoming requests on multiple *endpoints*.
The endpoints are normally specified either in ArangoDB's configuration file or on
the command-line, using the ["--server.endpoint"](../CommandLineOptions/Arangod.md) option.
the command-line, using the ["--server.endpoint"](../ConfigureArango/Arangod.md) option.
The default endpoint for ArangoDB is *tcp://127.0.0.1:8529* or *tcp://localhost:8529*.
The number of endpoints can also be changed at runtime using the API described
@ -26,44 +26,14 @@ When not in the default database, you must first switch to it using the
!SECTION Configuring and Removing Endpoints
`db._listEndpoints()`
!SUBSECTION List
<!-- js/server/modules/org/arangodb/arango-database.js -->
@startDocuBlock listEndpoints
Returns a list of all endpoints and their mapped databases.
!SUBSECTION Configure
<!-- js/server/modules/org/arangodb/arango-database.js -->
@startDocuBlock configureEndpoint
Please note that managing endpoints can only be performed from out of the *_system* database. When not in the default database, you must first switch to it using the *db._useDatabase* method.
`db._configureEndpoint(endpoint, databases)`
Adds and connects or updates the endpoint.
The optional databases argument allows restricting the endpoint for use with specific databases only. The first database in the list will automatically become the default database for the endpoint. The default database will be used for incoming requests that do not specify the database name explicitly.
If databases is an empty list, the endpoint will allow access to all existing databases.
The adjusted list of endpoints is saved in a file *ENDPOINTS* in the database directory. The endpoints are restored from the file at server start.
Please note that managing endpoints can only be performed from out of the *_system* database. When not in the default database, you must first switch to it using the *db._useDatabase* method.
`db._removeEndpoint(endpoint)`
Disconnects and removes the endpoint. If the endpoint was not configured before, the operation will fail. If the endpoint happens to be the last bound endpoint, the operation will also fail as disconnecting would make the server unable to communicate with any clients.
The adjusted list of endpoints is saved in a file *ENDPOINTS* in the database directory. The endpoints are restored from the file at server start.
Please note that managing endpoints can only be performed from out of the *_system* database. When not in the default database, you must first switch to it using the *db._useDatabase* method.
<!--
@anchor HandlingEndpointsList
@copydetails JSF_ArangoDatabase_prototype__listEndpoints
@CLEARPAGE
@anchor HandlingEndpointsConfigure
@copydetails JSF_ArangoDatabase_prototype__configureEndpoint
@CLEARPAGE
@anchor HandlingEndpointsRemove
@copydetails JSF_ArangoDatabase_prototype__removeEndpoint
-->
!SUBSECTION Remove
<!-- js/server/modules/org/arangodb/arango-database.js -->
@startDocuBlock removeEndpoint

174
Documentation/Books/Users/ConfigureArango/GeneralOptions.mdpp
View File

@ -1,174 +0,0 @@
!CHAPTER 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.
`--upgrade`
Specifying this option will make the server perform a database upgrade at start. A database upgrade will first compare the version number stored in the file VERSION in the database directory with the current server version.
If the two version numbers match, the server will start normally.
If the version number found in the database directory is higher than the version number the server is running, the server expects this is an unintentional downgrade and will warn about this. It will however start normally. Using the server in these conditions is however not recommended nor supported.
If the version number found in the database directory is lower than the version number the server is running, the server will check whether there are any upgrade tasks to perform. It will then execute all required upgrade tasks and print their statuses. If one of the upgrade tasks fails, the server will exit and refuse to start. Re-starting the server with the upgrade option will then again trigger the upgrade check and execution until the problem is fixed. If all tasks are finished, the server will start normally.
Whether or not this option is specified, the server will always perform a version check on startup. Running the server with a non-matching version number in the VERSION file will make the server refuse to start.
`--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 ~/.arango/arangod.conf in the user's home directory.
If no such file is found, the server will proceed to look for a file arangod.conf in the system configuration directory. The system configuration directory is platform-specific, and may be changed when compiling ArangoDB yourself. It may default to /etc/arangodb or /usr/local/etc/arangodb. This file is installed when using a package manager like rpm or dpkg. If you modify this file and later upgrade to a new version of ArangoDB, then the package manager normally warns you about the conflict. In order to avoid these warning for small adjustments, you can put local overrides into a file arangod.conf.local.
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.
Whitespace in the configuration file 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
or
--configuration none
when starting up the server. Note that, the word none is case-insensitive.
<!--
@anchor CommandLineHelp
@copydetails triagens::rest::ApplicationServer::_options
@CLEARPAGE
@anchor CommandLineVersion
@copydetails triagens::rest::ApplicationServer::_version
@CLEARPAGE
@anchor CommandLineUpgrade
@copydetails triagens::arango::ApplicationV8::_performUpgrade
@CLEARPAGE
@anchor CommandLineConfiguration
@copydetails triagens::rest::ApplicationServer::_configFile
@CLEARPAGE
@anchor CommandLineDaemon
-->
`--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.
--default-language default-language
The default language ist used for sorting and comparing strings. The language value is a two-letter language code (ISO-639) or it is composed by a two-letter language 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`
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.
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 supervisor
process 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 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.
`--console`
Runs the server in an exclusive emergency console mode. When starting the server with this option, the server is started with an interactive JavaScript emergency console, with all networking and HTTP interfaces of the server disabled.
No requests can be made to the server in this mode, and the only way to work with the server in this mode is by using the emergency console. Note that the server cannot be started in this mode if it is already running in this or another mode.
<!--
@CLEARPAGE
@anchor CommandLineUid
@copydetails triagens::rest::ApplicationServer::_uid
@CLEARPAGE
@anchor CommandLineGid
@copydetails triagens::rest::ApplicationServer::_gid
@CLEARPAGE
@anchor CommandLinePidFile
@copydetails triagens::rest::AnyServer::_pidFile
@CLEARPAGE
@anchor CommandLineConsole
@CMDOPT{\--console}
-->
Runs the server in an exclusive emergency console mode. When
starting the server with this option, the server is started with
an interactive JavaScript emergency console, with all networking
and HTTP interfaces of the server disabled.
No requests can be made to the server in this mode, and the only
way to work with the server in this mode is by using the emergency
console.
Note that the server cannot be started in this mode if it is
already running in this or another mode.

220
Documentation/Books/Users/ConfigureArango/Logging.mdpp
View File

@ -5,196 +5,60 @@ 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.
!SUBSECTION General Logging Options
!SECTION General Logging Options
`--log.file filename`
!SUBSECTION Logfile
<!-- lib/ApplicationServer/ApplicationServer.h -->
@startDocuBlock logFile
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.
!SUBSECTION Request
<!-- lib/ApplicationServer/ApplicationServer.h -->
@startDocuBlock logRequests
Use + to log to standard error. Use - to log to standard output. Use "" to disable logging to file.
!SUBSECTION Severity
<!-- lib/ApplicationServer/ApplicationServer.h -->
@startDocuBlock logSeverity
!SUBSECTION Syslog
<!-- lib/ApplicationServer/ApplicationServer.h -->
@startDocuBlock logSyslog
`--log.requests-file filename`
!SECTION Human Readable Logging
This option allows the user to specify the name of a file to which requests are logged. By default, no log file is used and requests are not logged. 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.
!SUBSECTION Level
<!-- lib/ApplicationServer/ApplicationServer.h -->
@startDocuBlock logLevel
Use + to log to standard error. Use - to log to standard output. Use "" to disable request logging altogether.
!SUBSECTION Line number
<!-- lib/ApplicationServer/ApplicationServer.h -->
@startDocuBlock logLineNumber
!SUBSECTION Prefix
<!-- lib/ApplicationServer/ApplicationServer.h -->
@startDocuBlock logPrefix
`--log.severity severity`
!SUBSECTION Thread
<!-- lib/ApplicationServer/ApplicationServer.h -->
@startDocuBlock logThread
This parameter provides a set of standard log severities which can be used. The currently accepted severities are:
!SUBSECTION Source Filter
<!-- lib/ApplicationServer/ApplicationServer.h -->
@startDocuBlock logSourceFilter
* exception
* technical
* functional
* development
* human
* all (human and non-human)
* non-human (exception, technical, functional, and development)
!SUBSECTION Content Filter
<!-- lib/ApplicationServer/ApplicationServer.h -->
@startDocuBlock logContentFilter
The default is all.
!SECTION Machine Readable Logging
!SUBSECTION Application
<!-- lib/ApplicationServer/ApplicationServer.h -->
@startDocuBlock logApplication
`--log.syslog arg`
!SUBSECTION Facility
<!-- lib/ApplicationServer/ApplicationServer.h -->
@startDocuBlock logFacility
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.
<!--
@anchor CommandLineLoggingLogFile
@copydetails triagens::rest::ApplicationServer::_logFile
@CLEARPAGE
@anchor CommandLineLoggingLogRequestsFile
@copydetails triagens::rest::ApplicationServer::_logRequestsFile
@CLEARPAGE
@anchor CommandLineLoggingLogSeverity
@copydetails triagens::rest::ApplicationServer::_logSeverity
@CLEARPAGE
@anchor CommandLineLoggingLogSyslog
@copydetails triagens::rest::ApplicationServer::_logSyslog
-->
!SUBSECTION 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.source-filter arg`
For debug and trace messages, only log those messages originated from the C source file arg. The argument can be used multiple times.
`--log.content-filter arg`
Only log message containing the specified string arg.
<!--
@anchor CommandLineLoggingLogLevel
@copydetails triagens::rest::ApplicationServer::_logLevel
@CLEARPAGE
@anchor CommandLineLoggingLogLineNumber
@copydetails triagens::rest::ApplicationServer::_logLineNumber
@CLEARPAGE
@anchor CommandLineLoggingLogPrefix
@copydetails triagens::rest::ApplicationServer::_logPrefix
@CLEARPAGE
@anchor CommandLineLoggingLogThread
@copydetails triagens::rest::ApplicationServer::_logThreadId
@CLEARPAGE
@anchor CommandLineLoggingLogSourceFilter
@copydetails triagens::rest::ApplicationServer::_logSourceFilter
@CLEARPAGE
@anchor CommandLineLoggingLogContentFilter
@copydetails triagens::rest::ApplicationServer::_logContentFilter
-->
!SUBSECTION Machine 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.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.
<!--
@anchor CommandLineLoggingLogApplication
@copydetails triagens::rest::ApplicationServer::_logApplicationName
@CLEARPAGE
@anchor CommandLineLoggingLogFacility
@copydetails triagens::rest::ApplicationServer::_logFacility
@CLEARPAGE
@anchor CommandLineLoggingLogHostName
@copydetails triagens::rest::ApplicationServer::_logHostName
-->
!SUBSECTION Histname
<!-- lib/ApplicationServer/ApplicationServer.h -->
@startDocuBlock logHostname

98
Documentation/Books/Users/ConfigureArango/README.mdpp
View File

@ -4,3 +4,101 @@
Options can be specified on the command line or in configuration files. If a
string *Variable* occurs in the value, it is replaced by the corresponding
environment variable.
!SECTION General Options
!SUBSECTION General help
<!-- lib/ApplicationServer/ApplicationServer.h -->
@startDocuBlock generalHelp
!SUBSECTION Upgrade
`--upgrade`
Specifying this option will make the server perform a database upgrade at start. A database upgrade will first compare the version number stored in the file VERSION in the database directory with the current server version.
If the two version numbers match, the server will start normally.
If the version number found in the database directory is higher than the version number the server is running, the server expects this is an unintentional downgrade and will warn about this. It will however start normally. Using the server in these conditions is however not recommended nor supported.
If the version number found in the database directory is lower than the version number the server is running, the server will check whether there are any upgrade tasks to perform. It will then execute all required upgrade tasks and print their statuses. If one of the upgrade tasks fails, the server will exit and refuse to start. Re-starting the server with the upgrade option will then again trigger the upgrade check and execution until the problem is fixed. If all tasks are finished, the server will start normally.
Whether or not this option is specified, the server will always perform a version check on startup. Running the server with a non-matching version number in the VERSION file will make the server refuse to start.
!SUBSECTION Configuration
<!-- lib/ApplicationServer/ApplicationServer.h -->
@startDocuBlock configurationFilename
!SUBSECTION Daemon
`--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.
!SUBSECTION Default Language
<!-- arangod/RestServer/ArangoServer.h -->
@startDocuBlock DefaultLanguage
!SUBSECTION Supervisor
`--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.
```js
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 supervisor
process and the actual database process:
```js
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 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/
```
!SUBSECTION User identity
<!-- lib/ApplicationServer/ApplicationServer.h -->
@startDocuBlock configurationUid
!SUBSECTION Group identity
<!-- lib/ApplicationServer/ApplicationServer.h -->
@startDocuBlock configurationGid
!SUBSECTION Process identity
<!-- lib/Rest/AnyServer.h -->
@startDocuBlock pidFile
!SUBSECTION Console
`--console`
Runs the server in an exclusive emergency console mode. When
starting the server with this option, the server is started with
an interactive JavaScript emergency console, with all networking
and HTTP interfaces of the server disabled.
No requests can be made to the server in this mode, and the only
way to work with the server in this mode is by using the emergency
console.
Note that the server cannot be started in this mode if it is
already running in this or another mode.
!SECTION Command-Line Options for Development
<!-- arangod/RestServer/ArangoServer.h -->
@startDocuBlock developmentMode

12
Documentation/Books/Users/ConfigureArango/RandomNumbers.mdpp
View File

@ -1,12 +1,4 @@
!SUBSECTION 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.
<!--
@anchor CommandLineRandomGenerator
@copydetails triagens::rest::ApplicationServer::_randomGenerator
-->
<!-- lib/ApplicationServer/ApplicationServer.h -->
@startDocuBlock randomGenerator

2
Documentation/Books/Users/SUMMARY.md
View File

@ -117,10 +117,8 @@
* [Firewall setup](Sharding/FirewallSetup.md)
<!-- 19 -->
* [Configure ArangoDB](ConfigureArango/README.md)
* [General options](ConfigureArango/GeneralOptions.md)
* [Arangod options](ConfigureArango/Arangod.md)
* [Endpoints options](ConfigureArango/Endpoint.md)
* [Development options](ConfigureArango/Development.md)
* [Cluster options](ConfigureArango/Cluster.md)
* [Logging options](ConfigureArango/Logging.md)
* [Communication options](ConfigureArango/Communication.md)

2
Documentation/Books/Users/localtheme/templates/includes/book/header.html
View File

@ -23,6 +23,6 @@
<!-- Title -->
<h1>
<a href="https://www.arangodb.org" > <img src="../Arangodb_Logo.png" alt="ArangoDB" style="position:relative; border:0px; top:-4px"></a>
<div style="position:relative; bottom:50px; left:79px; font-size:12pt">2.1.0</div>
<div style="position:relative; bottom:50px; left:79px; font-size:12pt">2.2.0</div>
</h1>
</div>

2
Documentation/Books/codeBlockReader.py
View File

@ -192,7 +192,7 @@ def fetch_comments(dirpath):
if __name__ == "__main__":
open("allComments.txt", "w").close()
path = ["arangod/cluster","arangod/RestHandler","arangod/V8Server","arangod/RestServer",
"lib/Admin","lib/HttpServer","lib/V8",
"lib/Admin","lib/HttpServer","lib/V8","lib/ApplicationServer","lib/Scheduler","lib/Rest",
"js/actions","js/client","js/apps/databases","js/apps/system/cerberus","js/apps/system/gharial","js/common","js/server"]
for i in path:
dirpath = os.path.abspath(os.path.join(os.path.dirname( __file__ ), os.pardir,"ArangoDB/../../"+i))

8
Documentation/Examples/openssl-ciphers
View File

@ -1,8 +0,0 @@
> 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
...

9
Documentation/Examples/openssl-options
View File

@ -1,9 +0,0 @@
> 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
...

1
Documentation/Examples/option-database-directory
View File

@ -1 +0,0 @@
> ./arangod --server.endpoint tcp://127.0.0.1:8529 --database.directory /tmp/vocbase

10
Documentation/Examples/server-keyfile
View File

@ -1,10 +0,0 @@
-----BEGIN CERTIFICATE-----
(base64 encoded certificate)
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
(base64 encoded private key)
-----END RSA PRIVATE KEY-----

17
Documentation/Examples/server-keyfile-openssl
View File

@ -1,17 +0,0 @@
# 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

8
Documentation/Examples/start-emergency-console
View File

@ -1,8 +0,0 @@
> ./arangod --console --log error /tmp/vocbase
ArangoDB shell [V8 version 3.9.4, DB version 1.x.y]
arango> 1 + 2;
3
arango> db.geo.count();
703

59
arangod/Cluster/ApplicationCluster.h
View File

@ -178,12 +178,13 @@ namespace triagens {
////////////////////////////////////////////////////////////////////////////////
/// @brief list of agency endpoints
///
/// @CMDOPT{\--cluster.agency-endpoint @CA{endpoint}}
/// @startDocuBlock clusterAgencyEndpoint
/// `--cluster.agency-endpoint endpoint`
///
/// An agency endpoint the server can connect to. The option can be specified
/// multiple times so the server can use a cluster of agency servers. 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
@ -195,56 +196,59 @@ namespace triagens {
///
/// @EXAMPLES
///
/// @code
/// ```
/// --cluster.agency-endpoint tcp://192.168.1.1:4001 --cluster.agency-endpoint tcp://192.168.1.2:4002
/// @endcode
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
std::vector<std::string> _agencyEndpoints;
////////////////////////////////////////////////////////////////////////////////
/// @brief global agency prefix
///
/// @CMDOPT{\--cluster.agency-prefix @CA{prefix}}
/// @startDocuBlock clusterAgencyPrefix
/// `--cluster.agency-prefix prefix`
///
/// The global key prefix used in all requests to the agency. The specified
/// prefix will become part of each agency key. Specifying the key prefix
/// allows managing multiple ArangoDB clusters with the same agency
/// server(s).
///
/// @CA{prefix} must consist of the letters `a-z`, `A-Z` and the digits `0-9`
/// *prefix* must consist of the letters *a-z*, *A-Z* and the digits *0-9*
/// only. Specifying a prefix is mandatory.
///
/// @EXAMPLES
///
/// @code
/// ```
/// --cluster.prefix mycluster
/// @endcode
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
std::string _agencyPrefix;
////////////////////////////////////////////////////////////////////////////////
/// @brief this server's id
/// @startDocuBlock clusterMyId
/// `--cluster.my-id id
///
/// @CMDOPT{\--cluster.my-id @CA{id}}
///
/// The local server's id in the cluster. Specifying @CA{id} is mandatory on
/// The local server's id in the cluster. Specifying *id* is mandatory on
/// startup. Each server of the cluster must have a unique id.
///
/// Specifying the id is very important because the server id is used for
/// determining the server's role and tasks in the cluster.
///
/// @CA{id} must be a string consisting of the letters `a-z`, `A-Z` or the
/// digits `0-9` only.
/// *id* must be a string consisting of the letters *a-z*, *A-Z* or the
/// digits *0-9* only.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
std::string _myId;
////////////////////////////////////////////////////////////////////////////////
/// @brief this server's address / endpoint
///
/// @CMDOPT{\--cluster.my-address @CA{endpoint}}
/// @startDocuBlock clusterMyAddress
/// `--cluster.my-address endpoint`
///
/// The server's endpoint for cluster-internal communication. If specified, it
/// must have the following pattern:
@ -253,23 +257,24 @@ namespace triagens {
/// - ssl://ipv4-address:port - TCP/IP endpoint, using IPv4, SSL encryption
/// - ssl://[ipv6-address]:port - TCP/IP endpoint, using IPv6, SSL encryption
///
/// If no @CA{endpoint} is specified, the server will look up its internal
/// If no *endpoint* is specified, the server will look up its internal
/// endpoint address in the agency. If no endpoint can be found in the agency
/// for the server's id, ArangoDB will refuse to start.
///
/// @EXAMPLES
///
/// @code
/// ```
/// --cluster.my-address tcp://192.168.1.1:8530
/// @endcode
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
std::string _myAddress;
////////////////////////////////////////////////////////////////////////////////
/// @brief username used for cluster-internal communication
///
/// @CMDOPT{\--cluster.username @CA{username}}
/// @startDocuBlock clusterUsername
/// `--cluster.username username`
///
/// The username used for authorization of cluster-internal requests.
/// This username will be used to authenticate all requests and responses in
@ -277,20 +282,21 @@ namespace triagens {
/// and individual database servers.
///
/// This option is used for cluster-internal requests only. Regular requests to
/// coordinators are authenticated normally using the data in the `_users`
/// coordinators are authenticated normally using the data in the *_users*
/// collection.
///
/// If coordinators and database servers are run with authentication turned off,
/// (e.g. by setting the `--server.disable-authentication` option to `true`),
/// (e.g. by setting the *--server.disable-authentication* option to *true*),
/// the cluster-internal communication will also be unauthenticated.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
std::string _username;
////////////////////////////////////////////////////////////////////////////////
/// @brief password used for cluster-internal communication
///
/// @CMDOPT{\--cluster.password @CA{password}}
/// @startDocuBlock clusterPassword
/// `--cluster.password password`
///
/// The password used for authorization of cluster-internal requests.
/// This password will be used to authenticate all requests and responses in
@ -302,8 +308,9 @@ namespace triagens {
/// collection.
///
/// If coordinators and database servers are run with authentication turned off,
/// (e.g. by setting the `--server.disable-authentication` option to `true`),
/// (e.g. by setting the *--server.disable-authentication* option to *true*),
/// the cluster-internal communication will also be unauthenticated.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
std::string _password;

130
arangod/RestServer/ArangoServer.h
View File

@ -234,31 +234,32 @@ namespace triagens {
////////////////////////////////////////////////////////////////////////////////
/// @brief whether or not only requests to internal URLs need authentication
///
/// @CMDOPT{\--server.authenticate-system-only @CA{boolean}}
/// @startDocuBlock serverAuthenticateSystemOnly
/// `--server.authenticate-system-only boolean`
///
/// Controls whether incoming requests need authentication only if they are
/// directed to the ArangoDB's internal APIs and features, located at `/_api/`,
/// `/_admin/` etc.
/// directed to the ArangoDB's internal APIs and features, located at */_api/*,
/// */_admin/* etc.
///
/// IF the flag is set to @LIT{true}, then HTTP authentication is only
/// required for requests going to URLs starting with `/_`, but not for other
/// IF the flag is set to *true*, then HTTP authentication is only
/// required for requests going to URLs starting with */_*, but not for other
/// URLs. The flag can thus be used to expose a user-made API without HTTP
/// authentication to the outside world, but to prevent the outside world from
/// using the ArangoDB API and the admin interface without authentication.
/// Note that checking the URL is performed after any database name prefix
/// has been removed. That means when the actual URL called is
/// `/_db/_system/myapp/myaction`, the URL `/myapp/myaction` will be used for
/// `authenticate-system-only` check.
/// */_db/_system/myapp/myaction*, the URL */myapp/myaction* will be used for
/// *authenticate-system-only* check.
///
/// The default is @LIT{false}.
/// The default is *false*.
///
/// 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 the
/// web interface. Setting only this flag is not enough.
///
/// You can control ArangoDB's general authentication feature with the
/// `--server.disable-authentication` flag.
/// *--server.disable-authentication* flag.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
bool _authenticateSystemOnly;
@ -280,56 +281,59 @@ namespace triagens {
////////////////////////////////////////////////////////////////////////////////
/// @brief disable authentication for requests via UNIX domain sockets
/// @startDocuBlock serverAuthenticationDisable
/// `--server.disable-authentication-unix-sockets value`
///
/// @CMDOPT{\--server.disable-authentication-unix-sockets @CA{value}}
///
/// Setting @CA{value} to true will turn off authentication on the server side
/// Setting *value* to true will turn off authentication on the server side
/// for requests coming in via UNIX domain sockets. With this flag enabled,
/// clients located on the same host as the ArangoDB server can use UNIX domain
/// sockets 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 @LIT{false}.
/// The default value is *false*.
///
/// Note: this option is only available on platforms that support UNIX domain
/// **Note**: this option is only available on platforms that support UNIX domain
/// sockets.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
bool _disableAuthenticationUnixSockets;
////////////////////////////////////////////////////////////////////////////////
/// @brief number of dispatcher threads for non-database worker
/// @startDocuBlock serverThreads
/// `--server.threads number`
///
/// @CMDOPT{\--server.threads @CA{number}}
///
/// Specifies the @CA{number} of threads that are spawned to handle action
/// Specifies the *number* of threads that are spawned to handle action
/// requests using Rest, JavaScript, or Ruby.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
int _dispatcherThreads;
////////////////////////////////////////////////////////////////////////////////
/// @brief maximum size of the dispatcher queue for asynchronous requests
/// @startDocuBlock serverAuthenticationDisable
/// `--scheduler.maximal-queue-size size`
///
/// @CMDOPT{\--scheduler.maximal-queue-size @CA{size}}
///
/// Specifies the maximum @CA{size} of the dispatcher queue for asynchronous
/// task execution. If the queue already contains @CA{size} tasks, new tasks
/// Specifies the maximum *size* of the dispatcher queue for asynchronous
/// task execution. If the queue already contains *size* tasks, new tasks
/// will be rejected until other tasks are popped from the queue. Setting this
/// value may help preventing from running out of memory if the queue is filled
/// up faster than the server can process requests.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
int _dispatcherQueueSize;
////////////////////////////////////////////////////////////////////////////////
/// @brief path to the database
///
/// @CMDOPT{\--database.directory @CA{directory}}
/// @startDocuBlock DatabaseDirectory
/// `--database.directory directory`
///
/// The directory containing the collections and datafiles. Defaults
/// to @LIT{/var/lib/arango}. When specifying the database directory, please
/// to */var/lib/arango*. When specifying the database directory, please
/// make sure the directory is actually writable by the arangod process.
///
/// You should further not use a database directory which is provided by a
@ -337,78 +341,102 @@ namespace triagens {
/// might cause inconsistencies when there are multiple parallel readers or
/// writers or they lack features required by arangod (e.g. flock()).
///
/// @CMDOPT{@CA{directory}}
/// `directory`
///
/// When using the command line version, you can simply supply the database
/// directory as argument.
///
/// @EXAMPLES
///
/// @verbinclude option-database-directory
/// ```
/// > ./arangod --server.endpoint tcp://127.0.0.1:8529 --database.directory /tmp/vocbase
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
string _databasePath;
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock databaseMaximalJournalSize
///
/// @CMDOPT{\--database.maximal-journal-size @CA{size}}
///
/// `--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 @LIT{32MB}.
/// The default is *32MB*.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
TRI_voc_size_t _defaultMaximalSize;
////////////////////////////////////////////////////////////////////////////////
/// @brief default wait for sync behavior
///
/// @CMDOPT{\--database.wait-for-sync @CA{boolean}}
/// @startDocuBlock databaseWaitForSync
/// `--database.wait-for-sync boolean`
///
/// Default wait-for-sync value. Can be overwritten when creating a new
/// collection.
///
/// The default is @LIT{false}.
/// The default is *false*.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
bool _defaultWaitForSync;
////////////////////////////////////////////////////////////////////////////////
/// @brief force syncing of collection properties
///
/// @CMDOPT{\--database.force-sync-properties @CA{boolean}}
/// @startDocuBlock databaseForceSync
/// `--database.force-sync-properties boolean`
///
/// Force syncing of collection properties to disk after creating a collection
/// or updating its properties.
///
/// If turned off, syncing will still happen for collection that have a
/// waitForSync value of @LIT{true}. If turned on, syncing of properties will
/// waitForSync value of *true*. If turned on, syncing of properties will
/// always happen, regardless of the value of waitForSync.
///
/// The default is @LIT{true}.
/// The default is *true*.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
bool _forceSyncProperties;
////////////////////////////////////////////////////////////////////////////////
/// @brief disable the replication applier on server startup
/// @startDocuBlock serverDisableReplicationApplier
/// `--server.disable-replication-applier flag`
///
/// @CMDOPT{\--server.disable-replication-applier @CA{flag}}
///
/// If @LIT{true} the server will start with the replication applier turned off,
/// even if the replication applier is configured with the `autoStart` option.
/// Using the command-line option will not change the value of the `autoStart`
/// If *true* the server will start with the replication applier turned off,
/// even if the replication applier is 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 the
/// replication applier just once.
///
/// If the option is not used, ArangoDB will read the applier configuration from
/// the file `REPLICATION-APPLIER-CONFIG` on startup, and use the value of the
/// `autoStart` attribute from this file.
/// the file *REPLICATION-APPLIER-CONFIG* on startup, and use the value of the
/// *autoStart* attribute from this file.
///
/// The default is @LIT{false}.
/// The default is *false*.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock serverDisableReplicationLogger
/// `--server.disable-replication-logger flag`
///
/// If *true* the server will start with the replication logger turned off, even
/// if the replication logger is configured with the autoStart option. Using this
/// option will not change the value of the autoStart option in the logger
///configuration, but will suppress auto-starting the replication logger just once.
///
/// If the option is not used, ArangoDB will read the logger configuration from
/// the file REPLICATION-LOGGER-CONFIG on startup, and use the value of the
/// autoStart attribute from this file.
///
/// The default is *false*.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
bool _disableReplicationApplier;
@ -455,8 +483,8 @@ namespace triagens {
////////////////////////////////////////////////////////////////////////////////
/// @brief server default language for sorting strings
///
/// @CMDOPT{\-\-default-language @CA{default-language}}
/// @startDocuBlock DefaultLanguage
/// `--default-language default-language`
///
/// The default language ist used for sorting and comparing strings.
/// The language value is a two-letter language code (ISO-639) or it is
@ -464,21 +492,23 @@ namespace triagens {
/// (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.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
string _defaultLanguage;
////////////////////////////////////////////////////////////////////////////////
/// @brief development mode
///
/// @CMDOPT{\--development-mode}
/// @startDocuBlock developmentMode
/// `--development-mode`
///
/// Specifying this option will start the server in development mode. The
/// development mode forces reloading of all actions and Foxx applications on
/// every HTTP request. This is very resource-intensive and slow, but makes
/// developing server-side actions and Foxx applications much easier.
///
/// Never use this option in production.
/// **WARNING**: Never use this option in production.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
bool _developmentMode; /* variable is only used for documentation generation */

52
arangod/V8Server/ApplicationV8.h
View File

@ -428,18 +428,20 @@ namespace triagens {
////////////////////////////////////////////////////////////////////////////////
/// @brief path to the directory containing the startup scripts
/// @startDocuBlock jsStartupDirectory
///
/// `--javascript.startup-directory directory`
///
/// @CMDOPT{\--javascript.startup-directory @CA{directory}}
///
/// Specifies the @CA{directory} path to the JavaScript files used for
/// Specifies the *directory* path to the JavaScript files used for
/// bootstraping.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
string _startupPath;
////////////////////////////////////////////////////////////////////////////////
/// @brief semicolon separated list of module directories
///
///
/// This variable is automatically set based on the value of
/// `--javascript.startup-directory`.
////////////////////////////////////////////////////////////////////////////////
@ -457,23 +459,25 @@ namespace triagens {
////////////////////////////////////////////////////////////////////////////////
/// @brief semicolon separated list of application directories
/// @startDocuBlock jsAppPath
/// `--javascript.app-path directory`
///
/// @CMDOPT{\--javascript.app-path @CA{directory}}
///
/// Specifies the @CA{directory} path where the applications are located.
/// Specifies the *directory* path where the applications are located.
/// Multiple paths can be specified separated with commas.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
string _appPath;
////////////////////////////////////////////////////////////////////////////////
/// @brief semicolon separated list of application directories
/// @startDocuBlock jsDevApp
/// `--javascript.dev-app-path directory`
///
/// @CMDOPT{\--javascript.dev-app-path @CA{directory}}
///
/// Specifies the @CA{directory} path where the development applications are
/// located. Multiple paths can be specified separated with commas. Never use
/// Specifies the `directory` path where the development applications are
/// located. Multiple paths can be specified separated with commas. Never use
/// this option for production.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
string _devAppPath;
@ -498,31 +502,33 @@ namespace triagens {
////////////////////////////////////////////////////////////////////////////////
/// @brief JavaScript garbage collection interval (each x requests)
///
/// @CMDOPT{\--javascript.gc-interval @CA{interval}}
/// @startDocuBlock jsStartupGcInterval
/// `--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.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
uint64_t _gcInterval;
////////////////////////////////////////////////////////////////////////////////
/// @brief JavaScript garbage collection frequency (each x seconds)
///
/// @CMDOPT{\--javascript.gc-frequency @CA{frequency}}
/// @startDocuBlock jsGcFrequency
/// `--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.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
double _gcFrequency;
////////////////////////////////////////////////////////////////////////////////
/// @brief optional arguments to pass to v8
///
/// @CMDOPT{\--javascript.v8-options @CA{options}}
/// @startDocuBlock jsV8Options
/// `--javascript.v8-options options`
///
/// Optional arguments to pass to the V8 Javascript engine. The V8 engine will
/// run with default settings unless explicit options are specified using this
@ -533,21 +539,23 @@ namespace triagens {
/// Options need to be passed in one string, with V8 option names being prefixed
/// with double dashes. Multiple options need to be separated by whitespace.
/// To get a list of all available V8 options, you can use
/// the value @LIT{"--help"} as follows:
/// @code
/// the value *"--help"* as follows:
/// ```
/// --javascript.v8-options "--help"
/// @endcode
/// ```
///
/// Another example of specific V8 options being set at startup:
/// @code
///
/// ```
/// --javascript.v8-options "--harmony --log"
/// @endcode
/// ```
///
/// Names and features or usable options depend on the version of V8 being used,
/// and might change in the future if a different version of V8 is being used
/// in ArangoDB. Not all options offered by V8 might be sensible to use in the
/// context of ArangoDB. Use the specific options only if you are sure that
/// they are not harmful for the regular database operation.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
string _v8Options;

6
js/server/modules/org/arangodb/arango-database.js
View File

@ -444,7 +444,7 @@ ArangoDatabase.prototype._dropIndex = function (id) {
///
/// Please note that managing endpoints can only be performed from out of the
/// *_system* database. When not in the default database, you must first switch
/// to it using the @ref JS_UseDatabase "db._useDatabase" method.
/// to it using the "db._useDatabase" method.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
@ -474,7 +474,7 @@ ArangoDatabase.prototype._listEndpoints = function () {
///
/// Please note that managing endpoints can only be performed from out of the
/// *_system* database. When not in the default database, you must first switch
/// to it using the @ref JS_UseDatabase "db._useDatabase" method.
/// to it using the "db._useDatabase" method.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
@ -498,7 +498,7 @@ ArangoDatabase.prototype._configureEndpoint = function (endpoint, databases) {
///
/// Please note that managing endpoints can only be performed from out of the
/// *_system* database. When not in the default database, you must first switch
/// to it using the @ref JS_UseDatabase "db._useDatabase" method.
/// to it using the "db._useDatabase" method.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////

221
lib/ApplicationServer/ApplicationServer.h
View File

@ -277,13 +277,14 @@ namespace triagens {
////////////////////////////////////////////////////////////////////////////////
/// @brief program options
/// @startDocuBlock generalHelp
/// `--help`
///
/// @CMDOPT{\--help}
///
/// @CMDOPT{-h}
/// `-h`
///
/// Prints a list of the most common options available and then
/// exits. In order to see all options use @LIT{\-\-help-all}.
/// exits. In order to see all options use *--help-all*.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
basics::ProgramOptions _options;
@ -345,38 +346,39 @@ namespace triagens {
////////////////////////////////////////////////////////////////////////////////
/// @brief version of the application
/// @startDocuBlock generalVersion
/// `--version`
///
/// @CMDOPT{\--version}
///
/// @CMDOPT{-v}
/// `-v`
///
/// Prints the version of the server and exits.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
std::string _version;
////////////////////////////////////////////////////////////////////////////////
/// @brief config file
/// @startDocuBlock configurationFilename
/// `--configuration filename`
///
/// @CMDOPT{\--configuration @CA{filename}}
///
/// @CMDOPT{-c @CA{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 `~/.arango/arangod.conf` in the
/// will attempt to first locate a file named *~/.arango/arangod.conf* in the
/// user's home directory.
///
/// If no such file is found, the server will proceed to look for a file
/// `arangod.conf` in the system configuration directory. The system
/// *arangod.conf* in the system configuration directory. The system
/// configuration directory is platform-specific, and may be changed when
/// compiling ArangoDB yourself. It may default to `/etc/arangodb` or
/// `/usr/local/etc/arangodb`. This file is installed when using a package
/// compiling ArangoDB yourself. It may default to */etc/arangodb* or
/// */usr/local/etc/arangodb*. This file is installed when using a package
/// manager like rpm or dpkg. If you modify this file and later upgrade to a new
/// version of ArangoDB, then the package manager normally warns you about the
/// conflict. In order to avoid these warning for small adjustments, you can put
/// local overrides into a file `arangod.conf.local`.
/// local overrides into a file *arangod.conf.local*.
///
/// Only command line options with a value should be set within the
/// configuration file. Command line options which act as flags should be
@ -423,8 +425,9 @@ namespace triagens {
/// --configuration none
/// ```
///
/// when starting up the server. Note that, the word @LIT{none} is
/// When starting up the server. Note that, the word *none* is
/// case-insensitive.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
std::string _configFile;
@ -443,8 +446,8 @@ namespace triagens {
////////////////////////////////////////////////////////////////////////////////
/// @brief the user id to use for the process
///
/// @CMDOPT{\--uid @CA{uid}}
/// @startDocuBlock configurationUid
/// `--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
@ -459,6 +462,7 @@ namespace triagens {
/// 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.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
std::string _uid;
@ -477,8 +481,8 @@ namespace triagens {
////////////////////////////////////////////////////////////////////////////////
/// @brief the group id to use for the process
///
/// @CMDOPT{\--gid @CA{gid}}
/// @startDocuBlock configurationGid
/// `--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
@ -489,6 +493,7 @@ namespace triagens {
/// files).
///
/// This parameter is related to the parameter uid.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
std::string _gid;
@ -507,117 +512,139 @@ namespace triagens {
////////////////////////////////////////////////////////////////////////////////
/// @brief log application name
/// @startDocuBlock logApplication
/// `--log.application name`
///
/// @CMDOPT{\--log.application @CA{name}}
///
/// Specifies the @CA{name} of the application which should be logged if this item of
/// Specifies the *name* of the application which should be logged if this item of
/// information is to be logged.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
string _logApplicationName;
////////////////////////////////////////////////////////////////////////////////
/// @brief log host name
/// @startDocuBlock logHostname
/// `--log.hostname name`
///
/// @CMDOPT{\--log.hostname @CA{name}}
///
/// Specifies the @CA{name} of the operating environment (the "hostname") which
/// 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.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
string _logHostName;
////////////////////////////////////////////////////////////////////////////////
/// @brief log facility
///
/// @CMDOPT{\--log.facility @CA{name}}
/// @startDocuBlock logFacility
/// `--log.facility name`
///
/// Specifies the name of the server instance which should be logged if this
/// item of information is to be logged.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
string _logFacility;
////////////////////////////////////////////////////////////////////////////////
/// @brief log level
/// @startDocuBlock logLevel
/// `--log.level level`
///
/// @CMDOPT{\--log.level @CA{level}}
///
/// @CMDOPT{\--log @CA{level}}
/// `--log level`
///
/// Allows the user to choose the level of information which is logged by the
/// server. The argument @CA{level} is specified as a string and can be one of
/// 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 @c log.level can be used in
/// configuration files, the variant @c log for command line options.
/// level assigned by the user. The variant *c* log.level can be used in
/// configuration files, the variant *c* log for command line options.
///
/// - fatal: Logs errors which cause the server to terminate.
/// **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,
///
/// @LIT{2010-09-20T07:32:12Z [4742] FATAL a http server has already been created}
/// ```
/// 2010-09-20T07:32:12Z [4742] FATAL a http server has already been created
/// ```
///
/// - error: Logs errors which the server has encountered.
/// **error**:
/// Logs errors which the server has encountered.
///
/// These errors may not necessarily result in the termination of the
/// server. For example,
///
/// @LIT{2010-09-17T13:10:22Z [13967] ERROR strange log level 'errors'\, going to 'warning'}
/// ```
/// 2010-09-17T13:10:22Z [13967] ERROR strange log level 'errors'\, going to 'warning'
/// ```
///
/// - warning: Provides information on errors encountered by the server,
/// **warning**:
/// Provides information on errors encountered by the server,
/// which are not necessarily detrimental to it's continued operation.
///
/// For example,
///
/// @LIT{2010-09-20T08:15:26Z [5533] WARNING got corrupted HTTP request 'POS?'}
/// ```
/// 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
/// **Note**: The 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.
/// **info**:
/// Logs information about the status of the server.
///
/// For example,
///
/// @LIT{2010-09-20T07:40:38Z [4998] INFO SimpleVOC ready for business}
/// ```
/// 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
/// **Note**: The 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**:
/// 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,
///
/// @LIT{2010-09-17T13:02:53Z [13783] DEBUG opened port 7000 for any}
/// ```
/// 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,
/// **Note**: The 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
/// **trace**:
/// As the name suggests, logs information which may be useful to trace
/// problems encountered with using the server.
///
/// For example,
///
/// @LIT{2010-09-20T08:23:12Z [5687] TRACE trying to open port 8000}
/// ```
/// 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,
/// **Note**: The setting the log level to trace will also result in all errors,
/// warnings, status information, and debug information to be logged as well.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
string _logLevel;
////////////////////////////////////////////////////////////////////////////////
/// @brief log severity
///
/// @CMDOPT{\--log.severity @CA{severity}}
/// @startDocuBlock logSeverity
/// `--log.severity severity`
///
/// This parameter provides a set of standard log severities which can be
/// used. The currently accepted @CA{severities} are:
/// used. The currently accepted *severities* are:
///
/// - exception
/// - technical
@ -628,144 +655,160 @@ namespace triagens {
/// - non-human (exception, technical, functional, and development)
///
/// The default is all.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
string _logSeverity;
////////////////////////////////////////////////////////////////////////////////
/// @brief log file
///
/// @CMDOPT{\--log.file @CA{filename}}
/// @startDocuBlock logFile
/// `--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 @CA{filename} does not
/// 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 @LIT{+} to log to standard error. Use @LIT{-} to log to standard output.
/// Use @LIT{""} to disable logging to file.
/// Use *+* to log to standard error. Use *-* to log to standard output.
/// Use *""* to disable logging to file.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
string _logFile;
////////////////////////////////////////////////////////////////////////////////
/// @brief log file for requests
///
/// @CMDOPT{\--log.requests-file @CA{filename}}
/// @startDocuBlock logRequests
/// `--log.requests-file filename`
///
/// This option allows the user to specify the name of a file to which
/// requests are logged. By default, no log file is used and requests are
/// not logged. Note that if the file named by @CA{filename} does not
/// not logged. 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 @LIT{+} to log to standard error. Use @LIT{-} to log to standard output.
/// Use @LIT{""} to disable request logging altogether.
/// Use *+* to log to standard error. Use *-* to log to standard output.
/// Use *""* to disable request logging altogether.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
string _logRequestsFile;
////////////////////////////////////////////////////////////////////////////////
/// @brief log prefix
///
/// @CMDOPT{\--log.prefix @CA{prefix}}
/// @startDocuBlock logPrefix
/// `--log.prefix prefix`
///
/// This option is used specify an prefix to logged text.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
string _logPrefix;
////////////////////////////////////////////////////////////////////////////////
/// @brief log level
///
/// @CMDOPT{\--log.syslog @CA{arg}}
/// @startDocuBlock logSyslog
/// `--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 @CA{arg} is the system log facility to use. See syslog for
/// facility. The *arg* is the system log facility to use. See syslog for
/// further details.
///
/// The value of @CA{arg} depends on your syslog configuration. In general it
/// will be @LIT{user}. Fatal messages are mapped to @LIT{crit}, so if @CA{arg}
/// is @LIT{user}, these messages will be logged as @LIT{user.crit}. Error
/// messages are mapped to @LIT{err}. Warnings are mapped to @LIT{warn}. Info
/// messages are mapped to @LIT{notice}. Debug messages are mapped to
/// @LIT{info}. Trace messages are mapped to @LIT{debug}.
/// 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*.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
string _logSyslog;
////////////////////////////////////////////////////////////////////////////////
/// @brief log thread identifier
///
/// @CMDOPT{\--log.thread}
/// @startDocuBlock logThread
/// `--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,
///
/// @LIT{2010-09-20T13:04:01Z [19355] INFO ready for business}
/// ```
/// 2010-09-20T13:04:01Z [19355] INFO ready for business
/// ```
///
/// when no thread is logged and
///
/// @LIT{2010-09-20T13:04:17Z [19371-18446744072487317056] ready for business}
/// ```
/// 2010-09-20T13:04:17Z [19371-18446744072487317056] ready for business
/// ```
///
/// when this command line option is set.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
bool _logThreadId;
////////////////////////////////////////////////////////////////////////////////
/// @brief log line number
///
/// @CMDOPT{\--log.line-number}
/// @startDocuBlock logLineNumber
/// `--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.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
bool _logLineNumber;
////////////////////////////////////////////////////////////////////////////////
/// @brief log source filter
///
/// @CMDOPT{\--log.source-filter @CA{arg}}
/// @startDocuBlock logSourceFilter
/// `--log.source-filter arg`
///
/// For debug and trace messages, only log those messages originated from the
/// C source file @CA{arg}. The argument can be used multiple times.
/// C source file *arg*. The argument can be used multiple times.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
vector<string> _logSourceFilter;
////////////////////////////////////////////////////////////////////////////////
/// @brief log content filter
/// @startDocuBlock logContentFilter
/// `--log.content-filter arg`
///
/// @CMDOPT{\--log.content-filter @CA{arg}}
///
/// Only log message containing the specified string @CA{arg}.
/// Only log message containing the specified string *arg*.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
string _logContentFilter;
////////////////////////////////////////////////////////////////////////////////
/// @brief random number generator to use
///
/// @CMDOPT{\--random.generator @CA{arg}}
/// @startDocuBlock randomGenerator
/// `--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
/// 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.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
uint32_t _randomGenerator;

169
lib/HttpServer/ApplicationEndpointServer.h
View File

@ -306,10 +306,10 @@ namespace triagens {
////////////////////////////////////////////////////////////////////////////////
/// @brief endpoints for client HTTP requests
/// @startDocuBlock serverEndpoint
/// `--server.endpoint endpoint`
///
/// @CMDOPT{\--server.endpoint @CA{endpoint}}
///
/// Specifies an @CA{endpoint} for HTTP requests by clients. Endpoints have
/// 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
@ -324,7 +324,7 @@ namespace triagens {
///
/// @EXAMPLES
///
/// @code
/// ```
/// unix> ./arangod --server.endpoint tcp://127.0.0.1:8529
/// --server.endpoint ssl://127.0.0.1:8530
/// --server.keyfile server.pem /tmp/vocbase
@ -333,25 +333,26 @@ namespace triagens {
/// 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!
/// @endcode
/// ```
///
/// Note that if you are using SSL-encrypted endpoints, you must also supply
/// **Note**: If you are using SSL-encrypted endpoints, you must also supply
/// the path to a server certificate using the \-\-server.keyfile option.
///
/// Endpoints can also be changed at runtime. Please refer to @ref HttpEndpoint
/// for more details.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
vector<string> _endpoints;
////////////////////////////////////////////////////////////////////////////////
/// @brief try to reuse address
/// @startDocuBlock serverReuseAddress
/// `--server.reuse-address`
///
/// @CMDOPT{\--server.reuse-address}
///
/// If this boolean option is set to `true` then the socket option
/// If this boolean option is set to *true* then the socket option
/// SO_REUSEADDR is set on all server endpoints, which is the default.
/// If this option is set to `false` it is possible that it takes up
/// If this option is set to *false* it is possible that it takes up
/// to a minute after a server has terminated until it is possible for
/// a new server to use the same endpoint again. This is why this is
/// activated by default.
@ -361,6 +362,7 @@ namespace triagens {
/// to bind to the same address and port, possibly hijacking network
/// traffic. Under Windows, ArangoDB additionally sets the flag
/// SO_EXCLUSIVEADDRUSE as a measure to alleviate this problem.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
bool _reuseAddress;
@ -382,14 +384,14 @@ namespace triagens {
////////////////////////////////////////////////////////////////////////////////
/// @brief default API compatibility
///
/// @CMDOPT{\--server.default-api-compatibility}
/// @startDocuBlock serverDefaultApi
/// `--server.default-api-compatibility`
///
/// This option can be used to determine the API compatibility of the ArangoDB
/// server. It expects an ArangoDB version number as an integer, calculated as
/// follows:
///
/// `10000 * major + 100 * minor` (example: `10400` for ArangoDB 1.4)
/// *10000 \* major + 100 \* minor (example: *10400* for ArangoDB 1.4)*
///
/// The value of this option will have an influence on some API return values
/// when the HTTP client used does not send any compatibility information.
@ -400,81 +402,114 @@ namespace triagens {
/// responses of the current version of ArangoDB, it might be reasonable to set
/// the option to an old version number to improve compatibility with older
/// clients.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
int32_t _defaultApiCompatibility;
////////////////////////////////////////////////////////////////////////////////
/// @brief allow HTTP method override via custom headers?
/// @startDocuBlock serverAllowMethod
/// `--server.allow-method-override`
///
/// @CMDOPT{\--server.allow-method-override}
///
/// When this option is set to `true`, the HTTP request method will optionally
/// When this option is set to *true*, the HTTP request method will optionally
/// be fetched from one of the following HTTP request headers if present in
/// the request:
///
/// - `x-http-method`
/// - `x-http-method-override`
/// - `x-method-override`
/// - *x-http-method*
/// - *x-http-method-override*
/// - *x-method-override*
///
/// If the option is set to `true` and any of these headers is set, the
/// If the option is set to *true* and any of these headers is set, the
/// request method will be overriden by the value of the header. For example,
/// this allows issuing an HTTP DELETE request which to the outside world will
/// look like an HTTP GET request. This allows bypassing proxies and tools that
/// will only let certain request types pass.
///
/// Setting this option to `true` may impose a security risk so it should only
/// Setting this option to *true* may impose a security risk so it should only
/// be used in controlled environments.
///
/// The default value for this option is `false`.
/// The default value for this option is *false*.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
bool _allowMethodOverride;
////////////////////////////////////////////////////////////////////////////////
/// @brief listen backlog size
/// @startDocuBlock serverBacklog
/// `--server.backlog-size`
///
/// @CMDOPT{\--server.backlog-size}
///
/// Allows to specify the size of the backlog for the `listen` system call
/// Allows to specify the size of the backlog for the *listen* system call
/// The default value is 10. The maximum value is platform-dependent.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
int _backlogSize;
////////////////////////////////////////////////////////////////////////////////
/// @brief keyfile containing server certificate
///
/// @CMDOPT{\--server.keyfile @CA{filename}}
/// @startDocuBlock serverKeyfile
/// `--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 @CA{filename} should have the following structure:
/// The file specified by *filename* should have the following structure:
///
/// @verbinclude server-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
/// ```
///
/// 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:
///
/// @verbinclude server-keyfile-openssl
/// ```
/// -----BEGIN CERTIFICATE-----
///
/// (base64 encoded certificate)
///
/// -----END CERTIFICATE-----
/// -----BEGIN RSA PRIVATE KEY-----
///
/// (base64 encoded private key)
///
/// -----END RSA PRIVATE KEY-----
/// ```
///
/// 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
/// **Note**: the \-\-server.keyfile option must be set if the server is started with
/// at least one SSL endpoint.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
string _httpsKeyfile;
////////////////////////////////////////////////////////////////////////////////
/// @brief CA file
///
/// @CMDOPT{\--server.cafile @CA{filename}}
/// @startDocuBlock serverCafile
/// `--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
@ -482,17 +517,18 @@ namespace triagens {
/// 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 @CA{filename} must be PEM formatted.
/// The certificates in *filename* must be PEM formatted.
///
/// Note: this option is only relevant if at least one SSL endpoint is used.
/// **Note**: this option is only relevant if at least one SSL endpoint is used.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
string _cafile;
////////////////////////////////////////////////////////////////////////////////
/// @brief SSL protocol type to use
///
/// @CMDOPT{\--server.ssl-protocol @CA{value}}
/// @startDocuBlock serverSSLProtocol
/// `--server.ssl-protocolvalue`
///
/// Use this option to specify the default encryption protocol to be used.
/// The following variants are available:
@ -501,32 +537,34 @@ namespace triagens {
/// - 3: SSLv3
/// - 4: TLSv1
///
/// The default @CA{value} is 4 (i.e. TLSv1).
/// The default *value* is 4 (i.e. TLSv1).
///
/// Note: this option is only relevant if at least one SSL endpoint is used.
/// **Note**: this option is only relevant if at least one SSL endpoint is used.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
uint32_t _sslProtocol;
////////////////////////////////////////////////////////////////////////////////
/// @brief whether or not to use SSL session caching
///
/// @CMDOPT{\--server.ssl-cache @CA{value}}
/// @startDocuBlock serverSSLCache
/// `--server.ssl-cache value`
///
/// Set to true if SSL session caching should be used.
///
/// @CA{value} has a default value of @LIT{false} (i.e. no caching).
/// *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
/// **Note**: this option is only relevant if at least one SSL endpoint is used, and
/// only if the client supports sending the session id.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
bool _sslCache;
////////////////////////////////////////////////////////////////////////////////
/// @brief ssl options to use
///
/// @CMDOPT{\--server.ssl-options @CA{value}}
/// @startDocuBlock serverSSLOptions
/// `--server.ssl-options value`
///
/// This option can be used to set various SSL-related options. Individual
/// option values must be combined using bitwise OR.
@ -535,34 +573,55 @@ namespace triagens {
/// version you use. The list of options available on your platform might be
/// retrieved by the following shell command:
///
/// @verbinclude openssl-options
/// ```
/// > 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
/// A description of the options can be found online in the
/// [OpenSSL documentation](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.
/// **Note**: this option is only relevant if at least one SSL endpoint is used.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
uint64_t _sslOptions;
////////////////////////////////////////////////////////////////////////////////
/// @brief ssl cipher list to use
///
/// @CMDOPT{\--server.ssl-cipher-list @CA{cipher-list}}
/// @startDocuBlock serverSSLCipher
/// `--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 @CA{cipher-list} is documented in the OpenSSL documentation.
/// 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:
///
/// @verbinclude openssl-ciphers
/// ```
/// > openssl ciphers -v
///
/// The default value for @CA{cipher-list} is "ALL".
/// 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
/// ...
/// ```
///
/// Note: this option is only relevant if at least one SSL endpoint is used.
/// The default value for *cipher-list* is "ALL".
///
/// **Note**: this option is only relevant if at least one SSL endpoint is used.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
string _sslCipherList;

9
lib/Rest/AnyServer.h
View File

@ -133,12 +133,13 @@ namespace triagens {
////////////////////////////////////////////////////////////////////////////////
/// @brief pid file
///
/// @CMDOPT{\--pid-file @CA{filename}}
/// @startDocuBlock pidFile
/// `--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 @LIT{daemon} or
/// @LIT{supervisor} is set.
/// daemon. This parameter must be specified if either the flag *daemon* or
/// *supervisor* is set.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
string _pidFile;

10
lib/Scheduler/ApplicationScheduler.h
View File

@ -216,24 +216,26 @@ namespace triagens {
////////////////////////////////////////////////////////////////////////////////
/// @brief number of scheduler threads
///
/// @CMDOPT{\--scheduler.threads @CA{arg}}
/// @startDocuBlock schedulerThreads
/// `--scheduler.threads arg`
///
/// An integer argument which sets the number of threads to use in the IO
/// scheduler. The default is 1.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
uint32_t _nrSchedulerThreads;
////////////////////////////////////////////////////////////////////////////////
/// @brief scheduler backend
///
/// @CMDOPT{\--scheduler.backend @CA{arg}}
/// @startDocuBlock schedulerBackend
/// `--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.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
uint32_t _backend;