nix-bitcoin/README.md

145 lines
7.9 KiB
Markdown
Raw Normal View History

2018-12-06 19:01:01 +03:00
nix-bitcoin
===
[![Build Status](https://travis-ci.org/fort-nix/nix-bitcoin.svg?branch=master)](https://travis-ci.org/fort-nix/nix-bitcoin)
2019-04-28 16:11:53 +03:00
Nix packages and nixos modules for easily installing Bitcoin nodes and higher layer protocols with an emphasis on security.
2020-03-22 00:40:15 +03:00
This is a work in progress - don't expect it to be bug-free, secure or stable.
2019-01-26 21:42:04 +03:00
2019-04-10 13:49:59 +03:00
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.
2019-08-01 18:05:07 +03:00
It also includes elements-daemon.
2019-04-10 13:49:59 +03:00
Outbound peer-to-peer traffic is forced through Tor, and listening services are bound to onion addresses.
2019-01-26 21:42:04 +03:00
2019-01-27 01:11:16 +03:00
A demo installation is running at [http://6tr4dg3f2oa7slotdjp4syvnzzcry2lqqlcvqkfxdavxo6jsuxwqpxad.onion](http://6tr4dg3f2oa7slotdjp4syvnzzcry2lqqlcvqkfxdavxo6jsuxwqpxad.onion).
2019-04-10 13:49:59 +03:00
The following screen cast shows a fresh deployment of a nix-bitcoin node.
2019-01-27 01:16:26 +03:00
2019-01-27 01:19:17 +03:00
<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>
</p>
2019-01-27 01:16:26 +03:00
2018-12-06 19:01:01 +03:00
2019-04-10 13:49:59 +03:00
The goal is to make it easy to deploy a reasonably secure Bitcoin node with a usable wallet.
2019-01-26 21:42:04 +03:00
It should allow managing bitcoin (the currency) effectively and providing public infrastructure.
2019-04-10 13:49:59 +03:00
It should be a reproducible and extensible platform for applications building on Bitcoin.
2019-01-26 21:42:04 +03:00
2020-09-27 13:43:32 +03:00
Examples
2020-03-22 00:40:15 +03:00
---
2020-03-29 19:21:04 +03:00
The easiest way to try out nix-bitcoin is to use one of the provided examples.
2020-03-22 00:40:15 +03:00
2020-09-27 13:43:32 +03:00
```bash
2020-03-22 00:40:15 +03:00
git clone https://github.com/fort-nix/nix-bitcoin
cd nix-bitcoin/examples/
2020-03-22 00:40:15 +03:00
nix-shell
```
The following example scripts set up a nix-bitcoin node according to [`examples/configuration.nix`](examples/configuration.nix) and then
2020-03-29 19:21:04 +03:00
shut down immediately. They leave no traces (outside of `/nix/store`) on the host system.
2020-04-15 19:54:03 +03:00
- [`./deploy-container.sh`](examples/deploy-container.sh) creates a [NixOS container](https://github.com/erikarvstedt/extra-container).\
2020-03-29 19:21:04 +03:00
This is the fastest way to set up a node.\
Requires: [Nix](https://nixos.org/), a systemd-based Linux distro and root privileges
2020-03-29 19:21:04 +03:00
2020-04-15 19:54:03 +03:00
- [`./deploy-qemu-vm.sh`](examples/deploy-qemu-vm.sh) creates a QEMU VM.\
2020-03-29 19:21:04 +03:00
Requires: [Nix](https://nixos.org/nix/)
2020-04-15 19:54:03 +03:00
- [`./deploy-nixops.sh`](examples/deploy-nixops.sh) creates a VirtualBox VM via [NixOps](https://github.com/NixOS/nixops).\
2020-03-29 19:21:04 +03:00
NixOps can be used to deploy to various other backends like cloud providers.\
Requires: [Nix](https://nixos.org/nix/), [VirtualBox](https://www.virtualbox.org)
2020-03-22 00:40:15 +03:00
- [`./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
2020-10-18 14:41:55 +03:00
Run the examples with option `--interactive` or `-i` to start a shell for interacting with
the node:
```bash
./deploy-qemu-vm.sh -i
```
2020-09-27 13:43:32 +03:00
#### Tests
The internal test suite is also useful for exploring features.\
2020-09-27 13:43:32 +03:00
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.
2019-04-10 13:49:59 +03:00
Available modules
2018-12-06 19:01:01 +03:00
---
2019-04-10 13:49:59 +03:00
By default the `configuration.nix` provides:
* bitcoind with outbound connections through Tor and inbound connections through a hidden service. By default loaded with banlist of spy nodes.
2019-04-10 13:49:59 +03:00
* [clightning](https://github.com/ElementsProject/lightning) with outbound connections through Tor, not listening
* 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:
2020-11-19 05:01:45 +03:00
* a clightning hidden service with [plugins](https://github.com/lightningd/plugins)
2019-08-01 18:05:07 +03:00
* [liquid](https://github.com/elementsproject/elements)
2019-04-10 13:49:59 +03:00
* [lightning charge](https://github.com/ElementsProject/lightning-charge)
* [nanopos](https://github.com/ElementsProject/nanopos)
* an index page using nginx to display node information and link to nanopos
* [spark-wallet](https://github.com/shesek/spark-wallet)
* [electrs](https://github.com/romanz/electrs)
2019-04-14 19:55:40 +03:00
* recurring-donations, a module to repeatedly send lightning payments to recipients specified in the configuration.
* [bitcoin-core-hwi](https://github.com/bitcoin-core/HWI).
* 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.
2018-12-06 19:01:01 +03:00
2019-01-26 21:42:04 +03:00
The data directories of the services can be found in `/var/lib` on the deployed machines.
2018-12-06 19:01:01 +03:00
2019-04-10 13:49:59 +03:00
Installation
2018-12-06 19:01:01 +03:00
---
2019-04-10 13:49:59 +03:00
See [install.md](docs/install.md) for a detailed tutorial.
2019-04-28 16:11:53 +03:00
Security
---
2020-08-04 16:32:06 +03:00
* **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.
* **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.
* **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.
2019-04-28 16:11:53 +03:00
Note that nix-bitcoin is still experimental.
Also, by design if the machine you're deploying *from* is insecure, there is nothing nix-bitcoin can do to protect itself.
2019-04-10 13:49:59 +03:00
Hardware requirements
---
2019-04-10 13:49:59 +03:00
* Disk space: 300 GB (235GB 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/).
2019-01-26 20:53:58 +03:00
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).
2019-01-02 17:56:57 +03:00
2019-04-10 13:49:59 +03:00
Usage
2019-01-02 17:56:57 +03:00
---
2019-04-10 13:49:59 +03:00
For usage instructions, such as how to connect to spark-wallet, electrs and the ssh Tor Hidden Service, see [usage.md](docs/usage.md).
2019-04-10 13:49:59 +03:00
Troubleshooting
2019-01-02 17:56:57 +03:00
---
2019-07-15 16:39:57 +03:00
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.
We are always happy to help.
2019-01-02 17:56:57 +03:00
2019-04-10 13:49:59 +03:00
Docs
2019-02-24 17:52:02 +03:00
---
2019-04-10 13:49:59 +03:00
* [FAQ](docs/faq.md)
* [Install instructions](docs/install.md)
* [Usage instructions](docs/usage.md)