Running Bitcoin Core

Binaries

bitcoind (node), bitcoin-cli (RPC client), bitcoin-qt (GUI). Since 30.0 (October 2025) a bitcoin wrapper dispatches to them: bitcoin node is bitcoind, bitcoin gui is bitcoin-qt, bitcoin rpc is bitcoin-cli -named, and bitcoin help lists the rest. It implements nothing itself and the existing commands are not deprecated, but upstream docs increasingly use it, so recognise both spellings.

Configuration file

~/.bitcoin/bitcoin.conf (Linux/macOS) or %APPDATA%\Bitcoin\bitcoin.conf (Windows). Optional -conf= flag.

Section markers

# Top-level: applied to all networks
dbcache=4096

[main]
# Mainnet-only
prune=550

[test]
# Testnet3
[testnet4]
# Testnet4 (BIP94, added in 28.0)
[signet]
# Signet
[regtest]
# Regtest

The chain=test/testnet4/signet/regtest cmdline flag selects active network. Without [section], top-level options apply universally.

Which public test network to point at - testnet3 (deprecated in Core's own -testnet help text), testnet4, signet - and the status of the testnet5 draft (BIP 95, still Draft as of September 2026) are covered in ../../testing/testnet/SKILL.md.

Key options

Relay policy since 30.0

Bitcoin Core 30.0 (October 2025) moved the default standardness policy, and this delta is what the Core/Knots divergence is actually about:

• -datacarriersize default raised from 83 to 100,000, "which effectively uncaps the limit (as the maximum transaction size limit will be hit first)". MAX_OP_RETURN_RELAY in src/policy/policy.h is now MAX_STANDARD_TX_WEIGHT / WITNESS_SCALE_FACTOR, against a hardcoded 83 in v28.0 (#32406).
• Multiple OP_RETURN outputs per transaction are relayed and mined; the limit applies to the aggregate scriptPubKey size across all of them (#32406).
• -minrelaytxfee and -incrementalrelayfee defaults cut to 0.1 sat/vB and -blockmintxfee to 0.001 sat/vB (#33106). Dust feerate, fee-estimator output and wallet feerates are unchanged. Upstream's own caveat: unless the lower defaults are widely adopted across the network, transactions built at those feerates are not guaranteed to propagate or confirm.
• getmempoolinfo gained permitbaremultisig and maxdatacarriersize fields, so effective policy is checkable at runtime (#29954).

-permitbaremultisig did not change: DEFAULT_PERMIT_BAREMULTISIG is true in src/policy/policy.h at v28.0 and in current master alike, so Core has always permitted bare multisig by default. Knots is the implementation that ships 0. Read the running value from getmempoolinfo.permitbaremultisig (30.0+) rather than inferring it from the binary's name.

Full RBF is unconditional since 29.0 (April 2025). -mempoolfullrbf was defaulted to 1 in 28.0 and then removed outright - "users no longer benefit from disabling it, so the option has been removed, making full replace-by-fee the standard behavior" (#30592). Passing it to 29.0+ is an unknown-setting startup error.

31.0 (April 2026) replaced the mempool implementation with "cluster mempool": ancestor/descendant limits are gone in favour of cluster limits (64 transactions, 101 kB vsize), RBF now requires a strictly better mempool feerate diagram, the CPFP carveout is removed, and getmempoolcluster / getmempoolfeeratediagram are new.

Initial Block Download (IBD)

Phases:

1. Header sync — fast, all headers from a single peer.
2. Block download — parallel download from multiple peers.
3. Block validation — script verify, UTXO set update.

Tips:

• Use a fast SSD; HDD adds days.
• dbcache=4096 (or higher with RAM) speeds up phase 3 dramatically. 31.0 (April 2026) raised the default from 450 to 1024 MiB on hosts where at least 4096 MiB of RAM is detected (#34692); 29.0 (April 2025) dropped the old upper cap, which had silently clamped large values to 16 GiB (1 GiB on 32-bit), and 30.0 (October 2025) re-capped 32-bit hosts at 1 GiB.
• Bandwidth: ~770 GB of block data at height ~967,000 (15 September 2026), growing roughly 7 GB/month. Restrict via maxuploadtarget= if metered.
• After IBD you can shrink dbcache, but the 31.0+ default is already 1024 MiB; only go below it on memory-constrained hosts.

Pruning vs txindex

• Pruned (550-15000 MB):
  • Fast disk usage; minimal historical access.
  • Cannot serve old blocks to peers (becomes NODE_NETWORK_LIMITED).
  • Cannot run Electrs / serve historical getrawtransaction.
• Full (no prune):
  • ~875 GB in blocks/ at height ~967,000 (15 September 2026), growing roughly 7 GB/month, plus ~11 GB of chainstate.
  • Can serve any block to peers.
  • Required for indexers.
• txindex=1:
  • Adds ~80 GB.
  • Required for arbitrary getrawtransaction.
  • Cannot combine with prune.

For a Lightning node: full + blockfilterindex=1 is typical (no txindex needed; LDK/CLN use filter scan).

Tor configuration

proxy=127.0.0.1:9050
onlynet=onion
listenonion=1
bind=127.0.0.1

bitcoind auto-creates a Tor v3 hidden service via torcontrol (needs controlport=9051 + cookie auth or password in torrc).

-privatebroadcast (31.0+) is a separate, narrower privacy lever: it makes sendrawtransaction announce only over Tor or I2P, on a separate connection per transaction, so the originator's IP is never known to the recipients and two unrelated transactions are not linkable through a shared connection (#29415). 31.0 shipped a bug where, under some circumstances, those connections were still made over clearnet; 31.1 (July 2026) "fixes an ip address leak when using the -privatebroadcast feature". Do not rely on it below 31.1.

debug.log

Located at ~/.bitcoin/debug.log (or ~/.bitcoin/<chain>/debug.log).

Categories, from LOG_CATEGORIES_BY_STR in src/logging.cpp at v31.1 (July 2026): net, tor, mempool, http, bench, zmq, walletdb, rpc, estimatefee, addrman, selectcoins, reindex, cmpctblock, rand, prune, proxy, mempoolrej, libevent, coindb, qt, leveldb, validation, i2p, ipc, blockstorage, txreconciliation, scan, txpackages, kernel, privatebroadcast, plus lock in DEBUG_LOCKCONTENTION builds. bitcoin-cli logging prints the live list. There is no per-RPC category: an unrecognised name is a startup error ("Unsupported logging category -debug=<name>."), not a warning, so a typo stops the node rather than silently logging nothing. libevent is a full category at v31.1; on master (September 2026) it has been removed from the map and survives only as a shim in GetLogCategory that logs "deprecated, does nothing, and will be removed in a future version" and enables nothing: accepted, but inert. Enable verbosity:

debug=mempool
debug=validation

Or all: debug=1. Performance impact moderate.

Key patterns:

• UpdateTip: — new block.
• received block — block arrival.
• txn-already-known — duplicate broadcast.
• bad-txns-inputs-missingorspent — invalid input.
• Pre-allocating up to ... — file allocation messages.

systemd unit

[Unit]
Description=Bitcoin Core
After=network-online.target

[Service]
ExecStart=/usr/local/bin/bitcoind -daemon -conf=/etc/bitcoin/bitcoin.conf
ExecStop=/usr/local/bin/bitcoin-cli stop
Type=forking
PIDFile=/var/lib/bitcoind/bitcoind.pid
User=bitcoin
Group=bitcoin
Restart=on-failure

[Install]
WantedBy=multi-user.target

Backup considerations

• wallet.dat (legacy) or wallets/<name>/wallet.dat (descriptor).
• For descriptor wallets: backup is just the descriptors + private keys (listdescriptors true).
• Stop bitcoind before file copy or use backupwallet RPC for consistent snapshot.

Common bugs

• Setting dbcache=8000 on a system with 4 GB RAM → OOM.
• Running 31.0+ in a container and inheriting the 1024 MiB dbcache default: the detected RAM can exceed the memory actually available under the cgroup limit, so the node is OOM-killed. Set -dbcache explicitly; 450 restores pre-31.0 behaviour.
• Using txindex=1 and prune=N>0 simultaneously → bitcoind exits on startup.
• Multi-wallet without explicit rpcwallet parameter → RPC fails with "Wallet file not specified".
• rpcbind=0.0.0.0 without firewall → exposes RPC to internet. Always pair with rpcallowip= or use SSH tunnel.
• Insufficient dbcache during IBD → 4x slower sync.

Security advisories and minimum safe version

Upstream maintains the latest three majors; the oldest drops out when a new major ships. As of September 2026 that is 31.x, 30.x and 29.x - 28.x reached EOL on 2026-04-19, the day 31.0 was released. Treat "oldest still-maintained major" as the version floor and run the newest maintenance release of it you can: 31.1 (July 2026) at time of writing.

28.x and every release back to 0.14.0 carry CVE-2024-52911, a high-severity use-after-free in script validation, disclosed 2026-05-05 and fixed in 29.0. Precomputed transaction data was destroyed before the object controlling the background script-check threads, so an early return from validating an invalid block could leave those threads reading freed memory; an attacker with sufficient proof-of-work could crash victim nodes with crafted invalid blocks. Found by Cory Fields (MIT DCI), who also supplied the proof of concept and the mitigation. Advisories are only published once the affected versions are EOL, so "no advisory yet" is not evidence that an old major is safe.

Tracking practice:

• bitcoincore.org/en/security-advisories/ - per-CVE disclosure pages.
• bitcoincore.org/en/lifecycle/ - the supported-major and EOL table.
• The bitcoincore.org announcements mailing list for release/security mail.
• Bitcoin Optech newsletters, which surface merged security fixes before the release that carries them.

Fixes merged to master in September 2026 and therefore not in any release yet: -walletnotify's %w substitution no longer goes through std::regex_replace, so an RPC-authenticated caller can no longer smuggle shell metacharacters through a wallet name (#36048, behaviour introduced in 24.0, not reachable from P2P); the HTTP server throttles per-connection reads while a request is in flight (#36123); and on Windows the RPC listener uses SO_EXCLUSIVEADDRUSE (#36169).

See also

• rpc/SKILL.md
• indexes/SKILL.md
• zmq/SKILL.md
• ../../infrastructure/node-distros/SKILL.md