2019-04-10 03:49:59 -07:00
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 )
2019-07-02 17:05:24 -07:00
2. [Install and configure NixOS for nix-bitcoin on VirtualBox (macOS host) ](#tutorial-install-and-configure-nixos-for-nix-bitcoin-on-virtualbox-macOS-host )
3. [Install and configure NixOS for nix-bitcoin on your own hardware ](#tutorial-install-and-configure-nixos-for-nix-bitcoin-on-your-own-hardware )
2019-04-10 03:49:59 -07:00
2019-07-03 12:26:51 -07:00
----
2019-04-10 03:49:59 -07:00
Tutorial: install and configure NixOS for nix-bitcoin on VirtualBox
---
## 1. VirtualBox installation
1. Add virtualbox.list to /etc/apt/sources.list.d (Debian 9 stretch)
2020-03-21 12:42:59 -07:00
```
echo "deb http://download.virtualbox.org/virtualbox/debian stretch contrib" | sudo tee /etc/apt/sources.list.d/virtualbox.list
```
2019-04-10 03:49:59 -07:00
2. Add Oracle VirtualBox public key
2020-03-21 12:42:59 -07:00
```
wget https://www.virtualbox.org/download/oracle_vbox_2016.asc
gpg2 oracle_vbox_2016.asc
```
2019-04-28 10:45:11 -07:00
2020-03-21 12:42:59 -07:00
Proceed _only_ if fingerprint reads B9F8 D658 297A F3EF C18D 5CDF A2F6 83C5 2980 AECF
2019-04-10 03:49:59 -07:00
2020-03-21 12:42:59 -07:00
```
sudo apt-key add oracle_vbox_2016.asc
```
2019-04-10 03:49:59 -07:00
3. Install virtualbox-5.2
2020-03-21 12:42:59 -07:00
```
sudo apt-get update
sudo apt-get install virtualbox-5.2
```
2019-04-10 03:49:59 -07:00
3. Create Host Adapter in VirtualBox
2020-03-21 12:42:59 -07:00
```
vboxmanage hostonlyif create
```
2019-04-10 03:49:59 -07:00
## 2. Nix installation
The following steps are meant to be run on the machine you deploy from, not the machine you deploy to.
2019-04-27 11:40:22 -07:00
You can also build Nix from source by following the instructions at https://nixos.org/nix/manual/#ch-installing-source.
2019-04-10 03:49:59 -07:00
1. Install Dependencies (Debian 9 stretch)
2020-03-21 12:42:59 -07:00
```
sudo apt-get install curl git gnupg2 dirmngr
```
2019-04-10 03:49:59 -07:00
2020-04-02 14:31:13 -07:00
2. Install latest Nix in "multi-user mode" with GPG Verification according to https://nixos.org/nix/download.html
2019-04-10 03:49:59 -07:00
2020-03-21 12:42:59 -07:00
```
2020-04-02 14:31:13 -07:00
curl -o install-nix-2.3.3 https://releases.nixos.org/nix/nix-2.3.3/install
curl -o install-nix-2.3.3.asc https://releases.nixos.org/nix/nix-2.3.3/install.asc
2020-03-21 12:42:59 -07:00
gpg2 --recv-keys B541D55301270E0BCF15CA5D8170B4726D7198DE
2020-04-02 14:31:13 -07:00
gpg2 --verify ./install-nix-2.3.3.asc
sh ./install-nix-2.3.3 --daemon
2020-03-21 12:42:59 -07:00
```
2019-04-28 10:45:11 -07:00
2020-03-21 12:42:59 -07:00
Then follow the instructions. Open a new terminal window when you're done.
2019-04-10 03:49:59 -07:00
2020-03-21 12:42:59 -07:00
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
```
you're likely not installing as multi-user because you forgot to pass the `--daemon` flag to the install script.
2019-04-10 03:49:59 -07:00
2019-04-27 11:40:22 -07:00
3. Optional: Disallow substitutes
2020-03-21 12:42:59 -07:00
You can put `substitute = false` to your `nix.conf` usually found in `/etc/nix/` to build the packages from source.
This eliminates an attack vector where nix's build server or binary cache is compromised.
2019-04-27 11:40:22 -07:00
2020-03-21 14:08:51 -07:00
## 3. Setup deployment directory
2019-04-10 03:49:59 -07:00
1. Clone this project
2020-03-21 12:42:59 -07:00
```
cd
git clone https://github.com/fort-nix/nix-bitcoin
```
2019-04-10 03:49:59 -07:00
2020-03-21 14:08:51 -07:00
2. Obtain the hash of the latest nix-bitcoin release
```
cd nix-bitcoin/examples
nix-shell
```
This will download the nix-bitcoin dependencies and might take a while without giving an output.
Now in the nix-shell run
```
fetch-release > nix-bitcoin-release.nix
```
3. Create a new directory for your nix-bitcoin deployment and copy initial files from nix-bitcoin
```
cd ../../
mkdir nix-bitcoin-node
cd nix-bitcoin-node
cp -r ../nix-bitcoin/examples/{configuration.nix,nixops,shell.nix,nix-bitcoin-release.nix} .
```
## 4. Deploy with NixOps
2020-08-18 13:55:24 -07:00
1. Enter `nix-shell` , which drops you into an environment with all the project dependencies loaded ([docs](https://nixos.wiki/wiki/Development_environment_with_nix-shell)).
2019-04-10 03:49:59 -07:00
2020-03-21 12:42:59 -07:00
```
nix-shell
```
2019-04-28 10:45:11 -07:00
2020-03-21 14:08:51 -07:00
Note that a new directory `secrets/` appeared which contains the secrets for your node.
2019-04-28 10:45:11 -07:00
2020-08-18 13:55:24 -07:00
2. Create a [nixops deployment ](https://nixos.org/nixops/manual/#sec-deploying-to-physical-nixos ) in nix-shell.
2019-04-10 03:49:59 -07:00
2020-03-21 12:42:59 -07:00
```
2020-03-21 14:08:51 -07:00
nixops create nixops/node.nix nixops/node-vbox.nix -d bitcoin-node
2020-03-21 12:42:59 -07:00
```
2019-04-10 03:49:59 -07:00
2020-08-18 13:55:24 -07:00
3. Adjust your 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.
2019-04-10 03:49:59 -07:00
2020-08-18 13:55:24 -07:00
4. Deploy with nixops in nix-shell
2019-04-10 03:49:59 -07:00
2020-03-21 12:42:59 -07:00
```
nixops deploy -d bitcoin-node
```
2019-04-10 03:49:59 -07:00
2020-03-21 12:42:59 -07:00
This will now create a nix-bitcoin node on the target machine.
2019-04-10 03:49:59 -07:00
2020-03-21 14:08:51 -07:00
5. Nixops automatically creates an ssh key for use with `nixops ssh` . Access `bitcoin-node` through ssh in nix-shell with
2019-04-10 03:49:59 -07:00
2020-03-21 12:42:59 -07:00
```
nixops ssh operator@bitcoin-node
```
2019-04-10 03:49:59 -07:00
2021-01-31 09:51:12 -08:00
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.
2019-04-10 03:49:59 -07:00
See [usage.md ](usage.md ) for usage instructions, such as how to update.
2019-11-08 06:41:02 -08:00
To resize the VM disk image, you can use this helper script from within nix-shell:
```
2020-03-21 14:08:51 -07:00
../nix-bitcoin/helper/vbox-resize-disk1.sh --help
2019-11-08 06:41:02 -08:00
```
2019-07-03 12:26:51 -07:00
----
2019-07-02 17:05:24 -07:00
Tutorial: install and configure NixOS for nix-bitcoin on VirtualBox (macOS host)
---
2019-07-03 12:26:51 -07:00
## 1. VirtualBox installation (macOS)
2019-07-02 17:05:24 -07:00
1. Download and install VirtualBox
2020-03-21 12:42:59 -07:00
Use the official Downloads page: [https://www.virtualbox.org/wiki/Downloads ](https://www.virtualbox.org/wiki/Downloads )
2019-07-02 17:05:24 -07:00
2020-03-21 12:42:59 -07:00
Make sure that the installer you download shows a lock icon in the top right corner to make sure it is signed by Oracle.
2019-07-02 17:05:24 -07:00
2. Create Host Adapter in VirtualBox
2020-03-21 12:42:59 -07:00
```
vboxmanage hostonlyif create
```
2019-07-02 17:05:24 -07:00
2019-07-03 12:26:51 -07:00
## 2. Nix installation (macOS)
2019-07-02 17:05:24 -07:00
2019-07-03 12:26:51 -07:00
Follow the instructions from [Nix installation on debian ](#2-nix-installation ). You will may need to replace `gpg2` with `gpg` .
2019-07-02 17:05:24 -07:00
## 3. LinuxKit Nix installation
In order to build binaries for your linux (NixOS) virtual machine on a macOS host machine, you need to use [linuxkit-nix ](https://github.com/nix-community/linuxkit-nix ). It uses hyperkit to spin up a separate VM on which it builds binaries. An alternative solution is [nix-docker-build-slave ](https://github.com/LnL7/nix-docker/blob/master/start-docker-nix-build-slave ).
1. Installation
2020-03-21 12:42:59 -07:00
```
nix-env -i /nix/store/jgq3savsyyrpsxvjlrz41nx09z7r0lch-linuxkit-builder
2019-07-02 17:05:24 -07:00
nix-linuxkit-configure
2020-03-21 12:42:59 -07:00
```
2019-07-02 17:05:24 -07:00
2020-03-21 12:42:59 -07:00
You may want to use `nix-linuxkit-configure -c 4` to give the builder 4 CPUs.
2019-07-02 17:05:24 -07:00
2. Confirm that nix-linuxkit works
```
2020-03-21 12:42:59 -07:00
nix-build ~/.cache/nix-linuxkit-builder/example.nix
```
2019-07-02 17:05:24 -07:00
2020-03-21 12:42:59 -07:00
As the installer says, run a `nix-build` to make sure that you are able to build linux binaries. The `example.nix` is specifically configured to force a x86_64-linux build. Remove the generated `result` folder afterwards.
2019-07-02 17:05:24 -07:00
2019-07-03 12:26:51 -07:00
## 4. Nixops deployment (macOS)
2019-07-02 17:05:24 -07:00
2019-07-03 12:26:51 -07:00
Follow the instructions from [Nixops deployment on debian ](#3-nixops-deployment ). Add `--option system x86_64-linux` to the `nixops deploy` command in step 5 to force your system to use linuxkit-nix.
2019-07-02 17:05:24 -07:00
2019-07-03 12:26:51 -07:00
----
2019-07-02 17:05:24 -07:00
2019-04-10 03:49:59 -07:00
Tutorial: install and configure NixOS for nix-bitcoin on your own hardware
---
2019-05-18 12:18:00 -07:00
## 0. Preparation
2019-05-21 16:12:54 -07:00
1. Optional: Make sure you have the latest firmware for your system (BIOS, microcode updates).
2. Optional: Disable Simultaneous Multi-Threading (SMT) in the BIOS
2019-05-18 12:18:00 -07:00
2019-07-12 14:22:57 -07:00
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/).
2019-05-18 12:18:00 -07:00
2019-04-10 03:49:59 -07:00
## 1. NixOS installation
This is borrowed from the [NixOS manual ](https://nixos.org/nixos/manual/index.html#ch-installation ). Look there for more information.
2020-03-21 10:27:44 -07:00
1. Obtain latest [NixOS ](https://nixos.org/nixos/download.html ). For example:
2019-04-10 03:49:59 -07:00
2020-03-21 12:42:59 -07:00
```
wget https://releases.nixos.org/nixos/19.09/nixos-19.09.2284.bf7c0f0461e/nixos-minimal-19.09.2284.bf7c0f0461e-x86_64-linux.iso
sha256sum nixos-minimal-19.09.2284.bf7c0f0461e-x86_64-linux.iso
# output: 9768eb945bef410fccfb82cb3d2e7ce7c02c3430aed0f2f1527273cb080fff3e
```
Alternatively you can build NixOS from source by following the instructions at https://nixos.org/nixos/manual/index.html#sec-building-cd.
2019-04-10 03:49:59 -07:00
2. Write NixOS iso to install media (USB/CD). For example:
2020-03-21 12:42:59 -07:00
```
cp nixos-minimal-19.09.2284.bf7c0f0461e-x86_64-linux.iso /dev/sdX
```
2019-04-28 10:45:11 -07:00
2020-03-21 12:42:59 -07:00
Replace /dev/sdX with the correct device name. You can find this using `sudo fdisk -l`
2019-04-10 03:49:59 -07:00
3. Boot the system
2020-03-21 12:42:59 -07:00
You will have to find out if your hardware uses UEFI or Legacy Boot for the next step.
2019-04-10 03:49:59 -07:00
4. Option 1: Partition and format for UEFI
2020-03-21 12:42:59 -07:00
```
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
```
2019-04-10 03:49:59 -07:00
4. Option 2: Partition and format for Legacy Boot (MBR)
2020-03-21 12:42:59 -07:00
```
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
```
2019-04-10 03:49:59 -07:00
2019-04-28 06:11:53 -07:00
4. Option 3: Set up encrypted partitions:
Follow the guide at https://gist.github.com/martijnvermaat/76f2e24d0239470dd71050358b4d5134.
2019-04-10 03:49:59 -07:00
5. Generate NixOS config
2020-03-21 12:42:59 -07:00
```
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";
};
}
```
2019-04-10 03:49:59 -07:00
6. Do the installation
2020-03-21 12:42:59 -07:00
```
nixos-install
```
Set root password
```
setting root password...
Enter new UNIX password:
Retype new UNIX password:
```
2019-04-10 03:49:59 -07:00
7. If everything went well
2020-03-21 12:42:59 -07:00
```
reboot
```
2019-04-10 03:49:59 -07:00
2020-03-21 14:08:51 -07:00
## 2. Nix installation
Follow the [Nix installation ](#2-nix-installation ) instructions from the tutorial above (on the machine you are going to deploy from).
2019-04-27 11:40:22 -07:00
2020-03-21 14:08:51 -07:00
## 3. Setup deployment directory
Follow the [Setup deployment directory ](#3-setup-deployment-directory ) instructions from the tutorial above (on the machine you are going to deploy from).
2019-04-10 03:49:59 -07:00
2020-03-21 14:08:51 -07:00
## 4. Deploy with NixOps
1. Make sure you are in the deployment directory and create a nixops network file as follows
2019-04-10 03:49:59 -07:00
2020-03-21 12:42:59 -07:00
```
2020-03-21 14:08:51 -07:00
nano nixops/node-nixos.nix
2020-03-21 12:42:59 -07:00
```
2019-04-10 03:49:59 -07:00
2020-03-21 12:42:59 -07:00
```
{
bitcoin-node =
{ config, pkgs, ... }:
{ deployment.targetHost = "1.2.3.4";
};
}
```
2019-04-10 03:49:59 -07:00
2020-03-21 12:42:59 -07:00
Replace 1.2.3.4 with NixOS machine's IP address.
2019-04-10 03:49:59 -07:00
2020-03-21 14:08:51 -07:00
2. Edit `configuration.nix`
2019-04-10 03:49:59 -07:00
2020-03-21 12:42:59 -07:00
```
nano configuration.nix
```
2019-04-10 03:49:59 -07:00
2020-03-21 12:42:59 -07:00
Uncomment `./hardware-configuration.nix` line by removing #.
2019-04-27 11:40:22 -07:00
2020-08-18 13:55:24 -07:00
3. Create `hardware-configuration.nix` .
2019-04-10 03:49:59 -07:00
2020-03-21 12:42:59 -07:00
```
nano hardware-configuration.nix
```
2020-08-18 13:55:24 -07:00
Copy contents of your NixOS machine's `/etc/nixos/hardware-configuration.nix` to this file.
2019-04-10 03:49:59 -07:00
2020-03-21 14:08:51 -07:00
4. Add boot option to `hardware-configuration.nix`
2019-04-10 03:49:59 -07:00
2020-03-21 12:42:59 -07:00
Option 1: Enable systemd boot for UEFI
```
2020-12-23 03:55:45 -08:00
boot.loader.systemd-boot.enable = true;
2020-03-21 12:42:59 -07:00
```
Option 2: Set grub device for Legacy Boot (MBR)
```
boot.loader.grub.device = "/dev/sda";
```
2019-04-10 03:49:59 -07:00
2020-03-21 14:08:51 -07:00
5. Enter environment
2019-04-28 10:45:11 -07:00
2020-03-21 12:42:59 -07:00
```
nix-shell
```
2019-04-10 03:49:59 -07:00
2020-03-21 14:08:51 -07:00
Note that a new directory `secrets/` appeared which contains the secrets for your node.
2019-04-28 10:45:11 -07:00
2020-08-18 13:55:24 -07:00
6. Create nixops [deployment ](https://nixos.org/nixops/manual/#sec-deploying-to-physical-nixos ) in nix-shell.
2019-04-28 10:45:11 -07:00
2020-03-21 12:42:59 -07:00
```
2020-03-21 14:08:51 -07:00
nixops create nixops/node.nix nixops/node-nixos.nix -d bitcoin-node
2020-03-21 12:42:59 -07:00
```
2019-04-10 03:49:59 -07:00
2020-08-18 13:55:24 -07:00
7. 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.
2019-04-27 11:40:22 -07:00
2020-08-18 13:55:24 -07:00
8. Deploy with nixops in nix-shell
2019-04-10 03:49:59 -07:00
2020-03-21 12:42:59 -07:00
```
nixops deploy -d bitcoin-node
```
2019-04-28 10:45:11 -07:00
2020-03-21 12:42:59 -07:00
This will now create a nix-bitcoin node on the target machine.
2019-04-10 03:49:59 -07:00
2020-03-21 14:08:51 -07:00
9. Nixops automatically creates an ssh key for use with `nixops ssh` . Access `bitcoin-node` through ssh in nix-shell with
2019-04-10 03:49:59 -07:00
2020-03-21 12:42:59 -07:00
```
nixops ssh operator@bitcoin-node
```
2019-04-10 03:49:59 -07:00
2021-01-31 09:51:12 -08:00
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.
2019-04-10 03:49:59 -07:00
See [usage.md ](usage.md ) for usage instructions, such as how to update.