Configuration Settings

Configuration Settings

BS uses Boost's program_options library to bind configuration settings to strongly-typed application level properties.

The implementation supports a two level hierarchy of settings using "sections" to group settings, similar to an .ini file:

# Libbitcoin Server configuration file

[network]
# The number of threads in the network threadpool, defaults to 4.
threads = 4
# The port for incoming connections, defaults to 8333 (18333 for testnet).
inbound_port = 8333
# The maximum number of incoming network connections, defaults to 0.
inbound_connection_limit = 0
# The maximum number of outgoing network connections, defaults to 1.
outbound_connections = 1
# The time limit for connection establishment, defaults to 5.
connect_timeout_seconds = 5
# The time limit to complete the connection handshake, defaults to 15.
channel_handshake_seconds = 15
# The time between blocks that initiates a request, defaults to 1.
channel_poll_seconds = 1
# The time between ping messages, defaults to 5.
channel_heartbeat_minutes = 5
# The inactivity time limit for any connection, defaults to 10.
channel_inactivity_minutes = 10
# The maximum age limit for an outbound connection, defaults to 1440.
channel_expiration_minutes = 1440
# Request that peers relay transactions, defaults to false.
relay_transactions = false
# The maximum number of peer hosts in the pool, defaults to 1000.
host_pool_capacity = 1000
# The peer hosts cache file path, defaults to 'hosts.cache'.
hosts_file = hosts.cache
# The debug log file path, defaults to 'debug.log'.
debug_file = debug.log
# The error log file path, defaults to 'error.log'.
error_file = error.log
# The advertised public address of this node, defaults to none.
self = 0.0.0.0:0
# A seed node for initializing the host pool, multiple entries allowed, defaults shown.
seed = seed.bitnodes.io:8333
seed = seed.bitcoinstats.com:8333
seed = seed.bitcoin.sipa.be:8333
seed = dnsseed.bluematt.me:8333
seed = seed.bitcoin.jonasschnelli.ch:8333
seed = dnsseed.bitcoin.dashjr.org:8333
# Testnet seed nodes.
#seed = testnet-seed.alexykot.me:18333
#seed = testnet-seed.bitcoin.petertodd.org:18333
#seed = testnet-seed.bluematt.me:18333
#seed = testnet-seed.bitcoin.schildbach.de:18333

[blockchain]
# The number of threads in the blockchain threadpool, defaults to 6.
threads = 6
# The maximum number of orphan blocks in the pool, defaults to 1.
block_pool_capacity = 1
# The history index start height, defaults to 0.
history_start_height = 0
# The blockchain database directory, defaults to 'blockchain'.
database_path = blockchain
# A hash:height checkpoint, multiple entries allowed, defaults shown.
checkpoint = 000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f:0
checkpoint = 0000000069e244f73d78e8fd29ba2fd2ed618bd6fa2ee92559f542fdb26e7c1d:11111
checkpoint = 000000002dd5588a74784eaa7ab0507a18ad16a236e7b1ce69f00d7ddfb5d0a6:33333
checkpoint = 00000000001e1b4903550a0b96e9a9405c8a95f387162e4944e8d9fbe501cd6a:68555
checkpoint = 00000000006a49b14bcf27462068f1264c961f11fa2e0eddd2be0791e1d4124a:70567
checkpoint = 0000000000573993a3c9e41ce34471c079dcf5f52a0e824a81e7f953b8661a20:74000
checkpoint = 00000000000291ce28027faea320c8d2b054b2e0fe44a773f3eefb151d6bdc97:105000
checkpoint = 000000000000774a7f8a7a12dc906ddb9e17e75d684f15e00f8767f9e8f36553:118000
checkpoint = 00000000000005b12ffd4cd315cd34ffd4a594f430ac814c91184a0d42d2b0fe:134444
checkpoint = 000000000000033b512028abb90e1626d8b346fd0ed598ac0a3c371138dce2bd:140700
checkpoint = 000000000000099e61ea72015e79632f216fe6cb33d7899acb35b75c8303b763:168000
checkpoint = 000000000000059f452a5f7340de6682a977387c17010ff6e6c3bd83ca8b1317:193000
checkpoint = 000000000000048b95347e83192f69cf0366076336c639f9b7228e9ba171342e:210000
checkpoint = 00000000000001b4f4b433e81ee46494af945cf96014816a4e2370f11b23df4e:216116
checkpoint = 00000000000001c108384350f74090433e7fcf79a606b8e797f065b130575932:225430
checkpoint = 000000000000003887df1f29024b06fc2200b55f8af8f35453d7be294df2d214:250000
checkpoint = 0000000000000001ae8c72a0b0c301f67e3afca10e819efa9041e458e9bd7e40:279000
checkpoint = 00000000000000004d9b4ef50f0f9d686fd69db2e03af35a100370c64632a983:295000
checkpoint = 000000000000000017a4b176294583519076f06cd2b5e4ef139dada8d44838d8:330791
checkpoint = 000000000000000017522241d7afd686bb2315930fc1121861c9abf52e8c37f1:337459
checkpoint = 0000000000000000086672a8c97ad666f89cf04736951791150015419810d586:368991
checkpoint = 0000000000000000006166e421051bd1ccc2bf3b80ebd2ed20c71a2eecc10633:389500
# Testnet checkpoints.
#checkpoint = 000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f:0
#checkpoint = 00000000009e2958c15ff9290d571bf9459e93b19765c6801ddeccadbb160a1e:100000
#checkpoint = 0000000000287bffd321963ef05feab753ebe274e1d78b2fd4e2bfe9ad3aa6f2:200000
#checkpoint = 000000000000226f7618566e70a2b5e020e29579b46743f05348427239bf41a1:300000
#checkpoint = 000000000598cbbb1e79057b79eef828c495d4fc31050e6b179c57d07d00367c:400000
#checkpoint = 000000000001a7c0aaa2630fbb2c0e476aafffc60f82177375b2aaa22209f606:500000
#checkpoint = 000000000000624f06c69d3a9fe8d25e0a9030569128d63ad1b704bbb3059a16:600000

[node]
# The number of threads in the node threadpool, defaults to 4.
threads = 4
# The minimum block bytes per minute during initial block download, defaults to 1000000.
minimum_bytes_per_minute = 1000000
# The maximum number of transactions in the pool, defaults to 2000.
transaction_pool_capacity = 2000
# Enforce consistency between the pool and the blockchain, defaults to false.
transaction_pool_consistency = false
# Persistent host:port to augment discovered hosts, multiple entries allowed.
# peer = obelisk.airbitz.co:8333
# IP address to disallow as a peer, multiple entries allowed.
# blacklist = 127.0.0.1

[server]
# The query service endpoint, defaults to 'tcp://*:9091'.
query_endpoint = tcp://*:9091
# The heartbeat service endpoint, defaults to 'tcp://*:9092'.
heartbeat_endpoint = tcp://*:9092
# The block publishing service endpoint, defaults to 'tcp://*:9093'.
block_publish_endpoint = tcp://*:9093
# The transaction publishing service endpoint, defaults to 'tcp://*:9094'.
transaction_publish_endpoint = tcp://*:9094
# Enable the block and transaction publishing endpoints, defaults to false.
publisher_enabled = false
# Enable the query and heartbeat endpoints, defaults to false.
queries_enabled = false
# Write service requests to the log, defaults to false.
log_requests = false
# The query polling interval in milliseconds, defaults to 1000.
polling_interval_milliseconds = 1000
# The heartbeat interval in seconds, defaults to 5.
heartbeat_interval_seconds = 5
# The subscription expiration time, defaults to 10 minutes.
subscription_expiration_minutes = 10
# The maximum number of subscriptions, defaults to 100000000.
subscription_limit = 100000000
# The path to the ZPL-encoded server private certificate file.
# certificate_file =
# The directory for ZPL-encoded client public certificate files, allows anonymous clients if not set.
# client_certificates_path =
# Allowed client IP address, all clients allowed if none set, multiple entries allowed.
# whitelist = 127.0.0.1

The --version command line option displays the current version number of the server and dependent libraries.

The path to the configuration settings file is specified by the CONFIG command line argument, the BS_CONFIG environment variable, or by default as follows:

• Linux/OSX (prefix): <prefix>/etc/libbitcoin/bs.cfg
• Linux/OSX (default): /usr/local/etc/libbitcoin/bs.cfg
• Windows: %ProgramData%\libbitcoin\bs.cfg

The Windows directory is hidden by default. If the file is not found default values are loaded. If the file is contains invalid settings an error is returned via STDERR. If any setting is not specified its default is loaded.

The $ bs --settings command option the definition for all configuration settings.

Environment Variables

BS uses Boost's program_options library to bind environment variables. All environment variables are prefixed with BS_. BS_CONFIG is the only bound environment variable.