mybonk-wiki

MY₿ONK logo


👉 Here is maintained the MY₿ONK Wiki, the detailed *manual* installation instructions ✍️.

Anyone can take part on MY₿ONK's GitHub.
Join the conversation on our Telegram group</a>!

Table of Contents

Tip: Click the ‘TOC’ button (Github TOC button) in one of the top corners to display the table of content in a separate pane.

Before you start

Read this document from the beginning to the end before getting your hands on the keyboard. Also watch this presentation by Valentin Gagarin about Flattening the Learning Curve for Nix/NixOS as Nix/NixOS is the cornerstone of MY₿ONK.

You might have a feeling of “déjà vu” as it is essentially a scrambled from various sources from nixOS manual, nixOS Wiki, nix-bitcoin, Virtual Box, Raspibolt, Raspiblitz (although the approach of MY₿ONK is radically different).

If you have any experience with the command line or already run any other full node you have a significant advantage, you could complete this setup in 2 hours maybe, otherwise allocate 1 day (excluding the time required for blockchain download and indexations which is what takes most time, possibly days unless you have a recent local copy of these e.g. on the local network or USB drive).

It is assumed that you know a little bit of everything but not enough so we show you the way step by step based on the MY₿ONK setup (one MY₿ONK orchestrator and one MY₿ONK console).

We [collaboratively] take great pride and care maintaining this document so it remains up to date and concise, often it refers to external links. Explore these external links, it will make your journey smoother.

You too can contribute to improving this document on GitHub.

Enjoy the ride, no stress, check out our baby rabbit holes :hole: :rabbit2: and the FAQ 👷

Terminology

Overview

This small ecosystem example consists of only two elements that we are going to build together:

Advice

Remote access

Being proficient with remote access is so essential that it deserves its own section. Have a look at the section dedicated to ssh in the baby rabbit holes section 🕳 🐇

Do your home work, this topic is now closed.

1. Build your MYBONK bitcoin full node

There are many ways to go about this, the one detailed here focuses on people with little (but still some) technical knowledge.

These steps can and will be automated but for now the goal is for you to understand how it works and the mechanics behind it.

1.1 The hardware

There are many many platforms, physical (HW) or virtual (Virtual Machines, Cloud) to choose from, which is what NixOS was made for to deal with in the first place. They even maintain a (non-exhaustive) collection of hardware-specific platform profiles with specific configurations and optimization settings NixOS Hardware repository.

The following steps focus on MY₿ONK console hardware platform specifically because it would be impossible to maintain and support all the possible combinations for a specific application domain: Each hardware has its own specs, some have additional features (BIOS capabilities, onboard encryption, various kinds of storages and partition systems .etc…) or limitations (too little RAM or unreliable parts, weak power source, “moving parts”, cooling issues, higher power consumption .etc…) making it unadvisable to install onto, or too difficult for an average user to setup and maintain; Even little things like bootable or not from USB stick can turn what should be a beautiful journey into hours of frustration trying to just make the thing boot until the next pitfall.

MY₿ONK console is a full-node bitcoin-only hardware platform designed with anonymity, security, low price, performance, durability, low-energy, supply chain resilience and generic parts in mind. You too can get a MY₿ONK console.

MY₿ONK console can also be used to run Raspiblitz similarly to Raspberry pi or other distributions.

1.2 Download and install NixOS

The idea is to kick-start a bare bone NixOS on your MY₿ONK console, from that point we’ll be able to easily and remotely “flash” MY₿ONK configuration on it using MY₿ONK orchestrator.

You can install NixOS on physical hardware equiped with a screen and a keyboard by simply copying its image onto a USB stick and booting from it.

We documented the installation of NixOS HERE but NixOS’ official installation documentation is bound to be most up to date.

By default the behavior of the complete NixOS system is defined by the content of it directory /etc/nixos:

  # ls /etc/nixos
  configuration.nix  hardware-configuration.nix

Take some time to have a look at “Nix - A One Pager” for a first brief introduction to Nix, the language used in these ‘.nix’ files.

1.3 ssh and auto login

The configuration is built on the orchestrator then pushed onto of the MY₿ONK console(s) over ssh.

As addressed in section “Remote access” in “0. Before you start” you need to understand ssh and public-private key pair relay well.

Let’s enable sshd on this new console, this is also nicely demonstrating how similarly straightforward it would be to configure other services very precisely, even a complete system, editing the Nix expression in configuration.nix.

We need 2 things: 1) The IP address of the console you want to connect to:

The IP address has most likely been assigned by your internet router built-in DHCP server. On the console you can use the command `ip` to figure it out:

```bash
$ ip a

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
  link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
  inet 127.0.0.1/8 scope host lo
    valid_lft forever preferred_lft forever
  inet6 ::1/128 scope host 
    valid_lft forever preferred_lft forever
2: enp2s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
  link/ether 68:1d:ef:2e:0c:b3 brd ff:ff:ff:ff:ff:ff
  inet 192.168.0.64/24 brd 192.168.0.255 scope global dynamic noprefixroute enp2s0
    valid_lft 84565sec preferred_lft 84565sec
  inet6 2a02:2788:a4:285:a1fd:5396:bef5:b7c4/64 scope global temporary dynamic 
    valid_lft 301sec preferred_lft 301sec

```

Your output may differ somewhat but in this can you can see that the wired network interface `enp2s0` has the IP address `192.168.0.64`.

2) Have sshd service running on the target machine:

It is not running nor installed by default. You can install and configure it simply by adding a few lines in `configuration.nix`:

```bash
# nano /etc/nixos/configuration.nix
```
Add the following lines:

```bash
# Enable the OpenSSH daemon.
services.openssh = {
  enable = true;
  settings.PermitRootLogin = "yes";
};
```

  Save the file and exit. 
  
  [`nixos-rebuild`](https://nixos.wiki/wiki/Nixos-rebuild) is the NixOS command used to apply changes made to the system configuration as well as various other tasks related to managing the state of a NixOS system. For a full list of nixos-rebuild sub-commands and options have a look at its man page (`$ man nixos-rebuild`). 

  Now build the configuration and activate it, but don't add it (just yet) to the bootloader menu. This is done using the `test` subcommand:
  ```bash
  # nixos-rebuild test
  building Nix...
  building the system configuration...
  activating the configuration...
  setting up /etc...
  reloading user units for root...
  reloading user units for mybonk...
  setting up tmpfiles
  ```
  Check the system logs as the system is reconfiguring:
  ```bash
  # journalctl -f -n 60
  ```
  Entries referring to the system changes and sshd being enabled are being displayed.

  Check sshd status:
  ```bash
  # systemctl status sshd.service 
● sshd.service - SSH Daemon
    Loaded: loaded (/etc/systemd/system/sshd.service; enabled; preset: enabled)
    Active: active (running) since Mon 2023-01-16 16:46:09 CST; 1h 42min ago
  Main PID: 850 (sshd)
        IP: 326.9K in, 379.5K out
        IO: 3.3M read, 0B written
      Tasks: 1 (limit: 9326)
    Memory: 5.9M
        CPU: 336ms
    CGroup: /system.slice/sshd.service
            └─850 "sshd: /nix/store/qy9jighrfllrfy8shipl3j41m9k336vv-openssh-9.1p1/bin/sshd -D -f /etc/ssh/sshd_config [listener] 0 of 10-100 startup>
  ```

Now that we know the IP address and that sshd is listening let’s connect to it from another machine:

$ ssh root@192.168.0.64

(root@mybonk_console) Password: 
Last login: Mon Jan 16 06:03:35 2023
#

It works, this is great.

Let’s configure ssh key-pair, this is typically done using ssh-keygen to generate the keys and ssh-copy-id to copy the public key onto the remote machine.

Instead of having to copy the public key onto the remote machine “manually” you can set it in the configuration.nix file: Let’s disable password-based login and use key-pair only instead, in a couple of lines, just make sure you don’t “lock yourself out” by disallowing password authentication and forgetting to copy your public key for instance.

  # nano /etc/nixos/configuration.nix

Add the following lines making sure you replace the parameter openssh.authorizedKeys.keys with your own public key):

  services.openssh = {
    enable = true;
    #settings.PermitRootLogin = "yes";
  };

  users.users.root = {
    openssh.authorizedKeys.keys = [
        "ecdsa-sha2-nistp521 AAAAE2VjZHNhLXNoYTItbmlzdHA1MjEAAAAIbmlzdHA1MjEAAACFBABTjXzlHGw941UGukM3HVUTpvsXCLgx7EZRJ83YE32qEe8HtXmGHo41YftauWwnTN5rQvMWTd0puFzXz4vKu7YC1gATUUtYNa6mzgtt+dNvTvLNcQ1vSQ5s19yKKgJjZV1MZBlcf/HklfNdS0Owja1aIrp0jKlJEaTWPXKtN6vkfLSF5r== Jay"
    ]
  ;
  };

You can get your own public key using the cat command in another terminal (ssh-copy-id will add user@clientmachine after the public key but the “@clientmachine” part can be removed).

cat ~/.ssh/id_ecdsa.pub

ecdsa-sha2-nistp521 AAAAE2VjZHNhLXNoYTItbmlzdHA1MjEAAAAIbmlzdHA1MjEAAACFBABTjXzlHGw941UGukM3HVUTpvsXCLgx7EZRJ83YE32qEe8HtXmGHo41YftauWwnTN5rQvMWTd0puFzXz4vKu7YC1gATUUtYNa6mzgtt+dNvTvLNcQ1vSQ5s19yKKgJjZV1MZBlcf/HklfNdS0Owja1aIrp0jKlJEaTWPXKtN6vkfLSF5r== Jay@orchestrator

More details regarding sshd configuration can be found on the dedicated nixOS Wiki page.

Play a little bit with the settings and nixos-rebuild test. Once ready you make your changes persistent as new default option in the bootloader run nixos-rebuild with the switch instead of the test subcommand:

  # nixos-rebuild switch
  building Nix...
  building the system configuration...
  updating GRUB 2 menu...
  Warning: os-prober will be executed to detect other bootable partitions.
  Its output will be used to detect bootable binaries on them and create new boot entries.
  lsblk: /dev/mapper/no*[0-9]: not a block device
  lsblk: /dev/mapper/raid*[0-9]: not a block device
  lsblk: /dev/mapper/disks*[0-9]: not a block device
  activating the configuration...
  setting up /etc...
  reloading user units for mybonk...
  setting up tmpfiles
  $

At a later point you’d want to insert a name alias in your ~/.ssh/config file or use Tailscale to not having to remember IP addresses.

This is it, MY₿ONK console is now ready to be operated through MY₿ONK orchestrator.

1.4 Download and install MYBONK stack

#### Option 1. The “automated” way using a MYBONK orchestrator

#### Option 2. The “manual” way

2. Build your MYBONK orchestrator

Note: Ref #30 - MY₿ONK orchestrator is planned to be integrated within the MY₿ONK console.

This machine is used to orchestrate your [fleet of] MY₿ONK console[s] (services, parameters, secrets). It is used to build MY₿ONK stack configuration and deploy it remotely onto your MY₿ONK console[s] in a secure and streamlined manner.

For this reason it is important that this machine remains clean and protected, isolated from threats and vulnerabilities.

The following sections describe the installation of MY₿ONK orchestrator on a VirtualBox virtual machine:

2.1. Download and install VirtualBox

Follow the instructions on their website https://www.virtualbox.org

2.2. Build the OS in VirtualBox

Now that VirtualBox is installed you need to install an OS on it (Linux Debian in our case, or any systemd-based Linux system).

Choose one of the following 2 options:

Option 1. Using the installation image from Debian

Option 2. Using a ready-made Virtual Box VDI (Virtual Disk Image)

2.3. ssh and auto login

You want to access your MY₿ONK orchestrator using ssh.

For more security some Linux distributions restrict ssh usage, for instance such restrictions may apply to root user.

Check this by opening the sshd configuration /etc/ssh/sshd_config on the target machine using # nano /etc/ssh/sshd_config and see the setting PermitRootLogin, its value can be yes, prohibit-password, without-password. The later two ban all interactive authentication methods, allowing only public-key, hostbased and GSSAPI authentication.

It is generally advised to avoid using user root especially to remote-access. You can use sudo (or doas whichever is available on your system) from another user instead when needed so just leave the setting PermitRootLogin as prohibit-password.

2.4. Install Nix

Choose one of the following 2 options.

#### Option 1. Using the ready-made binary distribution from nix cache

#### Option 2. Building Nix from the source

2.5. Build MYBONK stack

Now that your MY₿ONK orchestrator is up and running we can use it to build MY₿ONK stack and deploy it seamlessly to the [fleet of] MY₿ONK console(s) in a secure, controlled and effortless way.

MY₿ONK is derived from nix-bitcoin. Have a look at the GitHub, especially the MYBONK-core directory.

2.6. Deploy MYBONK stack to MYBONK consoles

The main component of MY₿ONK stack is MY₿ONK-core. It is a fork of nix-bitcoin, augmented of the MY₿ONK specificities, best practices and community (and hardware may you be running an authentic MY₿ONK console).

There are dozens of options available to deploy a nixOS configuration to a remote machine: NixOps, krops, morph, NixUS, deploy-rs, colmena, Bento, NixOS-anywhere .etc.. , each with their pros and cons.

NixOps, the official DevOps tool of NixOS is nice but it has some flaws.

krops solves some of these flaws with very simple concepts, some of its features are:

We are going to use krops, it is also used by the underlying nix-bitcoin, let’s not reinvent the wheel.

First read this very well written article to get a high level understanding of how krops works, here we are going to perform the steps together.

As you can read krops relies on ssh passwordless login, we have configured this in an earlier section let’s move on:

MY₿ONK stack is now running on your MY₿ONK console and you can monitor and control its behavior either locally (not recommended) or remotely from your MY₿ONK orchestrator.

3. Operations

Unless otherwise stated all the operations in this sections are executed from MY₿ONK orchestrator.

Learn how to use tmux and tmuxinator in the baby rabbit holes, it will take a little effort to get used to it but will save you hours every week and streamline your operations. We also made a tmuxinator_console.yml template available for you to reuse.

In the following example we pass the extra ‘node’ parameter (node="mybonk-jay"), it is the network name or IP address of the node to connect to (whatever you configured in your hosts file, your ssh or Tailscale configuration). The parameter -c allows to name the session.

  $ cd mybonk-core
  $ tmuxinator start -p ../.tmuxinator.yml -c mybonk-jay node="mybonk-jay"

You can kill the session you just created by using the following command:

  $ tmux kill-session -t mybonk-jay

You can kill all the running sessions using the following command:

  $ tmux kill-server

3.1. Baby steps

Your node must be running 24/7. It consumes very little electricity and the goal is to have a mesh of nodes that are super resilient and available. Again: Keep your node running all the time. If you ever have to move it to another location run the appropriate command # shutdown -h and let the system halt and power off properly before unplugging it.

This will also avoid potential physical damage, data corruption and in the worst but unlikely case funds being locked as a consequence.

Explore the running services using the following simple commands on your MY₿ONK console:

3.1.1 Start the services progressively

Some services take a very long time to start for the first time.

The most obvious examples are bitcoind and fulcrum, requiring up to a few days to synchronize and index until they are ready to operate. Software relying on these services may show warnings, error messages and not work until the services they depend on have fully started (e.g. c-lightning complaining about bitcoind not being ready, mempool complaining about fulcrum itself complaining about bitcoind not being ready).

This is a transitional state until the initial synchronization/indexation of these services is complete.

Keep a look at the system logs, they tell you exactly what the system is busy with. You also stop a particular service complaining because another one is not yet ready to serve requests using the standard systemd commands e.g. # systemctl stop clightning then # systemctl start clightning once the system is ready.

3.1.2 How the secrets are managed

The deployment mechanism we use to push MYBONK stack from the orchestrator to the console(s) (based on krops) creates a a directory named secrets in which it generates the random default passwords and keys required for the services that are enabled to operate.

Be extremely careful with what you do with the content of this directory as it allows anyone with read access to access the services.

3.1.3 Rebuild MY₿ONK console configuration directly on the host (instead of pushing a new configuration using krops)

3.2. Copy the complete blockchain from another MY₿ONK console

What takes most time during a full node installation is copying the complete blockchain. This is done automatically by bitcoind when the service starts and realizes its data directory (services.bitcoind.dataDir = "/data/bitcoind" by default in a MY₿ONK console) is empty or partial so it starts downloading what it needs from another random bitcoin full node on the Internet.

Bitcoind taking care of downloading the complete blockchain (nearly 500GB at the time of writting) from the Internet for you is great but can take days and weeks depending on your and the peer peer Internet connectivity, the maximum ateinable transfer rate being at most the worst of either.

Copying the bitcoin blockchain from a local machine would take a fraction of this time.

You absolutly don’t want to copy the whole content of your services.bitcoind.dataDir, only the files in the blocks, chainstate and optionaly indexes. These files are cross-platform and can be copied between different installations.

blocks and chainstate are known collectively as a node’s “block database”, they represent all of the information downloaded by a node during the syncing process. In other words, if you copy installation A’s block database into installation B, installation B will then have the same syncing percentage as installation A. This is usually far faster than doing the normal initial sync over again. However, when you copy someone’s database in this way, you are trusting them absolutely. Bitcoin Core assumes its block database files as 100% accurate and trustworthy, whereas during the normal initial sync it treats each block offered by a peer as invalid until proven otherwise (untill it had time to catch-up and process all the blocks sequencialy). If an attacker is able to modify your block database files, then they can do all sorts of evil things which could cause you to lose bitcoins. Therefore, you should only copy block databases from Bitcoin installations under your personal control, and only over a secure connection.

The files in the blocks and chainstate directories work hand in hand so it is important to copy all of them at once and both nodes have to be shut down while copying. Only the file with the highest number in the blocks directory is ever written to (earlier files will never change) and are accessed in a highly sequential manner.

The files in indexes can also be copied over but would be regenerated automatically by bitcoind if missing anyways.

Here are 2 simple possibilities to copy these files using the common tool rsync:

#### Option 1. Copy from USB drive

Transfer speed: About 175 M/s -> Need about 6h to transfer

#### Option 2. Copy from another machine over the LAN

Transfer speed: –to be done–

This method is essentially the same as Option 1., it uses rsync too but over the LAN.

3.3. Backup and restore

This section explains further the process of backing-up and restoring services and their data.

            ˜˜˜˜ONGOING˜˜˜˜

3.3.1 bitcoin

How to generate recovery phrase from private key?

3.3.2 clightning

            ˜˜˜˜ONGOING˜˜˜˜  ### 3.3.2 RTL (Ride the Lightning) ---

3.4. Node Recovery

https://node-recovery.com/ Particularily interesting on this page is the “Zombie Channel Recovery Matcher” section.

3.5. Join a Federation

            ˜˜˜˜ONGOING˜˜˜˜

Federation, noun, late Latin foederatio(n- ): “An encompassing entity formed by uniting smaller or more localized entities.”

Federation is a broad term meaning different thinks in different environments. In the scope of MYBONK it my refer to a MYBONK federation, Fedimint federation and a Liquid federation.

This site is open source. Improve this page.