Merge branch 'nixbitcoin-documentation'
This commit is contained in:
Jonas Nick
commit
4d3f1560e2
476
README.md
476
README.md
@ -1,16 +1,16 @@
|
||||
nix-bitcoin
|
||||
===
|
||||
|
||||
Nix packages and nixos modules with profiles for easily installing Bitcoin nodes and higher layer protocols.
|
||||
Nix packages and nixos modules for easily installing Bitcoin nodes and higher layer protocols.
|
||||
This is a work in progress - don't expect it to be bug free or secure.
|
||||
|
||||
The 'full' profile right now sets up a Bitcoin Core node and c-lightning, accessable with a smartphone using spark-wallet.
|
||||
A simple webpage shows the lightning nodeid and links to nanopos allowing to receive donations.
|
||||
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 liquid-daemon.
|
||||
Outbound peer-to-peer traffic is forced through Tor and listening services are bound to onion addresses.
|
||||
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 how a fresh deployment of the full profile.
|
||||
The following screen cast shows a fresh deployment of a nix-bitcoin node.
|
||||
|
||||
<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>
|
||||
@ -18,456 +18,54 @@ The following screen cast shows how a fresh deployment of the full profile.
|
||||
|
||||
|
||||
|
||||
The goal is too make it easy to deploy a reasonably secure Bitcoin node with a usable wallet.
|
||||
The goal is to make it easy to deploy a reasonably secure Bitcoin node with a usable wallet.
|
||||
It should allow managing bitcoin (the currency) effectively and providing public infrastructure.
|
||||
It should be a reproducible and extensible platform applications building on Bitcoin.
|
||||
It should be a reproducible and extensible platform for applications building on Bitcoin.
|
||||
|
||||
Profiles
|
||||
Available modules
|
||||
---
|
||||
The `nix-bitcoin.nix` module provides the two profiles "minimal" and "all":
|
||||
|
||||
* minimal
|
||||
* bitcoind (pruned) with outbound connections through Tor and inbound connections through a hidden
|
||||
By default the `configuration.nix` provides:
|
||||
* bitcoind (pruned) with outbound connections through Tor and inbound connections through a hidden
|
||||
service. By default loaded with banlist of spy nodes.
|
||||
* [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
|
||||
* all
|
||||
* adds clightning hidden service
|
||||
* [liquid-daemon](https://github.com/blockstream/liquid)
|
||||
* [lightning charge](https://github.com/ElementsProject/lightning-charge)
|
||||
* [nanopos](https://github.com/ElementsProject/nanopos)
|
||||
* adds an index page using nginx to display node information and link to nanopos
|
||||
* [spark-wallet](https://github.com/shesek/spark-wallet)
|
||||
* Notes: run `journalctl -eu spark-wallet` to get the onion address, access key and QR access code for the spark wallet android app.
|
||||
* other
|
||||
* [electrs](https://github.com/romanz/electrs) can be enabled by setting `services.electrs.enable` in modules `nix-bitcoin.nix` to `true`
|
||||
* [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:
|
||||
* a clightning hidden service
|
||||
* [liquid-daemon](https://github.com/blockstream/liquid)
|
||||
* [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)
|
||||
|
||||
The data directories of the services can be found in `/var/lib` on the deployed machines.
|
||||
|
||||
Installing profiles
|
||||
Installation
|
||||
---
|
||||
The easiest way is to run `nix-shell` (on a Linux machine) in the nix-bitcoin directory and then create a [NixOps](https://nixos.org/nixops/manual/) deployment with the provided network.nix.
|
||||
Fix the FIXMEs in configuration.nix and deploy with nixops in nix-shell.
|
||||
See below for a detailed tutorial.
|
||||
See [install.md](docs/install.md) for a detailed tutorial.
|
||||
|
||||
The profiles require 300 GB (235GB for Bitcoin blockchain + some room) of disk space and 2GB of memory.
|
||||
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.
|
||||
|
||||
Tutorial: install a nix-bitcoin node
|
||||
Hardware requirements
|
||||
---
|
||||
Get a machine to deploy nix-bitcoin on.
|
||||
This could be a VirtualBox, a machine that is already running [NixOs](https://nixos.org/nixos/manual/index.html) or a cloud provider.
|
||||
Have a look at the options in the [NixOps manual](https://nixos.org/nixops/manual/).
|
||||
There's a tutorial for installing and configuring VirtualBox in the [appendix](#appendix).
|
||||
* 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
|
||||
|
||||
The following steps are meant to be run on the machine you deploy from, not the machine you deploy to.
|
||||
Tested hardware includes [pcengine's apu2c4](https://pcengines.ch/apu2c4.htm)
|
||||
|
||||
Install Dependencies (Debian 9 stretch)
|
||||
```
|
||||
sudo apt-get install curl git gnupg2 dirmngr
|
||||
```
|
||||
Install Latest Nix with GPG Verification
|
||||
```
|
||||
curl -o install-nix-2.2.1 https://nixos.org/nix/install
|
||||
curl -o install-nix-2.2.1.sig https://nixos.org/nix/install.sig
|
||||
gpg2 --recv-keys B541D55301270E0BCF15CA5D8170B4726D7198DE
|
||||
gpg2 --verify ./install-nix-2.2.1.sig
|
||||
sh ./install-nix-2.2.1
|
||||
. /home/user/.nix-profile/etc/profile.d/nix.sh
|
||||
```
|
||||
|
||||
Sandboxing is enabled by default on Nix <2.2. This may cause problems on your system. If you get an error similar to
|
||||
```
|
||||
error: cloning builder process: Operation not permitted
|
||||
error: unable to start build process
|
||||
/tmp/nix-binary-tarball-unpack.hqawN4uSPr/unpack/nix-2.2.1-x86_64-linux/install: unable to install Nix into your default profile
|
||||
```
|
||||
try installing as root or building as user (see https://nixos.org/nix/manual/#conf-sandbox for more information).
|
||||
|
||||
Clone this project
|
||||
```
|
||||
cd
|
||||
git clone https://github.com/jonasnick/nix-bitcoin
|
||||
cd ~/nix-bitcoin
|
||||
```
|
||||
Setup environment
|
||||
```
|
||||
nix-shell
|
||||
```
|
||||
Create nixops deployment in nix-shell.
|
||||
When deploying in a VirtualBox you can use the provided `network-vbox.nix` file (ensure that you've created a host adaptor as explained in the appendix).
|
||||
```
|
||||
nixops create network.nix network-vbox.nix -d bitcoin-node
|
||||
```
|
||||
Otherwise replace it with a network file as explained in the [NixOps manual](https://nixos.org/nixops/manual/).
|
||||
|
||||
Adjust configuration by opening configuration.nix and removing FIXMEs.
|
||||
|
||||
Deploy Nixops in nix-shell
|
||||
```
|
||||
nixops deploy -d bitcoin-node
|
||||
```
|
||||
This will now create a nix-bitcoin node on the target machine.
|
||||
|
||||
Nixops automatically creates an ssh key for use with `nixops ssh`. Access `bitcoin-node` through ssh in nix-shell with
|
||||
```
|
||||
nixops ssh operator@bitcoin-node
|
||||
```
|
||||
|
||||
Run `nodeinfo` to see your onion addresses for the webindex, spark, etc. if they are included in the profile.
|
||||
|
||||
If you change anything in the configuration you can run
|
||||
```
|
||||
nixops deploy -d bitcoin-node
|
||||
```
|
||||
in the nix-shell again to redeploy the configuration to the node.
|
||||
|
||||
Updating
|
||||
Usage
|
||||
---
|
||||
Run `git pull` in the nix-bitcoin directory, enter the nix shell with `nix-shell` and redeploy with `nixops deploy -d bitcoin-node`.
|
||||
For usage instructions, such as how to connect to spark-wallet, electrs and the ssh Tor Hidden Service, see [usage.md](docs/usage.md).
|
||||
|
||||
FAQ
|
||||
Troubleshooting
|
||||
---
|
||||
* **Q:** When deploying or trying to SSH into the machine I see
|
||||
```
|
||||
bitcoin-node> waiting for SSH...
|
||||
Received disconnect from 10.1.1.200 port 22:2: Too many authentication failures
|
||||
```
|
||||
* **A:** Somehow ssh-agent and nixops don't play well together. Try killing the ssh-agent.
|
||||
* **Q:** When deploying or trying to SSH into the machine I see
|
||||
```
|
||||
root@xxx.xxx.xxx.xxx: Permission denied (publickey,password,keyboard-interactive).
|
||||
```
|
||||
Make sure you don't have something like
|
||||
```
|
||||
Host *
|
||||
PubkeyAuthentication no
|
||||
```
|
||||
in your ssh config.
|
||||
* **Q:** When deploying to virtualbox for the first time I see
|
||||
```
|
||||
bitcoin-node> Mar 19 09:22:27 bitcoin-node systemd[1]: Started Get NixOps SSH Key.
|
||||
bitcoin-node> Mar 19 09:22:27 bitcoin-node get-vbox-nixops-client-key-start[2226]: VBoxControl: error: Failed to connect to the guest property service, error VERR_INTERNAL_ERROR
|
||||
bitcoin-node> Mar 19 09:22:27 bitcoin-node systemd[1]: get-vbox-nixops-client-key.service: Main process exited, code=exited, status=1/FAILURE
|
||||
bitcoin-node> Mar 19 09:22:27 bitcoin-node systemd[1]: get-vbox-nixops-client-key.service: Failed with result 'exit-code'.
|
||||
bitcoin-node> error: Traceback (most recent call last):
|
||||
File "/nix/store/6zyvpi0q6mvprycadz2dpdqag4742y18-python2.7-nixops-1.6pre0_abcdef/lib/python2.7/site-packages/nixops/deployment.py", line 731, in worker
|
||||
raise Exception("unable to activate new configuration")
|
||||
Exception: unable to activate new configuration
|
||||
```
|
||||
* **A:** This is issue https://github.com/NixOS/nixops/issues/908. The machine needs to be rebooted. You can do that by running `nixops deploy` with the `--force-reboot` flag once.
|
||||
* **Q:** I'm deploying to virtualbox it's not able to connect anymore.
|
||||
* **A:** Maybe the IP address of the box changed. Run `nixops deploy --check` to update nixops with the new IP address. Sometimes you also need to remove the old IP address from `~/.ssh/known_hosts`.
|
||||
* **Q:** The clightning service is running but when I try to use it (f.e. by running `lightning-cli getinfo` as user operator) all I get is `lightning-cli: Connecting to 'lightning-rpc': Connection refused`.
|
||||
* **A:** Check your clightning logs with `journalctl -eu clightning`. Do you see something like `bitcoin-cli getblock ... false` failed? Are you using pruned mode? That means that clightning hasn't seen all the blocks it needs to and it can't get that block because your node is pruned. If you're just setting up a new node you can `systemctl stop clightning` and wipe your `/var/lib/clightning` directory. Otherwise you need to reindex the Bitcoin node.
|
||||
* **Q:** My disk space is getting low due to nix.
|
||||
* **A:** run `nix-collect-garbage -d`
|
||||
* **Q:** How do I connect to my nix-bitcoin node through the ssh Tor Hidden Service?
|
||||
* **A:**
|
||||
If you are having problems with nix-bitcoin check the [FAQ](docs/faq.md) or submit an issue. We are always happy to help.
|
||||
|
||||
1. Run `nodeinfo` on your nix-bitcoin node and note the `SSHD_ONION`
|
||||
|
||||
```
|
||||
nixops ssh operator@bitcoin-node
|
||||
nodeinfo | grep 'SSHD_ONION'
|
||||
```
|
||||
|
||||
2. Create a SSH key
|
||||
|
||||
```
|
||||
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519
|
||||
```
|
||||
|
||||
3. Place the ed25519 key's fingerprint in the `configuration.nix` `openssh.authorizedKeys.keys` field like so
|
||||
|
||||
```
|
||||
# FIXME: Add your SSH pubkey
|
||||
services.openssh.enable = true;
|
||||
users.users.root = {
|
||||
openssh.authorizedKeys.keys = [ "[contents of ~/.ssh/id_ed25519.pub]" ];
|
||||
};
|
||||
```
|
||||
|
||||
4. Connect to your nix-bitcoin node's ssh Tor Hidden Service, forwarding a local port to the nix-bitcoin node's ssh server
|
||||
|
||||
```
|
||||
ssh -i ~/.ssh/id_ed25519 -L [random port of your choosing]:localhost:22 root@[your SSHD_ONION]
|
||||
```
|
||||
|
||||
5. Edit your `network-nixos.nix` to look like this
|
||||
|
||||
```
|
||||
{
|
||||
bitcoin-node =
|
||||
{ config, pkgs, ... }:
|
||||
{ deployment.targetHost = "127.0.0.1";
|
||||
deployment.targetPort = [random port of your choosing];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
6. Now you can run `nixops deploy -d bitcoin-node` and it will connect through the ssh tunnel you established in step iv. This also allows you to do more complex ssh setups that `nixops ssh` doesn't support. An example would be authenticating with [Trezor's ssh agent](https://github.com/romanz/trezor-agent), which provides extra security.
|
||||
|
||||
# Appendix
|
||||
Tutorial: install and configure VirtualBox for nix-bitcoin on Debian 9 Stretch
|
||||
Docs
|
||||
---
|
||||
Add virtualbox.list to /etc/apt/sources.list.d
|
||||
```
|
||||
deb http://download.virtualbox.org/virtualbox/debian stretch contrib
|
||||
```
|
||||
Add Oracle VirtualBox public key
|
||||
```
|
||||
wget https://www.virtualbox.org/download/oracle_vbox_2016.asc
|
||||
gpg2 oracle_vbox_2016.asc
|
||||
```
|
||||
Proceed _only_ if fingerprint reads B9F8 D658 297A F3EF C18D 5CDF A2F6 83C5 2980 AECF
|
||||
|
||||
```
|
||||
sudo apt-key add oracle_vbox_2016.asc
|
||||
```
|
||||
Install virtualbox-5.2
|
||||
```
|
||||
sudo apt-get update
|
||||
sudo apt-get install virtualbox-5.2
|
||||
```
|
||||
|
||||
**IMPORTANT:** Create Host Adapter in VirtualBox
|
||||
```
|
||||
Open VirtualBox
|
||||
File -> Host Network Manager -> Create
|
||||
This should create a hostadapter named vboxnet0
|
||||
```
|
||||
Tutorial: install and configure NixOS for nix-bitcoin on your own hardware
|
||||
---
|
||||
## 1. NixOS installation
|
||||
|
||||
This is borrowed from the [NixOS manual](https://nixos.org/nixos/manual/index.html#ch-installation). Look there for more information.
|
||||
|
||||
1. Obtain latest NixOS. For example:
|
||||
|
||||
```
|
||||
wget https://releases.nixos.org/nixos/18.09/nixos-18.09.2257.235487585ed/nixos-graphical-18.09.2257.235487585ed-x86_64-linux.iso
|
||||
```
|
||||
|
||||
2. Write NixOS iso to install media (USB/CD). For example:
|
||||
|
||||
```
|
||||
dd if=nixos-graphical-18.09.2257.235487585ed-x86_64-linux.iso of=/dev/sdX
|
||||
```
|
||||
Replace /dev/sdX with the correct device name. You can find this using `sudo fdisk -l`
|
||||
|
||||
3. Boot the system
|
||||
|
||||
You will have to find out if your hardware uses UEFI or Legacy Boot for the next step.
|
||||
|
||||
4. Option 1: Partition and format for UEFI
|
||||
|
||||
```
|
||||
parted /dev/sda -- mklabel gpt
|
||||
parted /dev/sda -- mkpart primary 512MiB -8GiB
|
||||
parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
|
||||
parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB
|
||||
parted /dev/sda -- set 3 boot on
|
||||
mkfs.ext4 -L nixos /dev/sda1
|
||||
mkswap -L swap /dev/sda2
|
||||
mkfs.fat -F 32 -n boot /dev/sda3
|
||||
mount /dev/disk/by-label/nixos /mnt
|
||||
mkdir -p /mnt/boot
|
||||
mount /dev/disk/by-label/boot /mnt/boot
|
||||
swapon /dev/sda2
|
||||
```
|
||||
|
||||
4. Option 2: Partition and format for Legacy Boot (MBR)
|
||||
|
||||
```
|
||||
parted /dev/sda -- mklabel msdos
|
||||
parted /dev/sda -- mkpart primary 1MiB -8GiB
|
||||
parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
|
||||
mkfs.ext4 -L nixos /dev/sda1
|
||||
mkswap -L swap /dev/sda2
|
||||
mount /dev/disk/by-label/nixos /mnt
|
||||
swapon /dev/sda2
|
||||
```
|
||||
|
||||
5. Generate NixOS config
|
||||
|
||||
```
|
||||
nixos-generate-config --root /mnt
|
||||
nano /mnt/etc/nixos/configuration.nix
|
||||
```
|
||||
|
||||
Option 1: Edit NixOS configuration for UEFI
|
||||
|
||||
```
|
||||
{ config, pkgs, ... }: {
|
||||
imports = [
|
||||
# Include the results of the hardware scan.
|
||||
./hardware-configuration.nix
|
||||
];
|
||||
|
||||
boot.loader.systemd-boot.enable = true;
|
||||
|
||||
# Note: setting fileSystems is generally not
|
||||
# necessary, since nixos-generate-config figures them out
|
||||
# automatically in hardware-configuration.nix.
|
||||
#fileSystems."/".device = "/dev/disk/by-label/nixos";
|
||||
|
||||
# Enable the OpenSSH server.
|
||||
services.openssh = {
|
||||
enable = true;
|
||||
permitRootLogin = "yes";
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Option 2: Edit NixOS configuration for Legacy Boot (MBR)
|
||||
|
||||
```
|
||||
{ config, pkgs, ... }: {
|
||||
imports = [
|
||||
# Include the results of the hardware scan.
|
||||
./hardware-configuration.nix
|
||||
];
|
||||
|
||||
boot.loader.grub.device = "/dev/sda";
|
||||
|
||||
# Note: setting fileSystems is generally not
|
||||
# necessary, since nixos-generate-config figures them out
|
||||
# automatically in hardware-configuration.nix.
|
||||
#fileSystems."/".device = "/dev/disk/by-label/nixos";
|
||||
|
||||
# Enable the OpenSSH server.
|
||||
services.openssh = {
|
||||
enable = true;
|
||||
permitRootLogin = "yes";
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
6. Do the installation
|
||||
|
||||
```
|
||||
nixos-install
|
||||
```
|
||||
Set root password
|
||||
```
|
||||
setting root password...
|
||||
Enter new UNIX password:
|
||||
Retype new UNIX password:
|
||||
```
|
||||
|
||||
7. If everything went well
|
||||
|
||||
```
|
||||
reboot
|
||||
```
|
||||
|
||||
## 2. nix-bitcoin installation
|
||||
|
||||
On the machine you are deploying from:
|
||||
|
||||
1. Install Dependencies (Debian 9 stretch)
|
||||
|
||||
```
|
||||
sudo apt-get install curl git gnupg2 dirmngr
|
||||
```
|
||||
|
||||
2. Install Latest Nix with GPG Verification
|
||||
|
||||
```
|
||||
curl -o install-nix-2.2.1 https://nixos.org/nix/install
|
||||
curl -o install-nix-2.2.1.sig https://nixos.org/nix/install.sig
|
||||
gpg2 --recv-keys B541D55301270E0BCF15CA5D8170B4726D7198DE
|
||||
gpg2 --verify ./install-nix-2.2.1.sig
|
||||
sh ./install-nix-2.2.1
|
||||
. /home/user/.nix-profile/etc/profile.d/nix.sh
|
||||
```
|
||||
|
||||
Sandboxing is enabled by default on Nix <2.2. This may cause problems on your system. If you get an error similar to
|
||||
|
||||
```
|
||||
error: cloning builder process: Operation not permitted
|
||||
error: unable to start build process
|
||||
/tmp/nix-binary-tarball-unpack.hqawN4uSPr/unpack/nix-2.2.1-x86_64-linux/install: unable to install Nix into your default profile
|
||||
```
|
||||
|
||||
try installing as root or building as user (see https://nixos.org/nix/manual/#conf-sandbox for more information).
|
||||
|
||||
3. Clone this project
|
||||
|
||||
```
|
||||
cd
|
||||
git clone https://github.com/jonasnick/nix-bitcoin
|
||||
cd ~/nix-bitcoin
|
||||
```
|
||||
|
||||
4. Create network file
|
||||
|
||||
```
|
||||
nano network-nixos.nix
|
||||
```
|
||||
|
||||
```
|
||||
{
|
||||
bitcoin-node =
|
||||
{ config, pkgs, ... }:
|
||||
{ deployment.targetHost = 1.2.3.4;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Replace 1.2.3.4 with NixOS machine's IP address.
|
||||
|
||||
5. Edit `configuration.nix`
|
||||
|
||||
```
|
||||
nano configuration.nix
|
||||
```
|
||||
|
||||
Uncomment `./hardware-configuration.nix` line by removing #.
|
||||
|
||||
6. Create `hardware-configuration.nix`
|
||||
|
||||
```
|
||||
nano hardware-configuration.nix
|
||||
```
|
||||
Copy contents of NixOS machine's `hardware-configuration.nix` to file.
|
||||
|
||||
7. Add boot option to `hardware-configuration.nix`
|
||||
|
||||
Option 1: Enable systemd boot for UEFI
|
||||
```
|
||||
boot.loader.grub.device = "/dev/sda";
|
||||
```
|
||||
Option 2: Set grub device for Legacy Boot (MBR)
|
||||
```
|
||||
boot.loader.grub.device = "/dev/sda":
|
||||
```
|
||||
|
||||
8. Setup environment
|
||||
```
|
||||
nix-shell
|
||||
```
|
||||
|
||||
9. Create nixops deployment in nix-shell.
|
||||
```
|
||||
nixops create network.nix network-nixos.nix -d bitcoin-node
|
||||
```
|
||||
|
||||
10. Adjust configuration by opening configuration.nix and removing FIXMEs.
|
||||
|
||||
11. Deploy Nixops in nix-shell
|
||||
|
||||
```
|
||||
nixops deploy -d bitcoin-node
|
||||
```
|
||||
This will now create a nix-bitcoin node on the target machine.
|
||||
|
||||
12. Nixops automatically creates an ssh key for use with `nixops ssh`. Access `bitcoin-node` through ssh in nix-shell with
|
||||
|
||||
```
|
||||
nixops ssh operator@bitcoin-node
|
||||
```
|
||||
|
||||
* [FAQ](docs/faq.md)
|
||||
* [Install instructions](docs/install.md)
|
||||
* [Usage instructions](docs/usage.md)
|
||||
|
||||
34
docs/faq.md
Normal file
34
docs/faq.md
Normal file
@ -0,0 +1,34 @@
|
||||
* **Q:** When deploying or trying to SSH into the machine I see
|
||||
```
|
||||
bitcoin-node> waiting for SSH...
|
||||
Received disconnect from 10.1.1.200 port 22:2: Too many authentication failures
|
||||
```
|
||||
* **A:** Somehow ssh-agent and nixops don't play well together. Try killing the ssh-agent.
|
||||
* **Q:** When deploying or trying to SSH into the machine I see
|
||||
```
|
||||
root@xxx.xxx.xxx.xxx: Permission denied (publickey,password,keyboard-interactive).
|
||||
```
|
||||
Make sure you don't have something like
|
||||
```
|
||||
Host *
|
||||
PubkeyAuthentication no
|
||||
```
|
||||
in your ssh config.
|
||||
* **Q:** When deploying to virtualbox for the first time I see
|
||||
```
|
||||
bitcoin-node> Mar 19 09:22:27 bitcoin-node systemd[1]: Started Get NixOps SSH Key.
|
||||
bitcoin-node> Mar 19 09:22:27 bitcoin-node get-vbox-nixops-client-key-start[2226]: VBoxControl: error: Failed to connect to the guest property service, error VERR_INTERNAL_ERROR
|
||||
bitcoin-node> Mar 19 09:22:27 bitcoin-node systemd[1]: get-vbox-nixops-client-key.service: Main process exited, code=exited, status=1/FAILURE
|
||||
bitcoin-node> Mar 19 09:22:27 bitcoin-node systemd[1]: get-vbox-nixops-client-key.service: Failed with result 'exit-code'.
|
||||
bitcoin-node> error: Traceback (most recent call last):
|
||||
File "/nix/store/6zyvpi0q6mvprycadz2dpdqag4742y18-python2.7-nixops-1.6pre0_abcdef/lib/python2.7/site-packages/nixops/deployment.py", line 731, in worker
|
||||
raise Exception("unable to activate new configuration")
|
||||
Exception: unable to activate new configuration
|
||||
```
|
||||
* **A:** This is issue https://github.com/NixOS/nixops/issues/908. The machine needs to be rebooted. You can do that by running `nixops deploy` with the `--force-reboot` flag once.
|
||||
* **Q:** I'm deploying to virtualbox it's not able to connect anymore.
|
||||
* **A:** Maybe the IP address of the box changed. Run `nixops deploy --check` to update nixops with the new IP address. Sometimes you also need to remove the old IP address from `~/.ssh/known_hosts`.
|
||||
* **Q:** The clightning service is running but when I try to use it (f.e. by running `lightning-cli getinfo` as user operator) all I get is `lightning-cli: Connecting to 'lightning-rpc': Connection refused`.
|
||||
* **A:** Check your clightning logs with `journalctl -eu clightning`. Do you see something like `bitcoin-cli getblock ... false` failed? Are you using pruned mode? That means that clightning hasn't seen all the blocks it needs to and it can't get that block because your node is pruned. If you're just setting up a new node you can `systemctl stop clightning` and wipe your `/var/lib/clightning` directory. Otherwise you need to reindex the Bitcoin node.
|
||||
* **Q:** My disk space is getting low due to nix.
|
||||
* **A:** run `nix-collect-garbage -d`
|
||||
348
docs/install.md
Normal file
348
docs/install.md
Normal file
@ -0,0 +1,348 @@
|
||||
Preliminary steps
|
||||
---
|
||||
Get a machine to deploy nix-bitcoin on.
|
||||
This could be a VirtualBox, a machine that is already running [NixOS](https://nixos.org/nixos/manual/index.html) or a cloud provider.
|
||||
Have a look at the options in the [NixOps manual](https://nixos.org/nixops/manual/).
|
||||
|
||||
# Tutorials
|
||||
1. [Install and configure NixOS for nix-bitcoin on VirtualBox](#tutorial-install-and-configure-nixos-for-nix-bitcoin-on-virtualbox)
|
||||
2. [Install and configure NixOS for nix-bitcoin on your own hardware](#tutorial-install-and-configure-nixos-for-nix-bitcoin-on-your-own-hardware)
|
||||
|
||||
Tutorial: install and configure NixOS for nix-bitcoin on VirtualBox
|
||||
---
|
||||
## 1. VirtualBox installation
|
||||
The following steps are meant to be run on the machine you deploy from, not the machine you deploy to.
|
||||
|
||||
1. Add virtualbox.list to /etc/apt/sources.list.d (Debian 9 stretch)
|
||||
|
||||
```
|
||||
echo "deb http://download.virtualbox.org/virtualbox/debian stretch contrib" | sudo tee /etc/apt/sources.list.d/virtualbox.list
|
||||
```
|
||||
|
||||
2. Add Oracle VirtualBox public key
|
||||
|
||||
```
|
||||
wget https://www.virtualbox.org/download/oracle_vbox_2016.asc
|
||||
gpg2 oracle_vbox_2016.asc
|
||||
```
|
||||
Proceed _only_ if fingerprint reads B9F8 D658 297A F3EF C18D 5CDF A2F6 83C5 2980 AECF
|
||||
|
||||
```
|
||||
sudo apt-key add oracle_vbox_2016.asc
|
||||
```
|
||||
|
||||
3. Install virtualbox-5.2
|
||||
|
||||
```
|
||||
sudo apt-get update
|
||||
sudo apt-get install virtualbox-5.2
|
||||
```
|
||||
|
||||
3. Create Host Adapter in VirtualBox
|
||||
|
||||
```
|
||||
Open VirtualBox
|
||||
File -> Host Network Manager -> Create
|
||||
```
|
||||
This should create a host adapter named vboxnet0
|
||||
|
||||
## 2. Nix installation
|
||||
The following steps are meant to be run on the machine you deploy from, not the machine you deploy to.
|
||||
|
||||
1. Install Dependencies (Debian 9 stretch)
|
||||
|
||||
```
|
||||
sudo apt-get install curl git gnupg2 dirmngr
|
||||
```
|
||||
|
||||
2. Install Latest Nix with GPG Verification
|
||||
|
||||
```
|
||||
curl -o install-nix-2.2.1 https://nixos.org/nix/install
|
||||
curl -o install-nix-2.2.1.sig https://nixos.org/nix/install.sig
|
||||
gpg2 --recv-keys B541D55301270E0BCF15CA5D8170B4726D7198DE
|
||||
gpg2 --verify ./install-nix-2.2.1.sig
|
||||
sh ./install-nix-2.2.1
|
||||
. /home/user/.nix-profile/etc/profile.d/nix.sh
|
||||
```
|
||||
|
||||
Sandboxing is enabled by default on Nix <2.2. This may cause problems on your system. If you get an error similar to
|
||||
```
|
||||
error: cloning builder process: Operation not permitted
|
||||
error: unable to start build process
|
||||
/tmp/nix-binary-tarball-unpack.hqawN4uSPr/unpack/nix-2.2.1-x86_64-linux/install: unable to install Nix into your default profile
|
||||
```
|
||||
try installing as root or building as user (see https://nixos.org/nix/manual/#conf-sandbox for more information).
|
||||
|
||||
## 3. Nixops deployment
|
||||
|
||||
1. Clone this project
|
||||
|
||||
```
|
||||
cd
|
||||
git clone https://github.com/jonasnick/nix-bitcoin
|
||||
cd ~/nix-bitcoin
|
||||
```
|
||||
|
||||
2. Setup environment
|
||||
|
||||
```
|
||||
nix-shell
|
||||
```
|
||||
3. Create nixops deployment in nix-shell.
|
||||
|
||||
```
|
||||
nixops create network.nix network-vbox.nix -d bitcoin-node
|
||||
```
|
||||
|
||||
4. Adjust configuration by opening `configuration.nix` and removing FIXMEs. Enable/disable the modules you want in `configuration.nix`.
|
||||
|
||||
5. Deploy Nixops in nix-shell
|
||||
|
||||
```
|
||||
nixops deploy -d bitcoin-node
|
||||
```
|
||||
|
||||
This will now create a nix-bitcoin node on the target machine.
|
||||
|
||||
6. Nixops automatically creates an ssh key for use with `nixops ssh`. Access `bitcoin-node` through ssh in nix-shell with
|
||||
|
||||
```
|
||||
nixops ssh operator@bitcoin-node
|
||||
```
|
||||
|
||||
See [usage.md](usage.md) for usage instructions, such as how to update.
|
||||
|
||||
Tutorial: install and configure NixOS for nix-bitcoin on your own hardware
|
||||
---
|
||||
## 1. NixOS installation
|
||||
|
||||
This is borrowed from the [NixOS manual](https://nixos.org/nixos/manual/index.html#ch-installation). Look there for more information.
|
||||
|
||||
1. Obtain latest NixOS. For example:
|
||||
|
||||
```
|
||||
wget https://releases.nixos.org/nixos/18.09/nixos-18.09.2257.235487585ed/nixos-graphical-18.09.2257.235487585ed-x86_64-linux.iso
|
||||
```
|
||||
|
||||
2. Write NixOS iso to install media (USB/CD). For example:
|
||||
|
||||
```
|
||||
dd if=nixos-graphical-18.09.2257.235487585ed-x86_64-linux.iso of=/dev/sdX
|
||||
```
|
||||
Replace /dev/sdX with the correct device name. You can find this using `sudo fdisk -l`
|
||||
|
||||
3. Boot the system
|
||||
|
||||
You will have to find out if your hardware uses UEFI or Legacy Boot for the next step.
|
||||
|
||||
4. Option 1: Partition and format for UEFI
|
||||
|
||||
```
|
||||
parted /dev/sda -- mklabel gpt
|
||||
parted /dev/sda -- mkpart primary 512MiB -8GiB
|
||||
parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
|
||||
parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB
|
||||
parted /dev/sda -- set 3 boot on
|
||||
mkfs.ext4 -L nixos /dev/sda1
|
||||
mkswap -L swap /dev/sda2
|
||||
mkfs.fat -F 32 -n boot /dev/sda3
|
||||
mount /dev/disk/by-label/nixos /mnt
|
||||
mkdir -p /mnt/boot
|
||||
mount /dev/disk/by-label/boot /mnt/boot
|
||||
swapon /dev/sda2
|
||||
```
|
||||
|
||||
4. Option 2: Partition and format for Legacy Boot (MBR)
|
||||
|
||||
```
|
||||
parted /dev/sda -- mklabel msdos
|
||||
parted /dev/sda -- mkpart primary 1MiB -8GiB
|
||||
parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
|
||||
mkfs.ext4 -L nixos /dev/sda1
|
||||
mkswap -L swap /dev/sda2
|
||||
mount /dev/disk/by-label/nixos /mnt
|
||||
swapon /dev/sda2
|
||||
```
|
||||
|
||||
5. Generate NixOS config
|
||||
|
||||
```
|
||||
nixos-generate-config --root /mnt
|
||||
nano /mnt/etc/nixos/configuration.nix
|
||||
```
|
||||
|
||||
Option 1: Edit NixOS configuration for UEFI
|
||||
|
||||
```
|
||||
{ config, pkgs, ... }: {
|
||||
imports = [
|
||||
# Include the results of the hardware scan.
|
||||
./hardware-configuration.nix
|
||||
];
|
||||
|
||||
boot.loader.systemd-boot.enable = true;
|
||||
|
||||
# Note: setting fileSystems is generally not
|
||||
# necessary, since nixos-generate-config figures them out
|
||||
# automatically in hardware-configuration.nix.
|
||||
#fileSystems."/".device = "/dev/disk/by-label/nixos";
|
||||
|
||||
# Enable the OpenSSH server.
|
||||
services.openssh = {
|
||||
enable = true;
|
||||
permitRootLogin = "yes";
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Option 2: Edit NixOS configuration for Legacy Boot (MBR)
|
||||
|
||||
```
|
||||
{ config, pkgs, ... }: {
|
||||
imports = [
|
||||
# Include the results of the hardware scan.
|
||||
./hardware-configuration.nix
|
||||
];
|
||||
|
||||
boot.loader.grub.device = "/dev/sda";
|
||||
|
||||
# Note: setting fileSystems is generally not
|
||||
# necessary, since nixos-generate-config figures them out
|
||||
# automatically in hardware-configuration.nix.
|
||||
#fileSystems."/".device = "/dev/disk/by-label/nixos";
|
||||
|
||||
# Enable the OpenSSH server.
|
||||
services.openssh = {
|
||||
enable = true;
|
||||
permitRootLogin = "yes";
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
6. Do the installation
|
||||
|
||||
```
|
||||
nixos-install
|
||||
```
|
||||
Set root password
|
||||
```
|
||||
setting root password...
|
||||
Enter new UNIX password:
|
||||
Retype new UNIX password:
|
||||
```
|
||||
|
||||
7. If everything went well
|
||||
|
||||
```
|
||||
reboot
|
||||
```
|
||||
|
||||
## 2. nix-bitcoin installation
|
||||
|
||||
On the machine you are deploying from:
|
||||
|
||||
1. Install Dependencies (Debian 9 stretch)
|
||||
|
||||
```
|
||||
sudo apt-get install curl git gnupg2 dirmngr
|
||||
```
|
||||
|
||||
2. Install Latest Nix with GPG Verification
|
||||
|
||||
```
|
||||
curl -o install-nix-2.2.1 https://nixos.org/nix/install
|
||||
curl -o install-nix-2.2.1.sig https://nixos.org/nix/install.sig
|
||||
gpg2 --recv-keys B541D55301270E0BCF15CA5D8170B4726D7198DE
|
||||
gpg2 --verify ./install-nix-2.2.1.sig
|
||||
sh ./install-nix-2.2.1
|
||||
. /home/user/.nix-profile/etc/profile.d/nix.sh
|
||||
```
|
||||
|
||||
Sandboxing is enabled by default on Nix <2.2. This may cause problems on your system. If you get an error similar to
|
||||
|
||||
```
|
||||
error: cloning builder process: Operation not permitted
|
||||
error: unable to start build process
|
||||
/tmp/nix-binary-tarball-unpack.hqawN4uSPr/unpack/nix-2.2.1-x86_64-linux/install: unable to install Nix into your default profile
|
||||
```
|
||||
|
||||
try installing as root or building as user (see https://nixos.org/nix/manual/#conf-sandbox for more information).
|
||||
|
||||
3. Clone this project
|
||||
|
||||
```
|
||||
cd
|
||||
git clone https://github.com/jonasnick/nix-bitcoin
|
||||
cd ~/nix-bitcoin
|
||||
```
|
||||
|
||||
4. Create network file
|
||||
|
||||
```
|
||||
nano network-nixos.nix
|
||||
```
|
||||
|
||||
```
|
||||
{
|
||||
bitcoin-node =
|
||||
{ config, pkgs, ... }:
|
||||
{ deployment.targetHost = 1.2.3.4;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Replace 1.2.3.4 with NixOS machine's IP address.
|
||||
|
||||
5. Edit `configuration.nix`
|
||||
|
||||
```
|
||||
nano configuration.nix
|
||||
```
|
||||
|
||||
Uncomment `./hardware-configuration.nix` line by removing #.
|
||||
|
||||
6. Create `hardware-configuration.nix`
|
||||
|
||||
```
|
||||
nano hardware-configuration.nix
|
||||
```
|
||||
Copy contents of NixOS machine's `hardware-configuration.nix` to file.
|
||||
|
||||
7. Add boot option to `hardware-configuration.nix`
|
||||
|
||||
Option 1: Enable systemd boot for UEFI
|
||||
```
|
||||
boot.loader.grub.device = "/dev/sda";
|
||||
```
|
||||
Option 2: Set grub device for Legacy Boot (MBR)
|
||||
```
|
||||
boot.loader.grub.device = "/dev/sda":
|
||||
```
|
||||
|
||||
8. Setup environment
|
||||
```
|
||||
nix-shell
|
||||
```
|
||||
|
||||
9. Create nixops deployment in nix-shell.
|
||||
```
|
||||
nixops create network.nix network-nixos.nix -d bitcoin-node
|
||||
```
|
||||
|
||||
10. Adjust configuration by opening `configuration.nix` and removing FIXMEs. Enable/disable the modules you want in `configuration.nix`.
|
||||
|
||||
11. Deploy Nixops in nix-shell
|
||||
|
||||
```
|
||||
nixops deploy -d bitcoin-node
|
||||
```
|
||||
This will now create a nix-bitcoin node on the target machine.
|
||||
|
||||
12. Nixops automatically creates an ssh key for use with `nixops ssh`. Access `bitcoin-node` through ssh in nix-shell with
|
||||
|
||||
```
|
||||
nixops ssh operator@bitcoin-node
|
||||
```
|
||||
|
||||
See [usage.md](usage.md) for usage instructions, such as how to update.
|
||||
140
docs/usage.md
Normal file
140
docs/usage.md
Normal file
@ -0,0 +1,140 @@
|
||||
Updating
|
||||
---
|
||||
Run `git pull` in the nix-bitcoin directory, enter the nix shell with `nix-shell` and redeploy with `nixops deploy -d bitcoin-node`.
|
||||
|
||||
## Verifying GPG Signatures (recommended)
|
||||
1. Import jonasnick's gpg key
|
||||
|
||||
```
|
||||
gpg2 --receive-key 36C71A37C9D988BDE82508D9B1A70E4F8DCD0366
|
||||
```
|
||||
|
||||
2. Trust jonasnick's gpg key
|
||||
|
||||
```
|
||||
gpg2 --edit-key 36C71A37C9D988BDE82508D9B1A70E4F8DCD0366
|
||||
trust
|
||||
4
|
||||
quit
|
||||
```
|
||||
|
||||
3. Verify commit after `git pull`
|
||||
|
||||
```
|
||||
git verify-commit <hash of latest commit>
|
||||
```
|
||||
|
||||
Nodeinfo
|
||||
---
|
||||
Run `nodeinfo` to see your onion addresses for the webindex, spark, etc. if they are enabled.
|
||||
|
||||
Connect to spark-wallet
|
||||
---
|
||||
1. Enable spark-wallet in `configuration.nix`
|
||||
|
||||
Change
|
||||
```
|
||||
# services.spark-wallet.enable = true;
|
||||
```
|
||||
to
|
||||
```
|
||||
services.spark-wallet.enable = true;
|
||||
```
|
||||
|
||||
2. Deploy new `configuration.nix`
|
||||
|
||||
```
|
||||
nixops deploy -d bitcoin-node
|
||||
```
|
||||
|
||||
3. Get the onion address, access key and QR access code for the spark wallet android app
|
||||
|
||||
```
|
||||
journalctl -eu spark-wallet
|
||||
```
|
||||
Note: The qr code might have issues scanning if you have a light terminal theme. Try setting it to dark or highlightning the entire output to invert the colors.
|
||||
|
||||
4. Connect to spark-wallet android app
|
||||
|
||||
```
|
||||
Server Settings
|
||||
Scan QR
|
||||
Done
|
||||
```
|
||||
|
||||
Connect to electrs
|
||||
---
|
||||
1. Enable electrs in `configuration.nix`
|
||||
|
||||
Change
|
||||
```
|
||||
# services.electrs.enable = true;
|
||||
```
|
||||
to
|
||||
```
|
||||
services.electrs.enable = true;
|
||||
```
|
||||
|
||||
2. Deploy new `configuration.nix`
|
||||
|
||||
```
|
||||
nixops deploy -d bitcoin-node
|
||||
```
|
||||
|
||||
3. Get electrs onion address
|
||||
|
||||
```
|
||||
nodeinfo | grep 'ELECTRS_ONION'
|
||||
```
|
||||
|
||||
4. Connect to electrs
|
||||
|
||||
On electrum wallet machine
|
||||
```
|
||||
electrum --oneserver --server=<ELECTRS_ONION>:50001:t
|
||||
```
|
||||
|
||||
Connect to nix-bitcoin node through ssh Tor Hidden Service
|
||||
---
|
||||
1. Run `nodeinfo` on your nix-bitcoin node and note the `SSHD_ONION`
|
||||
|
||||
```
|
||||
nixops ssh operator@bitcoin-node
|
||||
nodeinfo | grep 'SSHD_ONION'
|
||||
```
|
||||
|
||||
2. Create a SSH key
|
||||
|
||||
```
|
||||
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519
|
||||
```
|
||||
|
||||
3. Place the ed25519 key's fingerprint in the `configuration.nix` `openssh.authorizedKeys.keys` field like so
|
||||
|
||||
```
|
||||
# FIXME: Add your SSH pubkey
|
||||
services.openssh.enable = true;
|
||||
users.users.root = {
|
||||
openssh.authorizedKeys.keys = [ "[contents of ~/.ssh/id_ed25519.pub]" ];
|
||||
};
|
||||
```
|
||||
|
||||
4. Connect to your nix-bitcoin node's ssh Tor Hidden Service, forwarding a local port to the nix-bitcoin node's ssh server
|
||||
|
||||
```
|
||||
ssh -i ~/.ssh/id_ed25519 -L [random port of your choosing]:localhost:22 root@[your SSHD_ONION]
|
||||
```
|
||||
|
||||
5. Edit your `network-nixos.nix` to look like this
|
||||
|
||||
```
|
||||
{
|
||||
bitcoin-node =
|
||||
{ config, pkgs, ... }:
|
||||
{ deployment.targetHost = "127.0.0.1";
|
||||
deployment.targetPort = [random port of your choosing];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
6. Now you can run `nixops deploy -d bitcoin-node` and it will connect through the ssh tunnel you established in step iv. This also allows you to do more complex ssh setups that `nixops ssh` doesn't support. An example would be authenticating with [Trezor's ssh agent](https://github.com/romanz/trezor-agent), which provides extra security.
|
||||
Loading…
Reference in New Issue
Block a user