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 magic number for message headers, defaults to 3652501241 (use 118034699 for testnet).
identifier = 3652501241
# The port for incoming connections, defaults to 8333 (use 18333 for testnet).
inbound_port = 8333
# The target number of total network connections, defaults to 16.
connection_limit = 16
# The target number of outgoing network connections, defaults to 8.
outbound_connections = 8
# The retry limit for manual connection establishment, defaults to 0 (forever).
manual_retry_limit = 0
# The time limit for connection establishment, defaults to 5.
connect_timeout_seconds = 5
# The time limit to complete the connection handshake, defaults to 30.
channel_handshake_seconds = 30
# The time between blocks that initiates a request, defaults to 5.
channel_revival_minutes = 5
# The time between ping messages, defaults to 5.
channel_heartbeat_minutes = 5
# The inactivity time limit for any connection, defaults to 30.
channel_inactivity_minutes = 30
# The maximum age limit for an outbound connection, defaults to 90.
channel_expiration_minutes = 90
# The maximum time limit for obtaining seed addresses, defaults to 30.
channel_germination_seconds = 30
# The maximum number of peer hosts in the pool, defaults to 1000.
host_pool_capacity = 1000
# Request that peers relay transactions, defaults to true.
relay_transactions = true
# 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
# IP address to disallow as a peer, multiple entries allowed.
blacklist = 127.0.0.1
# 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.bitcoin.petertodd.org:18333
#seed = testnet-seed.bitcoin.schildbach.de:18333
#seed = testnet-seed.bluematt.me: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 50.
block_pool_capacity = 50
# The history index start height, defaults to 0.
history_start_height = 0
# Use testnet rules for determination of work required, defaults to false (use true for testnet).
use_testnet_rules = false
# 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
# Testnet checkpoints.
#checkpoint = 000000000933ea01ad0ee984209779baaec3ced90fa3f408719526f8d77f4943:0
#checkpoint = 00000000009e2958c15ff9290d571bf9459e93b19765c6801ddeccadbb160a1e:100000
#checkpoint = 0000000000287bffd321963ef05feab753ebe274e1d78b2fd4e2bfe9ad3aa6f2:200000
#checkpoint = 000000000000226f7618566e70a2b5e020e29579b46743f05348427239bf41a1:300000
#checkpoint = 000000000598cbbb1e79057b79eef828c495d4fc31050e6b179c57d07d00367c:400000
#checkpoint = 000000000001a7c0aaa2630fbb2c0e476aafffc60f82177375b2aaa22209f606:500000

[node]
# The number of threads in the node threadpool, defaults to 4.
threads = 4
# The maximum number of transactions in the pool, defaults to 2000.
transaction_pool_capacity = 2000
# Persistent host:port to augment discovered hosts, multiple entries allowed.
# peer = obelisk.airbitz.co:8333

[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 true.
publisher_enabled = true
# Enable the query and heartbeat endpoints, defaults to true.
queries_enabled = true
# Write service requests to the log, defaults to false.
log_requests = false
# The query polling interval in seconds, defaults to 1.
polling_interval_seconds = 1
# 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.