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

docs: describe deploying with krops in installation tutorial

Browse Source
This commit is contained in:
Jonas Nick 2021-03-10 14:08:42 +01:00 committed by Erik Arvstedt
parent eb6dff5478
commit 7c0b521785
No known key found for this signature in database
GPG Key ID: 33312B944DD97846
2 changed files with 87 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
docs/install.md
View File

@ -1,21 +1,15 @@
Preliminary steps # Tutorial: Install and configure NixOS for nix-bitcoin on a dedicated machine
---
Get a machine to deploy nix-bitcoin on (see [hardware.md](hardware.md)).
# Tutorials This tutorial describes how to manage your Bitcoin node comfortably from your personal computer with the deployment tool [krops](https://github.com/krebs/krops).
However, nix-bitcoin is agnostic to the deployment method and can be used with different or without such tools (see [examples](../examples/README.md)).
1. [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 your own hardware
---
## 0. Preparation ## 0. Preparation
1. Optional: Make sure you have the latest firmware for your system (BIOS, microcode updates). 1. Find a machine to deploy nix-bitcoin on (see [hardware.md](hardware.md)).
2. Optional: Disable Simultaneous Multi-Threading (SMT) in the BIOS 2. Optional: Make sure you have the latest firmware for your system (BIOS, microcode updates).
3. Optional: Disable Simultaneous Multi-Threading (SMT) in the BIOS
Researchers recommend disabling (SMT), also known as Hyper-Threading Technology in the Intel® world to significantly reduce the impact of speculative execution-based attacks (https://mdsattacks.com/). Researchers recommend disabling (SMT), also known as Hyper-Threading Technology in the Intel® world to significantly reduce the impact of speculative execution-based attacks (https://mdsattacks.com/).
@ -241,29 +235,77 @@ You can also build Nix from source by following the instructions at https://nixo
cd ../../ cd ../../
mkdir nix-bitcoin-node mkdir nix-bitcoin-node
cd nix-bitcoin-node cd nix-bitcoin-node
# TODO cp -r ../nix-bitcoin/examples/{nix-bitcoin-release.nix,configuration.nix,shell.nix,krops,.gitignore} .
cp -r ../nix-bitcoin/examples/{configuration.nix,shell.nix,nix-bitcoin-release.nix,.gitignore} .
``` ```
## 4. Deploy with TODO ## 4. Deploy with krops
1. TODO
2. Edit `configuration.nix` 1. Edit your ssh config
```
nano ~/.ssh/config
```
and add the node with an entry similar to the following (make sure to fix `Hostname` and `IdentityFile`):
```
Host bitcoin-node
# FIXME
Hostname NODE_IP_ADDRESS_OR_HOST_NAME_HERE
User root
PubkeyAuthentication yes
# FIXME
IdentityFile ~/.ssh/id_...
AddKeysToAgent yes
```
2. Make sure you are in the deployment directory and edit `krops/deploy.nix`
```
nano krops/deploy.nix
```
Locate the `FIXME` and set the target to the name of the ssh config entry created earlier, i.e. `bitcoin-node`.
Note that any file imported by your `configuration.nix` must be copied to the target machine by krops.
For example, if there is an import of `networking.nix` you must add it to `extraSources` in `krops/deploy.nix` like this:
```
extraSources = {
"hardware-configuration.nix".file = toString ../hardware-configuration.nix;
"networking.nix".file = toString ../networking.nix;
};
```
3. Optional: Disallow substitutes
If you prefer to build the system from source instead of copying binaries from the Nix cache, add the following line to `configuration.nix`:
```
nix.extraOptions = "substitute = false";
```
If the build process fails for some reason when deploying with `krops-deploy` (see later step), it may be difficult to find the cause due to the missing output.
To see the build output, SSH into the target machine and run
```
nixos-rebuild -I /var/src switch
```
4. Copy `hardware-configuration.nix` from your node to the deployment directory.
```
scp root@bitcoin-node:/etc/nixos/hardware-configuration.nix .
```
5. Adjust configuration by opening the `configuration.nix` file and enable/disable the modules you want by editing this file.
``` ```
nano configuration.nix nano configuration.nix
``` ```
Uncomment `./hardware-configuration.nix` line by removing #. Pay attention to lines that are preceded by `FIXME` comments. In particular:
1. Make sure to set your SSH pubkey. Otherwise, you loose remote access because the config does not enable `permitRootLogin` (unless you add that manually).
2. Uncomment the line `./hardware-configuration.nix` by removing `#`.
3. Create `hardware-configuration.nix`. 6. Enter the deployment environment
```
nano hardware-configuration.nix
```
Copy contents of your NixOS machine's `/etc/nixos/hardware-configuration.nix` to this file.
4. Enter environment
``` ```
nix-shell nix-shell
@ -271,10 +313,21 @@ You can also build Nix from source by following the instructions at https://nixo
NOTE that a new directory `secrets/` appeared which contains the secrets for your node. NOTE that a new directory `secrets/` appeared which contains the secrets for your node.
5. TODO 7. Deploy with krops in nix-shell
6. Adjust configuration by opening the `configuration.nix` file and enable/disable the modules you want by editing this file. Pay particular attention to lines that are preceded by `FIXME` comments. Make sure to set your SSH pubkey. Otherwise, you loose remote access because the config does not enable `permitRootLogin` (unless you add that manually).
7. TODO ```
krops-deploy
```
This will now create a nix-bitcoin node on the target machine.
8. You can now access `bitcoin-node` via ssh
```
ssh operator@bitcoin-node
```
Note that you're able to log in as the unprivileged `operator` user because nix-bitcoin automatically authorizes the ssh key added to `root`.
For security reasons, all normal system management tasks can and should be performed with the `operator` user. Logging in as `root` should be done as rarely as possible. For security reasons, all normal system management tasks can and should be performed with the `operator` user. Logging in as `root` should be done as rarely as possible.

4
docs/usage.md
View File

@ -174,7 +174,9 @@ Connect to nix-bitcoin node through the SSH onion service
ssh -i ~/.ssh/id_ed25519 -L <random port of your choosing>:localhost:22 root@<SSH onion address> ssh -i ~/.ssh/id_ed25519 -L <random port of your choosing>:localhost:22 root@<SSH onion address>
``` ```
5. Edit your network to change the node's address to `localhost` and the ssh port to `[random port of your choosing]` 5. Edit your deployment tool's configuration and change the node's address to `localhost` and the ssh port to `<random port of your choosing>`.
If you use krops as described in the [installation tutorial](./install.md), set `target = "localhost:<random port of your choosing>";` in `krops/deploy.nix`.
6. After deploying the new configuration, it will connect through the SSH tunnel you established in step iv. This also allows you to do more complex SSH setups that some deployment tools don't support. An example would be authenticating with [Trezor's SSH agent](https://github.com/romanz/trezor-agent), which provides extra security. 6. After deploying the new configuration, it will connect through the SSH tunnel you established in step iv. This also allows you to do more complex SSH setups that some deployment tools don't support. An example would be authenticating with [Trezor's SSH agent](https://github.com/romanz/trezor-agent), which provides extra security.