9.1 KiB
sys-bitcoin
Bitcoin Core in Qubes OS.
Table of Contents
Description
Setup a Bitcoin Daemon full-node qube named "sys-bitcoin", where you will index the Bitcoin blockchain. A second non-networked qube named "bitcoin" can manage a wallet and sign transactions.
By default, installation from upstream binaries will be used, but you can choose to build from source if you prefer. Compiling from source will not have the default configuration flags, but will be optimized to our use case.
The download of the Bitcoin source code or binaries as well as the connections to the Bitcoin P2P network will happen over the Tor network.
If you already have a node on your network that has indexed the blockchain already and has RPC enabled for remote clients, you can also connect to it, preferably if it has transport encryption when connecting to the Bitcoin node with an encrypted tunnel.
A disposable qube "disp-bitcoin-builder" will be created, based on Whonix-Workstation, it will server to install and verify Bitcoin Core. After the verification succeeds, files are copied to the template "tpl-sys-bitcoin". This method was chosen so the client can be always offline and the build artifacts are built on a machine that is not running the daemon and thus can be copied to the template with a higher degree of trust.
At least 1TB of disk space is required. At block 829054 (2024-02-05),
642G are used.
Installation
- Top
qubesctl top.enable sys-bitcoin
qubesctl --targets=sys-bitcoin-gateway,tpl-sys-bitcoin,disp-sys-bitcoin-builder,sys-bitcoin,bitcoin state.apply
qubesctl top.disable sys-bitcoin
qubesctl state.apply sys-bitcoin.appmenus
- State
qubesctl state.apply sys-bitcoin.create
qubesctl --skip-dom0 --targets=sys-bitcoin-gateway state.apply sys-bitcoin.configure-gateway
qubesctl --skip-dom0 --targets=tpl-sys-bitcoin state.apply sys-bitcoin.install
qubesctl --skip-dom0 --targets=disp-bitcoin-builder state.apply sys-bitcoin.configure-builder
qubesctl --skip-dom0 --targets=sys-bitcoin state.apply sys-bitcoin.configure
qubesctl --skip-dom0 --targets=bitcoin state.apply sys-bitcoin.configure-client
qubesctl state.apply sys-bitcoin.appmenus
If you prefer to build from source (will take approximately 1 hour to build):
qubesctl --skip-dom0 --targets=tpl-sys-bitcoin state.apply sys-bitcoin.install-source
qubesctl --skip-dom0 --targets=disp-bitcoin-builder state.apply sys-bitcoin.configure-builder-source
If you want to relay blocks (listening node):
qubesctl --skip-dom0 --targets=sys-bitcoin-gateway state.apply sys-bitcoin.configure-gateway-listen
qubesctl --skip-dom0 --targets=sys-bitcoin state.apply sys-bitcoin.configure-listen
Add the tag bitcoin-client to the client and install in the client template:
qubesctl --skip-dom0 --targets=tpl-QUBE state.apply sys-bitcoin.install-client
Usage
The qube sys-bitcoin can:
- Index the Bitcoin blockchain connecting to peers over Tor;
- Connect to a remote Bitcoin RPC reachable over Tor; and
- Broadcast transactions over Tor.
The qube bitcoin can:
- Create wallet addresses; and
- Sign transactions.
Custom daemon parameters
You can set extra parameters for the daemon in
~/.bitcoin/conf.d/bitcoin.conf.local, this file will never be changed
externally.
One of these parameters is prune, which reduces storage requirements by
deleting old blocks. The downside is that it can't serve old blocks, can't be
used to rescan old wallet and is incompatible to serve any Electrum Server.
You can enable pruning in /home/user/.bitcoin/conf.d/bitcoin.conf.local by
specifying how many MiB of block files to retain:
prune=550
A configuration you may want to do after IBD (Initial Block Download) is to
reduce the used memory, as it is not necessary anymore to have a large cache.
As the bitcoind option dbcache is dynamic allocated per the qube memory,
you just need to reduce the memory available to the sys-bitcoin qube. From
dom0, run:
qvm-prefs sys-bitcoin memory 1000
Bitcoin Core GUI
Do not use the GUI in the sys-bitcoin qube to edit configuration, it won't
persist and bitcoin-qt cannot be run at the same time as bitcoind.
You can use the GUI in the bitcoin qube, specially useful for an easy-to-use
interface for the Bitcoin Core Wallet.
Connect to a remote Bitcoin RPC
Evaluation of remote Bitcoin RPC
You may wish to connect to a remote Bitcoin node with RPC available to:
- Lower disk space usage and to lower resource consumption by not having multiple Bitcoin blockchains;
- Avoid changing scripts and configurations that expect the connection to be
working on
127.0.0.1:8332, such as the Qrexec policy for connecting Bitcoind RPC to the Electrum Servers.
But there are huge disadvantages to this method:
- Bitcoin Core RPC does not have transport encryption.
Therefore, this method is advised against unless you know how to enable
transport encryption to connect to your Bitcoin RPC. If you run bitcoind on
sys-bitcoin, you do not have to worry about transport encryption as communication is done securely via Qrexec. - Bitcoin configuration cannot be changed remotely, therefore adding RPC Authentication for clients such as Electrum Servers have to be done manually.
The remote bitcoind setup is difficult to fit all user needs and requires you to change a remote node we have no control over the configuration, therefore, it is intended for advanced users only.
Configure the remote node
On the remote node:
- You must set in the node's
bitcoin.conf, the following options to bind to the external interface:rpcbind,bind(Electrs),whitelist=download@<ADDR>(ElectRS),zmqpubhashblock(Fulcrum) and allow connections of the external IP of your upstream netvm viarpcallowip. - Open the configured ports of the previous settings in the firewall to be reachable by the Qubes system.
- Generate RPC credentials (see
bitcoin/share/rpcauth/rpcauth.py), addrpcauth=option tobitcoin.confand save theuserandpasswordfor later. - Restart bitcoind to apply the configuration changes.
Connect the qube to the remote node
Warning: use of sys-bitcoin for the remote node connection is
discouraged as you either need to expose the node RPC port to an onion service
(preferably with Onion Authentication) or punch a hole in the Whonix firewall
so it can reach your LAN.
The following example uses the qube sys-net as a netvm that can connect
to your remote node running on the address 192.168.2.10, RPC port 8332,
P2P port 8333, ZMQPUBHASHBLOCK port 8433.
In dom0, create the user Qrexec policy to target the qube sys-net in
/etc/qubes/policy.d/30-user.policy:
## Getting Auth doesn't work with remote node.
qusal.BitcoinAuthGet * @anyvm @anyvm deny
qubes.ConnectTCP +8332 @tag:bitcoin-client @default allow target=sys-net
qubes.ConnectTCP +8333 @tag:bitcoin-client @default allow target=sys-net
qubes.ConnectTCP +8433 @tag:bitcoin-client @default allow target=sys-net
qubes.ConnectTCP * @tag:bitcoin-client @anyvm deny
In the qube sys-net, add the socat command (only the ones you need) to the
file /rw/config/rc.local:
## RPC
socat TCP-LISTEN:8332,reuseaddr,fork,bind=127.0.0.1 TCP:192.168.2.10:8332 &
## P2P (ElectRS)
socat TCP-LISTEN:8333,reuseaddr,fork,bind=127.0.0.1 TCP:192.168.2.10:8333 &
## ZMQPubHashBlock (Fulcrum)
socat TCP-LISTEN:8433,reuseaddr,fork,bind=127.0.0.1 TCP:192.168.2.10:8433 &
In the Electrum Server qubes or any Bitcoin Client, sys-electrumx,
sys-electrs, sys-fulcrum, add the qvm-connect-tcp command to the file
/rw/config/rc.local:
## RPC
qvm-connnect-tcp ::8332
## P2P (ElectRS)
qvm-connnect-tcp ::8333
## ZMQPubHashBlock (Fulcrum)
qvm-connnect-tcp ::8433
Still in the Electrum Server qube, you will have to add the RPC authentication
you got from the remote node to ~/.bitcoin/.cookie.
Restart the qubes you modified the configuration to check if the service is starting automatically on boot.
Database on external drive
Your machine might not have enough disk space to store the database and you don't want to configure a remote client. Unfortunately, this method is unsupported. It may be possible, but as mounting the drive requires user intervention, you are on your own to adjust the database path.
If you have done this, please share a guide.