Configuration Settings

Specifying a Configuration File

The path to the configuration settings file is specified by the --config command line option, 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 specified file is not found default values are loaded. If the file contains invalid settings an error is returned via STDERR. If any setting is not specified its default is loaded.

BS uses Boost's program_options library to bind configuration settings. The implementation supports a two level hierarchy of settings using "sections" to group settings, similar to an .ini file:

Default Configuration Settings

For convenience, the bs.cfg file is populated with all default settings values. A copy of the file is shown below:

# Libbitcoin Server configuration file

[log]
# 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 log archive directory, defaults to 'archive'.
archive_directory = archive
# The size at which a log is archived, defaults to 0 (disabled).
rotation_size = 0
# The minimum free space required in the archive directory, defaults to 0.
minimum_free_space = 0
# The maximum combined size of archived logs, defaults to 0 (maximum).
maximum_archive_size = 0
# The maximum number of logs to archive, defaults to 0 (maximum).
maximum_archive_files = 0
# The address of the statistics collection server, defaults to none.
statistics_server = 0.0.0.0:0
# Enable verbose logging, defaults to false.
verbose = false

[network]
# The minimum number of threads in the network threadpool, defaults to 0 (physical cores).
threads = 0
# The maximum network protocol version, defaults to 70013.
protocol_maximum = 70013
# The minimum network protocol version, defaults to 31402.
protocol_minimum = 31402
# The services exposed by network connections, defaults to 1 (full node).
services = 1
# The magic number for message headers, defaults to 3652501241 (use 118034699 for testnet).
identifier = 3652501241
# Validate the checksum of network messages, defaults to false.
validate_checksum = false
# The port for incoming connections, defaults to 8333 (use 18333 for testnet).
inbound_port = 8333
# The target number of incoming network connections, defaults to 8.
inbound_connections = 8
# The target number of outgoing network connections, defaults to 8.
outbound_connections = 8
# The attempt limit for manual connection establishment, defaults to 0 (forever).
manual_attempt_limit = 0
# The number of concurrent attempts to establish one connection, defaults to 5.
connect_batch_size = 5
# 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 ping messages, defaults to 5.
channel_heartbeat_minutes = 5
# The inactivity time limit for any connection, defaults to 30.
channel_inactivity_minutes = 30
# The age limit for any connection, defaults to 1440.
channel_expiration_minutes = 1440
# The 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
# The peer hosts cache file path, defaults to 'hosts.cache'.
hosts_file = hosts.cache
# 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 persistent peer node, multiple entries allowed.
#peer = mainnet.libbitcoin.net:8333
#peer = testnet.libbitcoin.net:8333
# A seed node for initializing the host pool, multiple entries allowed, defaults shown.
seed = seed.bitcoin.sipa.be:8333
seed = dnsseed.bluematt.me:8333
seed = dnsseed.bitcoin.dashjr.org:8333
seed = seed.bitcoinstats.com:8333
seed = seed.bitcoin.jonasschnelli.ch:8333
seed = seed.voskuil.org:8333
# Testnet seed nodes.
#seed = testnet-seed.bitcoin.jonasschnelli.ch:18333
#seed = seed.tbtc.petertodd.org:18333
#seed = testnet-seed.bluematt.me:18333
#seed = testnet-seed.bitcoin.schildbach.de:18333
#seed = testnet-seed.voskuil.org:18333

[database]
# The blockchain database directory, defaults to 'blockchain'.
directory = blockchain
# Flush each write to disk, defaults to true.
flush_writes = true
# Full database files increase by this percentage, defaults to 50.
file_growth_rate = 50
# Block hash table size, defaults to 650000.
block_table_buckets = 650000
# Transaction hash table size, defaults to 110000000.
transaction_table_buckets = 110000000
# Spend hash table size, defaults to 250000000.
spend_table_buckets = 250000000
# History hash table size, defaults to 107000000.
history_table_buckets = 107000000
# The maximum number of entries in the unspent outputs cache, defaults to 0.
cache_capacity = 0

[blockchain]
# The number of cores dedicated to block validation, defaults to 0 (physical cores).
cores = 0
# Use high thread priority for block validation, defaults to false.
priority = false
# Use libconsensus for script validation if integrated, defaults to false.
use_libconsensus = false
# The maximum reorganization depth, defaults to 256 (0 for unlimited).
reorganization_limit = 256
# The block version for block creation and transaction pool validation, defaults to 4.
block_version = 4
# 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
# Testnet checkpoints.
#checkpoint = 000000000933ea01ad0ee984209779baaec3ced90fa3f408719526f8d77f4943:0
#checkpoint = 00000000009e2958c15ff9290d571bf9459e93b19765c6801ddeccadbb160a1e:100000
#checkpoint = 0000000000287bffd321963ef05feab753ebe274e1d78b2fd4e2bfe9ad3aa6f2:200000
#checkpoint = 000000000000226f7618566e70a2b5e020e29579b46743f05348427239bf41a1:300000
#checkpoint = 000000000598cbbb1e79057b79eef828c495d4fc31050e6b179c57d07d00367c:400000
#checkpoint = 000000000001a7c0aaa2630fbb2c0e476aafffc60f82177375b2aaa22209f606:500000
#checkpoint = 000000000000624f06c69d3a9fe8d25e0a9030569128d63ad1b704bbb3059a16:600000

[fork]
# Allow minimum difficulty blocks, defaults to false (use true for testnet).
easy_blocks = false
# Add pay-to-script-hash processing, defaults to true (soft fork).
bip16 = true
# Disallow collision of unspent transaction hashes, defaults to true (hard fork).
bip30 = true
# Coinbase input must include block height, defaults to true (soft fork).
bip34 = true
# Require strict signature encoding, defaults to true (soft fork).
bip66 = true
# Add check locktime verify op code, defaults to true (soft fork).
bip65 = true
# Assume bip34, bip65, and bip66 activation if enabled, defaults to true (hard fork).
bip90 = true

[node]
# The time period for block polling after initial block download, defaults to 1 (0 disables).
block_poll_seconds = 1
# The minimum fee per byte required for transaction acceptance, defaults to 1.
minimum_byte_fee_satoshis = 1
# Request that peers relay transactions, defaults to true.
relay_transactions = true
# Request transactions on each channel start, defaults to true.
refresh_transactions = true

[server]
# The lower limit of address and spend indexing, defaults to 0.
index_start_height = 0
# Disable public endpoints, defaults to false.
secure_only = false
# The number of query worker threads per endpoint, defaults to 1 (0 disables service).
query_workers = 1
# The maximum number of subscriptions, defaults to 0 (disabled).
subscription_limit = 0
# The subscription expiration time, defaults to 10.
subscription_expiration_minutes = 10
# The heartbeat interval, defaults to 5 (0 disables service).
heartbeat_interval_seconds = 5
# Enable the block publishing service, defaults to true.
block_service_enabled = true
# Enable the transaction publishing service, defaults to true.
transaction_service_enabled = true
# The public query endpoint, defaults to 'tcp://*:9091'.
public_query_endpoint = tcp://*:9091
# The public heartbeat endpoint, defaults to 'tcp://*:9092'.
public_heartbeat_endpoint = tcp://*:9092
# The public block publishing endpoint, defaults to 'tcp://*:9093'.
public_block_endpoint = tcp://*:9093
# The public transaction publishing endpoint, defaults to 'tcp://*:9094'.
public_transaction_endpoint = tcp://*:9094
# The secure query endpoint, defaults to 'tcp://*:9081'.
secure_query_endpoint = tcp://*:9081
# The secure heartbeat endpoint, defaults to 'tcp://*:9082'.
secure_heartbeat_endpoint = tcp://*:9082
# The secure block publishing endpoint, defaults to 'tcp://*:9083'.
secure_block_endpoint = tcp://*:9083
# The secure transaction publishing endpoint, defaults to 'tcp://*:9084'.
secure_transaction_endpoint = tcp://*:9084
# The Z85-encoded private key of the server, enables secure endpoints.
#server_private_key =
# Allowed Z85-encoded public key of the client, multiple entries allowed.
#client_public_key =
# Allowed client IP address, multiple entries allowed.
#client_address = 127.0.0.1

Exporting Settings

The --settings command line option emits the definitions for all configuration settings.