bigchaindb/docs/server/source/server-reference/configuration.md

# Configuration Settings

The value of each BigchainDB Server configuration setting is determined according to the following rules:

* 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

For convenience, here's a list of all the relevant environment variables (documented below):

`BIGCHAINDB_KEYPAIR_PUBLIC`<br>
`BIGCHAINDB_KEYPAIR_PRIVATE`<br>
`BIGCHAINDB_KEYRING`<br>
`BIGCHAINDB_DATABASE_BACKEND`<br>
`BIGCHAINDB_DATABASE_HOST`<br>
`BIGCHAINDB_DATABASE_PORT`<br>
`BIGCHAINDB_DATABASE_NAME`<br>
`BIGCHAINDB_DATABASE_REPLICASET`<br>
`BIGCHAINDB_DATABASE_CONNECTION_TIMEOUT`<br>
`BIGCHAINDB_DATABASE_MAX_TRIES`<br>
`BIGCHAINDB_SERVER_BIND`<br>
`BIGCHAINDB_SERVER_LOGLEVEL`<br>
`BIGCHAINDB_SERVER_WORKERS`<br>
`BIGCHAINDB_WSSERVER_SCHEME`<br>
`BIGCHAINDB_WSSERVER_HOST`<br>
`BIGCHAINDB_WSSERVER_PORT`<br>
`BIGCHAINDB_WSSERVER_ADVERTISED_SCHEME`<br>
`BIGCHAINDB_WSSERVER_ADVERTISED_HOST`<br>
`BIGCHAINDB_WSSERVER_ADVERTISED_PORT`<br>
`BIGCHAINDB_CONFIG_PATH`<br>
`BIGCHAINDB_BACKLOG_REASSIGN_DELAY`<br>
`BIGCHAINDB_LOG`<br>
`BIGCHAINDB_LOG_FILE`<br>
`BIGCHAINDB_LOG_ERROR_FILE`<br>
`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>
`BIGCHAINDB_LOG_GRANULAR_LEVELS`<br>
`BIGCHAINDB_LOG_PORT`<br>
`BIGCHAINDB_DATABASE_SSL`<br>
`BIGCHAINDB_DATABASE_LOGIN`<br>
`BIGCHAINDB_DATABASE_PASSWORD`<br>
`BIGCHAINDB_DATABASE_CA_CERT`<br>
`BIGCHAINDB_DATABASE_CERTFILE`<br>
`BIGCHAINDB_DATABASE_KEYFILE`<br>
`BIGCHAINDB_DATABASE_KEYFILE_PASSPHRASE`<br>
`BIGCHAINDB_DATABASE_CRLFILE`<br>

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`.
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.

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.)

Running `bigchaindb -y configure mongodb` will generate a local config file in `$HOME/.bigchaindb` with all the default values (for using MongoDB as the database backend), with two exceptions: it will generate a valid private/public keypair, rather than using the default keypair (`None` and `None`).


## keypair.public & keypair.private

The [cryptographic keypair](../appendices/cryptography.html) used by the node. The public key is how the node idenifies itself to the world. The private key is used to generate cryptographic signatures. Anyone with the public key can verify that the signature was generated by whoever had the corresponding private key.

**Example using environment variables**
```text
export BIGCHAINDB_KEYPAIR_PUBLIC=8wHUvvraRo5yEoJAt66UTZaFq9YZ9tFFwcauKPDtjkGw
export BIGCHAINDB_KEYPAIR_PRIVATE=5C5Cknco7YxBRP9AgB1cbUVTL4FAcooxErLygw1DeG2D
```

**Example config file snippet**
```js
"keypair": {
  "public": "8wHUvvraRo5yEoJAt66UTZaFq9YZ9tFFwcauKPDtjkGw",
  "private": "5C5Cknco7YxBRP9AgB1cbUVTL4FAcooxErLygw1DeG2D"
}
```

Internally (i.e. in the Python code), both keys have a default value of `None`, but that's not a valid key. Therefore you can't rely on the defaults for the keypair. If you want to run BigchainDB, you must provide a valid keypair, either in the environment variables or in the local config file. You can generate a local config file with a valid keypair (and default everything else) using `bigchaindb -y configure mongodb`.


## keyring

A list of the public keys of all the nodes in the cluster, excluding the public key of this node.

**Example using an environment variable**
```text
export BIGCHAINDB_KEYRING=BnCsre9MPBeQK8QZBFznU2dJJ2GwtvnSMdemCmod2XPB:4cYQHoQrvPiut3Sjs8fVR1BMZZpJjMTC4bsMTt9V71aQ
```

Note how the keys in the list are separated by colons.

**Example config file snippet**
```js
"keyring": ["BnCsre9MPBeQK8QZBFznU2dJJ2GwtvnSMdemCmod2XPB",
            "4cYQHoQrvPiut3Sjs8fVR1BMZZpJjMTC4bsMTt9V71aQ"]
```

**Default value (from a config file)**
```js
"keyring": []
```


## database.*

The settings with names of the form `database.*` are for the database backend
(currently either MongoDB or RethinkDB). They are:

* `database.backend` is either `mongodb` or `rethinkdb`.
* `database.host` is the hostname (FQDN) of the backend database.
* `database.port` is self-explanatory.
* `database.name` is a user-chosen name for the database inside MongoDB or RethinkDB, e.g. `bigchain`.
* `database.replicaset` is only relevant if using MongoDB; it's the name of the MongoDB replica set, e.g. `bigchain-rs`.
* `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.
* `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.
* `database.ssl` is a flag that determines if BigchainDB connects to the
  backend database over TLS/SSL or not. This can be set to either `true` or
  `false` (the default).
  Note: This parameter is only supported for the MongoDB backend currently.
* `database.login` and `database.password` are the login and password used to
  authenticate to the database before performing any operations, specified in
  plaintext. The default values for both are currently `null`, which means that
  BigchainDB will not authenticate with the backend database.
  Note: These parameters are only supported for the MongoDB backend currently.
* `database.ca_cert`, `database.certfile`, `database.keyfile` and `database.crlfile` are the paths to the CA, signed certificate, private key and certificate revocation list files respectively.
  Note: These parameters are only supported for the MongoDB backend currently.
* `database.keyfile_passphrase` is the private key decryption passphrase, specified in plaintext.
  Note: This parameter is only supported for the MongoDB backend currently.

**Example using environment variables**
```text
export BIGCHAINDB_DATABASE_BACKEND=mongodb
export BIGCHAINDB_DATABASE_HOST=localhost
export BIGCHAINDB_DATABASE_PORT=27017
export BIGCHAINDB_DATABASE_NAME=bigchain
export BIGCHAINDB_DATABASE_REPLICASET=bigchain-rs
export BIGCHAINDB_DATABASE_CONNECTION_TIMEOUT=5000
export BIGCHAINDB_DATABASE_MAX_TRIES=3
```

**Default values**

If (no environment variables were set and there's no local config file), or you used `bigchaindb -y configure rethinkdb` to create a default local config file for a RethinkDB backend, then the defaults will be:
```js
"database": {
    "backend": "rethinkdb",
    "host": "localhost",
    "port": 28015,
    "name": "bigchain",
    "connection_timeout": 5000,
    "max_tries": 3
}
```

If you used `bigchaindb -y configure mongodb` to create a default local config file for a MongoDB backend, then the defaults will be:
```js
"database": {
    "backend": "mongodb",
    "host": "localhost",
    "port": 27017,
    "name": "bigchain",
    "replicaset": "bigchain-rs",
    "connection_timeout": 5000,
    "max_tries": 3,
    "login": null,
    "password": null
    "ssl": false,
    "ca_cert": null,
    "crlfile": null,
    "certfile": null,
    "keyfile": null,
    "keyfile_passphrase": null,
}
```


## server.bind, server.loglevel & server.workers

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).

`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.)

`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.

`server.workers` is [the number of worker processes](http://docs.gunicorn.org/en/stable/settings.html#workers) for handling requests. If `None` (the default), 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.

**Example using environment variables**
```text
export BIGCHAINDB_SERVER_BIND=0.0.0.0:9984
export BIGCHAINDB_SERVER_LOGLEVEL=debug
export BIGCHAINDB_SERVER_WORKERS=5
```

**Example config file snippet**
```js
"server": {
    "bind": "0.0.0.0:9984",
    "loglevel": "debug",
    "workers": 5,
}
```

**Default values (from a config file)**
```js
"server": {
    "bind": "localhost:9984",
    "loglevel": "info",
    "workers": null,
}
```


## wsserver.scheme, wsserver.host and wsserver.port

These settings are for the
[aiohttp server](https://aiohttp.readthedocs.io/en/stable/index.html),
which is used to serve the
[WebSocket Event Stream API](../websocket-event-stream-api.html).
`wsserver.scheme` should be either `"ws"` or `"wss"`
(but setting it to `"wss"` does *not* enable SSL/TLS).
`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
export BIGCHAINDB_WSSERVER_SCHEME=ws
export BIGCHAINDB_WSSERVER_HOST=0.0.0.0
export BIGCHAINDB_WSSERVER_PORT=9985
```

**Example config file snippet**
```js
"wsserver": {
    "scheme": "wss",
    "host": "0.0.0.0",
    "port": 65000
}
```

**Default values (from a config file)**
```js
"wsserver": {
    "scheme": "ws",
    "host": "localhost",
    "port": 9985
}
```

## 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
}
```

## backlog_reassign_delay

Specifies how long, in seconds, transactions can remain in the backlog before being reassigned.  Long-waiting transactions must be reassigned because the assigned node may no longer be responsive.  The default duration is 120 seconds.

**Example using environment variables**
```text
export BIGCHAINDB_BACKLOG_REASSIGN_DELAY=30
```

**Default value (from a config file)**
```js
"backlog_reassign_delay": 120
```


## log

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",
        "error_file": "/var/log/bigchaindb-errors.log",
        "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",
        "fmt_logfile": "%(asctime)s [%(levelname)s] (%(name)s) %(message)s",
        "granular_levels": {
            "bichaindb.backend": "info",
            "bichaindb.core": "info"
        },
        "port": 7070
}
```

**Defaults to**:

```
{
    "log": {
        "file": "~/bigchaindb.log",
        "error_file": "~/bigchaindb-errors.log",
        "level_console": "info",
        "level_logfile": "info",
        "datefmt_console": "%Y-%m-%d %H:%M:%S",
        "datefmt_logfile": "%Y-%m-%d %H:%M:%S",
        "fmt_logfile": "[%(asctime)s] [%(levelname)s] (%(name)s) %(message)s (%(processName)-10s - pid: %(process)d)",
        "fmt_console": "[%(asctime)s] [%(levelname)s] (%(name)s) %(message)s (%(processName)-10s - pid: %(process)d)",
        "granular_levels": {},
        "port": 9020
}
```

The next subsections explain each field of the `log` configuration.


### log.file & log.error_file
The full paths to the files where logs and error logs should be written to.

**Example**:

```
{
    "log": {
        "file": "/var/log/bigchaindb/bigchaindb.log"
        "error_file": "/var/log/bigchaindb/bigchaindb-errors.log"
    }
}
```

**Defaults to**:

    * `"~/bigchaindb.log"`
    * `"~/bigchaindb-errors.log"`

Please note that the user running `bigchaindb` must have write access to the
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
`bigchain.log` reaches 200 MB it would be closed and renamed
`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`.


### log.level_console
The log level used to log to the console. Possible allowed values are the ones
defined by [Python](https://docs.python.org/3.6/library/logging.html#levels),
but case insensitive for convenience's sake:

```
"critical", "error", "warning", "info", "debug", "notset"
```

**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
defined by [Python](https://docs.python.org/3.6/library/logging.html#levels),
but case insensitive for convenience's sake:

```
"critical", "error", "warning", "info", "debug", "notset"
```

**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
logging of the `core.py` module to be more verbose, you would set the
 configuration shown in the example below.

**Example**:

```
{
    "log": {
        "granular_levels": {
            "bichaindb.core": "debug"
        }
}
```

**Defaults to**: `{}`


### log.port
The port number at which the logging server should listen.

**Example**:

```
{
    "log": {
        "port": 7070
        }
}
```

**Defaults to**: `9020`