475af2d6cb
addfa8ec6bab320de0b808fd76809635947377e8 test: support `run`, `debug` commands in basic NixOS tests (Erik Arvstedt)
ae733d887eae83ec589af53aa11638d711135a18 tests/clightning-replication: reuse `pkgs` instance (Erik Arvstedt)
6cbd0d93ae80176a853c31ca8cf5891bd6fb0646 tests: rename `clightningReplication` -> `clightning-replication` (Erik Arvstedt)
85310b533a00f1f5dfbc535a91356bab3692d4c6 secrets: use type `lines` for `generateSecretsCmds` (Erik Arvstedt)
bc2f66d4f122dbd37679159002275f87ed87deb4 bitcoind, liquid: increase start/stop timeouts (Erik Arvstedt)
519ae31202a7e878fe7fe3be83f321df741acf43 netns-isolation: improve formatting (Erik Arvstedt)
a1023696e69fbe871cfadf18d054d87eede9bba0 netns-isolation: reserve netns id for mempool (Erik Arvstedt)
34fe8675bd6e0396e3986e0d4b262e166708d8b0 add option `nix-bitcoin.pkgOverlays` (Erik Arvstedt)
a3bdecb10bd6d27d040d10ac9255d99b86d630df helper: add start-bash-session.sh (Erik Arvstedt)
690a8f6256bfed9b9ed074d89e734364b87681f1 nodeinfo: extract fn `mkInfoLong` (Erik Arvstedt)
2af642f56ad0856d5a07d0bb27722b3861719b75 improve comments (Erik Arvstedt)
5634f0887391419b10a3e8c43c6377214b79b115 rtl: make `extraConfig` recursively mergeable (Erik Arvstedt)
b76728a1ec187700fd303933510f0b5a82a2996a treewide: use bool literals for systemd (Erik Arvstedt)
Pull request description:
ACKs for top commit:
jonasnick:
ACK addfa8ec6bab320de0b808fd76809635947377e8
Tree-SHA512: 46f779f8477b566ffc6d0dfb024f2098757f509b2b3e0cbb509cf3308de7029e913f6e6c3d6d3d226cc72f8a5031fd5586b2efdf7c2d9d15f4bdd7ed08b27425
nix-bitcoin is a collection of Nix packages and NixOS modules for easily installing full-featured Bitcoin nodes with an emphasis on security.
Overview
nix-bitcoin can be used for personal or merchant wallets, public infrastructure or for Bitcoin application backends. In all cases, the aim is to provide security and privacy by default. However, while nix-bitcoin is used in production today, it is still considered experimental.
nix-bitcoin nodes can be deployed on dedicated hardware, virtual machines or containers. The Nix packages and NixOS modules can be used independently and combined freely.
nix-bitcoin is built on top of Nix and NixOS which provide powerful abstractions to keep it highly customizable and maintainable. Testament to this are nix-bitcoin's robust security features and its potent test framework. However, running nix-bitcoin does not require any previous experience with the Nix ecosystem.
Get started
- See the examples for an overview of all features.
- To setup a new node from scratch, see the installation instructions.
- To add nix-bitcoin to an existing NixOS configuration, see importable-configuration.nix and the Flake example.
Docs
Hint: To show a table of contents, click the button (
) in the
top left corner of the documents.
- NixOS options search
- Hardware requirements
- Installation
- Configuration and maintenance
- Using services
- FAQ
Features
A configuration preset for setting up a secure node
- All applications use Tor for outbound connections and support accepting inbound connections via onion services.
NixOS modules (src)
- Application services
- bitcoind
- clightning with support for announcing an onion service
and database replication.
Available plugins:- clboss: automated C-Lightning Node Manager
- currencyrate: currency converter
- helpme: walks you through setting up a fresh c-lightning node
- monitor: helps you analyze the health of your peers and channels
- prometheus: lightning node exporter for the prometheus timeseries server
- rebalance: keeps your channels balanced
- summary: print a nice summary of the node status
- zmq: publishes notifications via ZeroMQ to configured endpoints
- clightning-rest: REST server for clightning
- lnd with support for announcing an onion service and static channel backups
- Lightning Loop
- Lightning Pool
- charge-lnd: policy-based channel fee manager
- lndconnect: connect your wallet to lnd or clightning via a REST onion service
- Ride The Lightning: web interface for
lndandclightning - spark-wallet
- electrs
- fulcrum (see the module for a comparison to electrs)
- btcpayserver
- liquid
- JoinMarket
- bitcoin-core-hwi
- Helper
- netns-isolation: isolates applications on the network-level via network namespaces
- nodeinfo: script which prints info about the node's services
- backups: duplicity backups of all your node's important files
- operator: adds non-root user
operatorwho has access to client tools (e.g.bitcoin-cli,lightning-cli)
Security
See SECURITY.md for the security policy and how to report a vulnerability.
nix-bitcoin aims to achieve a high degree of security by building on the following principles:
- Simplicity: Only services enabled in
configuration.nixand their dependencies are installed, support for doas (sudo alternative), code is continuously reviewed and refined. - Integrity: The Nix package manager guarantees that all dependencies are exactly specified, packages can be built from source to reduce reliance on binary caches, nix-bitcoin merge commits are signed, all commits are approved by multiple nix-bitcoin developers, upstream packages are cryptographically verified where possible, we use this software ourselves.
- Principle of Least Privilege: Services operate with least privileges; they each have their own user and are restricted further with systemd features, RPC whitelisting and netns-isolation. There's a non-root user operator to interact with the various services.
- Defense-in-depth: nix-bitcoin supports a hardened kernel, services are confined through discretionary access control, Linux namespaces, dbus firewall and seccomp-bpf with continuous improvements.
Note that if the machine you're deploying from is insecure, there is nothing nix-bitcoin can do to protect itself.
Security fund
The nix-bitcoin security fund is a 2 of 3 bitcoin multisig address open for donations, used to reward
security researchers who discover vulnerabilities in nix-bitcoin or its upstream dependencies.
See Security Fund for details.
Developing
See dev/README.
Troubleshooting
If you are having problems with nix-bitcoin check the FAQ or submit an issue.
There's also a Matrix room at #general:nixbitcoin.org
and a #nix-bitcoin IRC channel on libera.
We are always happy to help.