Network Settings

The following networking settings are implemented in the libbitcoin-network and exposed in both Bitcoin Node (BN) and Bitcoin Server (BS).

[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 9 (full node, witness).
services = 9
# The advertised services that cause a peer to be dropped, defaults to 0 (none).
invalid_services = 0
# 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 0.
inbound_connections = 0
# The target number of outgoing network connections, defaults to 2.
outbound_connections = 2
# 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 60.
channel_expiration_minutes = 60
# 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

This section pertains to the bitcoin peer-to-peer network.

threads

The number of network threads is capped by the number of physical cores, however this setting allows that value to be reduced.

protocol_maximum

The node negotiates a common version with each peer, and always attempts to achieve this value. The negotiated version will be the lowest of this value and the a peer's advertised version. This value must neither exceed the supported maximum of 70013 nor be set below the configured minimum. The discrete levels implemented are all between 31402 and 70013. Block filtering, an optional aspect of 70001, and mempool response are not supported:

• 70013 [feefilter]
• 70012 [sendheaders]
• 70002 [multiple mempool inv responses, reject]
• 70001 [notfound, version.relay, merkleblock (unfiltered)]
• 60002 [mempool (request)]
• 60001 [ping.nonce, pong]
• 31800 [headers, getheaders] (minimum recent satoshi client support)
• 31402 [addr.time]

protocol_minimum

The minimum acceptable negotiates version. If the peer advertises a version below this value the connection will be terminated. This value must neither exceed the configured maximum nor be set below the supported minimum of 31402.

services

The services exposed by own network connections and expected of peers. This value is defined by the version message and should generally be set to 9, which indicates a full node (1) with witness data (8).

identifier

The magic number for message headers. This value is defined by message structure and must match the intended network.

validate_checksum

Validate the checksum number for message headers. The checksum is defined by message structure. For compatibility message checksum values are always written but validation is costly and entirely unnecessary.

inbound_port

If set to 0 no incoming connections are allowed.

inbound_connections

This is a target value, however due to asynchronous operation it is possible that this value can be exceeded temporarily. The port configuration must be nonzero for incoming connections to be accepted. The host address must be configured in self for the host to be advertised to peers. When using ensure that firewalls are configured to allow/relay incoming connections as necessary.

outbound_connections

This requires an address pool, either seeded after startup or populated before startup.

manual_attempt_limit

Peers configured using the peer setting are called "manual". When a manual peer is not connected the node will continue to attempt to connect (or reconnect) indefinitely. Set this value to limit the number of of attempts. The attempt count is reset upon connection.

connect_batch_size

Typically the host pool is populated with a significant number of unreachable peers. Batch connection attempts to concurrently connect to a set of peers for each configured outbound connection. So with outbound_connections = 8 and connect_batch_size = 5 the node will gather 8 * 5 = 40 host addresses and simultaneously attempt connection to each. The first peer from each set to connect is retained and the others in the set are dropped. If a set does not connect before connect_timeout_seconds, or if a connection is dropped, the process is reset for that connection. This significantly reduces connection time and tends to result in faster peers and/or lower latency connections (since these are the first to connect). When setting a large number of outbound connections this value should be reduced.

connect_timeout_seconds

This value controls expiration of individual outbound and manual connection attempts.

channel_handshake_seconds

This value controls expiration of version negotiation. The prevents the node from waiting indefinitely on a peer that fails to send a version message, or to respond with a verack message, in a timely manner.

channel_heartbeat_minutes

A ping message is sent on this interval. If the interval passes without receiving a pong message (as applicable to the protocol level) the channel is dropped.

channel_inactivity_minutes

If the time between incoming messages exceeds this value the channel is dropped. This is useful in the case of protocol versions prior to 60001, which lack the pong message.

channel_expiration_minutes

Each channel is terminated no later than this period after connection. This can be useful in ensuring that no very slow or poorly-connected peer is able to hold on to a port indefinitely. This includes manual connections, which are automatically reestablished after being dropped.

channel_germination_seconds

This value controls expiration of the seeding process for each configured seed node. The prevents the node from waiting indefinitely on a seed node that fails to send an addr message in a timely manner.

host_pool_capacity

This value can be increased significantly though this can have a minor impact on performance.

hosts_file

Since the file is only read and written at startup and shutdown respectively, this file does not require a high performance drive and can reside in any file system location. The file is a simple list of standard format host addresses. The values can be manually populated before starting, one per line of the text file. If there are any addresses in the file the seeding processes is bypassed. Each connection may contributes addresses to the list, though these are not written to the file until shutdown.

self

If set this value is returned in the version negotiation, unsolicited at connect in the addr message, and in response to getaddr requests.

blacklist

The node automatically drops connections to itself based on version nonce correlation. Blocking localhost is however necessary to block connection from another local node. Blocking a host addresses is not a security measure, as given sufficient network access IP addresses can be spoofed. This feature is not effective until v3.2.

peer

Each of these addresses will be reconnected at any time they are dropped. Sequential connection attempts can be limited by setting manual_attempt_limit.

seed

Seeding is skipped if any addresses are populated in the host cache at startup. However, in v3.2 and later seeding will fail if less than 100 seeds are generated.