readme: update and split into various parts
This commit is contained in:
nixbitcoin
parent
37caf814a7
commit
bcedf69549
199
README.md
199
README.md
@ -1,144 +1,103 @@
|
|||||||
nix-bitcoin
|
|
||||||
===
|
|
||||||
|
|
||||||
[](https://cirrus-ci.com/github/fort-nix/nix-bitcoin)
|
|
||||||
|
|
||||||
Nix packages and nixos modules for easily installing Bitcoin nodes and higher layer protocols with an emphasis on security.
|
|
||||||
This is a work in progress - don't expect it to be bug-free, secure or stable.
|
|
||||||
|
|
||||||
The default configuration sets up a Bitcoin Core node and c-lightning. The user can enable spark-wallet in `configuration.nix` to make c-lightning accessible with a smartphone using spark-wallet.
|
|
||||||
A simple webpage shows the lightning nodeid and links to nanopos letting the user receive donations.
|
|
||||||
It also includes elements-daemon.
|
|
||||||
Outbound peer-to-peer traffic is forced through Tor, and listening services are bound to onion addresses.
|
|
||||||
|
|
||||||
A demo installation is running at [http://6tr4dg3f2oa7slotdjp4syvnzzcry2lqqlcvqkfxdavxo6jsuxwqpxad.onion](http://6tr4dg3f2oa7slotdjp4syvnzzcry2lqqlcvqkfxdavxo6jsuxwqpxad.onion).
|
|
||||||
The following screen cast shows a fresh deployment of a nix-bitcoin node.
|
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<a href="https://asciinema.org/a/223630/?speed=2&autoplay=1"><img src="https://asciinema.org/a/223630.png" height="500"></a>
|
<img
|
||||||
|
width="320"
|
||||||
|
src="docs/img/nix-bitcoin-logo.png"
|
||||||
|
alt="nix-bitcoin logo">
|
||||||
</p>
|
</p>
|
||||||
|
<br/>
|
||||||
|
<p align="center">
|
||||||
|
<a href="https://cirrus-ci.com/github/fort-nix/nix-bitcoin" target="_blank">
|
||||||
|
<img src="https://api.cirrus-ci.com/github/fort-nix/nix-bitcoin.svg?branch=master" alt="CirrusCI status">
|
||||||
|
</a>
|
||||||
|
<a href="https://github.com/fort-nix/nix-bitcoin/releases/latest" target="_blank">
|
||||||
|
<img src="https://img.shields.io/github/v/release/fort-nix/nix-bitcoin" alt="GitHub tag (latest SemVer)">
|
||||||
|
</a>
|
||||||
|
<a href="https://github.com/fort-nix/nix-bitcoin/commits/master" target="_blank">
|
||||||
|
<img src="https://img.shields.io/github/commit-activity/y/fort-nix/nix-bitcoin" alt="GitHub commit activity">
|
||||||
|
</a>
|
||||||
|
<a href="https://github.com/fort-nix/nix-bitcoin/graphs/contributors" target="_blank">
|
||||||
|
<img src="https://img.shields.io/github/contributors-anon/fort-nix/nix-bitcoin" alt="GitHub contributors">
|
||||||
|
</a>
|
||||||
|
<a href="https://github.com/fort-nix/nix-bitcoin/releases" target="_blank">
|
||||||
|
<img src="https://img.shields.io/github/downloads/fort-nix/nix-bitcoin/total" alt="GitHub downloads">
|
||||||
|
</a>
|
||||||
|
</p>
|
||||||
|
<br/>
|
||||||
|
|
||||||
|
nix-bitcoin is a collection of Nix packages and NixOS modules for easily installing **full-featured Bitcoin nodes** with an emphasis on **security**.
|
||||||
|
|
||||||
|
Overview
|
||||||
|
---
|
||||||
|
A Bitcoin node verifies the Bitcoin protocol and provides ways of interacting with the Bitcoin network. nix-bitcoin
|
||||||
|
nodes are used for a variety of purposes and can serve as personal or merchant wallets, second layer public
|
||||||
|
infrastructure and as backends for Bitcoin applications. 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.
|
||||||
|
|
||||||
The goal is to make it easy to deploy a reasonably secure Bitcoin node with a usable wallet.
|
A full installation of nix-bitcoin is usually deployed either on a dedicated (virtual) machine or runs in a container
|
||||||
It should allow managing bitcoin (the currency) effectively and providing public infrastructure.
|
and is online 24/7. Alternatively, the Nix packages, NixOS modules and configurations can be used independently and
|
||||||
It should be a reproducible and extensible platform for applications building on Bitcoin.
|
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.
|
||||||
|
|
||||||
Examples
|
Examples
|
||||||
---
|
---
|
||||||
The easiest way to try out nix-bitcoin is to use one of the provided examples.
|
See the [examples directory](examples/README.md).
|
||||||
|
|
||||||
```bash
|
Features
|
||||||
git clone https://github.com/fort-nix/nix-bitcoin
|
|
||||||
cd nix-bitcoin/examples/
|
|
||||||
nix-shell
|
|
||||||
```
|
|
||||||
|
|
||||||
The following example scripts set up a nix-bitcoin node according to [`examples/configuration.nix`](examples/configuration.nix) and then
|
|
||||||
shut down immediately. They leave no traces (outside of `/nix/store`) on the host system.
|
|
||||||
|
|
||||||
- [`./deploy-container.sh`](examples/deploy-container.sh) creates a [NixOS container](https://github.com/erikarvstedt/extra-container).\
|
|
||||||
This is the fastest way to set up a node.\
|
|
||||||
Requires: [Nix](https://nixos.org/), a systemd-based Linux distro and root privileges
|
|
||||||
|
|
||||||
- [`./deploy-qemu-vm.sh`](examples/deploy-qemu-vm.sh) creates a QEMU VM.\
|
|
||||||
Requires: [Nix](https://nixos.org/nix/)
|
|
||||||
|
|
||||||
- [`./deploy-nixops.sh`](examples/deploy-nixops.sh) creates a VirtualBox VM via [NixOps](https://github.com/NixOS/nixops).\
|
|
||||||
NixOps can be used to deploy to various other backends like cloud providers.\
|
|
||||||
Requires: [Nix](https://nixos.org/nix/), [VirtualBox](https://www.virtualbox.org)
|
|
||||||
|
|
||||||
- [`./deploy-container-minimal.sh`](examples/deploy-container-minimal.sh) creates a
|
|
||||||
container defined by [minimal-configuration.nix](examples/minimal-configuration.nix) that
|
|
||||||
doesn't use the [secure-node.nix](modules/presets/secure-node.nix) preset.
|
|
||||||
Also shows how to use nix-bitcoin in an existing NixOS config.\
|
|
||||||
Requires: [Nix](https://nixos.org/), a systemd-based Linux distro and root privileges
|
|
||||||
|
|
||||||
Run the examples with option `--interactive` or `-i` to start a shell for interacting with
|
|
||||||
the node:
|
|
||||||
```bash
|
|
||||||
./deploy-qemu-vm.sh -i
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Tests
|
|
||||||
The internal test suite is also useful for exploring features.\
|
|
||||||
The following `run-tests.sh` commands leave no traces (outside of `/nix/store`) on
|
|
||||||
the host system.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git clone https://github.com/fort-nix/nix-bitcoin
|
|
||||||
cd nix-bitcoin/test
|
|
||||||
|
|
||||||
# Run a Python test shell inside a VM node
|
|
||||||
./run-tests.sh debug
|
|
||||||
print(succeed("systemctl status bitcoind"))
|
|
||||||
|
|
||||||
# Run a node in a container. Requires systemd and root privileges.
|
|
||||||
./run-tests.sh container
|
|
||||||
c systemctl status bitcoind
|
|
||||||
|
|
||||||
# Explore a single feature
|
|
||||||
./run-tests.sh --scenario electrs container
|
|
||||||
```
|
|
||||||
See [`run-tests.sh`](test/run-tests.sh) for a complete documentation.
|
|
||||||
|
|
||||||
Available modules
|
|
||||||
---
|
---
|
||||||
By default the `configuration.nix` provides:
|
A [configuration preset](modules/presets/secure-node.nix) for setting up a secure node
|
||||||
* bitcoind with outbound connections through Tor and inbound connections through a hidden service. By default loaded with banlist of spy nodes.
|
* All applications use Tor for outbound connections and accept inbound connections via onion services.
|
||||||
* [clightning](https://github.com/ElementsProject/lightning) with outbound connections through Tor, not listening
|
* Includes a [nodeinfo](modules/nodeinfo.nix) script which prints basic info about the node.
|
||||||
* includes "nodeinfo" script which prints basic info about the node
|
|
||||||
* adds non-root user "operator" which has access to bitcoin-cli and lightning-cli
|
|
||||||
|
|
||||||
In `configuration.nix` the user can enable:
|
NixOS modules
|
||||||
* a clightning hidden service with [plugins](https://github.com/lightningd/plugins)
|
* Application services
|
||||||
* [liquid](https://github.com/elementsproject/elements)
|
* [bitcoind](https://github.com/bitcoin/bitcoin), with a default banlist against spy nodes
|
||||||
* [lightning charge](https://github.com/ElementsProject/lightning-charge)
|
* [clightning](https://github.com/ElementsProject/lightning) with support for announcing an onion service\
|
||||||
* [nanopos](https://github.com/ElementsProject/nanopos)
|
Available plugins:
|
||||||
* an index page using nginx to display node information and link to nanopos
|
* [clboss](https://github.com/ZmnSCPxj/clboss): automated C-Lightning Node Manager
|
||||||
* [spark-wallet](https://github.com/shesek/spark-wallet)
|
* [helpme](https://github.com/lightningd/plugins/tree/master/helpme): walks you through setting up a fresh c-lightning node
|
||||||
* [electrs](https://github.com/romanz/electrs)
|
* [monitor](https://github.com/renepickhardt/plugins/tree/master/monitor): helps you analyze the health of your peers and channels
|
||||||
* recurring-donations, a module to repeatedly send lightning payments to recipients specified in the configuration.
|
* [prometheus](https://github.com/lightningd/plugins/tree/master/prometheus): lightning node exporter for the prometheus timeseries server
|
||||||
* [bitcoin-core-hwi](https://github.com/bitcoin-core/HWI).
|
* [rebalance](https://github.com/lightningd/plugins/tree/master/rebalance): keeps your channels balanced
|
||||||
* You no longer need extra software to connect your hardware wallet to Bitcoin Core. Use Bitcoin Core's own **H**ardware **W**allet **I**nterface with one `configuration.nix` setting.
|
* [summary](https://github.com/lightningd/plugins/tree/master/summary): print a nice summary of the node status
|
||||||
|
* [zmq](https://github.com/lightningd/plugins/tree/master/zmq): publishes notifications via ZeroMQ to configured endpoints
|
||||||
The data directories of the services can be found in `/var/lib` on the deployed machines.
|
* [lnd](https://github.com/lightningnetwork/lnd) with support for announcing an onion service
|
||||||
|
* [spark-wallet](https://github.com/shesek/spark-wallet)
|
||||||
Installation
|
* [electrs](https://github.com/romanz/electrs)
|
||||||
---
|
* [btcpayserver](https://github.com/btcpayserver/btcpayserver)
|
||||||
See [install.md](docs/install.md) for a detailed tutorial.
|
* [liquid](https://github.com/elementsproject/elements)
|
||||||
|
* [lightning charge](https://github.com/ElementsProject/lightning-charge) (deprecated)
|
||||||
|
* [nanopos](https://github.com/ElementsProject/nanopos) (deprecated)
|
||||||
|
* [Lightning Loop](https://github.com/lightninglabs/loop)
|
||||||
|
* [JoinMarket](https://github.com/joinmarket-org/joinmarket-clientserver)
|
||||||
|
* [recurring-donations](modules/recurring-donations.nix): for periodic lightning payments
|
||||||
|
* [bitcoin-core-hwi](https://github.com/bitcoin-core/HWI)
|
||||||
|
* Helper
|
||||||
|
* [netns-isolation](modules/netns-isolation.nix): isolates applications on the network-level via network namespaces
|
||||||
|
* [backups](modules/backups.nix): daily duplicity backups of all your node's important files
|
||||||
|
* [operator](modules/operator.nix): adds non-root user `operator` who has access to client tools (e.g. `bitcoin-cli`, `lightning-cli`)
|
||||||
|
* [nix-bitcoin webindex](modules/nix-bitcoin-webindex.nix): a local website to display node information
|
||||||
|
|
||||||
Security
|
Security
|
||||||
---
|
---
|
||||||
* **Simplicity:** Only services you select in `configuration.nix` and their dependencies are installed, packages and dependencies are [pinned](pkgs/nixpkgs-pinned.nix), most packages are built from the [nixos stable channel](https://github.com/NixOS/nixpkgs-channels/tree/nixos-19.03), with a few exceptions that are built from the nixpkgs unstable channel, builds happen in a [sandboxed environment](https://nixos.org/nix/manual/), code is continuously reviewed and refined.
|
* **Simplicity:** Only services you select in `configuration.nix` and their dependencies are installed, packages and dependencies are [pinned](pkgs/nixpkgs-pinned.nix), most packages are built from the [NixOS stable channel](https://github.com/NixOS/nixpkgs/tree/nixos-20.09), with a few exceptions that are built from the nixpkgs unstable channel, builds happen in a [sandboxed environment](https://nixos.org/manual/nix/stable/#conf-sandbox), code is continuously reviewed and refined.
|
||||||
* **Integrity:** Nix package manager, NixOS and 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.
|
* **Integrity:** Nix package manager, NixOS and 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 options](modules/nix-bitcoin-services.nix), there's a non-root user *operator* to interact with the various services.
|
* **Principle of Least Privilege:** Services operate with least privileges; they each have their own user and are restricted further with [systemd options](modules/nix-bitcoin-services.nix), [RPC whitelisting](modules/bitcoind-rpc-public-whitelist.nix), and [netns-isolation](modules/netns-isolation.nix). There's a non-root user *operator* to interact with the various services.
|
||||||
* **Defense-in-depth:** nix-bitcoin is built with a [hardened kernel](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/profiles/hardened.nix) by default, services are confined through discretionary access control, Linux namespaces, and seccomp-bpf with continuous improvements.
|
* **Defense-in-depth:** nix-bitcoin is built with a [hardened kernel](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/profiles/hardened.nix) by default, services are confined through discretionary access control, Linux namespaces, [dbus firewall](modules/security.nix) and seccomp-bpf with continuous improvements.
|
||||||
|
|
||||||
Note that nix-bitcoin is still experimental.
|
Note that if the machine you're deploying *from* is insecure, there is nothing nix-bitcoin can do to protect itself.
|
||||||
Also, by design if the machine you're deploying *from* is insecure, there is nothing nix-bitcoin can do to protect itself.
|
|
||||||
|
|
||||||
Hardware requirements
|
Docs
|
||||||
---
|
---
|
||||||
* Disk space: 300 GB (235GB for Bitcoin blockchain + some room)
|
* [FAQ](docs/faq.md)
|
||||||
* Bitcoin Core pruning is not supported at the moment because it's not supported by c-lightning. It's possible to use pruning but you need to know what you're doing.
|
* [Hardware Requirements](docs/hardware.md)
|
||||||
* RAM: 2GB of memory. ECC memory is better. Additionally, it's recommended to use DDR4 memory with targeted row refresh (TRR) enabled (https://rambleed.com/).
|
* [Install instructions](docs/install.md)
|
||||||
|
* [Usage instructions](docs/usage.md)
|
||||||
Tested hardware includes [pcengine's apu2c4](https://pcengines.ch/apu2c4.htm), [GB-BACE-3150](https://www.gigabyte.com/Mini-PcBarebone/GB-BACE-3150-rev-10), [GB-BACE-3160](https://www.gigabyte.com/de/Mini-PcBarebone/GB-BACE-3160-rev-10#ov).
|
|
||||||
Some hardware (including Intel NUCs) may not be compatible with the hardened kernel turned on by default (see https://github.com/fort-nix/nix-bitcoin/issues/39#issuecomment-517366093 for a workaround).
|
|
||||||
|
|
||||||
Usage
|
|
||||||
---
|
|
||||||
For usage instructions, such as how to connect to spark-wallet, electrs and the ssh Tor Hidden Service, see [usage.md](docs/usage.md).
|
|
||||||
|
|
||||||
Troubleshooting
|
Troubleshooting
|
||||||
---
|
---
|
||||||
If you are having problems with nix-bitcoin check the [FAQ](docs/faq.md) or submit an issue.
|
If you are having problems with nix-bitcoin check the [FAQ](docs/faq.md) or submit an issue.
|
||||||
There's also a `#nix-bitcoin` IRC channel on freenode.
|
There's also a `#nix-bitcoin` IRC channel on freenode.
|
||||||
We are always happy to help.
|
We are always happy to help.
|
||||||
|
|
||||||
Docs
|
|
||||||
---
|
|
||||||
* [FAQ](docs/faq.md)
|
|
||||||
* [Install instructions](docs/install.md)
|
|
||||||
* [Usage instructions](docs/usage.md)
|
|
||||||
|
|||||||
8
docs/hardware.md
Normal file
8
docs/hardware.md
Normal file
@ -0,0 +1,8 @@
|
|||||||
|
Hardware requirements
|
||||||
|
---
|
||||||
|
* Disk space: 500 GB (400GB for Bitcoin blockchain + some room)
|
||||||
|
* Bitcoin Core pruning is not supported at the moment because it's not supported by c-lightning. It's possible to use pruning but you need to know what you're doing.
|
||||||
|
* RAM: 2GB of memory. ECC memory is better. Additionally, it's recommended to use DDR4 memory with targeted row refresh (TRR) enabled (https://rambleed.com/).
|
||||||
|
|
||||||
|
Tested hardware includes [pcengine's apu2c4](https://pcengines.ch/apu2c4.htm), [GB-BACE-3150](https://www.gigabyte.com/Mini-PcBarebone/GB-BACE-3150-rev-10), [GB-BACE-3160](https://www.gigabyte.com/de/Mini-PcBarebone/GB-BACE-3160-rev-10#ov).
|
||||||
|
Some hardware (including Intel NUCs) may not be compatible with the hardened kernel turned on by default (see https://github.com/fort-nix/nix-bitcoin/issues/39#issuecomment-517366093 for a workaround).
|
||||||
BIN
docs/img/nix-bitcoin-logo.png
Normal file
BIN
docs/img/nix-bitcoin-logo.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 44 KiB |
59
examples/README.md
Normal file
59
examples/README.md
Normal file
@ -0,0 +1,59 @@
|
|||||||
|
Examples
|
||||||
|
---
|
||||||
|
|
||||||
|
The easiest way to try out nix-bitcoin is to use one of the provided examples.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/fort-nix/nix-bitcoin
|
||||||
|
cd nix-bitcoin/examples/
|
||||||
|
nix-shell
|
||||||
|
```
|
||||||
|
|
||||||
|
The following example scripts set up a nix-bitcoin node according to [`configuration.nix`](configuration.nix) and then
|
||||||
|
shut down immediately. They leave no traces (outside of `/nix/store`) on the host system.\
|
||||||
|
By default, [`configuration.nix`](configuration.nix) enables `bitcoind` and `clightning` (with an onion service).
|
||||||
|
|
||||||
|
- [`./deploy-container.sh`](deploy-container.sh) creates a [NixOS container](https://github.com/erikarvstedt/extra-container).\
|
||||||
|
This is the fastest way to set up a node.\
|
||||||
|
Requires: [Nix](https://nixos.org/), a systemd-based Linux distro and root privileges
|
||||||
|
|
||||||
|
- [`./deploy-qemu-vm.sh`](deploy-qemu-vm.sh) creates a QEMU VM.\
|
||||||
|
Requires: [Nix](https://nixos.org/nix/)
|
||||||
|
|
||||||
|
- [`./deploy-nixops.sh`](deploy-nixops.sh) creates a VirtualBox VM via [NixOps](https://github.com/NixOS/nixops).\
|
||||||
|
NixOps can be used to deploy to various other backends like cloud providers.\
|
||||||
|
Requires: [Nix](https://nixos.org/nix/), [VirtualBox](https://www.virtualbox.org)
|
||||||
|
|
||||||
|
- [`./deploy-container-minimal.sh`](deploy-container-minimal.sh) creates a
|
||||||
|
container defined by [minimal-configuration.nix](minimal-configuration.nix) that
|
||||||
|
doesn't use the [secure-node.nix](../modules/presets/secure-node.nix) preset.
|
||||||
|
Also shows how to use nix-bitcoin in an existing NixOS config.\
|
||||||
|
Requires: [Nix](https://nixos.org/), a systemd-based Linux distro and root privileges
|
||||||
|
|
||||||
|
Run the examples with option `--interactive` or `-i` to start a shell for interacting with
|
||||||
|
the node:
|
||||||
|
```bash
|
||||||
|
./deploy-qemu-vm.sh -i
|
||||||
|
```
|
||||||
|
|
||||||
|
### Tests
|
||||||
|
The internal test suite is also useful for exploring features.\
|
||||||
|
The following `run-tests.sh` commands leave no traces (outside of `/nix/store`) on
|
||||||
|
the host system.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/fort-nix/nix-bitcoin
|
||||||
|
cd nix-bitcoin/test
|
||||||
|
|
||||||
|
# Run a Python test shell inside a VM node
|
||||||
|
./run-tests.sh debug
|
||||||
|
print(succeed("systemctl status bitcoind"))
|
||||||
|
|
||||||
|
# Run a node in a container. Requires systemd and root privileges.
|
||||||
|
./run-tests.sh container
|
||||||
|
c systemctl status bitcoind
|
||||||
|
|
||||||
|
# Explore a single feature
|
||||||
|
./run-tests.sh --scenario electrs container
|
||||||
|
```
|
||||||
|
See [`run-tests.sh`](../test/run-tests.sh) for a complete documentation.
|
||||||
@ -1,7 +1,7 @@
|
|||||||
#!/usr/bin/env bash
|
#!/usr/bin/env bash
|
||||||
|
|
||||||
# Modules integration test runner.
|
# Modules integration test runner.
|
||||||
# The tests (./tests.nix) use the NixOS testing framework and are executed in a VM.
|
# The tests (defined in ./tests.nix) use the NixOS testing framework and are executed in a VM.
|
||||||
#
|
#
|
||||||
# Usage:
|
# Usage:
|
||||||
# Run all tests
|
# Run all tests
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user