2016-10-04 16:12:23 +02:00
# Configuration Settings
2016-08-08 15:26:27 +02:00
2016-10-04 16:12:23 +02:00
The value of each BigchainDB Server configuration setting is determined according to the following rules:
2016-04-08 15:14:14 +02:00
2016-06-23 16:36:34 +02:00
* If it's set by an environment variable, then use that value
* Otherwise, if it's set in a local config file, then use that value
* Otherwise, use the default value
2016-04-08 15:14:14 +02:00
2016-06-24 11:10:19 +02:00
For convenience, here's a list of all the relevant environment variables (documented below):
2016-12-12 18:31:34 +01:00
`BIGCHAINDB_DATABASE_BACKEND` < br >
2016-06-24 11:10:19 +02:00
`BIGCHAINDB_DATABASE_HOST` < br >
`BIGCHAINDB_DATABASE_PORT` < br >
`BIGCHAINDB_DATABASE_NAME` < br >
2017-03-24 15:38:27 +01:00
`BIGCHAINDB_DATABASE_CONNECTION_TIMEOUT` < br >
`BIGCHAINDB_DATABASE_MAX_TRIES` < br >
2016-06-24 11:10:19 +02:00
`BIGCHAINDB_SERVER_BIND` < br >
2017-04-13 16:18:02 +02:00
`BIGCHAINDB_SERVER_LOGLEVEL` < br >
2016-06-24 11:10:19 +02:00
`BIGCHAINDB_SERVER_WORKERS` < br >
2017-06-14 13:49:47 +02:00
`BIGCHAINDB_WSSERVER_SCHEME` < br >
2017-04-19 11:21:59 +02:00
`BIGCHAINDB_WSSERVER_HOST` < br >
`BIGCHAINDB_WSSERVER_PORT` < br >
2017-08-08 12:04:58 +02:00
`BIGCHAINDB_WSSERVER_ADVERTISED_SCHEME` < br >
`BIGCHAINDB_WSSERVER_ADVERTISED_HOST` < br >
`BIGCHAINDB_WSSERVER_ADVERTISED_PORT` < br >
2016-07-11 15:58:29 +02:00
`BIGCHAINDB_CONFIG_PATH` < br >
2017-03-21 14:09:06 +01:00
`BIGCHAINDB_LOG` < br >
`BIGCHAINDB_LOG_FILE` < br >
2017-04-18 12:05:36 +02:00
`BIGCHAINDB_LOG_ERROR_FILE` < br >
2017-03-21 14:09:06 +01:00
`BIGCHAINDB_LOG_LEVEL_CONSOLE` < br >
`BIGCHAINDB_LOG_LEVEL_LOGFILE` < br >
`BIGCHAINDB_LOG_DATEFMT_CONSOLE` < br >
`BIGCHAINDB_LOG_DATEFMT_LOGFILE` < br >
`BIGCHAINDB_LOG_FMT_CONSOLE` < br >
`BIGCHAINDB_LOG_FMT_LOGFILE` < br >
2018-06-29 15:45:22 +02:00
`BIGCHAINDB_TENDERMINT_HOST` < br >
`BIGCHAINDB_TENDERMINT_PORT` < br >
2018-03-21 12:42:43 +01:00
2016-06-24 11:10:19 +02:00
2016-07-11 15:58:29 +02:00
The local config file is `$HOME/.bigchaindb` by default (a file which might not even exist), but you can tell BigchainDB to use a different file by using the `-c` command-line option, e.g. `bigchaindb -c path/to/config_file.json start`
or using the `BIGCHAINDB_CONFIG_PATH` environment variable, e.g. `BIGHAINDB_CONFIG_PATH=.my_bigchaindb_config bigchaindb start` .
2016-07-11 16:42:32 +02:00
Note that the `-c` command line option will always take precedence if both the `BIGCHAINDB_CONFIG_PATH` and the `-c` command line option are used.
2016-04-08 15:14:14 +02:00
2016-06-23 16:36:34 +02:00
You can read the current default values in the file [bigchaindb/\_\_init\_\_.py ](https://github.com/bigchaindb/bigchaindb/blob/master/bigchaindb/__init__.py ). (The link is to the latest version.)
2018-03-21 12:42:43 +01:00
Running `bigchaindb -y configure localmongodb` will generate a local config file in `$HOME/.bigchaindb` with all the default values.
2016-04-08 15:14:14 +02:00
2017-03-24 15:38:27 +01:00
## database.*
2016-04-08 15:14:14 +02:00
2017-03-24 15:38:27 +01:00
The settings with names of the form `database.*` are for the database backend
2018-03-21 12:42:43 +01:00
(currently only MongoDB). They are:
2017-03-24 15:38:27 +01:00
2018-03-21 12:42:43 +01:00
* `database.backend` is only `localmongodb` , currently.
2017-03-24 15:38:27 +01:00
* `database.host` is the hostname (FQDN) of the backend database.
* `database.port` is self-explanatory.
2018-03-21 12:42:43 +01:00
* `database.name` is a user-chosen name for the database inside MongoDB, e.g. `bigchain` .
2017-06-01 15:20:00 +02:00
* `database.connection_timeout` is the maximum number of milliseconds that BigchainDB will wait before giving up on one attempt to connect to the database backend.
2017-03-24 15:38:27 +01:00
* `database.max_tries` is the maximum number of times that BigchainDB will try to establish a connection with the database backend. If 0, then it will try forever.
2016-04-08 15:14:14 +02:00
2016-06-23 16:36:34 +02:00
**Example using environment variables**
```text
2018-03-21 12:42:43 +01:00
export BIGCHAINDB_DATABASE_BACKEND=localmongodb
2016-06-23 16:36:34 +02:00
export BIGCHAINDB_DATABASE_HOST=localhost
2017-02-19 15:27:21 +01:00
export BIGCHAINDB_DATABASE_PORT=27017
2017-03-24 15:38:27 +01:00
export BIGCHAINDB_DATABASE_CONNECTION_TIMEOUT=5000
export BIGCHAINDB_DATABASE_MAX_TRIES=3
2016-06-23 16:36:34 +02:00
```
2016-04-11 11:26:58 +02:00
2017-02-17 12:15:50 +01:00
**Default values**
2018-03-21 12:42:43 +01:00
If (no environment variables were set and there's no local config file), or you used `bigchaindb -y configure localmongodb` to create a default local config file for a `localmongodb` backend, then the defaults will be:
2017-02-17 12:15:50 +01:00
```js
"database": {
2018-03-21 12:42:43 +01:00
"backend": "localmongodb",
2017-02-17 12:15:50 +01:00
"host": "localhost",
"port": 27017,
2017-03-24 15:38:27 +01:00
"name": "bigchain",
2018-03-21 12:42:43 +01:00
"replicaset": null,
2017-03-24 15:38:27 +01:00
"connection_timeout": 5000,
2017-06-16 15:27:56 +02:00
"max_tries": 3,
"login": null,
"password": null
"ssl": false,
"ca_cert": null,
"crlfile": null,
"certfile": null,
"keyfile": null,
"keyfile_passphrase": null,
2016-06-23 16:36:34 +02:00
}
```
2016-04-08 15:14:14 +02:00
2016-04-18 12:02:05 +02:00
2017-05-19 14:05:28 +02:00
## server.bind, server.loglevel & server.workers
2016-04-18 12:02:05 +02:00
2017-04-10 15:14:18 +02:00
These settings are for the [Gunicorn HTTP server ](http://gunicorn.org/ ), which is used to serve the [HTTP client-server API ](../http-client-server-api.html ).
2016-04-11 14:51:26 +02:00
2017-06-20 17:27:51 +02:00
`server.bind` is where to bind the Gunicorn HTTP server socket. It's a string. It can be any valid value for [Gunicorn's bind setting ](http://docs.gunicorn.org/en/stable/settings.html#bind ). If you want to allow IPv4 connections from anyone, on port 9984, use `0.0.0.0:9984` . In a production setting, we recommend you use Gunicorn behind a reverse proxy server. If Gunicorn and the reverse proxy are running on the same machine, then use `localhost:PORT` where PORT is _not_ 9984 (because the reverse proxy needs to listen on port 9984). Maybe use PORT=9983 in that case because we know 9983 isn't used. If Gunicorn and the reverse proxy are running on different machines, then use `A.B.C.D:9984` where A.B.C.D is the IP address of the reverse proxy. There's [more information about deploying behind a reverse proxy in the Gunicorn documentation ](http://docs.gunicorn.org/en/stable/deploy.html ). (They call it a proxy.)
2016-04-11 14:51:26 +02:00
2017-04-13 16:18:02 +02:00
`server.loglevel` sets the log level of Gunicorn's Error log outputs. See
[Gunicorn's documentation ](http://docs.gunicorn.org/en/latest/settings.html#loglevel )
for more information.
2018-03-29 16:26:54 +02:00
`server.workers` is [the number of worker processes ](http://docs.gunicorn.org/en/stable/settings.html#workers ) for handling requests. If set to `None` , the value will be (2 × cpu_count + 1). Each worker process has a single thread. The HTTP server will be able to handle `server.workers` requests simultaneously.
2016-04-11 14:51:26 +02:00
2016-06-23 16:36:34 +02:00
**Example using environment variables**
```text
export BIGCHAINDB_SERVER_BIND=0.0.0.0:9984
2017-04-13 16:18:02 +02:00
export BIGCHAINDB_SERVER_LOGLEVEL=debug
2016-06-23 16:36:34 +02:00
export BIGCHAINDB_SERVER_WORKERS=5
```
2016-04-11 14:51:26 +02:00
2016-06-23 16:36:34 +02:00
**Example config file snippet**
```js
"server": {
"bind": "0.0.0.0:9984",
2017-04-13 16:18:02 +02:00
"loglevel": "debug",
2016-06-23 16:36:34 +02:00
"workers": 5,
2016-04-11 14:51:26 +02:00
}
```
2016-06-23 16:36:34 +02:00
**Default values (from a config file)**
```js
"server": {
"bind": "localhost:9984",
2017-04-13 16:18:02 +02:00
"loglevel": "info",
2018-05-03 11:52:54 +02:00
"workers": null,
2016-04-11 14:51:26 +02:00
}
2016-06-23 16:36:34 +02:00
```
2017-04-19 11:21:59 +02:00
2017-06-16 13:22:01 +02:00
## wsserver.scheme, wsserver.host and wsserver.port
2017-04-19 11:21:59 +02:00
These settings are for the
2018-02-13 14:09:41 +01:00
[aiohttp server ](https://aiohttp.readthedocs.io/en/stable/index.html ),
2017-04-19 11:21:59 +02:00
which is used to serve the
[WebSocket Event Stream API ](../websocket-event-stream-api.html ).
2017-06-16 13:22:01 +02:00
`wsserver.scheme` should be either `"ws"` or `"wss"`
(but setting it to `"wss"` does *not* enable SSL/TLS).
2017-04-19 11:21:59 +02:00
`wsserver.host` is where to bind the aiohttp server socket and
`wsserver.port` is the corresponding port.
If you want to allow connections from anyone, on port 9985,
set `wsserver.host` to 0.0.0.0 and `wsserver.port` to 9985.
**Example using environment variables**
```text
2017-06-16 13:22:01 +02:00
export BIGCHAINDB_WSSERVER_SCHEME=ws
2017-04-19 11:21:59 +02:00
export BIGCHAINDB_WSSERVER_HOST=0.0.0.0
export BIGCHAINDB_WSSERVER_PORT=9985
```
**Example config file snippet**
```js
"wsserver": {
2017-06-16 13:22:01 +02:00
"scheme": "wss",
2017-04-19 11:21:59 +02:00
"host": "0.0.0.0",
"port": 65000
}
```
**Default values (from a config file)**
```js
"wsserver": {
2017-06-16 13:22:01 +02:00
"scheme": "ws",
2017-04-19 11:21:59 +02:00
"host": "localhost",
"port": 9985
}
```
2017-08-08 12:04:58 +02:00
## wsserver.advertised_scheme, wsserver.advertised_host and wsserver.advertised_port
These settings are for the advertising the Websocket URL to external clients in
the root API endpoint. These configurations might be useful if your deployment
is hosted behind a firewall, NAT, etc. where the exposed public IP or domain is
different from where BigchainDB is running.
**Example using environment variables**
```text
export BIGCHAINDB_WSSERVER_ADVERTISED_SCHEME=wss
export BIGCHAINDB_WSSERVER_ADVERTISED_HOST=mybigchaindb.com
export BIGCHAINDB_WSSERVER_ADVERTISED_PORT=443
```
**Example config file snippet**
```js
"wsserver": {
"advertised_scheme": "wss",
"advertised_host": "mybigchaindb.com",
"advertised_port": 443
}
```
**Default values (from a config file)**
```js
"wsserver": {
"advertised_scheme": "ws",
"advertised_host": "localhost",
"advertised_port": 9985
}
```
2017-03-21 14:09:06 +01:00
## log
2017-04-13 09:56:03 +02:00
2017-03-21 14:09:06 +01:00
The `log` key is expected to point to a mapping (set of key/value pairs)
holding the logging configuration.
**Example**:
```
{
"log": {
"file": "/var/log/bigchaindb.log",
2017-04-18 12:05:36 +02:00
"error_file": "/var/log/bigchaindb-errors.log",
2017-03-21 14:09:06 +01:00
"level_console": "info",
"level_logfile": "info",
"datefmt_console": "%Y-%m-%d %H:%M:%S",
"datefmt_logfile": "%Y-%m-%d %H:%M:%S",
"fmt_console": "%(asctime)s [%(levelname)s] (%(name)s) %(message)s",
2018-06-11 13:08:03 +02:00
"fmt_logfile": "%(asctime)s [%(levelname)s] (%(name)s) %(message)s"
2017-03-21 14:09:06 +01:00
}
```
2017-04-18 15:59:31 +02:00
**Defaults to**:
2017-03-21 14:09:06 +01:00
```
{
"log": {
"file": "~/bigchaindb.log",
2017-04-18 15:59:31 +02:00
"error_file": "~/bigchaindb-errors.log",
2017-03-21 14:09:06 +01:00
"level_console": "info",
"level_logfile": "info",
"datefmt_console": "%Y-%m-%d %H:%M:%S",
"datefmt_logfile": "%Y-%m-%d %H:%M:%S",
2017-04-18 15:59:31 +02:00
"fmt_logfile": "[%(asctime)s] [%(levelname)s] (%(name)s) %(message)s (%(processName)-10s - pid: %(process)d)",
2018-06-11 13:08:03 +02:00
"fmt_console": "[%(asctime)s] [%(levelname)s] (%(name)s) %(message)s (%(processName)-10s - pid: %(process)d)"
2017-03-21 14:09:06 +01:00
}
```
The next subsections explain each field of the `log` configuration.
2017-04-18 12:05:36 +02:00
### log.file & log.error_file
The full paths to the files where logs and error logs should be written to.
2017-03-21 14:09:06 +01:00
**Example**:
```
{
"log": {
"file": "/var/log/bigchaindb/bigchaindb.log"
2017-04-18 12:05:36 +02:00
"error_file": "/var/log/bigchaindb/bigchaindb-errors.log"
2017-03-21 14:09:06 +01:00
}
}
```
2018-02-13 14:09:41 +01:00
**Defaults to**:
2017-04-18 12:05:36 +02:00
* `"~/bigchaindb.log"`
* `"~/bigchaindb-errors.log"`
2017-03-21 14:09:06 +01:00
Please note that the user running `bigchaindb` must have write access to the
2017-04-18 12:05:36 +02:00
locations.
#### Log rotation
Log files have a size limit of 200 MB and will be rotated up to five times.
For example if we consider the log file setting:
```
{
"log": {
"file": "~/bigchain.log"
}
}
```
logs would always be written to `bigchain.log` . Each time the file
2018-02-13 14:09:41 +01:00
`bigchain.log` reaches 200 MB it would be closed and renamed
2017-04-18 12:05:36 +02:00
`bigchain.log.1` . If `bigchain.log.1` and `bigchain.log.2` already exist they
would be renamed `bigchain.log.2` and `bigchain.log.3` . This pattern would be
applied up to `bigchain.log.5` after which `bigchain.log.5` would be
overwritten by `bigchain.log.4` , thus ending the rotation cycle of whatever
logs were in `bigchain.log.5` .
2017-03-21 14:09:06 +01:00
### log.level_console
The log level used to log to the console. Possible allowed values are the ones
2017-03-21 15:58:18 +01:00
defined by [Python ](https://docs.python.org/3.6/library/logging.html#levels ),
but case insensitive for convenience's sake:
2017-03-21 14:09:06 +01:00
```
2018-06-14 15:19:26 +02:00
"critical", "error", "warning", "info", "benchmark", "debug", "notset"
2017-03-21 14:09:06 +01:00
```
**Example**:
```
{
"log": {
"level_console": "info"
}
}
```
**Defaults to**: `"info"` .
### log.level_logfile
The log level used to log to the log file. Possible allowed values are the ones
2017-03-21 15:58:18 +01:00
defined by [Python ](https://docs.python.org/3.6/library/logging.html#levels ),
but case insensitive for convenience's sake:
2017-03-21 14:09:06 +01:00
```
2018-06-14 15:19:26 +02:00
"critical", "error", "warning", "info", "benchmark", "debug", "notset"
2017-03-21 14:09:06 +01:00
```
**Example**:
```
{
"log": {
"level_file": "info"
}
}
```
**Defaults to**: `"info"` .
### log.datefmt_console
The format string for the date/time portion of a message, when logged to the
console.
**Example**:
```
{
"log": {
"datefmt_console": "%x %X %Z"
}
}
```
**Defaults to**: `"%Y-%m-%d %H:%M:%S"` .
For more information on how to construct the format string please consult the
table under Python's documentation of
[`time.strftime(format[, t])`](https://docs.python.org/3.6/library/time.html#time.strftime)
### log.datefmt_logfile
The format string for the date/time portion of a message, when logged to a log
file.
**Example**:
```
{
"log": {
"datefmt_logfile": "%c %z"
}
}
```
**Defaults to**: `"%Y-%m-%d %H:%M:%S"` .
For more information on how to construct the format string please consult the
table under Python's documentation of
[`time.strftime(format[, t])`](https://docs.python.org/3.6/library/time.html#time.strftime)
### log.fmt_console
A string used to format the log messages when logged to the console.
**Example**:
```
{
"log": {
"fmt_console": "%(asctime)s [%(levelname)s] %(message)s %(process)d"
}
}
```
**Defaults to**: `"[%(asctime)s] [%(levelname)s] (%(name)s) %(message)s (%(processName)-10s - pid: %(process)d)"`
For more information on possible formatting options please consult Python's
documentation on
[LogRecord attributes ](https://docs.python.org/3.6/library/logging.html#logrecord-attributes )
### log.fmt_logfile
A string used to format the log messages when logged to a log file.
**Example**:
```
{
"log": {
"fmt_logfile": "%(asctime)s [%(levelname)s] %(message)s %(process)d"
}
}
```
**Defaults to**: `"[%(asctime)s] [%(levelname)s] (%(name)s) %(message)s (%(processName)-10s - pid: %(process)d)"`
For more information on possible formatting options please consult Python's
documentation on
[LogRecord attributes ](https://docs.python.org/3.6/library/logging.html#logrecord-attributes )
### log.granular_levels
Log levels for BigchainDB's modules. This can be useful to control the log
level of specific parts of the application. As an example, if you wanted the
2017-03-21 15:54:35 +01:00
logging of the `core.py` module to be more verbose, you would set the
configuration shown in the example below.
2017-03-21 14:09:06 +01:00
**Example**:
```
{
"log": {
"granular_levels": {
"bichaindb.core": "debug"
}
}
```
2017-10-23 18:22:30 +02:00
**Defaults to**: `{}`
2018-06-29 15:45:22 +02:00
## tendermint.host & tendermint.port
The settings with names of the form `tendermint.*` are for
consensus(Tendermint) backend that we are using:
* `tendermint.host` is the hostname (FQDN)/IP address of the tendermint backend.
* `tendermint.port` is self-explanatory.
**Example using environment variables**
```text
export BIGCHAINDB_TENDERMINT_HOST=tendermint
2018-07-10 14:16:02 +02:00
export BIGCHAINDB_TENDERMINT_PORT=26657
2018-06-29 15:45:22 +02:00
```
**Default values**
```js
"tendermint": {
"host": "localhost",
2018-07-10 14:16:02 +02:00
"port": 26657,
2018-06-29 15:45:22 +02:00
}
```