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
BIGCHAINDB_KEYPAIR_PRIVATE
BIGCHAINDB_KEYRING
BIGCHAINDB_DATABASE_BACKEND
BIGCHAINDB_DATABASE_HOST
BIGCHAINDB_DATABASE_PORT
BIGCHAINDB_DATABASE_NAME
BIGCHAINDB_DATABASE_REPLICASET
BIGCHAINDB_DATABASE_CONNECTION_TIMEOUT
BIGCHAINDB_DATABASE_MAX_TRIES
BIGCHAINDB_SERVER_BIND
BIGCHAINDB_SERVER_LOGLEVEL
BIGCHAINDB_SERVER_WORKERS
BIGCHAINDB_SERVER_THREADS
BIGCHAINDB_CONFIG_PATH
BIGCHAINDB_BACKLOG_REASSIGN_DELAY
BIGCHAINDB_LOG
BIGCHAINDB_LOG_FILE
BIGCHAINDB_LOG_LEVEL_CONSOLE
BIGCHAINDB_LOG_LEVEL_LOGFILE
BIGCHAINDB_LOG_DATEFMT_CONSOLE
BIGCHAINDB_LOG_DATEFMT_LOGFILE
BIGCHAINDB_LOG_FMT_CONSOLE
BIGCHAINDB_LOG_FMT_LOGFILE
BIGCHAINDB_LOG_GRANULAR_LEVELS

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. (The link is to the latest version.)

Running bigchaindb -y configure rethinkdb will generate a local config file in $HOME/.bigchaindb with all the default values, 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 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

export BIGCHAINDB_KEYPAIR_PUBLIC=8wHUvvraRo5yEoJAt66UTZaFq9YZ9tFFwcauKPDtjkGw
export BIGCHAINDB_KEYPAIR_PRIVATE=5C5Cknco7YxBRP9AgB1cbUVTL4FAcooxErLygw1DeG2D

Example config file snippet

"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 rethinkdb.

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

export BIGCHAINDB_KEYRING=BnCsre9MPBeQK8QZBFznU2dJJ2GwtvnSMdemCmod2XPB:4cYQHoQrvPiut3Sjs8fVR1BMZZpJjMTC4bsMTt9V71aQ

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

Example config file snippet

"keyring": ["BnCsre9MPBeQK8QZBFznU2dJJ2GwtvnSMdemCmod2XPB",
            "4cYQHoQrvPiut3Sjs8fVR1BMZZpJjMTC4bsMTt9V71aQ"]

Default value (from a config file)

"keyring": []

database.*

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

• database.backend is either rethinkdb or mongodb.
• 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 RethinkDB or MongoDB, 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. Note: At the time of writing, this setting was only used by MongoDB; there was an open issue to make RethinkDB use it as well.
• 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.

Example using environment variables

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:

"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:

"database": {
    "backend": "mongodb",
    "host": "localhost",
    "port": 27017,
    "name": "bigchain",
    "replicaset": "bigchain-rs",
    "connection_timeout": 5000,
    "max_tries": 3
}

server.bind, server.loglevel, server.workers & server.threads

These settings are for the Gunicorn HTTP server, which is used to serve the HTTP client-server API.

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. 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. (They call it a proxy.)

server.loglevel sets the log level of Gunicorn's Error log outputs. See Gunicorn's documentation for more information.

server.workers is the number of worker processes for handling requests. If None (the default), the value will be (cpu_count * 2 + 1). server.threads is the number of threads-per-worker for handling requests. If None (the default), the value will be (cpu_count * 2 + 1). The HTTP server will be able to handle server.workers * server.threads requests simultaneously.

Example using environment variables

export BIGCHAINDB_SERVER_BIND=0.0.0.0:9984
export BIGCHAINDB_SERVER_LOGLEVEL=debug
export BIGCHAINDB_SERVER_WORKERS=5
export BIGCHAINDB_SERVER_THREADS=5

Example config file snippet

"server": {
    "bind": "0.0.0.0:9984",
    "loglevel": "debug",
    "workers": 5,
    "threads": 5
}

Default values (from a config file)

"server": {
    "bind": "localhost:9984",
    "loglevel": "info",
    "workers": null,
    "threads": null
}

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

export BIGCHAINDB_BACKLOG_REASSIGN_DELAY=30

Default value (from a config file)

"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",
        "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"
        }
}

Defaults to: "{}".

Please note that although the default is "{}" as per the configuration file, internal defaults are used, such that the actual operational default is:

{
    "log": {
        "file": "~/bigchaindb.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": {}
}

The next subsections explain each field of the log configuration.

log.file

The full path to the file where logs should be written to.

Example:

{
    "log": {
        "file": "/var/log/bigchaindb/bigchaindb.log"
    }
}

Defaults to: "~/bigchaindb.log".

Please note that the user running bigchaindb must have write access to the location.

log.level_console

The log level used to log to the console. Possible allowed values are the ones defined by Python, 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, 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])

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

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

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

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: "{}"