greg/nix-bitcoin
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge #289: readme: update and split into various parts

Browse Source 
bcedf69549 readme: update and split into various parts (nixbitcoin)

Pull request description:

ACKs for top commit:
  erikarvstedt:
    ACK bcedf69549

Tree-SHA512: a2c3c08c4b147225621d61ac67fd11b2ebec55bda1976a731d307a9935db23499a0f4a4d6d2c7dc27940027d8e0db42c1b02ff25554c49f81d5102c8599c2439
This commit is contained in:
Jonas Nick 2020-12-30 19:02:50 +00:00
commit 656c6a1d67
No known key found for this signature in database
GPG Key ID: 4861DBF262123605
5 changed files with 147 additions and 121 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

199
README.md
View File

@ -1,144 +1,103 @@
nix-bitcoin
===
[![Build Status](https://api.cirrus-ci.com/github/fort-nix/nix-bitcoin.svg?branch=master)](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
View 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
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB

59
examples/README.md Normal file
View 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.

2
test/run-tests.sh
View File

@ -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