Remove upstream tests, docs, examples, dev env and release tooling

Replace upstream's README with a short one for this fork, and add
docs/fork-maintenance.md describing what was removed and how to
maintain the rest. Keeps helper/update-fixed-output-derivation.sh for
pkgs/mempool/generate.sh. There is no test suite.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
pleb
2026-11-15 19:49:32 -08:00
co-authored by Claude Opus 5.5
parent 5d7289532b
commit e1af5b794e
79 changed files with 294 additions and 6862 deletions
-55
View File
@@ -1,55 +0,0 @@
name: nix-bitcoin tests
on: [push, pull_request]
env:
CACHIX_SIGNING_KEY: ${{ secrets.CACHIX_SIGNING_KEY }}
# Strategy:
# Job `build_test_drivers` evals all VM tests and builds all test drivers in a single Nix build.
# Compared to launching a separate build job for each VM test, this avoids duplicated
# builds of derivations that the test drivers have in common.
#
# The job matrix `test_scenario` runs the VM tests.
# When job `build_test_drivers` determines that all tests have already been built successfully,
# job `test_scenario` is skipped via output variable `run_scenario_tests`.
jobs:
build_test_drivers:
runs-on: ubuntu-latest
outputs:
run_scenario_tests: ${{ steps.main.outputs.run_scenario_tests }}
steps:
- uses: actions/checkout@v4
- uses: cachix/install-nix-action@v31
- id: main
name: Build test drivers
run: |
echo "::group::Setup Nix env"
nix shell --inputs-from . nixpkgs#{bash,coreutils,cachix} -c ./test/ci/build_test_drivers.sh
test_scenario:
runs-on: ubuntu-latest
strategy:
matrix:
scenario:
- default
- netns
- netnsRegtest
- joinmarket-bitcoind-29
needs: build_test_drivers
if: needs.build_test_drivers.outputs.run_scenario_tests == 'true'
steps:
- uses: actions/checkout@v4
- uses: cachix/install-nix-action@v31
- run: nix shell --inputs-from . nixpkgs#{bash,coreutils,cachix} -c ./test/ci/build.sh ${{ matrix.scenario }}
check_flake:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: cachix/install-nix-action@v31
- run: nix flake check --all-systems
# FIXME: Re-enable when the nixos-search input is usable again.
# This is also disabled in ./test/run-tests.sh.
# - run: ./test/nixos-search/ci-test.sh
- run: ./test/shellcheck.sh
+46 -121
View File
@@ -1,135 +1,60 @@
> [!WARNING]
> **Archived and unmaintained as of August 13, 2026.**
> v0.0.139 is the final release; there will be no further updates or security fixes.
# nix-bitcoin (satstack fork)
<p align="center">
<img
width="320"
src="docs/img/nix-bitcoin-logo.png"
alt="nix-bitcoin logo">
</p>
<br/>
<p align="center">
<a href="https://github.com/fort-nix/nix-bitcoin/actions" target="_blank">
<img src="https://github.com/fort-nix/nix-bitcoin/actions/workflows/test.yml/badge.svg?branch=master"
alt="Github Actions status">
</a>
<a href="https://github.com/fort-nix/nix-bitcoin/releases/latest" target="_blank">
<img src="https://img.shields.io/github/v/release/fort-nix/nix-bitcoin" alt="GitHub tag (latest SemVer)">
</a>
<a href="https://github.com/fort-nix/nix-bitcoin/commits/master" target="_blank">
<img src="https://img.shields.io/github/commit-activity/y/fort-nix/nix-bitcoin" alt="GitHub commit activity">
</a>
<a href="https://github.com/fort-nix/nix-bitcoin/graphs/contributors" target="_blank">
<img src="https://img.shields.io/github/contributors-anon/fort-nix/nix-bitcoin" alt="GitHub contributors">
</a>
<a href="https://github.com/fort-nix/nix-bitcoin/releases" target="_blank">
<img src="https://img.shields.io/github/downloads/fort-nix/nix-bitcoin/total" alt="GitHub downloads">
</a>
</p>
<br/>
NixOS modules for a Bitcoin node running **bitcoind, lnd, electrs and
mempool**, with Tor onion services and host-generated secrets.
nix-bitcoin is a collection of Nix packages and NixOS modules for easily installing **full-featured Bitcoin nodes** with an emphasis on **security**.
This is a trimmed fork of [fort-nix/nix-bitcoin](https://github.com/fort-nix/nix-bitcoin),
which was archived in August 2026. Everything squirtle doesn't use has
been removed. See [docs/fork-maintenance.md](docs/fork-maintenance.md) for
what was cut, what's left, and the per-release checklist.
Overview
---
nix-bitcoin can be used for personal or merchant wallets, public infrastructure or
for Bitcoin application backends. In all cases, the aim is to provide security and
privacy by default. However, while nix-bitcoin is used in production today, it is
still considered experimental.
## Usage
nix-bitcoin nodes can be deployed on dedicated hardware, virtual machines or containers.
The Nix packages and NixOS modules can be used independently and combined freely.
```nix
# flake.nix
inputs.nix-bitcoin = {
url = "git+ssh://gitea@gitea.satstack.dev/pleb/nix-bitcoin.git";
inputs.nixpkgs.follows = "nixpkgs";
};
nix-bitcoin is built on top of Nix and [NixOS](https://nixos.org/) which provide powerful abstractions to keep it highly customizable and
maintainable. Testament to this are nix-bitcoin's robust security features and its potent test framework. However,
running nix-bitcoin does not require any previous experience with the Nix ecosystem.
# in a nixosSystem's modules
inputs.nix-bitcoin.nixosModules.default
```
Get started
---
- See the [examples](examples/README.md) for an overview of all features.
- To setup a new node from scratch, see the [installation instructions](docs/install.md).
- To add nix-bitcoin to an existing NixOS configuration, see [importable-configuration.nix](examples/importable-configuration.nix)
and the [Flake example](examples/flakes/flake.nix).
```nix
{
nix-bitcoin = {
generateSecrets = true; # writes /etc/nix-bitcoin-secrets on the host
operator = { enable = true; name = "alice"; };
nodeinfo.enable = true;
onionServices.bitcoind.public = true;
};
Docs
---
Hint: To show a table of contents, click the button (![Github TOC button](docs/img/github-table-of-contents.svg)) in the
top left corner of the documents.
services.tor = { enable = true; client.enable = true; };
<!-- TODO-EXTERNAL: -->
<!-- Change query to `nix-bitcoin` when upstream search has been fixed -->
* [NixOS options search](https://search.nixos.org/flakes?channel=unstable&sort=relevance&type=options&query=bitcoin)
* [Hardware requirements](docs/hardware.md)
* [Installation](docs/install.md)
* [Configuration and maintenance](docs/configuration.md)
* [Using services](docs/services.md)
* [FAQ](docs/faq.md)
services.bitcoind = { enable = true; tor.proxy = true; };
services.lnd.enable = true;
services.electrs.enable = true;
services.mempool.enable = true; # also enables electrs
}
```
Features
---
A [configuration preset](modules/presets/secure-node.nix) for setting up a secure node
* All applications use Tor for outbound connections and support accepting inbound connections via onion services.
Packages come from the consumer's nixpkgs (`pkgs.bitcoind`, `pkgs.lnd`,
`pkgs.electrs`, `pkgs.lndinit`). The only package built here is mempool
(`pkgs/mempool/`).
NixOS modules ([src](modules/modules.nix))
* Application services
* [bitcoind](https://github.com/bitcoin/bitcoin)
* [clightning](https://github.com/ElementsProject/lightning) with support for announcing an onion service
and [database replication](docs/services.md#setup-clightning-database-replication).\
Available plugins:
* [clboss](https://github.com/ZmnSCPxj/clboss): automated C-Lightning Node Manager
* [currencyrate](https://github.com/lightningd/plugins/tree/master/currencyrate): currency converter
* [monitor](https://github.com/lightningd/plugins/tree/master/monitor): helps you analyze the health of your peers and channels
* [rebalance](https://github.com/lightningd/plugins/tree/master/rebalance): keeps your channels balanced
* [trustedcoin](https://github.com/nbd-wtf/trustedcoin) ([experimental](docs/services.md#trustedcoin)): replaces bitcoind with trusted public explorers
* [zmq](https://github.com/lightningd/plugins/tree/master/zmq): publishes notifications via ZeroMQ to configured endpoints
* [lnd](https://github.com/lightningnetwork/lnd) with support for announcing an onion service and [static channel backups](https://github.com/lightningnetwork/lnd/blob/master/docs/recovery.md)
* [Lightning Loop](https://github.com/lightninglabs/loop)
* [Lightning Pool](https://github.com/lightninglabs/pool)
* [charge-lnd](https://github.com/accumulator/charge-lnd): policy-based channel fee manager
* [lndconnect](https://github.com/LN-Zap/lndconnect): connect your wallet to lnd or
clightning [via WireGuard](./docs/services.md#use-zeus-mobile-lightning-wallet-via-wireguard) or
[Tor](./docs/services.md#use-zeus-mobile-lightning-wallet-via-tor)
* [Ride The Lightning](https://github.com/Ride-The-Lightning/RTL): web interface for `lnd` and `clightning`
* [mempool](https://github.com/mempool/mempool): Bitcoin visualizer, explorer, and API service
* [electrs](https://github.com/romanz/electrs): Electrum server
* [fulcrum](https://github.com/cculianu/Fulcrum): Electrum server (see [the module](modules/fulcrum.nix) for a comparison with electrs)
* [btcpayserver](https://github.com/btcpayserver/btcpayserver)
* [liquid](https://github.com/elementsproject/elements): federated sidechain
* [JoinMarket](https://github.com/joinmarket-org/joinmarket-clientserver)
* [JoinMarket Orderbook Watcher](https://github.com/JoinMarket-Org/joinmarket-clientserver/blob/master/docs/orderbook.md)
* [bitcoin-core-hwi](https://github.com/bitcoin-core/HWI)
* Helper
* [netns-isolation](modules/netns-isolation.nix): isolates applications on the network-level via network namespaces
* [nodeinfo](modules/nodeinfo.nix): script which prints info about the node's services
* [backups](modules/backups.nix): duplicity backups of all your node's important files
* [operator](modules/operator.nix): configures a non-root user who has access to client tools (e.g. `bitcoin-cli`, `lightning-cli`)
## What's in the repo
Security
---
See [SECURITY.md](SECURITY.md) for the security policy and how to report a vulnerability.
| Path | Contents |
|---|---|
| `modules/` | `bitcoind`, `lnd`, `electrs`, `mempool`, plus `secrets/`, `operator`, `security`, `onion-services`, `onion-addresses`, `nodeinfo` |
| `pkgs/mempool/` | mempool backend, frontend, rust-gbt and nginx config. `generate.sh` bumps the version and refreshes hashes |
| `pkgs/lib.nix` | systemd hardening and Tor helpers shared by the modules |
nix-bitcoin aims to achieve a high degree of security by building on the following principles:
There is no test suite. Build squirtle in nix-pleb before switching,
and roll back (`nixos-rebuild switch --rollback`) if a service fails at
runtime.
* **Simplicity:** Only services enabled in `configuration.nix` and their dependencies are installed, support for [doas](https://github.com/Duncaen/OpenDoas) ([sudo alternative](https://lobste.rs/s/efsvqu/heap_based_buffer_overflow_sudo_cve_2021#c_c6fcfa)), code is continuously reviewed and refined.
* **Integrity:** The Nix package manager guarantees that all dependencies are exactly specified, 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 features](pkgs/lib.nix), [RPC whitelisting](modules/bitcoind-rpc-public-whitelist.nix) and [netns-isolation](modules/netns-isolation.nix). There's a non-root user *operator* to interact with the various services.
* **Defense-in-depth:** nix-bitcoin supports a [hardened kernel](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/profiles/hardened.nix), services are confined through discretionary access control, Linux namespaces, [dbus firewall](modules/security.nix) and seccomp-bpf with continuous improvements.
## License
Note that if the machine you're deploying *from* is insecure, there is nothing nix-bitcoin can do to protect itself.
Security fund
---
The nix-bitcoin security fund is a 2 of 3 bitcoin multisig address open for donations, used to reward
security researchers who discover vulnerabilities in nix-bitcoin or its upstream dependencies.\
See [Security Fund](./SECURITY.md#nix-bitcoin-security-fund) for details.
Developing
---
See [dev/README](./dev/README.md).
Troubleshooting
---
If you are having problems with nix-bitcoin check the [FAQ](docs/faq.md) or submit an issue.\
There's also a Matrix room at [#general:nixbitcoin.org](https://matrix.to/#/#general:nixbitcoin.org).\
We are always happy to help.
MIT, see [LICENSE](LICENSE).
-109
View File
@@ -1,109 +0,0 @@
# Security Policy
## Reporting a Vulnerability
To report security issues send an encrypted email to the following nix-bitcoin developers or contact them via [matrix](https://matrix.org/).
| Name | GPG Fingerprint | Email | Matrix |
|---------------|----------------------------------------------------|-------------------------|------------------------------------------------------------------------------------|
| Jonas Nick | 36C7 1A37 C9D9 88BD E825 08D9 B1A7 0E4F 8DCD 0366 | jonasd.nick@gmail.com | [@nickler:nixbitcoin.org](https://matrix.to/#/@nickler:nixbitcoin.org) |
| Erik Arvstedt | 4E28 0A8C 1B33 4C86 C26B C134 3331 2B94 4DD9 7846 | erik.arvstedt@gmail.com | [@erikarvstedt:matrix.org](https://matrix.to/#/@erikarvstedt:matrix.org) |
| nixbitcoindev | 577A 3452 7F3E 2A85 E80F E164 DD11 F9AD 5308 B3BA | nixbitcoin@i2pmail.org | [@nixbitcoindev:nixbitcoin.org](https://matrix.to/#/@nixbitcoindev:nixbitcoin.org) |
You can import a GPG key by running the following command with that individual’s fingerprint: `gpg --keyserver hkps://keys.openpgp.org --recv-keys "<fingerprint>"`. Ensure that you put quotes around fingerprints containing spaces.
[Responsible disclosures](https://en.wikipedia.org/wiki/Coordinated_vulnerability_disclosure) may qualify for a reward from the nix-bitcoin security fund (see [below](#nix-bitcoin-security-fund)).
## Wall of Fame
### [haoxucu](https://github.com/haoxucu)
* Reported that `netns-exec` was executable by all normal users ([fixed in `34a18f92`](https://github.com/fort-nix/nix-bitcoin/commit/34a18f92eeacc754e5857249aaf8decf24e98cde)); received 5% of the fund.
* Reported that `lnd-create-macaroons` exposed the LND admin macaroon in `curl`'s process arguments ([fixed in `df184b6e`](https://github.com/fort-nix/nix-bitcoin/commit/df184b6e06cc3404add42ccf5ae68306395e8d6c)); received 10% of the fund.
Both rewards were paid in transaction [`5b93fbad4b9a2c35daaf40b74fc76f0b69d2b75bc4da927cd3398dbc432eb888`](https://mempool.nixbitcoin.org/tx/5b93fbad4b9a2c35daaf40b74fc76f0b69d2b75bc4da927cd3398dbc432eb888).
## nix-bitcoin security fund
The nix-bitcoin security fund rewards security researchers who discover and
report vulnerabilities in nix-bitcoin or its upstream dependencies.\
It is held on a 2 of 3 bitcoin multisig address and is open for donations:
```
bc1qrpnz05n0yznaj6yw82wy8dhwuqz86s87vdlhq4cu92fus9qal25s555wsy
```
([View balance](https://mempool.nixbitcoin.org/address/bc1qrpnz05n0yznaj6yw82wy8dhwuqz86s87vdlhq4cu92fus9qal25s555wsy))
Rewards are paid out as percentages of the total fund, rather than as fixed
amounts.
The nix-bitcoin developers [listed above](#reporting-a-vulnerability) each hold
one key to the multisig address and collectively form the nix-bitcoin developer
quorum.
### Eligible Vulnerabilities
The following types of vulnerabilities qualify for rewards, to the exclusion of
all other security vulnerabilities.
| Type | Description | Examples |
| :-: | :-: | :-: |
| Outright Vulnerabilities | Vulnerabilities in nix-bitcoin specific tooling (except CI tooling) | privilege escalation in SUID binary `netns-exec`, improper release signature verification through `fetch-release` |
| Violations of [PoLP](https://en.wikipedia.org/wiki/Principle_of_least_privilege) | nix-bitcoin services are given too much privilege over the system or unnecessary access to other nix-bitcoin services, or one of the nix-bitcoin isolation measures is incorrectly implemented | `netns-isolation` doesn't work, RTL has access to bitcoin RPC interface or files |
| Vulnerabilities in Dependencies | A vulnerability in any dependency of a nix-bitcoin installation with a configuration consisting of any combination of the following services: bitcoind, clightning, lnd, electrs, joinmarket, btcpayserver, liquidd.<br />**Note:** The vulnerability must first be reported to and handled by the maintainers of the dependency before it qualifies for a reward| Compromised NixOS expression pulls in malicious package, JoinMarket pulls in a python dependency with a known severe vulnerability |
| Bad Documentation | Our documentation suggests blatantly insecure things | `install.md` tells you to add our SSH keys to your root user |
| Compromise of Signing Key | Compromise of the nix-bitcoin signing key, i.e., `0xB1A70E4F8DCD0366` | Leaking the key, managing to sign something with it |
### Reward
Researchers qualify for a maximum reward[^1] of 10% of the total fund holdings for
reporting any vulnerability that matches the above eligibility requirements. If
a vulnerability or any combination of a number of vulnerabilities that meet the
above-described eligibility requirements can lead to a realistic attack on
nix-bitcoin users, researchers qualify for a higher maximum reward[^1] depending
the final outcome of the attack scenario:
| Outcome | Description | Maximum Reward of Total Fund[^1] |
| :-: | :-: | :-: |
| Loss of Funds | Attack allows stealing or destroying user's funds | 50 % |
| Loss of Privacy | Attack allows exfiltrating sensitive information or otherwise attributing a user's real world identity to his nix-bitcoin node or funds held/managed thereon without the user specifically opting-in to this (e.g., by disabling the `secure-node` preset) | 25 % |
| Denial of Service | Attack allows crashing a service or otherwise denying a user service from his node | 25 % |
All other reported vulnerabilities which meet the above requirements without a
clear and plausible attack scenario receive a maximum reward[^1] of 10% of the
fund.
[^1]: Rewards are subject to a discount at the discretion of the nix-bitcoin
developer quorum for reasons such as insignificance of the vulnerability or
obscurity of the victim's required configuration, as well as simple mitigation
(i.e. the attack should have been mitigated anyway by common-sense security
measures) or complex/unlikely attack execution.
### Policy
* Vulnerabilities must be [responsibly
disclosed](https://en.wikipedia.org/wiki/Coordinated_vulnerability_disclosure).
* E2EE: Vulnerabilities must be disclosed via end-to-end encrypted communication
methods, such as PGP E-Mail or Matrix.
* Wall of Fame: In addition to the above rewards, security researchers will also
be added to the Wall of Fame, unless, of course, they wish to remain
anonymous.
* First come, first serve: Rewards are awarded strictly on a first come, first
serve basis from the date they were responsibly disclosed in their entirety.
Multiple reports from the same researcher can either be bundled for a higher
likelihood of receiving the full maximum reward or rewarded individually,
proportional to the remaining amount.
* Exclusion of dependencies with existing bug bounty programms: Software which
is covered by an existing bug bounty program is not eligible for rewards under
the "Vulnerabilities in Dependencies" category.
* Exclusion of dependencies with known vulnerabilities that are in the process
of being patched: Software with a known vulnerability where there is reason to
believe that the patch is still under development or simply has not yet been
ported to NixOS, due to the relative recency of the patch, is not eligible for
rewards under the "Vulnerabilities in Dependencies" category.
* Termination: The fund can be terminated at any time by the quorum of key
holders in which case the holdings are donated to non-profit organizations.
* This document may be updated over time to ensure smooth and purposeful
operation of the fund as an incentive for security researchers to investigate
and report vulnerabilities in the nix-bitcoin ecosystem.
-101
View File
@@ -1,101 +0,0 @@
This directory contains docs and helper scripts for developing and debugging:
- [`dev.sh`](./dev.sh): misc dev helpers
- [`dev-features.sh`](./dev-features.sh): helpers for developing specific
nix-bitcoin features, like services
- [`topics`](./topics) features specific topics
- [`dev-scenarios.nix`](./dev-scenarios.nix): extra test scenarios used in the above scripts
See also: [test/README.md](../test/README.md)
## Run a dev shell
There are two ways to run a dev shell:
### 1. Run command `nix develop`
This starts a shell with [`test/run-tests.sh`](../test/run-tests.sh) and
the scripts in dir [`helper`](../helper) added to `PATH`.
### 2. Setup and start the `direnv` dev env
This is an opinionated, [direnv](https://direnv.net/)-based dev env, optimized for developer experience.
[`dev-env/create.sh`](./dev-env/create.sh) creates a git repo with the following contents:
- Dir `src` which contains the nix-bitcoin repo
- Dir `bin` for helper scripts
- File `scenarios.nix` for custom test scenarios
- File `.envrc` that defines a [direnv](https://direnv.net/) environment,
mainly for adding nix-bitcoin and helper scripts to `PATH`
#### Installation
1. [Install direnv](https://direnv.net/docs/installation.html).\
If you use NixOS (and Bash as the default shell), just add the following to your system config:
```nix
environment.systemPackages = [ pkgs.direnv ];
programs.bash.interactiveShellInit = ''
eval "$(direnv hook bash)"
'';
```
2. Create the dev env:
```bash
# Set up a dev environment in dir ~/dev/nix-bitcoin.
# The dir is created automatically.
./dev-env/create.sh ~/dev/nix-bitcoin
cd ~/dev/nix-bitcoin
# Enable direnv
direnv allow
```
3. Optional: Editor integration
- Add envrc support to your editor
- Setup your editor so you can easily execute lines or paragraphs from a shell script
file in a shell.\
This simplifies using dev helper scripts like [`./dev.sh`](./dev.sh).
#### Explore the dev env
```bash
# The direnv is automatically activated when visiting any subdir of ~/dev/nix-bitcoin
cd ~/dev/nix-bitcoin
ls -al . bin lib
# The direnv config file
cat .envrc
# You can use this file to define extra scenarios
cat scenarios.nix
# Binary `dev-run-tests` runs nix-bitcoin's `run-tests.sh` with extra scenarios from ./scenarios.nix
# Example:
# Run command `nodeinfo` in `myscenario` (defined in ./scenarios.nix) via a container
dev-run-tests -s myscenario container --run c nodeinfo
# Equivalent (shorthand)
te -s myscenario container --run c nodeinfo
# Run the tests for `myscenario` in a VM
te -s myscenario
# Start an interactive shell inside a VM
te -s myscenario vm
```
See also: [test/README.md](../test/README.md)
## Adding a new service
It's easiest to use an existing service as a template:
- [electrs.nix](../modules/electrs.nix): a basic service
- [clightning.nix](../modules/clightning.nix): simple, but covers a few more features.\
(A `cli` binary and a runtime-composed config to include secrets.)
- [rtl.nix](../modules/rtl.nix): includes a custom package, defined in [pkgs/rtl](../pkgs/rtl).\
Most other services use packages that are already included in nixpkgs.
## Switching to a new NixOS release
- Run command `update-flake.sh 26.05`
- Treewide: check if any `TODO-EXTERNAL` comments can be resolved
-65
View File
@@ -1,65 +0,0 @@
#!/usr/bin/env bash
# shellcheck disable=SC2016
set -euo pipefail
destDir=${1:-nix-bitcoin}
scriptDir=$(cd "${BASH_SOURCE[0]%/*}" && pwd)
mkdir -p "$destDir/"{bin,lib}
cd "$destDir"
if [[ ! -e src ]]; then
echo "Cloning fort-nix/nix-bitcoin"
git clone https://github.com/fort-nix/nix-bitcoin src
fi
echo 'export root=$PWD
export src=$root/src
PATH_add bin
PATH_add src/helper' > .envrc
if [[ ! -e scenarios.nix ]]; then
cp "$scriptDir/template-scenarios.nix" scenarios.nix
fi
install -m 755 <(
echo '#!/usr/bin/env bash'
echo 'exec run-tests.sh --extra-scenarios "$root/scenarios.nix" "$@"'
) bin/dev-run-tests
install -m 755 <(
echo '#!/usr/bin/env bash'
echo 'exec $root/src/test/run-tests.sh --out-link-prefix /tmp/nix-bitcoin/test "$@"'
) bin/run-tests.sh
ln -sfn dev-run-tests bin/te
## nix-bitcoin-firejail
echo '# Add your shell config files here that should be accessible in the sandbox
whitelist ${HOME}/.bashrc
read-only ${HOME}/.bashrc' > lib/nix-bitcoin-firejail.conf
install -m 755 <(
echo '#!/usr/bin/env bash'
echo '# A sandbox for running shells/binaries in an isolated environment:'
echo '# - The sandbox user is the calling user, with all capabilities dropped'
echo '# and with no way to gain new privileges (e.g. via `sudo`).'
echo '# - $HOME is bind-mounted to a dir that only contains shell config files and files required by direnv.'
echo '#'
echo '# You can modify the firejail env by editing `lib/nix-bitcoin-firejail.conf` in your dev env dir.'
echo 'exec firejail --profile="$root/lib/nix-bitcoin-firejail.conf" --profile="$root/src/dev/dev-env/nix-bitcoin-firejail.conf" "$@"'
) bin/nix-bitcoin-firejail
echo "1" > lib/dev-env-version
## git
echo '/src' > .gitignore
if [[ ! -e .git ]]; then
git init
git add .
git commit -a -m init
fi
-16
View File
@@ -1,16 +0,0 @@
pkgs:
pkgs.mkShell {
shellHook = ''
# A known rev from the master branch to test whether `nix develop`
# is called inside the nix-bitcoin repo
rev=5cafafd02777919c10e559b5686237fdefe920c2
if git cat-file -e $rev &>/dev/null; then
root=$(git rev-parse --show-toplevel)
export PATH=$root/test:$root/helper:$PATH
else
echo 'Error: `nix develop` must be called inside the nix-bitcoin repo.'
exit 1
fi
'';
}
-25
View File
@@ -1,25 +0,0 @@
include default.local
include globals.local
include disable-common.inc
include disable-programs.inc
caps.drop all
netfilter
noinput
nonewprivs
noroot
notv
novideo
protocol unix,inet,inet6
seccomp
## Enable features
allow-debuggers
# Enable direnv configs
whitelist ${HOME}/.config/direnv
read-only ${HOME}/.config/direnv
whitelist ${HOME}/.local/share/direnv
read-only ${HOME}/.local/share/direnv
-20
View File
@@ -1,20 +0,0 @@
{ pkgs, lib, scenarios, nix-bitcoin }:
with lib;
rec {
# For more examples, see `scenarios` and `exampleScenarios` in ./src/test/tests.nix
template = { config, pkgs, lib, ... }: {
imports = [
(nix-bitcoin + "/modules/presets/secure-node.nix")
scenarios.netnsBase
scenarios.regtestBase
];
test.container.enableWAN = true;
test.container.exposeLocalhost = true;
};
myscenario = { config, pkgs, lib, ... }: {
services.clightning.enable = true;
nix-bitcoin.nodeinfo.enable = true;
};
}
-320
View File
@@ -1,320 +0,0 @@
# shellcheck disable=SC2086,SC2154
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# Run tests
# See ../test/README.md for a tutorial
# and ../test/run-tests.sh for a complete documentation
# Start a shell in a container
run-tests.sh -s electrs container
# Run a command in a container.
# The container is deleted afterwards.
run-tests.sh -s electrs container --run c journalctl -u electrs
# Run a bash command
run-tests.sh -s bitcoind container --run c bash -c "sleep 1; journalctl -u bitcoind"
run-tests.sh -s '{
imports = [ scenarios.regtestBase ];
services.electrs.enable = true;
}' container --run c journalctl -u electrs
run-tests.sh -s "{
services.electrs.enable = true;
nix-bitcoin.nodeinfo.enable = true;
}" container --run c nodeinfo
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# Get generic node infos
# Start container shell
run-tests.sh -s bitcoind container
# Run commands inside the shell:
# The node's services
c systemctl status
# Failed units
c systemctl list-units --failed
# Analyze container boot performance
c systemd-analyze critical-chain
# Listening TCP sockets
c netstat -nltp
# Listening sockets
c netstat -nlp
# The container root filesystem
ls -al /var/lib/nixos-containers/nb-test
# The container root filesystem on NixOS systems with stateVersion < 22.05
ls -al /var/lib/containers/nb-test
# Start a shell in the context of a service process.
# Must be run inside the container (enter with cmd `c`).
enter_service() {
name=$1
pid=$(systemctl show -p MainPID --value "$name")
IFS=- read -r uid gid < <(stat -c "%u-%g" "/proc/$pid")
nsenter --all -t "$pid" --setuid "$uid" --setgid "$gid" bash
}
enter_service clightning
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# bitcoind
run-tests.sh -s bitcoind container
c systemctl status bitcoind
c systemctl cat bitcoind
c journalctl --output=short-precise -u bitcoind
ls -al /var/lib/nixos-containers/nb-test/var/lib/bitcoind
c bitcoin-cli getpeerinfo
c bitcoin-cli getnetworkinfo
c bitcoin-cli getblockchaininfo
run-tests.sh -s '{
imports = [ scenarios.regtestBase ];
services.bitcoind.enable = true;
}' container
address=$(c bitcoin-cli getnewaddress)
echo $address
c bitcoin-cli generatetoaddress 10 $address
# Run bitcoind with network access
run-tests.sh -s "{
test.container.enableWAN = true;
services.bitcoind.enable = true;
}" container --run c journalctl -u bitcoind -f
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# clightning
run-tests.sh -s clightning container
c systemctl status clightning
c journalctl --output=short-precise -u clightning
c lightning-cli getinfo
# Plugins
run-tests.sh -s "{
services.clightning.enable = true;
test.features.clightningPlugins = true;
}" container
c lightning-cli plugin list
# Show plugin config
nix eval --raw .#makeTest --apply '
makeTest: let
config = (makeTest {
config = {
services.clightning.enable = true;
test.features.clightningPlugins = true;
};
}).nodes.machine;
in
config.services.clightning.extraConfig
'
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# clightning-rest
run-tests.sh -s clightning-rest container
c systemctl status clightning-rest
c journalctl -u clightning-rest
c systemctl status clightning-rest-migrate-datadir
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# electrs
run-tests.sh -s "{
imports = [ scenarios.regtestBase ];
services.electrs.enable = true;
}" container
c systemctl status electrs
c systemctl cat electrs
c journalctl --output=short-precise -u electrs
electrs_rpc() {
echo "$1" | c nc 127.0.0.1 50001 | head -1 | jq
}
electrs_rpc '{"method": "server.version", "id": 0, "params": ["electrum/3.3.8", "1.4"]}'
electrs_rpc '{"method": "blockchain.headers.subscribe", "id": 0}'
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# fulcrum
run-tests.sh -s "{
imports = [ scenarios.regtestBase ];
services.fulcrum.enable = true;
}" container
c systemctl status fulcrum
c systemctl cat fulcrum
c journalctl --output=short-precise -u fulcrum
fulcrum_rpc() {
echo "$1" | c nc 127.0.0.1 50002 | head -1 | jq
}
fulcrum_rpc '{"method": "server.version", "id": 0, "params": ["electrum/3.3.8", "1.4"]}'
fulcrum_rpc '{"method": "blockchain.headers.subscribe", "id": 0}'
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# lnd
run-tests.sh -s lnd container
c systemctl status lnd
c journalctl -u lnd
c lncli getinfo
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# lightning-loop
run-tests.sh -s lightning-loop container
c systemctl status lightning-loop
c journalctl -u lightning-loop
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# btcpayserver
# https://docs.btcpayserver.org/Development/GreenFieldExample/
run-tests.sh -s btcpayserver-regtest container
c systemctl status btcpayserver
c journalctl -u btcpayserver
c systemctl cat btcpayserver
c systemctl status nbxplorer
c journalctl -u nbxplorer
## Access the API
request() {
local type=$1
local method=$2
local body=$3
shift; shift; shift
curl -sSL -H "Content-Type: application/json" -X $type --user "a@a.a:aaaaaa" \
-d "$body" "$@" "$ip:23000/api/v1/$method" | jq
}
post() {
local method=$1
local body=$2
shift; shift
request post "$method" "$body" "$@"
}
get() {
local method=$1
request get "$method"
}
# Create new user
post users '{"email": "a@a.a", "password": "aaaaaa", "isAdministrator": true}'
# Login with:
# user: a@a.a
# password: aaaaaa
runuser -u "$(logname)" -- xdg-open http://$ip:23000
# create store
post stores '{"name": "a", "defaultPaymentMethod": "BTC_LightningNetwork"}'
post stores '{"name": "a", "defaultPaymentMethod": "BTC"}'
store=$(get stores | jq -r .[].id)
echo $store
get stores/$store
get stores/$store/payment-methods
get stores/$store/payment-methods/LightningNetwork
# Connect to internal lightning node (internal API, doesn't work)
# Lightning must be manually setup via the webinterface.
post stores/$store/lightning/BTC/setup "" --data-raw 'LightningNodeType=Internal&ConnectionString=&command=save'
nix run --inputs-from . nixpkgs#lynx -- --dump http://$ip:23000/embed/$store/BTC/ln
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# liquid
run-tests.sh -s liquid container
c systemctl status liquidd
c elements-cli getpeerinfo
c elements-cli getnetworkinfo
c liquidswap-cli --help
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# tor
run-tests.sh container
c cat /var/lib/tor/state
c ls -al /var/lib/tor/onion/
c ls -al /var/lib/tor/onion/bitcoind
c ls -al /var/lib/tor/onion/clightning-rest
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# joinmarket
run-tests.sh -s joinmarket container
c systemctl status joinmarket
c journalctl -u joinmarket
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# joinmarket-ob-watcher
# This starts a container with WAN access, so that jm-ob-watcher
# can connect to the joinmarket IRC servers over Tor
run-tests.sh -s jm-ob-watcher container
c systemctl status joinmarket-ob-watcher
c journalctl -u joinmarket-ob-watcher
# Manually wait for string 'started http server, visit http://127.0.0.1:62601/'
# This can take >10 minutes when the Tor network is under heavy load.
# While connecting, errors like `We failed to connect and handshake with ANY directories...`
# may be shown.
c journalctl -f -u joinmarket-ob-watcher
# Check webinterface
c curl 127.0.0.1:62601
nix run --inputs-from . nixpkgs#lynx -- --dump $ip:62601
c curl -s 127.0.0.1:62601 | grep -i "orders found"
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# trustedcoin
run-tests.sh -s trustedcoin-online container
c systemctl start clightning
c journalctl -u clightning -f
# This should show log msgs like
# plugin-trustedcoin returning block 801409, 0000000000000000000482ddc4…, 1483968 bytes
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# mempool
run-tests.sh -s mempool-regtest container
c systemctl status mempool
c journalctl -u mempool
c systemctl status mysql
c nodeinfo
# Check backend
c curl -fsS localhost:8999/api/v1/blocks/1 | jq
c curl -fsS localhost:8999/api/v1/blocks/tip/height | jq
c curl -fsS localhost:8999/api/v1/address/1CGG9qVq2P6F7fo6sZExvNq99Jv2GDpaLE | jq
# Check frontend
c systemctl status nginx
c journalctl -u nginx
c curl -fsS localhost:60845
c curl -fsS localhost:60845/api/mempool | jq
c curl -fsS localhost:60845/api/blocks/1 | jq
c curl -fsS localhost:60845/api/v1/blocks/1 | jq
c curl -fsS localhost:60845/api/blocks/tip/height | jq
# Open frontend
# shellcheck disable=SC2154
runuser -u "$(logname)" -- xdg-open "http://$ip:60845/"
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# rtl
# see ./topics/rtl.sh
-121
View File
@@ -1,121 +0,0 @@
# Extra scenarios for developing and debugging
{ lib, scenarios }:
with lib;
{
btcpayserver-regtest = {
imports = [ scenarios.regtestBase ];
services.btcpayserver.enable = true;
test.container.exposeLocalhost = true;
# services.btcpayserver.lbtc = false;
# Required for testing interactive plugin installation
test.container.enableWAN = true;
};
# A node with internet access to test joinmarket-ob-watcher
jm-ob-watcher = {
services.joinmarket-ob-watcher.enable = true;
# Don't download blocks
services.bitcoind.extraConfig = ''
connect = 0;
'';
test.container.exposeLocalhost = true;
test.container.enableWAN = true;
};
rtl-dev = { config, pkgs, lib, ... }: {
imports = [
# scenarios.netnsBase
# scenarios.regtestBase
];
services.rtl = {
enable = true;
nodes.clightning = {
enable = true;
extraConfig.Settings.themeColor = "INDIGO";
};
# nodes.lnd.enable = false;
# nodes.reverseOrder = true;
nightTheme = true;
extraCurrency = "CHF";
};
test.container.exposeLocalhost = true;
nix-bitcoin.nodeinfo.enable = true;
# test.container.enableWAN = true;
};
wireguard-lndconnect-online = { config, pkgs, lib, ... }: {
imports = [
../modules/presets/wireguard.nix
scenarios.regtestBase
];
# 51820 (default wg port) + 1
networking.wireguard.interfaces.wg-nb.listenPort = 51821;
test.container.enableWAN = true;
# test.container.exposeLocalhost = true;
services.clightning.extraConfig = "disable-dns";
services.lnd = {
enable = true;
lndconnect = {
enable = true;
onion = true;
};
};
services.clightning = {
enable = true;
plugins.clnrest = {
enable = true;
lnconnect = {
enable = true;
onion = true;
};
};
};
services.clightning-rest = {
enable = true;
lndconnect = {
enable = true;
onion = true;
};
};
nix-bitcoin.nodeinfo.enable = true;
};
trustedcoin-online = {
services.clightning = {
enable = true;
tor.proxy = true;
plugins.trustedcoin.enable = true;
plugins.trustedcoin.tor.proxy = false;
};
# Don't run clightning on startup.
# This breaks the follwing dependency cycle:
# clightning
# -> network (trustedcoin fails and exits clightning without network access)
# -> multi-user.target (NixOS containers only gain network access after multi-user.target has completed)
# -> clightning
systemd.services.clightning.wantedBy = mkForce [];
test.container.enableWAN = true;
};
mempool-regtest = {
imports = [
scenarios.regtestBase
];
services.mempool = {
enable = true;
frontend = {
address = "0.0.0.0";
settings.LIQUID_ENABLED = true;
};
};
nix-bitcoin.nodeinfo.enable = true;
};
}
-129
View File
@@ -1,129 +0,0 @@
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# Access nix-bitcoin flake packages
function nb() {
nix build --no-link --print-out-paths --print-build-logs "$@"
}
# A package defined by nix-bitcoin
nb .#joinmarket
# Equivalent
nb .#modulesPkgs.joinmarket
# A nix-bitcoin python package
nb .#nbPython3Packages.pyln-client
# A pinned package from nixpkgs(-unstable)
nb .#pinned.electrs
# Equivalent
nb .#modulesPkgs.electrs
## Eval packages
# Check version
nix eval .#joinmarket.version
# Eval derivation. --raw is needed due to a Nix bug (https://github.com/NixOS/nix/issues/5731)
nix eval --raw .#joinmarket; echo
# Check the version of a package in the nixpkgs(-unstable) inputs of the nix-bitcoin flake
nix eval --inputs-from . nixpkgs#electrs.version
nix eval --inputs-from . nixpkgs-unstable#electrs.version
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# Inspect test systems
# Build a test system
nix build -o /tmp/system --print-build-logs "$(nix eval --raw .#tests.default --apply '
test: test.nodes.machine.system.build.toplevel.drvPath
')"
readlink /tmp/system
# Inspect system files
cat /tmp/system/activate
cat /tmp/system/etc/system/bitcoind.service
# Evaluate a config value
nix eval .#tests.default --apply '
test: test.nodes.machine.services.bitcoind.rpc.port
'
# Evaluate a config value in a custom test
nix eval .#makeTest --apply '
makeTest: let
config = (makeTest {
config = {
services.electrs.port = 10000;
};
}).nodes.machine;
in
config.services.electrs.port
'
# Evaluate a config value in a scenario defined in a file
nix eval --impure .#getTest --apply '
getTest: let
config = (getTest {
name = "default";
extraScenariosFile = builtins.getEnv("root") + "/scenarios.nix";
}).nodes.machine;
in
config.services.bitcoind.port
'
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# Manually run a nix-bitcoin container, without the test framework.
# This allows sharing directories with the container host via option `bindMounts.`
read -rd '' src <<'EOF' || :
let
nix-bitcoin = builtins.getFlake "git+file://${toString ../.}";
in
nix-bitcoin.inputs.extra-container.lib.buildContainers {
system = "x86_64-linux";
inherit (nix-bitcoin.inputs) nixpkgs;
# legacyInstallDirs = true;
config = {
imports = [ ../test/lib/extra-container-workaround.nix ];
containers.nb-adhoc = {
# bindMounts."/shared" = { hostPath = "/my/hostpath"; isReadOnly = false; };
extra.addressPrefix = "10.200.255";
config = {
imports = [ nix-bitcoin.nixosModules.default ];
services.bitcoind.enable = true;
nix-bitcoin.generateSecrets = true;
nix-bitcoin.nodeinfo.enable = true;
};
};
};
}
EOF
nix run --impure --expr "$src"
# Run command in container
nix shell --impure --expr "$src" -c container --run c nodeinfo
# TODO-EXTERNAL: Use this instead when https://github.com/NixOS/nix/issues/7444 is fixed
# nix run --impure --expr "$src" -- --run c nodeinfo
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# Show build logs from a CI test run
#
# If a specific test derivation was already built successfully, the test is not rerun
# and the CI logs don't show the test output.
# To view the test output:
# 1. Get the test store path at the end of the CI logs
# 2.
fetch_build_log() {
local log=$1
nix cat-store --store https://nix-bitcoin.cachix.org "$log/output.xml" |
nix shell --inputs-from . nixpkgs#html-tidy -c tidy -xml -i - > /tmp/build-output.xml
echo
echo "Fetched log to /tmp/build-output.xml"
}
# Set this to your store path
fetch_build_log /nix/store/0cdjhvg84jsp47f3357812zjmj2wmz94-vm-test-run-nix-bitcoin-default
# Show runtime
grep "script finished in" /tmp/build-output.xml
# View XML with node folding
firefox /tmp/build-output.xml
-70
View File
@@ -1,70 +0,0 @@
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# Test Tor and WireGuard connections on a mobile device
# 1. Run container
run-tests.sh -s wireguard-lndconnect-online container
# 2. Test connecting via Tor
# Print QR codes for lnd, clightning-rest connections via Tor
c lndconnect
c lnconnect-clnrest
c lndconnect-clightning
# Add these to Zeus >= 0.9.0.
# To explicitly check if the connection is successful, press the node logo in the top
# left corner, and then "Node Info".
# Debug
c lndconnect --url
c lnconnect-clnrest --url
c lndconnect-clightning --url
# 3. Test connecting via WireGuard
# 3.1 Forward WireGuard port from the container host to the container
iptables -t nat -A PREROUTING -p udp --dport 51821 -j DNAT --to-destination 10.225.255.2
# 3.2. Optional: When your container host has an external firewall,
# forward the WireGuard port to the container host:
# - Port: 51821
# - Protocol: UDP
# - Destination: IPv4 of the container host
# 3.2 Print QR code and setup wireguard on the mobile device
c nix-bitcoin-wg-connect
c nix-bitcoin-wg-connect --text
# Print QR codes for lnd, clightning-rest connections via WireGuard
c lndconnect-wg
c lnconnect-clnrest-wg
c lndconnect-clightning-wg
# Add these to Zeus >= 0.9.0.
# To explicitly check if the connection is successful, press the menu button in the top
# left corner, and then "Node Info".
# Debug
c lndconnect-wg --url
c lnconnect-clnrest-wg --url
c lndconnect-clightning-wg --url
# 3.3.remove external firewall port forward, remove local port forward:
iptables -t nat -D PREROUTING -p udp --dport 51821 -j DNAT --to-destination 10.225.255.2
# Now exit the container shell
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# Debug lndconnect
run-tests.sh -s wireguard-lndconnect-online container
c nodeinfo
c lndconnect --url
c lndconnect-wg --url
c lndconnect-clnrest --url
c lndconnect-clnrest-wg --url
c lndconnect-clightning --url
c lndconnect-clightning-wg --url
c lndconnect
c lndconnect-wg
c lndconnect-clightning
c lndconnect-clightning-wg
-45
View File
@@ -1,45 +0,0 @@
# shellcheck disable=SC2154
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# Docs
# https://github.com/Ride-The-Lightning/RTL
# config options: https://github.com/Ride-The-Lightning/RTL/blob/master/.github/docs/Application_configurations.md
# https://github.com/Ride-The-Lightning/c-lightning-REST
# local src: ~/s/RTL/
# Browse API docs (in container shell)
runuser -u "$(logname)" -- xdg-open "http://$ip:4001/api-docs/"
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# Debug the service
run-tests.sh -s rtl-dev container
c systemctl status rtl
c journalctl -u rtl
c cat /var/lib/rtl/RTL-Config.json
# Open webinterface. Password: a
runuser -u "$(logname)" -- xdg-open "http://$ip:3000"
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# Build RTL manually
# [[~/s/RTL/dockerfiles/Dockerfile][dockerfile]]
# [[~/s/RTL/package.json][package.json]]
rtl_src=~/s/RTL
git clone https://github.com/Ride-The-Lightning/RTL "$rtl_src"
nix build -o /tmp/nix-bitcoin-dev/nodejs --inputs-from . nixpkgs#nodejs_22
# Start a shell in a sandbox
env --chdir "$rtl_src" nix-bitcoin-firejail --whitelist="$rtl_src" --whitelist=/tmp/nix-bitcoin-dev/nodejs
PATH=/tmp/nix-bitcoin-dev/nodejs/bin:"$PATH"
# Install
npm ci --omit=dev --omit=optional --no-update-notifier --ignore-scripts
# If the above fails, try: (details: https://github.com/Ride-The-Lightning/RTL/issues/1182)
npm ci --omit=dev --omit=optional --no-update-notifier --ignore-scripts --legacy-peer-deps
# Run
node rtl --help
git clean -xdf # Cleanup repo
-264
View File
@@ -1,264 +0,0 @@
# Managing your deployment
This section applies to users of the deployment method described in the [installation guide](./install.md).
## Deployment shell
Run command `nix-shell` in your deployment directory.\
You now have access to deployment commands:
- `deploy`\
Deploy the current configuration to your node.
- `eval-config`\
Locally evaluate the configuration. This is useful to check for configuration errors.
- `h`, `help`\
Show help
## Updating nix-bitcoin
Run `update-nix-bitcoin` from the deployment shell.\
This fetches the latest release, verifies its signatures and updates `nix-bitcoin-release.nix`.
# Customizing your configuration
## Get started with Nix
See [Nix - A One Pager](https://github.com/tazjin/nix-1p) for a short guide
to Nix, the language used in `configuration.nix`.\
You can follow along this guide by running command `nix repl` which allows you to interactively
evaluate Nix expressions.
For a general introduction to the Nix and NixOS ecosystem, see [nix.dev](https://nix.dev/).
## Set options
All features and services are configurable through options. You can find a list of
supported options at the top of each nix-bitcoin [module](../modules/modules.nix)
(Examples: [bitcoind.nix](../modules/bitcoind.nix), [btcpayserver.nix](../modules/btcpayserver.nix)).
Example: Set some `bitcoind` options by adding these lines to your `configuration.nix`:
```nix
# Use a custom data dir
services.bitcoind.dataDir = "/my/datadir";
# Enable txindex
services.bitcoind.txindex = true;
```
You can also use regular [NixOS options](https://search.nixos.org/options)
for configuring your system:
```nix
networking.hostName = "myhost";
time.timeZone = "UTC";
```
## Debug your configuration
To print the values of specific options of your config, add the following to your `configuration.nix`:
```nix
system.extraDependencies = let
debugVal = config.networking.firewall.allowedTCPPorts;
# More example options:
# debugVal = config.environment.systemPackages;
# debugVal = config.services.bitcoind.dataDir;
in lib.traceSeqN 3 debugVal [];
```
and run command `eval-config` from the deployment shell.
# Allowing external connections to services
## Allow peer connections to bitcoind
```nix
services.bitcoind = {
# Accept incoming peer connections
listen = true;
# Listen to connections on all interfaces
address = "0.0.0.0";
# Set this to also add IPv6 connectivity.
extraConfig = ''
bind=::
'';
# If you're using the `secure-node.nix` template, set this to allow non-Tor connections
# to bitcoind
tor.enforce = false;
# Also set this if bitcoind should not use Tor for outgoing peer connections
tor.proxy = false;
};
# Open the p2p port in the firewall
networking.firewall.allowedTCPPorts = [ config.services.bitcoind.port ];
```
## Allow bitcoind RPC connections from LAN
```nix
services.bitcoind = {
# Listen to RPC connections on all interfaces
rpc.address = "0.0.0.0";
# Allow RPC connections from external addresses
rpc.allowip = [
"10.10.0.0/24" # Allow a subnet
"10.50.0.3" # Allow a specific address
"0.0.0.0/0" # Allow all addresses
];
# Set this if you're using the `secure-node.nix` template
tor.enforce = false;
};
# Open the RPC port in the firewall
networking.firewall.allowedTCPPorts = [ config.services.bitcoind.rpc.port ];
```
## Allow connections to electrs
```nix
services.electrs = {
# Listen to connections on all interfaces
address = "0.0.0.0";
# Set this if you're using the `secure-node.nix` template
tor.enforce = false;
};
# Open the electrs port in the firewall
networking.firewall.allowedTCPPorts = [ config.services.electrs.port ];
```
You can use the same approach to allow connections to other services.
# Migrate existing services to nix-bitcoin
## Example: bitcoind
```shell
# 1. Stop bitcoind on your node
ssh root@nix-bitcoin-node 'systemctl stop bitcoind'
# Also stop bitcoind on the node that you'll be copying data from
# 2. Copy the data to the nix-bitcoin node
# Important: Add a trailing slash to the source path
rsync /path/to/existing/bitcoind-datadir/ root@nix-bitcoin-node:/var/lib/bitcoind
# 3. Fix data dir permissions on the nix-bitcoin node
ssh root@nix-bitcoin-node 'chown -R bitcoin: /var/lib/bitcoind'
# 4. Start bitcoind
ssh root@nix-bitcoin-node 'systemctl start bitcoind'
```
You can use the same workflow for other services.\
The default data dir path is `/var/lib/<service>` for all services.
Some services require extra steps:
- lnd
Copy your wallet password to `$secretsDir/lnd-wallet-password` (See: [Secrets dir](#secrets-dir)).
- btcpayserver
Copy the postgresql database:
```shell
# Export (on the other node)
sudo -u postgres pg_dump YOUR_BTCPAYSERVER_DB > export.sql
# Restore (on the nix-bitcoin node)
sudo -u postgres psql btcpaydb < export.sql
```
- joinmarket
Copy your wallet to `/var/lib/joinmarket/wallets/wallet.jmdat`.\
Write your wallet password, without a trailing newline, to
`$secretsDir/jm-wallet-password` (See: [Secrets dir](#secrets-dir)).
# Use bitcoind from another node
Here's how to use a bitcoind instance running on another node within a nix-bitcoin config:
```nix
imports = [ <nix-bitcoin/modules/presets/bitcoind-remote.nix> ];
services.bitcoind = {
enable = true;
# Address of the other node
address = "10.10.0.2";
rpc.address = "10.10.0.2";
# Some nix-bitcoin services require whitelisted bitcoind p2p connections
# to work reliably.
# Search for `whitelistedPort` in this repo to see the affected services.
# If you're using one of these services, either add a whitelisted p2p port
# on your remote node via `whitebind` and set it here:
whitelistedPort = <remote whitebind RPC port>;
#
# Or use the default p2p port and add `whitelist=<address of this node>` to
# your remote bitcoind config:
whitelistedPort = config.services.bitcoind.port;
rpc.users = let
# The fully privileged bitcoind RPC username of the other node
name = "myrpcuser";
in {
privileged.name = name;
public.name = name;
## Set this if you use btcpayserver
# btcpayserver.name = name;
## Set this if you use joinmarket-ob-watcher
# joinmarket-ob-watcher.name = name;
};
};
```
For each service that connects to bitcoind and has option
`services.<service>.tor.enforce` enabled (either explicitly or by importing
`secure-node.nix` or `enable-tor.nix`), you need to
allow the remote bitcoind connection:
```nix
systemd.services.<service>.serviceConfig.IPAddressAllow = [ ${services.bitcoind.rpc.address} ];
```
> The above configuration is only required if the remote bitcoind **is
> not** accessed via Tor.
Now save the password of the RPC user to the following files on your nix-bitcoin node:
```shell
$secretsDir/bitcoin-rpcpassword-privileged
$secretsDir/bitcoin-rpcpassword-public
## Only needed when set in the above config snippet
# $secretsDir/bitcoin-rpcpassword-btcpayserver
# $secretsDir/bitcoin-rpcpassword-joinmarket-ob-watcher
```
See: [Secrets dir](#secrets-dir)
Afterwards, restart `bitcoind`: `systemctl restart bitcoind`.
# Temporarily disable a service
Sometimes you might want to disable a service without removing the service user and
integration with other services, as it would happen when setting
`services.<service>.enable = false`.
Use the following approach:
```
systemd.services.<service>.wantedBy = mkForce [];
```
This way, the systemd service still exists, but is not automatically started.\
Note: This only works for services that are not required by other active services.
# Appendix
## Secrets dir
The secrets dir is set by option `nix-bitoin.secretsDir` and has the
following default values:
- If you're using the krops deployment method: `/var/src/secrets`
- Otherwise: `/etc/nix-bitcoin-secrets`
-19
View File
@@ -1,19 +0,0 @@
- **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:** Where is `sudo`?\
**A:** After [CVE-2021-3156](https://www.openwall.com/lists/oss-security/2021/01/26/3),
we've replaced `sudo` with OpenBSD's `doas` for users of the `secure-node.nix` template.
It has greatly reduced complexity and is therefore less likely to be a source of
severe vulnerabilities in the future.
+248
View File
@@ -0,0 +1,248 @@
# Maintaining this fork
Upstream (fort-nix/nix-bitcoin) is archived. This fork is now the only
source of fixes, so every module and package left in it is something we
port across each NixOS release. This note lists what squirtle actually
uses, what can be removed, and what still needs maintenance after that.
Assessed 2026-11-15, against fork `master` at `da27f27` (upstream's tree
minus its last two SECURITY.md commits; no fork-only commits yet) and
nix-pleb's squirtle config on NixOS 26.05 and 26.11pre.
**Status (2026-11-15):** steps 1–5 of *Suggested order* are done on
branch `slim`. Step 3's nix-pleb half (squirtle's `services.nix`,
`configuration.nix`, `nixosConfigurations.nix`) is uncommitted in
nix-pleb. Step 6 is still to do. Upstream's tests were dropped, not
replaced (see *Testing*).
## Who consumes the fork
Only one host does: squirtle, in nix-pleb
(`systems/brenise.dev/nixosConfigurations.nix`). It imports
`nixosModules.default` and `modules/presets/secure-node.nix`. No other
flake in `~/ops` uses the fork.
These are squirtle's evaluated settings, not just what the config file
declares:
| Feature | State on squirtle |
|---|---|
| `services.bitcoind` | on, `bitcoind-32.1` from system nixpkgs, `i2p = false` |
| `services.lnd` | on, package overridden to nix-pleb's `unstablePkgs.lnd` |
| `services.electrs` | on, from system nixpkgs |
| `services.mempool` | on, fork-packaged `mempool-*-3.2.1`, `electrumServer = "electrs"` |
| `nix-bitcoin.operator` | on (`pleb`) |
| `nix-bitcoin.nodeinfo` | on (from secure-node preset) |
| `nix-bitcoin.generateSecrets` | on, `secretsSetupMethod = "setup-secrets"` |
| onion services | bitcoind (public), electrs, sshd |
| `nix-bitcoin.security.dbusHideProcessInformation` | on (preset) |
| `services.tor` | on (preset) |
| `nix-bitcoin.netns-isolation` | **off** |
| `services.i2pd` | **off** |
| `services.backups` | **off** |
| `nix-bitcoin.configVersion` | unset |
| clightning, rtl, fulcrum, btcpayserver, nbxplorer, joinmarket, liquidd, loop, pool, charge-lnd, clightning-rest, hardware-wallets, lndconnect | all **off** |
Squirtle runs four services: **bitcoind, lnd, electrs and mempool**. The
rest of the fork is unused.
## What can go
### Unused services: remove
These modules and their packages have no consumer. Each one breaks
independently whenever nixpkgs renames an option or drops a dependency.
| Module | Package(s) in `pkgs/` | Lines (module + pkg) |
|---|---|---|
| `clightning.nix`, `clightning-plugins/`, `clightning-rest.nix`, `clightning-replication.nix` | `clightning-plugins/`, `clightning-rest/`, `clnrest/`, `trustedcoin/`, most of `python-packages/` (pyln-*, pylightning) | ~1,500 |
| `joinmarket.nix`, `joinmarket-ob-watcher.nix` | `joinmarket/`, `python-packages/` (joinmarket, bencoderpyx, chromalog, txzmq, python-bitcointx…) | ~1,000 |
| `btcpayserver.nix` | `nbxplorer/` | ~410 |
| `rtl.nix` | `rtl/` | ~345 |
| `liquid.nix` | `liquid-swap/` | ~320 |
| `lndconnect.nix` | — | ~280 |
| `lightning-loop.nix`, `lightning-pool.nix`, `charge-lnd.nix` | — | ~400 |
| `fulcrum.nix` | — | ~140 |
| `hardware-wallets.nix` | `hwi` (python-packages) | ~85 + |
| — | `bitcoind_29/` (old bitcoind pin) | ~215 |
`python-packages/` (~520 lines) disappears completely once clightning,
joinmarket and hwi are gone. Its own comments note that it pins older
cython, ecdsa and similar, and that kind of pin breaks on each nixpkgs
bump.
### Unused support features: remove
- **`netns-isolation.nix`** (366 lines). It's off on squirtle, but it is
the module that reaches into every other service (btcpayserver,
clightning, joinmarket, rtl, i2pd, …). The 26.11 i2pd breakage came from
here. Removing it also drops `pkgs/netns-exec/` and the
netns-only helpers in `pkgs/lib.nix`.
- **i2p support in `bitcoind.nix`.** `i2p` is false on squirtle. Dropping
the `i2p` option, `i2pSAM` and the `services.i2pd` block makes the
26.11 compatibility patch on branch `nixos-26.11` unnecessary. **Prefer
this over that patch.**
- **`backups.nix`.** It's off on squirtle; the secure-node preset only
sets its `frequency`. Squirtle isn't in raichu's restic jobs either, so
if you want its lnd channel backup or config backed up, add it there
rather than reviving this module.
- **`versioning.nix`** (292 lines) and **`obsolete-options.nix`** (145
lines). Both exist for migrating *other people's* configs across
upstream releases. Squirtle has no `configVersion` set and has never
needed either. Most of their entries reference removed services
(joinmarket, liquidd, clightning-rest…).
- **`modules/deployment/`** (krops, nixops), **`pkgs/krops/`,
`pkgs/nixops/`, `pkgs/generate-secrets-deprecated.nix`.** Squirtle
deploys with `nixos-rebuild` from nix-pleb.
### Presets: fold into squirtle, then remove
`presets/secure-node.nix` and `presets/enable-tor.nix` mostly configure
services squirtle doesn't run. What squirtle actually gets from them:
- `services.tor.enable`, `tor.client.enable`
- `tor.proxy`/`tor.enforce` defaults for bitcoind, lnd, electrs, mempool
(squirtle then overrides `enforce = false` on bitcoind, lnd, electrs)
- onion services for bitcoind, electrs and sshd, plus `onionAddresses.access.pleb`
- `nodeinfo.enable`, `operator.enable`, `dbusHideProcessInformation`
- `bitcoind.listen = true`, `bitcoind.dbCache = 1000`
- doas instead of sudo (`squirtle/configuration.nix` already sets this),
`networking.firewall.enable = true`
Those lines belong in `squirtle/services.nix`. That also fixes the
existing annoyance noted there: `dbCache` "cannot be changed here",
because the preset sets it without `mkDefault`. `hardened.nix`,
`hardened-extended.nix`, `wireguard.nix` and `bitcoind-remote.nix` have no
users.
### Repo scaffolding: remove or shrink
- `test/` (2,700 lines). The VM scenarios exercise every service. Removed
entirely; see *Testing*.
- `examples/` (1,250), `dev/` (900), most of `docs/` (1,700). These are
upstream's user-facing docs and dev environment. Replace them with a
short README covering what's left.
- `helper/`: `fetch-release`, `push-release.sh` and `key-jonasnick.bin`
are upstream's release signing. `update-flake.{nix,sh}` regenerates
`pkgs/pinned.nix` and becomes unnecessary once pins are gone (below).
Keep `update-fixed-output-derivation.sh` only if it's still handy for
mempool hashes.
### Extra nixpkgs pins: remove
The fork's flake has three nixpkgs inputs plus `extra-container` and
`flake-utils`. nix-pleb overrides only `nixpkgs` (`inputs.nixpkgs.follows`).
`nixpkgs-unstable` and `nixpkgs-25_05` stay pinned at whatever the fork's
`flake.lock` says, and they feed `pinned.nix`:
- `pkgsUnstable` supplies `lnd` (squirtle overrides it), plus
`bitcoind-knots`, `clboss`, `fulcrum` and `lightning-loop` (all unused).
- `pkgs-25_05` is only plumbed through to python-packages.
Once the unused packages are gone, take everything from the consumer's
`pkgs`. Make `lnd` default to `pkgs.lnd`; squirtle sets the package
explicitly anyway. Then delete `pinned.nix`, `nixpkgs-pinned.nix`, the
two extra inputs, `extra-container` (used only for container tests and
examples), and the `useVersionLockedPkgs` option. The fork then has one
input, `nixpkgs`, which nix-pleb already follows.
## What's left, and what it costs to maintain
After the removals the fork is roughly these modules: `nix-bitcoin.nix`,
`secrets/`, `operator.nix`, `security.nix`, `bitcoind.nix` (with
`bitcoind-rpc-public-whitelist.nix`, which it imports), `lnd.nix`,
`electrs.nix`, `mempool.nix`, `onion-services.nix`, `onion-addresses.nix`,
`nodeinfo.nix`. Plus `pkgs/lib.nix`, `pkgs/mempool/` and
`pkgs/build-support/fetch-node-modules.nix`. That's about 2,300 lines,
down from about 16,500.
Ordered from most to least work:
1. **mempool package (`pkgs/mempool/`)**: the only real package we
maintain. It has five fixed-output hashes (source, frontend and backend
node modules, the frontend-assets fetch, and the rust-gbt cargo
vendor), a local patch
(`0001-allow-disabling-mining-pool-fetching.patch`), and a pinned
`nodejs_22`. It's at 3.2.1 against upstream's 3.3.2. Expect every
version bump to need the hashes redone. Node 22 also has an end-of-life
date, after which nixpkgs will drop `nodejs_22` and force a Node bump
here. nixpkgs doesn't package mempool, so there's no upstream to lean
on. If you ever stop wanting the mempool UI, removing it is the
biggest maintenance cut available.
2. **`mempool.nix` module**: configures mariadb, nginx (includes
`mempool-nginx-conf` from the package) and the backend's JSON config.
It follows NixOS changes to the mysql and nginx modules and mempool's
config schema. Drop its `fulcrum` option along with fulcrum.
3. **`bitcoind.nix`**: tracks Bitcoin Core config changes across major
versions (nixpkgs moves bitcoind on its own schedule; 32.1 today). It
disables NixOS's own `services/networking/bitcoind.nix`, so watch for
that module being renamed or split. That `disabledModules` path is
in `modules.nix`.
4. **`lnd.nix`**: tracks lnd config changes. It uses `lndinit` from
`pkgs/lndinit/`, which is **0.1.3** while nixpkgs and upstream are at
**0.1.38**. Switch to `pkgs.lndinit` and delete `pkgs/lndinit/`; check
that `gen-seed` and `init-wallet` flags still match. Also drop its
clightning port-conflict assertion.
5. **Tor plumbing** (`onion-services.nix`, `onion-addresses.nix`,
`nbLib.tor`): built on `services.tor.relay.onionServices` and
`tor.client.socksListenAddress`, which NixOS has kept stable for years.
Low churn.
6. **Secrets (`secrets/`)**: generates RPC passwords, the lnd cert and
similar on the host via `setup-secrets`. It's mostly shell and openssl,
so low churn. Note that nix-pleb uses sops for everything else; moving
these to sops would remove this too, at the cost of a migration on a
live node.
7. **`electrs.nix`, `nodeinfo.nix`, `operator.nix`, `security.nix`,
`nix-bitcoin.nix`**: small. The package comes from nixpkgs. Remove the
dead service entries from `nodeinfo.nix` (clightning, liquidd,
joinmarket-ob-watcher…) along with those services.
8. **systemd hardening in `pkgs/lib.nix`** (`defaultHardening`,
`allowedIPAddresses`, `allowNetlink`): occasionally a systemd or NixOS
change makes a service fail at runtime, not at evaluation. That only
shows up after a deploy or in a VM test.
### Per-release checklist
On each NixOS release, or each nixpkgs bump in nix-pleb:
1. `nix build .#nixosConfigurations.squirtle.config.system.build.toplevel`
in nix-pleb. Evaluation errors land in this fork's modules.
2. If mempool or Node changed, build `services.mempool.package` and
`services.mempool.frontend.package` first, and update the hashes.
3. Switch squirtle and check that bitcoind, lnd, electrs, mempool and
nginx are running. Hardening regressions don't show at build time.
If one fails, `nixos-rebuild switch --rollback`.
## Testing
There is no test suite. The fork isn't distributed and only squirtle
consumes it, so problems are handled as they show up on squirtle, with
rollback as the fallback. A regtest VM test mirroring squirtle was
written and then dropped as not worth maintaining; if runtime breakage
becomes frequent, upstream's `test/tests.py` (in git history before
branch `slim`) has per-service checks for all four services to start
from.
## Suggested order
Each step should leave squirtle's evaluated system unchanged on 26.05.
Compare `toplevel.drvPath` before and after, as was done for the i2pd
patch.
1. Remove unused services, their packages, python-packages and
`bitcoind_29`. Edit `modules.nix`, `nodeinfo.nix`, `onion-services.nix`,
`enable-tor.nix`, `backups.nix`, `versioning.nix`, `obsolete-options.nix`
and `netns-isolation.nix` only enough to drop references. Expect the
drvPath to change slightly here, because nodeinfo's script and the
module set shrink.
2. Remove netns-isolation, i2p support, backups, versioning,
obsolete-options and deployment, and abandon branch `nixos-26.11`'s
compatibility patch.
3. Move what squirtle uses from the presets into nix-pleb's
`squirtle/services.nix`, stop importing `secure-node.nix`, and delete
`presets/`.
4. Drop `pinned.nix` and the extra flake inputs; switch to nixpkgs `lndinit`.
5. Remove `test/`, `examples/`, `dev/`, `docs/` and `helper/` (except
`update-fixed-output-derivation.sh`, used by `pkgs/mempool/generate.sh`)
and replace upstream's README with a short one (keep this file).
6. Rebuild squirtle on 26.11 in nix-pleb.
-18
View File
@@ -1,18 +0,0 @@
Hardware requirements
---
* RAM: 2GB. ECC memory is better. Additionally, it's recommended to use DDR4 memory with
targeted row refresh (TRR) enabled (https://rambleed.com/).
* Disk space: 1 TB for an unpruned
instance of Bitcoin Core.
* This can be significantly lowered by enabling pruning.
Note: Pruning is not supported by `electrs` and `fulcrum`.
Tested low-end hardware includes:
- [Raspberry Pi 4](https://www.raspberrypi.org/products/raspberry-pi-4-model-b/)
- [PC Engines apu2c4](https://pcengines.ch/apu2c4.htm)
- [Gigabyte GB-BACE-3150](https://www.gigabyte.com/Mini-PcBarebone/GB-BACE-3150-rev-10)
- [Gigabyte 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 preset](../modules/presets/hardened.nix)
(See https://github.com/fort-nix/nix-bitcoin/issues/39#issuecomment-517366093
for a workaround).
-1
View File
@@ -1 +0,0 @@
"nix-bitcoin-logo.png" is a derivative of "nix-snowflake.svg" (https://github.com/NixOS/nixos-artwork/blob/376ed4ba8dc2e611b7e8a62fdc680967ead5bd87/logo/nix-snowflake.svg) by Tim Cuthbertson, used under CC BY. "nix-bitcoin-logo.png" is licensed under CC BY by the nix-bitcoin developers.
-3
View File
@@ -1,3 +0,0 @@
<svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="16" height="16" viewBox="0 -2 16 16">
<path fill-rule="evenodd" d="M2 4a1 1 0 100-2 1 1 0 000 2zm3.75-1.5a.75.75 0 000 1.5h8.5a.75.75 0 000-1.5h-8.5zm0 5a.75.75 0 000 1.5h8.5a.75.75 0 000-1.5h-8.5zm0 5a.75.75 0 000 1.5h8.5a.75.75 0 000-1.5h-8.5zM3 8a1 1 0 11-2 0 1 1 0 012 0zm-1 6a1 1 0 100-2 1 1 0 000 2z"></path>
</svg>

Before

Width:  |  Height:  |  Size: 387 B

Binary file not shown.

Before

Width:  |  Height:  |  Size: 44 KiB

-342
View File
@@ -1,342 +0,0 @@
# Tutorial: Install and configure NixOS for nix-bitcoin on a dedicated machine
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)).
## 0. Preparation
1. Find a machine to deploy nix-bitcoin on (see [hardware.md](hardware.md)).
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/).
## 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](https://nixos.org/nixos/download.html). For example:
```
wget https://releases.nixos.org/nixos/24.05/nixos-24.05.3164.63d37ccd2d17/nixos-minimal-24.05.3164.63d37ccd2d17-x86_64-linux.iso
# output: 35dd79596f12b159efc533400ba8f730d819eee2d1014683a658020c2b54ae0c
sha256sum nixos-minimal-24.05.3164.63d37ccd2d17-x86_64-linux.iso
```
Alternatively you can build NixOS from source by following the instructions at https://nixos.org/nixos/manual/index.html#sec-building-cd.
2. Write NixOS iso to install media (USB/CD). For example:
```
cp nixos-minimal-23.05.3701.e9b4b56e5a20-x86_64-linux.iso /dev/sdX
```
Replace /dev/sdX with the correct device name. You can find this using `sudo fdisk -l`
3. Boot the system and become root
```
sudo -i
```
You will have to find out if your hardware uses UEFI or Legacy Boot for the next step. You can do that, for example, by executing
```
ls /sys/firmware/efi
```
If the file exists you should continue the installation for UEFI otherwise for Legacy Boot.
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
```
4. Option 3: Set up encrypted partitions:
Follow the guide at https://gist.github.com/martijnvermaat/76f2e24d0239470dd71050358b4d5134.
5. Generate NixOS config
```
nixos-generate-config --root /mnt
nano /mnt/etc/nixos/configuration.nix
```
We now need to adjust the configuration to make sure that we can ssh into the system and that it boots correctly. We add some lines to set `services.openssh` such that the configuration looks as follows:
```
{ config, pkgs, ... }:
{
imports = [
...
];
# Enable the OpenSSH server.
services.openssh = {
enable = true;
permitRootLogin = "yes";
};
# The rest of the file are default options and hints.
}
```
Now we open `hardware-configuration.nix`
```
nano /mnt/etc/nixos/hardware-configuration.nix
```
which will look similar to
```
{ config, pkgs, ... }:
{
imports = [ ];
# Add line here as explained below
# The rest of the file are generated options.
}
```
Now add one of the following lines to the location mentioned in above example hardware config.
**Option 1**: UEFI
```
boot.loader.systemd-boot.enable = true;
```
**Option 2**: Legacy Boot (MBR)
```
boot.loader.grub.device = "/dev/sda";
```
Lastly, in rare circumstances the hardware configuration does not have a `fileSystems` option. In that case you need to add it with the folllowing line:
```
fileSystems."/".device = "/dev/disk/by-label/nixos";
```
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 installation
The following steps are meant to be run on the machine you deploy from, not the machine you deploy to.
You can also build Nix from source by following the instructions at https://nixos.org/nix/manual/#ch-installing-source.
1. Install Dependencies (Debian 10 Buster)
```
sudo apt-get install curl git gnupg2 dirmngr
```
2. Install latest Nix in "multi-user mode" with GPG Verification according to https://nixos.org/nix/download.html
```
curl -o install-nix-2.3.10 https://releases.nixos.org/nix/nix-2.3.10/install
curl -o install-nix-2.3.10.asc https://releases.nixos.org/nix/nix-2.3.10/install.asc
gpg2 --recv-keys B541D55301270E0BCF15CA5D8170B4726D7198DE
gpg2 --verify ./install-nix-2.3.10.asc
sh ./install-nix-2.3.10 --daemon
```
Then follow the instructions. Open a new terminal window when you're done.
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.
3. Optional: Disallow substitutes
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.
## 3. Setup deployment directory
1. Clone this project
```
git clone https://github.com/fort-nix/nix-bitcoin
```
2. Create a new directory for your nix-bitcoin node config and copy initial files from nix-bitcoin
```
mkdir nix-bitcoin-node
cd nix-bitcoin-node
cp -r ../nix-bitcoin/examples/{configuration.nix,shell.nix,krops,.gitignore} .
```
3. Obtain the hash of the latest nix-bitcoin release
```
../nix-bitcoin/helper/fetch-release > nix-bitcoin-release.nix
```
#### Optional: Specify the system of your node
This enables evaluating your node config on a machine that has a different system platform
than your node.\
Examples: Deploying from macOS or deploying from a x86 desktop PC to a Raspberry Pi.
```bash
# Run this when your node has a 64-Bit x86 CPU (e.g., an Intel or AMD CPU)
echo "x86_64-linux" > krops/system
# Run this when your node has a 64-Bit ARM CPU (e.g., Raspberry Pi 4 B, Pine64)
echo "aarch64-linux" > krops/system
```
Other available systems:
- `i686-linux` (`x86`)
- `armv7l-linux` (`ARMv7`)\
This platform is untested and has no binary caches.
[See here](https://nixos.wiki/wiki/NixOS_on_ARM) for details.
## 4. Deploy with krops
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
```
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 `#`.
6. Enter the deployment environment
```
nix-shell
```
7. Deploy with krops in nix-shell
```
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.
See also:
- [Migrating existing services to nix-bitcoin](configuration.md#migrate-existing-services-to-nix-bitcoin)
- [Managing your deployment](configuration.md#managing-your-deployment)
- [Using services](services.md)
-130
View File
@@ -1,130 +0,0 @@
# Tutorial: Moving from a NixOps to a Krops deployment
1. Add a new ssh key to your nix-bitcoin node
Krops doesn't automatically generate ssh keys like NixOps, instead you add your own.
If you don't have a ssh key yet
```
ssh-keygen -t ed25519 -f ~/.ssh/bitcoin-node
```
Edit `configuration.nix`
```
users.users.root = {
openssh.authorizedKeys.keys = [
"<contents of ~/.ssh/bitcoin-node.pub or existing .pub key file>"
];
};
```
Deploy new key
```
nixops deploy -d bitcoin-node
```
2. Update your nix-bitcoin, depending on your setup either with `fetch-release` or `git`. Make sure you are at least on `v0.0.41`.
3. Pull the latest nix-bitcoin source
```
cd ~/nix-bitcoin
git pull
```
4. Copy new and updated files into your deployment folder
```
cd <deployment directory, for example `~/nix-bitcoin-node`>
cp -r ~/nix-bitcoin/examples/{krops,shell.nix} .
```
5. 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 key from step 1 or path to existing key>
AddKeysToAgent yes
```
6. 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;
};
```
7. If `lnd` or `joinmarket` is enabled on your node, run the commmand
```
nix-shell --run 'nix-instantiate --eval -E "
(import <nixpkgs/nixos> {
configuration = { lib, ... }: {
imports = [ ./configuration.nix ];
nix-bitcoin.configVersion = lib.mkDefault \"0.0.31\";
nix-bitcoin.secretsSetupMethod = lib.mkForce \"manual\";
};
}).vm.outPath
"'
```
and follow the migration instructions from the error message.
8. Optional: Disallow substitutes
You may have been building nix-bitcoin "without substitutes" to avoid pulling in binaries from the Nix cache. If you want to continue doing so, you have to add the following line to the `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.
In that case, it is possible to SSH into the target machine and run
```
nixos-rebuild -I /var/src switch
```
9. Deploy with krops
```
nix-shell --run krops-deploy
```
Remove the old secrets directory. For krops deployments, secrets are always
located at `/var/src/secrets`.
```
ssh bitcoin-node 'rm -rf /secrets'
```
9. You can now access `bitcoin-node` via ssh
```
ssh operator@bitcoin-node
```
10. You can remove the remaining traces of nixops as follows:
```
nix-shell
nix run -f '<nix-bitcoin>' nixops19_09 -c nixops delete -d bitcoin-node --force
git rm -r nixops
```
-598
View File
@@ -1,598 +0,0 @@
# Nodeinfo
Run `nodeinfo` to see onion addresses and local addresses for enabled services.
# Managing services
NixOS uses the [systemd](https://wiki.archlinux.org/title/systemd) service manager.
Usage:
```shell
# Show service status
systemctl status bitcoind
# Show the last 100 log messages
journalctl -u bitcoind -n 100
# Show all log messages since the last system boot
journalctl -b -u bitcoind
# These commands require root permissions
systemctl stop bitcoind
systemctl start bitcoind
systemctl restart bitcoind
# Show the service definition
systemctl cat bitcoind
# Show all service parameters
systemctl show bitcoind
```
# clightning database replication
The clightning database can be replicated to a local path
or to a remote SSH target.\
When remote replication is enabled, nix-bitcoin mounts a SSHFS to a local path.\
Optionally, backups can be encrypted via `gocryptfs`.
Note: You should also backup the static file `hsm_secret` (located at
`/var/lib/clightning/bitcoin/hsm_secret` by default), either manually
or via the `services.backups` module.
## Remote target via SSHFS
1. Add this to your `configuration.nix`:
```nix
services.clightning.replication = {
enable = true;
sshfs.destination = "user@hostname:directory";
# This is optional
encrypt = true;
};
programs.ssh.knownHosts."hostname".publicKey = "<ssh public key from running `ssh-keyscan` on the host>";
```
Leave out the `encrypt` line if you want to store data on your destination
in plaintext.\
Adjust `user`, `hostname` and `directory` as necessary.
2. Deploy
3. To allow SSH access from the nix-bitcoin node to the target node, either
use the remote node config below, or copy the contents of `$secretsDir/clightning-replication-ssh.pub`
to the `authorized_keys` file of `user` (or use `ssh-copy-id`).
4. You can restrict the nix-bitcoin node's capabilities on the SSHFS target
using OpenSSH's builtin features, as detailed
[here](https://serverfault.com/questions/354615/allow-sftp-but-disallow-ssh).
To implement this on NixOS, add the following to the NixOS configuration of
the SSHFS target node:
```nix
systemd.tmpfiles.rules = [
# Because this directory is chrooted by sshd, it must only be writable by user/group root
"d /var/backup/nb-replication 0755 root root - -"
"d /var/backup/nb-replication/writable 0700 nb-replication - - -"
];
services.openssh = {
extraConfig = ''
Match user nb-replication
ChrootDirectory /var/backup/nb-replication
AllowTcpForwarding no
AllowAgentForwarding no
ForceCommand internal-sftp
PasswordAuthentication no
X11Forwarding no
'';
};
users.users.nb-replication = {
isSystemUser = true;
group = "nb-replication";
shell = "${pkgs.coreutils}/bin/false";
openssh.authorizedKeys.keys = [ "<contents of $secretsDir/clightning-replication-ssh.pub>" ];
};
users.groups.nb-replication = {};
```
With this setup, the corresponding `sshfs.destination` on the nix-bitcoin
node is `"nb-replication@hostname:writable"`.
## Local directory target
1. Add this to your `configuration.nix`
```nix
services.clightning.replication = {
enable = true;
local.directory = "/var/backup/clightning";
encrypt = true;
};
```
Leave out the `encrypt` line if you want to store data in
`local.directory` in plaintext.
2. Deploy
clightning will now replicate database files to `local.directory`. This
can be used to replicate to an external HDD by mounting it at path
`local.directory`.
## Custom remote destination
Follow the steps in section "Local directory target" above and mount a custom remote
destination (e.g., a NFS or SMB share) to `local.directory`.\
You might want to disable `local.setupDirectory` in order to create the mount directory
yourself with custom permissions.
# Connect to RTL
Normally you would connect to RTL via SSH tunneling with a command like this
```
ssh -L 3000:127.0.0.1:3000 root@bitcoin-node
```
Or like this, if you are using `netns-isolation`
```
ssh -L 3000:169.254.1.29:3000 root@bitcoin-node
```
Otherwise, you can access it via Tor Browser at `http://<onion-address>`.
You can find the `<onion-address>` with command `nodeinfo`.
The default password location is `$secretsDir/rtl-password`.
See: [Secrets dir](./configuration.md#secrets-dir)
# Use Zeus (mobile lightning wallet) via Tor
1. Install [Zeus](https://zeusln.app) (version ≥ 0.9.0)
2. Edit your `configuration.nix`
##### For lnd
Add the following config:
```nix
services.lnd.lndconnect = {
enable = true;
onion = true;
};
```
##### For clightning
Add the following config:
```nix
services.clightning.plugins.clnrest = {
enable = true;
lnconnect = {
enable = true;
onion = true;
};
};
```
3. Deploy your configuration
4. Run the following command on your node (as user `operator`) to create a QR code
with address and authentication information:
##### For lnd
```
lndconnect
```
##### For clightning
```
lnconnect-clnrest
```
5. Configure Zeus
- Add a new node and scan the QR code
- Click `Save node config`
- Start sending and stacking sats privately
### Additional lndconnect features
- Create a plain text URL:
```bash
lndconnect --url
```
- Set a custom host. By default, `lndconnect` detects the system's external IP and uses it as the host.
```bash
lndconnect --host myhost
```
# Use Zeus (mobile lightning wallet) via WireGuard
Connecting Zeus directly to your node is much faster than using Tor, but a bit more complex to setup.
There are two ways to establish a secure, direct connection:
- Connecting via TLS. This requires installing your lightning app's
TLS Certificate on your mobile device.
- Connecting via WireGuard. This approach is simpler and more versatile, and is
described in this guide.
1. Install [Zeus](https://zeusln.app) (version ≥ 0.9.0) and
[WireGuard](https://www.wireguard.com/install/) on your mobile device.
2. Add the following to your `configuration.nix`:
```nix
imports = [
# Use this line when using the default deployment method
<nix-bitcoin/modules/presets/wireguard.nix>
# Use this line when using Flakes
(nix-bitcoin + /modules/presets/wireguard.nix)
]
# For lnd
services.lnd.lndconnect.enable = true;
# For clightning
services.clightning = {
plugins.clnrest = {
enable = true;
lnconnect.enable = true;
};
};
```
3. Deploy your configuration.
4. If your node is behind an external firewall or NAT (e.g. a router), add the following port forwarding
rule to the external device:
- Port: 51820 (the default value of option `networking.wireguard.interfaces.wg-nb.listenPort`)
- Protocol: UDP
- Destination: IP of your node
5. Setup WireGuard on your mobile device.
Run the following command on your node (as user `operator`) to create a QR code
for WireGuard:
```bash
nix-bitcoin-wg-connect
# For debugging: Show the WireGuard config as text
nix-bitcoin-wg-connect --text
```
The above commands automatically detect your node's external IP.\
To set a custom IP or hostname, run the following:
```
nix-bitcoin-wg-connect 93.184.216.34
nix-bitcoin-wg-connect mynode.org
```
Configure WireGuard:
- Press the `+` button in the bottom right corner
- Scan the QR code
- Add the tunnel
6. Setup Zeus
Run the following command on your node (as user `operator`) to create a QR code for Zeus:
##### For lnd
```
lndconnect-wg
```
##### For clightning
```
lnconnect-clnrest-wg
```
Configure Zeus:
- Add a new node and scan the QR code
- Click `Save node config`
- On the certificate warning screen, click `I understand, save node config`.\
Certificates are not needed when connecting via WireGuard.
- Start sending and stacking sats privately
### Additional lndconnect features
Create a plain text URL:
```bash
lndconnect-wg --url
``````
# Connect to electrs
### Requirements Android
* Android phone
* [Orbot](https://guardianproject.info/apps/orbot/) installed from [F-Droid](https://guardianproject.info/fdroid) (recommended) or [Google Play](https://play.google.com/store/apps/details?id=org.torproject.android&hl=en)
* [Electrum mobile app](https://electrum.org/#home) 4.0.1 and newer installed from [direct download](https://electrum.org/#download) or [Google Play](https://play.google.com/store/apps/details?id=org.electrum.electrum)
### Requirements Desktop
* [Tor](https://www.torproject.org/) installed from [source](https://www.torproject.org/docs/tor-doc-unix.html.en) or [repository](https://www.torproject.org/docs/debian.html.en)
* [Electrum](https://electrum.org/#download) installed
1. Enable electrs in `configuration.nix`
Change
```
# services.electrs.enable = true;
```
to
```
services.electrs.enable = true;
```
2. Deploy new `configuration.nix`
3. Get electrs onion address with format `<onion-address>:<port>`
```
nodeinfo | jq -r .electrs.onion_address
```
4. Connect to electrs
Make sure Tor is running on Desktop or as Orbot on Android.
On Desktop
```
electrum --oneserver -1 -s "<electrs onion address>:t" -p socks5:127.0.0.1:9050
```
On Android
```
Three dots in the upper-right-hand corner
Network > Proxy mode: socks5, Host: 127.0.0.1, Port: 9050
Network > Auto-connect: OFF
Network > One-server mode: ON
Network > Server: <electrs onion address>:t
```
# Connect to nix-bitcoin node through the SSH onion service
1. Get the SSH onion address (excluding the port suffix)
```
ssh operator@bitcoin-node
nodeinfo | jq -r .sshd.onion_address | sed 's/:.*//'
```
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 onion service, forwarding a local port to the nix-bitcoin node's SSH server
```
ssh -i ~/.ssh/id_ed25519 -L <random port of your choosing>:127.0.0.1:22 root@<SSH onion address>
```
5. Edit your deployment tool's configuration and change the node's address to `127.0.0.1` and the ssh port to `<random port of your choosing>`.
If you use krops as described in the [installation tutorial](./install.md), set `target = "127.0.0.1:<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.
# Initialize a Trezor for Bitcoin Core's Hardware Wallet Interface
1. Enable Trezor in `configuration.nix`
Change
```
# services.hardware-wallets.trezor = true;
```
to
```
services.hardware-wallets.trezor = true;
```
2. Deploy new `configuration.nix`
3. Check that your nix-bitcoin node recognizes your Trezor
```
ssh operator@bitcoin-node
lsusb
```
Should show something relating to your Trezor
4. If your Trezor has outdated firmware or is not yet initialized: Start your Trezor in bootloader mode
Trezor v1
```
Plug in your Trezor with both buttons depressed
```
Trezor v2
```
Start swiping your finger across your Trezor's touchscreen and plug in the USB cable when your finger is halfway through
```
5. If your Trezor's firmware is outdated: Update your Trezor's firmware
```
trezorctl firmware-update
```
Follow the on-screen instructions
**Caution: This command _will_ wipe your Trezor. If you already store Bitcoin on it, only do this with the recovery seed nearby.**
6. If your Trezor is not yet initialized: Set up your Trezor
```
trezorctl reset-device -p
```
Follow the on-screen instructions
7. Find your Trezor
```
hwi enumerate
hwi -t trezor -d <path from previous command> promptpin
hwi -t trezor -d <path> sendpin <number positions for the PIN as displayed on your device's screen>
hwi enumerate
```
8. Follow Bitcoin Core's instructions on [Using Bitcoin Core with Hardware Wallets](https://github.com/bitcoin-core/HWI/blob/master/docs/bitcoin-core-usage.md) to use your Trezor with `bitcoin-cli` on your nix-bitcoin node
# JoinMarket
## Diff to regular JoinMarket usage
For clarity reasons, nix-bitcoin renames all scripts to `jm-*` without `.py`, for
example `wallet-tool.py` becomes `jm-wallet-tool`. The rest of this section
details nix-bitcoin specific workflows for JoinMarket.
## Wallets
By default, a wallet is automatically generated at service startup.
It's stored at `/var/lib/joinmarket/wallets/wallet.jmdat`, and its mnmenoic recovery
seed phrase is stored at `/var/lib/joinmarket/jm-wallet-seed`.
A missing wallet file is automatically recreated if the seed file is still present.
If you want to manually initialize your wallet instead, follow these steps:
1. Enable JoinMarket in your node configuration
```
services.joinmarket.enable = true;
```
2. Move the automatically generated `wallet.jmdat`
```console
mv /var/lib/joinmarket/wallet.jmdat /var/lib/joinmarket/bak.jmdat
```
3. Generate wallet on your node
```console
jm-wallet-tool generate
```
Follow the on-screen instructions and write down your seed.
In order to use nix-bitcoin's `joinmarket.yieldgenerator`, use the password
from `$secretsDir/jm-wallet-password` and use the suggested default wallet name
`wallet.jmdat`. If you want to use your own `jm-wallet-password`, simply
replace the password string in your local secrets directory.
See: [Secrets dir](./configuration.md#secrets-dir)
## Run the tumbler
The tumbler needs to be able to run in the background for a long time, use screen
to run it accross SSH sessions. You can also use tmux in the same fashion.
1. Add screen to your `environment.systemPackages`, for example
```
environment.systemPackages = with pkgs; [
vim
screen
];
```
2. Start the screen session
```console
screen -S "tumbler"
```
3. Start the tumbler
Example: Tumbling into your wallet after buying from an exchange to improve privacy:
```console
jm-tumbler wallet.jmdat <addr1> <addr2> <addr3>
```
After tumbling your bitcoin end up in these three addresses. You can now
spend them without the exchange collecting data on your purchases.
Get more information [here](https://github.com/JoinMarket-Org/joinmarket-clientserver/blob/master/docs/tumblerguide.md)
4. Detach the screen session to leave the tumbler running in the background
```
Ctrl-a d or Ctrl-a Ctrl-d
```
5. Re-attach to the screen session
```console
screen -r tumbler
```
6. End screen session
Type exit when tumbler is done
```console
exit
```
## Run a "maker" or "yield generator"
The maker/yield generator in nix-bitcoin is implemented using a systemd service.
See [here](https://github.com/JoinMarket-Org/joinmarket-clientserver/blob/master/docs/YIELDGENERATOR.md) for more yield generator information.
1. Enable yield generator bot in your node configuration
```
services.joinmarket.yieldgenerator = {
enable = true;
# Optional: Add custom parameters
cjfee_a = 300;
cjfee_r = 0.00003;
};
'';
```
2. Check service status
```console
systemctl status joinmarket-yieldgenerator
```
3. Profit
# clightning
## Plugins
There is a number of [plugins](https://github.com/lightningd/plugins) available for clightning.
See [`Readme: Features → clightning`](../README.md#features) or [search.nixos.org][1] for a complete list.
[1]: https://search.nixos.org/flakes?channel=unstable&from=0&size=30&sort=relevance&type=options&query=services.clightning.plugins
You can activate and configure these plugins like so:
```nix
services.clightning = {
enable = true;
plugins = {
clboss.enable = true;
clboss.min-onchain = 40000;
};
};
```
Please have a look at the module for a plugin (e.g. [clboss.nix](../modules/clightning-plugins/clboss.nix)) to learn its configuration options.
### Trustedcoin
When `services.clightning.tor.proxy` is enabled, [trustedcoin](https://github.com/nbd-wtf/trustedcoin)
also uses Tor for all external connections by default.
In this case, connections to block explorers can sometimes get blocked.
An example of clightning log error output when connections are getting blocked:
```
lightningd[5138]: plugin-trustedcoin estimatefees error: https://blockstream.info/api error: 403 Forbidden
lightningd[4933]: plugin-trustedcoin getblock error: got something that isn't a block hash: <html><head>...
```
To work around this and connect via clearnet instead, set this option:
```nix
services.clightning.plugins.trustedcoin.tor.proxy = false;
```
-1
View File
@@ -1 +0,0 @@
secrets/
-77
View File
@@ -1,77 +0,0 @@
## Examples
The easiest way to try out nix-bitcoin is to use one of the provided examples.
### Flakes-based quick start
If you use a Flakes-enabled version of Nix, run the following command to start a minimal
nix-bitcoin QEMU VM:
```bash
nix run github:fort-nix/nix-bitcoin/release
```
The VM (defined in [flake.nix](../flake.nix)) runs in the terminal and has `bitcoind`
and `clightning` installed.\
It leaves no traces (outside of `/nix/store`) on the host system.
### More examples
Clone this repo and enter the examples shell:
```bash
git clone https://github.com/fort-nix/nix-bitcoin
cd nix-bitcoin/examples/
nix-shell
```
The following example scripts set up a nix-bitcoin node according to [`./configuration.nix`](configuration.nix) and then
shut down immediately. They leave no traces (outside of `/nix/store`) on the host system.\
By default, [`./configuration.nix`](configuration.nix) enables `bitcoind` and `clightning`.
- [`./deploy-container.sh`](deploy-container.sh) creates a [NixOS container](https://github.com/erikarvstedt/extra-container).\
This is the fastest way to set up a node.\
Requires: [Nix](https://nixos.org/), a systemd-based Linux distro and root privileges
- [`./deploy-qemu-vm.sh`](deploy-qemu-vm.sh) creates a QEMU VM.\
Requires: [Nix](https://nixos.org/nix/), Linux
- [`./deploy-krops.sh`](deploy-krops.sh) creates a QEMU VM and deploys a
nix-bitcoin configuration to it using [krops](https://github.com/krebs/krops).\
Requires: [Nix](https://nixos.org/nix/), Linux
- [`./deploy-container-minimal.sh`](deploy-container-minimal.sh) creates a
container defined by [importable-configuration.nix](importable-configuration.nix).\
You can copy and import this file to use nix-bitcoin in an existing NixOS configuration.\
The configuration doesn't use the [secure-node.nix](../modules/presets/secure-node.nix) preset.\
Requires: [Nix](https://nixos.org/), a systemd-based Linux distro and root privileges
Run the examples with option `--interactive` or `-i` to start a shell for interacting with
the node:
```bash
./deploy-qemu-vm.sh -i
```
### Tests
The [nix-bitcoin test suite](../test/README.md) is also useful for exploring features.
### Real-world example
Check the [server repo](https://github.com/fort-nix/nixbitcoin.org) for https://nixbitcoin.org
to see the configuration of a Flakes-based nix-bitcoin node that's used in production.
The commands in `shell.nix` allow you to locally run the node in a VM or container.
### Flakes
Flakes make it easy to include `nix-bitcoin` in an existing NixOS config.
The [flakes example](./flakes/flake.nix) shows how to use `nix-bitcoin` as an input to a system flake.
### Persistent container with Flakes
The [persistent container](./container) example shows how to run a Flake-based node
in a container.\
Requires: A systemd-based Linux distro and root privileges.
### Extending nix-bitcoin with Flakes
The [mempool extension flake](https://github.com/fort-nix/nix-bitcoin-mempool) shows how to define new
pkgs and modules in a Flake.\
Since mempool is now a core nix-bitcoin module, this Flake just serves as an example.
-333
View File
@@ -1,333 +0,0 @@
# Edit this configuration file to define what should be installed on
# your system. Help is available in the configuration.nix(5) man page
# and in the NixOS manual (accessible by running ‘nixos-help’).
{ config, pkgs, lib, ... }: {
imports = [
<nix-bitcoin/modules/modules.nix>
# FIXME: The secure-node preset is an opinionated config to enhance security
# and privacy.
# Among other settings, it routes traffic of all nix-bitcoin services through Tor.
# Turn it off when not needed.
<nix-bitcoin/modules/presets/secure-node.nix>
# FIXME: The hardened kernel profile improves security but
# decreases performance by ~50%.
# Turn it off when not needed.
<nix-bitcoin/modules/presets/hardened.nix>
#
# You can enable the hardened-extended preset instead to further improve security
# at the cost of functionality and performance.
# See the comments at the top of `hardened-extended.nix` for further details.
# <nix-bitcoin/modules/presets/hardened-extended.nix>
# FIXME: Uncomment the next line to import your hardware configuration. If so,
# add the hardware configuration file to the same directory as this file.
#./hardware-configuration.nix
];
# FIXME: Enable modules by uncommenting their respective line. Disable
# modules by commenting out their respective line.
### BITCOIND
# Bitcoind is enabled by default via secure-node.nix.
#
# Set this option to enable pruning with a specified MiB value.
# clightning is compatible with pruning. See
# https://github.com/ElementsProject/lightning/#pruning for more information.
# LND and electrs are not compatible with pruning.
# services.bitcoind.prune = 100000;
#
# Set this to accounce the onion service address to peers.
# The onion service allows accepting incoming connections via Tor.
# nix-bitcoin.onionServices.bitcoind.public = true;
#
# You can add options that are not defined in modules/bitcoind.nix as follows
# services.bitcoind.extraConfig = ''
# maxorphantx=110
# '';
### CLIGHTNING
# Enable clightning, a Lightning Network implementation in C.
services.clightning.enable = true;
#
# Set this to create an onion service by which clightning can accept incoming connections
# via Tor.
# The onion service is automatically announced to peers.
# nix-bitcoin.onionServices.clightning.public = true;
#
# == Plugins
# See ../README.md (Features → clightning) for the list of available plugins.
# services.clightning.plugins.clboss.enable = true;
#
# == REST server
# Set this to create a clightning REST onion service.
# This also adds binary `lnconnect-clnrest` to the system environment.
# This binary creates QR codes or URLs for connecting applications to clightning
# via the REST onion service.
# You can also connect via WireGuard instead of Tor.
# See ../docs/services.md for details.
#
# services.clightning.plugins.clnrest = {
# enable = true;
# lnconnect = {
# enable = true;
# onion = true;
# };
# };
### LND
# Set this to enable lnd, a lightning implementation written in Go.
# services.lnd.enable = true;
#
# NOTE: In order to avoid collisions with clightning you must disable clightning or
# change the services.clightning.port or services.lnd.port to a port other than
# 9735.
#
# Set this to create an onion service by which lnd can accept incoming connections
# via Tor.
# The onion service is automatically announced to peers.
# nix-bitcoin.onionServices.lnd.public = true;
#
# Set this to create a lnd REST onion service.
# This also adds binary `lndconnect` to the system environment.
# This binary generates QR codes or URLs for connecting applications to lnd via the
# REST onion service.
# You can also connect via WireGuard instead of Tor.
# See ../docs/services.md for details.
#
# services.lnd.lndconnect = {
# enable = true;
# onion = true;
# };
#
## WARNING
# If you use lnd, you should manually backup your wallet mnemonic
# seed. This will allow you to recover on-chain funds. You can run the
# following commands after the lnd service starts:
# mkdir -p ./backups/lnd/
# scp bitcoin-node:/var/lib/lnd/lnd-seed-mnemonic ./backups/lnd/
#
# You should also backup your channel state after opening new channels.
# This will allow you to recover off-chain funds, by force-closing channels.
# scp bitcoin-node:/var/lib/lnd/chain/bitcoin/mainnet/channel.backup ./backups/lnd/
#
# Alternatively, you can have these files backed up by services.backups below.
### RIDE THE LIGHTNING
# Set this to enable RTL, a web interface for lnd and clightning.
# services.rtl.enable = true;
#
# Set this to add a clightning node interface.
# Automatically enables clightning.
# services.rtl.nodes.clightning.enable = true;
#
# Set this to add a lnd node interface.
# Automatically enables lnd.
# services.rtl.nodes.lnd.enable = true;
#
# You can enable both nodes simultaneously.
#
# Set this option to enable swaps with lightning-loop.
# Automatically enables lightning-loop.
# services.rtl.nodes.lnd.loop = true;
### MEMPOOL
# Set this to enable mempool, a fully featured Bitcoin visualizer, explorer,
# and API service.
#
# services.mempool.enable = true;
#
# Possible options for the Electrum backend server:
#
# - electrs (enabled by default):
# Small database size, slow when querying new addresses.
#
# - fulcrum:
# Large database size, quickly serves arbitrary address queries.
# Enable with:
# services.mempool.electrumServer = "fulcrum";
#
# Set this to create an onion service to make the mempool web interface
# available via Tor:
# nix-bitcoin.onionServices.mempool-frontend.enable = true;
### ELECTRS
# Set this to enable electrs, an Electrum server implemented in Rust.
# services.electrs.enable = true;
### FULCRUM
# Set this to enable fulcrum, an Electrum server implemented in C++.
#
# Compared to electrs, fulcrum has higher storage demands but
# can serve arbitrary address queries instantly.
#
# Before enabling fulcrum, and for more info on storage demands,
# see the description of option `enable` in ../modules/fulcrum.nix
#
# services.fulcrum.enable = true;
### BTCPayServer
# Set this to enable BTCPayServer, a self-hosted, open-source
# cryptocurrency payment processor.
# services.btcpayserver.enable = true;
#
# Privacy Warning: BTCPayServer currently looks up price rates without
# proxying them through Tor. This means an outside observer can correlate
# your BTCPayServer usage, like invoice creation times, with your IP address.
#
# Enable this option to connect BTCPayServer to clightning.
# services.btcpayserver.lightningBackend = "clightning";
#
# Enable this option to connect BTCPayServert to lnd.
# services.btcpayserver.lightningBackend = "lnd";
#
# The lightning backend service is automatically enabled.
# Afterwards you need to go into Store > General Settings > Lightning Nodes
# and select "the internal lightning node of this BTCPay Server".
#
# Set this to create an onion service to make the btcpayserver web interface
# accessible via Tor.
# Security WARNING: Create a btcpayserver administrator account before allowing
# public access to the web interface.
# nix-bitcoin.onionServices.btcpayserver.enable = true;
### LIQUIDD
# Enable this module to use Liquid, a sidechain for an inter-exchange
# settlement network linking together cryptocurrency exchanges and
# institutions around the world.
# services.liquidd.enable = true;
#
# Liquid can be controlled with command 'elements-cli'.
### Hardware wallets
# Enable the following to allow using hardware wallets.
# See https://github.com/bitcoin-core/HWI for more information.
#
# Ledger must be initialized through the official ledger live app and the Bitcoin app must
# be installed and running on the device.
# services.hardware-wallets.ledger = true;
#
# Trezor can be initialized with the trezorctl command in nix-bitcoin. More information in
# `../docs/services.md`.
# services.hardware-wallets.trezor = true;
### lightning-loop
# Set this to enable lightninglab's non-custodial off/on chain bridge.
# services.lightning-loop.enable = true;
#
# loopd (lightning-loop daemon) will be started automatically. Users can
# interact with off/on chain bridge using `loop in` and `loop out`.
# Automatically enables lnd.
### lightning-pool
# Set this to enable Lightning Lab's non-custodial batched uniform
# clearing-price auction for Lightning Channel Leases.
# services.lightning-pool.enable = true;
#
# Use the `pool` command to interact with the lightning-pool service.
# Automatically enables lnd.
#
# lightning-pool requires that lnd has a publicly reachable address.
# Set this to create a public onion service for lnd.
# nix-bitcoin.onionServices.lnd.public = true;
### charge-lnd
# Set this to enable charge-lnd, a simple policy based fee manager for
# LND. With this tool you can set fees to autobalance, recover channel open
# costs, use on-chain fees as reference, or just use static fees. You decide.
# services.charge-lnd.enable = true;
#
# Define policies as outlined in the project documentation.
# services.charge-lnd.policies = ''
# '';
### JOINMARKET
# Set this to enable the JoinMarket service, including its command-line scripts.
# These scripts have prefix 'jm-', like 'jm-tumbler'.
# Note: JoinMarket has full access to bitcoind, including its wallet functionality.
# services.joinmarket.enable = true;
#
# Set this to enable the JoinMarket Yield Generator Bot. You will be able to
# earn sats by providing CoinJoin liquidity. This makes it impossible to use other
# scripts that access your wallet.
# services.joinmarket.yieldgenerator.enable = true;
#
# Set this to enable the JoinMarket order book watcher.
# services.joinmarket-ob-watcher.enable = true;
### Nodeinfo
# Set this to add command `nodeinfo` to the system environment.
# It shows info about running services like onion addresses and local addresses.
# It is enabled by default when importing `secure-node.nix`.
# nix-bitcoin.nodeinfo.enable = true;
### Backups
# Set this to enable nix-bitcoin's own backup service. By default, it
# uses duplicity to incrementally back up all important files in /var/lib to
# /var/lib/localBackups once a day.
# services.backups.enable = true;
#
# You can pull the localBackups folder with
# `scp -r bitcoin-node:/var/lib/localBackups /my-backup-path/`
# Alternatively, you can also set a remote target url, for example
# services.backups.destination = "sftp://user@host[:port]/[relative|/absolute]_path";
# Supply the sftp password by appending the FTP_PASSWORD environment variable
# to secrets/backup-encryption-env like so
# `echo "FTP_PASSWORD=<password>" >> secrets/backup-encryption-env`
# You many also need to set a ssh host and publickey with
# programs.ssh.knownHosts."host" = {
# hostNames = [ "host" ];
# publicKey = "<ssh public from `ssh-keyscan`>";
# };
# If you also want to backup bulk data like the Bitcoin & Liquid blockchains
# and electrs data directory, enable
# services.backups.with-bulk-data = true;
### netns-isolation (EXPERIMENTAL)
# Enable this module to use Network Namespace Isolation. This feature places
# every service in its own network namespace and only allows truly necessary
# connections between network namespaces, making sure services are isolated on
# a network-level as much as possible.
# nix-bitcoin.netns-isolation.enable = true;
# FIXME: Define your hostname.
networking.hostName = "host";
time.timeZone = "UTC";
services.openssh = {
enable = true;
settings.PasswordAuthentication = false;
};
users.users.root = {
openssh.authorizedKeys.keys = [
# FIXME: Replace this with your SSH pubkey
"ssh-ed25519 AAAAC3..."
];
};
# FIXME: Uncomment this to allow the operator user to run
# commands as root with `sudo` or `doas`
# users.users.operator.extraGroups = [ "wheel" ];
# FIXME: add packages you need in your system
environment.systemPackages = with pkgs; [
vim
];
# FIXME: Add custom options (like boot options, output of
# nixos-generate-config, etc.):
# This value determines the NixOS release from which the default
# settings for stateful data, like file locations and database versions
# on your system were taken. It's perfectly fine and recommended to leave
# this value at the release version of the first install of this system.
# Before changing this value read the documentation for this option
# (e.g. man configuration.nix or on https://nixos.org/nixos/options.html).
system.stateVersion = "26.05"; # Did you read the comment?
# The nix-bitcoin release version that your config is compatible with.
# When upgrading to a backwards-incompatible release, nix-bitcoin will display an
# an error and provide instructions for migrating your config to the new release.
nix-bitcoin.configVersion = "0.0.85";
}
-73
View File
@@ -1,73 +0,0 @@
# See how this flake is used in ./usage.sh
# See also:
# https://github.com/erikarvstedt/extra-container
# https://github.com/erikarvstedt/extra-container/blob/master/examples/flake
# Container-related NixOS options
# https://search.nixos.org/options?channel=unstable&query=containers.%3Cname%3E
{
description = "A basic nix-bitcoin container node";
inputs = {
nix-bitcoin.url = "github:fort-nix/nix-bitcoin/release";
# You can also use a version branch to track a specific NixOS release
# nix-bitcoin.url = "github:fort-nix/nix-bitcoin/nixos-26.05";
nixpkgs.follows = "nix-bitcoin/nixpkgs";
nixpkgs-unstable.follows = "nix-bitcoin/nixpkgs-unstable";
extra-container.follows = "nix-bitcoin/extra-container";
};
outputs = { nixpkgs, nix-bitcoin, extra-container, ... }:
extra-container.lib.eachSupportedSystem (system: {
packages.default = extra-container.lib.buildContainers {
inherit system;
# The container uses the nixpkgs from `nix-bitcoin.inputs.nixpkgs` by default
# Only set this if the `system.stateVersion` of your container
# host is < 22.05
# legacyInstallDirs = true;
config = {
# See the file for why this is needed and when it can be removed
imports = [ (nix-bitcoin.outPath + "/test/lib/extra-container-workaround.nix") ];
containers.mynode = {
# Always start container along with the container host
autoStart = true;
# This assigns the following addresses:
# Host IP: 10.250.0.1
# Container IP: 10.250.0.2
extra.addressPrefix = "10.250.0";
# Enable internet access for the container
extra.enableWAN = true;
# Map `/my/host/dir` to `/my/mount` in the container
# bindMounts."/my/mount" = { hostPath = "/my/host/dir"; isReadOnly = false; };
# Setup port forwarding
# forwardPorts = [ { containerPort = 80; hostPort = 8080; protocol = "tcp";} ];
config = { config, pkgs, ... }: {
imports = [
nix-bitcoin.nixosModules.default
];
# Automatically generate all secrets required by services.
# The secrets are stored in /etc/nix-bitcoin-secrets in the container
nix-bitcoin.generateSecrets = true;
# Enable some services.
# See ../configuration.nix for all available features.
services.bitcoind.enable = true;
services.electrs.enable = true;
};
};
};
};
});
}
-47
View File
@@ -1,47 +0,0 @@
# Requirements:
# - A systemd-based Linux distro
# - extra-container (https://github.com/erikarvstedt/extra-container/#install)
# - Nix
# - Root privileges
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# Create container
# Create and start container defined by ./flake.nix
nix run . -- create --start
# You can use the same command to update the (running) container,
# after changing the container configuration.
# In the default configuration, the container is automatically started on
# system boot (option `autoStart`).
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# Use container
# Run command in container
extra-container run mynode -- hostname
extra-container run mynode -- systemctl status bitcoind
extra-container run mynode -- bitcoin-cli -getinfo
extra-container run mynode -- bash -c 'bitcoin-cli -getinfo && systemctl status electrs'
# Start shell in container
extra-container root-login mynode
# Show the container filesystem
sudo ls -al /var/lib/nixos-containers/mynode
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# Stop container
extra-container stop mynode
# Resume the container
extra-container start mynode
# You can also use the `create --start` command above
# Destroy container
extra-container destroy mynode
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# Inspect container config
nix eval .#default.outPath
nix eval . --apply 'sys: sys.containers.mynode.config.networking.hostName'
-30
View File
@@ -1,30 +0,0 @@
#!/usr/bin/env bash
set -euo pipefail
tmpDir=$(mktemp -d /tmp/nix-bitcoin-minimal-container.XXX)
trap 'rm -rf $tmpDir' EXIT
cd "${BASH_SOURCE[0]%/*}"
# Modify importable-configuration.nix to use the local <nix-bitcoin>
# source instead of fetchTarball
<importable-configuration.nix sed '
s|nix-bitcoin = .*|nix-bitcoin = toString <nix-bitcoin>;|;
s|system.extraDependencies = .*||
' > "$tmpDir/importable-configuration.nix"
cat > "$tmpDir/configuration.nix" <<EOF
{
imports = [ $tmpDir/importable-configuration.nix ];
users.users.main = {
isNormalUser = true;
password = "a";
};
# When WAN is disabled, DNS bootstrapping slows down service startup by ~15 s
services.clightning.extraConfig = ''
disable-dns
'';
}
EOF
./deploy-container.sh "$tmpDir/configuration.nix" "$@"
-95
View File
@@ -1,95 +0,0 @@
#!/usr/bin/env bash
set -euo pipefail
# This script demonstrates how to setup a nix-bitcoin node in a NixOS container.
# Running this script leaves no traces on your host system.
# This demo is a template for your own experiments.
# Run with option `--interactive` or `-i` to start a shell for interacting with
# the node.
if [[ $EUID != 0 ]]; then
# NixOS containers require root permissions
exec sudo "${BASH_SOURCE[0]}" "$@"
fi
if [[ $(sysctl -n net.ipv4.ip_forward) != 1 ]]; then
echo "Error: IP forwarding (net.ipv4.ip_forward) is not enabled."
echo "Needed for container WAN access."
exit 1
fi
if [[ ! -v DEPLOY_CONTAINER_NIX_SHELL ]]; then
echo "Running script in nix shell env..."
cd "${BASH_SOURCE[0]%/*}"
DEPLOY_CONTAINER_NIX_SHELL=1 exec nix-shell --run "./${BASH_SOURCE[0]##*/} $*"
fi
interactive=
configuration=
for arg in "$@"; do
case $arg in
-i|--interactive)
interactive=1
;;
*)
configuration=$arg
;;
esac
done
# These commands can also be executed interactively in a shell session
demoCmds='
echo
echo "Bitcoind service:"
c systemctl status bitcoind
echo
echo "Bitcoind network:"
c bitcoin-cli getnetworkinfo
echo
echo "lightning-cli state:"
c lightning-cli getinfo
echo
echo "Bitcoind data dir:"
sudo ls -al /var/lib/*containers/demo-node/var/lib/bitcoind
'
nodeInfoCmd='
echo
echo "Node info:"
c nodeinfo
'
if [[ ! $configuration ]]; then
configuration=configuration.nix
demoCmds="${demoCmds}${nodeInfoCmd}"
fi
if [[ $interactive ]]; then
runCmd=()
else
runCmd=(--run bash -c "$demoCmds")
fi
# Build container.
# Learn more: https://github.com/erikarvstedt/extra-container
#
read -rd '' src <<EOF || true
{ pkgs, lib, ... }: {
imports = [ $(realpath "${BASH_SOURCE[0]%/*}"/../test/lib/extra-container-workaround.nix) ];
containers.demo-node = {
extra.addressPrefix = "10.250.0";
extra.enableWAN = true;
config = { pkgs, config, lib, ... }: {
imports = [
$(realpath "$configuration")
];
nix-bitcoin.generateSecrets = true;
};
};
}
EOF
. "${BASH_SOURCE[0]%/*}"/../test/lib/extra-container-check-version.sh
extra-container shell -E "$src" "${runCmd[@]}"
# The container is automatically deleted at exit
-130
View File
@@ -1,130 +0,0 @@
#!/usr/bin/env bash
set -euo pipefail
# This script demonstrates how to setup a nix-bitcoin node with krops.
# The node is deployed to a minimal NixOS QEMU VM.
# Running this script leaves no traces on your host system.
# This demo is a template for your own experiments.
# Run with option `--interactive` or `-i` to start a shell for interacting with
# the node.
# MAKE SURE TO REPLACE the SSH identity file if you use this script for
# anything serious.
if [[ ! -v NIX_BITCOIN_EXAMPLES_DIR ]]; then
echo "Running script in nix shell env..."
cd "${BASH_SOURCE[0]%/*}"
exec nix-shell --run "./${BASH_SOURCE[0]##*/} $*"
else
cd "$NIX_BITCOIN_EXAMPLES_DIR"
fi
source qemu-vm/run-vm.sh
echo "Building the target VM"
# Build the initial VM to which the nix-bitcoin node is deployed via krops
nix-build --out-link "$tmpDir/vm" - <<'EOF'
(import <nixpkgs/nixos> {
configuration = { config, lib, ... }: {
imports = [ <qemu-vm/vm-config.nix> ];
services.openssh.enable = true;
# Silence the following warning that appears when deploying via krops:
# warning: Nix search path entry '/nix/var/nix/profiles/per-user/root/channels' does not exist, ignoring
nix.nixPath = lib.mkForce [];
system.stateVersion = lib.mkDefault config.system.nixos.release;
};
}).config.system.build.vm
EOF
vmNumCPUs=4
vmMemoryMiB=2048
sshPort=60734
# Start the VM in the background
runVM "$tmpDir/vm" "$vmNumCPUs" "$vmMemoryMiB" "$sshPort"
# Build the krops deploy script
export sshPort
nix-build --out-link "$tmpDir/krops-deploy" - <<'EOF'
let
krops = (import <nix-bitcoin> {}).krops;
extraSources = {
# Skip uploading nixpkgs to the target node.
# This works because /nix/store is shared with the target VM.
nixpkgs.symlink = toString <nixpkgs>;
nixos-config.file = toString <krops-vm-configuration.nix>;
qemu-vm.file = toString <qemu-vm>;
};
in
krops.pkgs.krops.writeCommand "krops-deploy" {
source = import <krops/sources.nix> { inherit extraSources krops; };
force = true;
target = {
user = "root";
host = "127.0.0.1";
port = builtins.getEnv "sshPort";
extraOptions = [
"-i" (toString <qemu-vm/id-vm>) "-oConnectTimeout=1"
"-oStrictHostKeyChecking=no" "-oUserKnownHostsFile=/dev/null" "-oLogLevel=ERROR"
"-oControlMaster=auto" "-oControlPath=${builtins.getEnv "tmpDir"}/ssh-connection" "-oControlPersist=60"
];
};
# "test" instead of "switch" to avoid installing a bootloader which
# is not possible in this VM
command = targetPath: ''
nixos-rebuild test -I /var/src
'';
}
EOF
echo "Building the nix-bitcoin node"
# Pre-build the nix-bitcoin node outside of the VM to save some time
nix-build --out-link "$tmpDir/store-paths" -E '
let
system = (import <nixpkgs/nixos> { configuration = <krops-vm-configuration.nix>; }).system;
pkgsUnstable = (import <nix-bitcoin/pkgs/nixpkgs-pinned.nix>).nixpkgs-unstable;
pkgs = import <nixpkgs> {};
in
pkgs.closureInfo { rootPaths = [ system pkgsUnstable ]; }
' > /dev/null
vmWaitForSSH
# Add the store paths that include the nix-bitcoin node
# to the nix store db in the VM
c "nix-store --load-db < $(realpath "$tmpDir/store-paths")/registration"
echo
echo "Generate secrets"
nix-shell --run generate-secrets
echo
echo "Deploy with krops"
"$tmpDir/krops-deploy"
echo
echo "Bitcoind service:"
c systemctl status bitcoind
echo
echo "Bitcoind network:"
c bitcoin-cli getnetworkinfo
echo
echo "lightning-cli state:"
c lightning-cli getinfo
echo
echo "Node info:"
c nodeinfo
case ${1:-} in
-i|--interactive)
. ./start-bash-session.sh
;;
esac
# Cleanup happens at exit (defined in qemu-vm/run-vm.sh)
-69
View File
@@ -1,69 +0,0 @@
#!/usr/bin/env bash
set -euo pipefail
# This script demonstrates how to run a nix-bitcoin node in QEMU.
# Running this script leaves no traces on your host system.
# This demo is a template for your own experiments.
# Run with option `--interactive` or `-i` to start a shell for interacting with
# the node.
# MAKE SURE TO REPLACE the SSH identity file if you use this script for
# anything serious.
if [[ ! -v NIX_BITCOIN_EXAMPLES_DIR ]]; then
echo "Running script in nix shell env..."
cd "${BASH_SOURCE[0]%/*}"
exec nix-shell --run "./${BASH_SOURCE[0]##*/} $*"
else
cd "$NIX_BITCOIN_EXAMPLES_DIR"
fi
source qemu-vm/run-vm.sh
echo "Building VM"
nix-build --out-link "$tmpDir/vm" - <<'EOF'
(import <nixpkgs/nixos> {
configuration = {
imports = [
<configuration.nix>
<qemu-vm/vm-config.nix>
];
nix-bitcoin.generateSecrets = true;
};
}).config.system.build.vm
EOF
vmNumCPUs=4
vmMemoryMiB=2048
sshPort=60734
runVM "$tmpDir/vm" "$vmNumCPUs" "$vmMemoryMiB" "$sshPort"
vmWaitForSSH
printf "Waiting until services are ready"
c "
$(cat qemu-vm/wait-until.sh)
waitUntil 'systemctl is-active clightning &> /dev/null' 100
"
echo
echo
echo "Bitcoind service:"
c systemctl status bitcoind
echo
echo "Bitcoind network:"
c bitcoin-cli getnetworkinfo
echo
echo "lightning-cli state:"
c lightning-cli getinfo
echo
echo "Node info:"
c nodeinfo
case ${1:-} in
-i|--interactive)
. ./start-bash-session.sh
;;
esac
# Cleanup happens at exit (defined in qemu-vm/run-vm.sh)
-70
View File
@@ -1,70 +0,0 @@
# This is a system configuration template that uses nix-bitcoin.
#
# You can adapt this to an existing system flake by copying the parts
# relevant to nix-bitcoin.
#
# Make sure to check and edit all lines marked by 'FIXME:'
{
description = "A basic nix-bitcoin node";
inputs.nix-bitcoin.url = "github:fort-nix/nix-bitcoin/release";
# You can also use a version branch to track a specific NixOS release
# inputs.nix-bitcoin.url = "github:fort-nix/nix-bitcoin/nixos-26.05";
inputs.nixpkgs.follows = "nix-bitcoin/nixpkgs";
inputs.nixpkgs-unstable.follows = "nix-bitcoin/nixpkgs-unstable";
outputs = { self, nixpkgs, nix-bitcoin, ... }: {
nixosConfigurations.mynode = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
nix-bitcoin.nixosModules.default
# Optional:
# Import the secure-node preset, an opinionated config to enhance security
# and privacy.
#
# (nix-bitcoin + "/modules/presets/secure-node.nix")
{
# Automatically generate all secrets required by services.
# The secrets are stored in /etc/nix-bitcoin-secrets
nix-bitcoin.generateSecrets = true;
# Enable some services.
# See ../configuration.nix for all available features.
services.bitcoind.enable = true;
services.clightning.enable = true;
# When using nix-bitcoin as part of a larger NixOS configuration, set the following to enable
# interactive access to nix-bitcoin features (like bitcoin-cli) for your system's main user
nix-bitcoin.operator = {
enable = true;
# FIXME: Set this to your system's main user
name = "main";
};
# The system's main unprivileged user.
# In an existing NixOS configuration, this setting is usually already defined.
users.users.main = {
isNormalUser = true;
# FIXME: This is unsafe. Use `hashedpassword` or `passwordFile` instead in a real
# deployment: https://search.nixos.org/options?show=users.users.%3Cname%3E.hashedPassword
password = "a";
};
# If you use a custom nixpkgs version for evaluating your system
# (instead of `nix-bitcoin.inputs.nixpkgs` like in this example),
# consider setting `useVersionLockedPkgs = true` to use the exact pkgs
# versions for nix-bitcoin services that are tested by nix-bitcoin.
# The downsides are increased evaluation times and increased system
# closure size.
#
# nix-bitcoin.useVersionLockedPkgs = true;
}
];
};
};
}
-38
View File
@@ -1,38 +0,0 @@
# You can directly copy and import this file to use nix-bitcoin
# in an existing NixOS configuration.
# Make sure to check and edit all lines marked by 'FIXME:'
# See ./flakes/flake.nix on how to include nix-bitcoin in a flake-based
# system configuration.
let
# FIXME:
# Overwrite `builtins.fetchTarball {}` with the output of
# command ../helper/fetch-release
nix-bitcoin = builtins.fetchTarball {};
in
{ config, pkgs, lib, ... }: {
imports = [
"${nix-bitcoin}/modules/modules.nix"
];
# Automatically generate all secrets required by services.
# The secrets are stored in /etc/nix-bitcoin-secrets
nix-bitcoin.generateSecrets = true;
# Enable some services.
# See ./configuration.nix for all available features.
services.bitcoind.enable = true;
services.clightning.enable = true;
# Enable interactive access to nix-bitcoin features (like bitcoin-cli) for
# your system's main user
nix-bitcoin.operator = {
enable = true;
# FIXME: Set this to your system's main user
name = "main";
};
# Prevent garbage collection of the nix-bitcoin source
system.extraDependencies = [ nix-bitcoin ];
}
-7
View File
@@ -1,7 +0,0 @@
{ lib, ... }: {
imports = [
./configuration.nix
<nix-bitcoin/modules/deployment/krops.nix>
<qemu-vm/vm-config.nix>
];
}
-20
View File
@@ -1,20 +0,0 @@
let
# FIXME:
target = "root@HOSTNAME_OR_IP_ADDRESS";
extraSources = {
"hardware-configuration.nix".file = toString ../hardware-configuration.nix;
};
krops = (import <nix-bitcoin> {}).krops;
in
krops.pkgs.krops.writeDeploy "deploy" {
inherit target;
source = import ./sources.nix { inherit extraSources krops; };
# Avoid having to create a sentinel file.
# Otherwise /var/src/.populate must be created on the target node to signal krops
# that it is allowed to deploy.
force = true;
}
-7
View File
@@ -1,7 +0,0 @@
# This file allows you to build your krops configuration locally
{
imports = [
../configuration.nix
<nix-bitcoin/modules/deployment/krops.nix>
];
}
-43
View File
@@ -1,43 +0,0 @@
{ extraSources, krops }:
krops.lib.evalSource [({
nixos-config.file = builtins.toFile "nixos-config" ''
{
imports = [
./configuration.nix
<nix-bitcoin/modules/deployment/krops.nix>
];
}
'';
"configuration.nix".file = toString ../configuration.nix;
# Enable `useChecksum` for sources which might be located in the nix store
# and which therefore might have static timestamps.
nixpkgs.file = {
path = toString <nixpkgs>;
useChecksum = true;
# TODO-EXTERNAL:
# Work around symlink sync error on macOS/BSD
# (https://github.com/NixOS/nixpkgs/issues/180046)
# by excluding the single symlink that's present in nixpkgs.
filters = [
{
type = "exclude";
pattern = "/pkgs/development/libraries/readline/update-patch-set.sh";
}
];
};
nix-bitcoin.file = {
path = toString <nix-bitcoin>;
useChecksum = true;
filters = [{
type = "exclude";
pattern = ".git";
}];
};
secrets.file = toString ../secrets;
} // extraSources)]
-1
View File
@@ -1 +0,0 @@
../.
-19
View File
@@ -1,19 +0,0 @@
# This is an example network definition for deploying a nix-bitcoin node via NixOps.
# NixOps deployment is currently untested.
{
network.description = "Bitcoin node";
bitcoin-node = { config, pkgs, lib, ... }: {
imports = [
../configuration.nix
<nix-bitcoin/modules/deployment/nixops.nix>
];
nix-bitcoin.deployment.secretsDir = toString ../secrets;
#FIXME:
# Set `deployment.*` options like
# deployment.targetHost = "<address_or_hostname>";
};
}
-7
View File
@@ -1,7 +0,0 @@
-----BEGIN OPENSSH PRIVATE KEY-----
b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtzc2gtZW
QyNTUxOQAAACBbda93/QYwDf4PGJp2KgJ1xwKPgKhEHeJrubXAeZWPpgAAAIgDA7dzAwO3
cwAAAAtzc2gtZWQyNTUxOQAAACBbda93/QYwDf4PGJp2KgJ1xwKPgKhEHeJrubXAeZWPpg
AAAECuRSsNFRQgAOid87b/2kIhgycAH5nPgZwkY4bUpq7LQFt1r3f9BjAN/g8YmnYqAnXH
Ao+AqEQd4mu5tcB5lY+mAAAABG5vbmUB
-----END OPENSSH PRIVATE KEY-----
-1
View File
@@ -1 +0,0 @@
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFt1r3f9BjAN/g8YmnYqAnXHAo+AqEQd4mu5tcB5lY+m none
-62
View File
@@ -1,62 +0,0 @@
nix-bitcoin: pkgs: system:
rec {
inherit (nix-bitcoin.inputs) nixpkgs;
mkVMScript = vm: pkgs.writers.writeBash "run-vm" ''
set -euo pipefail
export TMPDIR=$(mktemp -d /tmp/nix-bitcoin-vm.XXX)
trap 'rm -rf $TMPDIR' EXIT
export NIX_DISK_IMAGE=$TMPDIR/nixos.qcow2
# shellcheck disable=SC2211
QEMU_OPTS="-smp $(nproc) -m 1500" ${vm}/bin/run-*-vm
'';
vm = (import (nixpkgs + "/nixos") {
inherit system;
configuration = { config, lib, modulesPath, ... }: {
imports = [
nix-bitcoin.nixosModules.default
(nix-bitcoin + "/modules/presets/secure-node.nix")
(modulesPath + "/virtualisation/qemu-vm.nix")
];
virtualisation.graphics = false;
nix-bitcoin.generateSecrets = true;
services.clightning.enable = true;
# disable-dns leads to faster startup in offline VMs
services.clightning.extraConfig = ''
disable-dns
'';
# Avoid lengthy build of the nixos manual
documentation.nixos.enable = false;
nixpkgs.pkgs = pkgs;
services.getty.autologinUser = "root";
nix.nixPath = [ "nixpkgs=${nixpkgs}" ];
services.getty.helpLine = lib.mkAfter ''
Welcome to nix-bitcoin!
To explore running services, try the following commands:
nodeinfo
systemctl status bitcoind
systemctl status clightning
bitcoin-cli -getinfo
lightning-cli getinfo
'';
# Power off VM when the user exits the shell
systemd.services."serial-getty@".preStop = ''
echo o >/proc/sysrq-trigger
'';
system.stateVersion = lib.mkDefault config.system.nixos.release;
};
}).config.system.build.vm;
runVM = mkVMScript vm;
}
-52
View File
@@ -1,52 +0,0 @@
qemuDir=$(cd "${BASH_SOURCE[0]%/*}" && pwd)
# shellcheck disable=SC1091
source "$qemuDir/wait-until.sh"
tmpDir=/tmp/nix-bitcoin-qemu-vm
mkdir -p "$tmpDir"
# Cleanup on exit
cleanup() {
set +eu
if [[ $qemuPID ]]; then
kill -9 "$qemuPID"
fi
rm -rf "$tmpDir"
}
trap "cleanup" EXIT
identityFile=$qemuDir/id-vm
chmod 0600 "$identityFile"
runVM() {
vm=$1
vmNumCPUs=$2
vmMemoryMiB=$3
sshPort=$4
export NIX_DISK_IMAGE="$tmpDir/img"
export QEMU_NET_OPTS="hostfwd=tcp::${sshPort}-:22"
# shellcheck disable=SC2211
</dev/null "$vm"/bin/run-*-vm -m "$vmMemoryMiB" -smp "$vmNumCPUs" &>/dev/null &
qemuPID=$!
}
vmWaitForSSH() {
echo
printf "Waiting for SSH connection..."
waitUntil "c : 2>/dev/null" 500
echo
}
# Run command in VM
c() {
ssh -p "$sshPort" -i "$identityFile" -o IdentitiesOnly=yes -o ConnectTimeout=1 \
-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o LogLevel=ERROR \
-o ControlMaster=auto -o ControlPath=$tmpDir/ssh-connection -o ControlPersist=60 \
root@127.0.0.1 "$@"
}
export identityFile
export sshPort
export tmpDir
export -f c
-15
View File
@@ -1,15 +0,0 @@
{ modulesPath, ... }:
{
# Disable the hardened preset to improve VM performance
disabledModules = [ <nix-bitcoin/modules/presets/hardened.nix> ];
imports = [ (modulesPath + "/virtualisation/qemu-vm.nix") ];
config = {
virtualisation.graphics = false;
services.getty.autologinUser = "root";
users.users.root = {
openssh.authorizedKeys.keyFiles = [ ./id-vm.pub ];
};
};
}
-21
View File
@@ -1,21 +0,0 @@
# Wait until $condition is true, retrying every $intervalMs milliseconds.
# Print a '.' character every second as a progress indicator.
waitUntil() {
condition=$1
intervalMs=$2
lastDotTime=$(getTimeMs)
while ! { t0=$(getTimeMs); eval "$condition"; }; do
now=$(getTimeMs)
if ((now - lastDotTime >= 1000)); then
printf .
lastDotTime=$now
fi
toSleep=$((t0 + intervalMs - now))
if ((toSleep > 0)); then
sleep $((toSleep / 1000)).$((toSleep % 1000));
fi
done
}
getTimeMs() { date +%s%3N; }
-9
View File
@@ -1,9 +0,0 @@
let
nix-bitcoin = toString (import ./nix-bitcoin-release.nix);
in
import "${nix-bitcoin}/helper/makeShell.nix" {
configDir = ./.;
shellVersion = "0.0.51";
# Set this to modify your shell
# extraShellInitCmds = pkgs: ''<my bash code>'';
}
-21
View File
@@ -1,21 +0,0 @@
# Start an interactive bash session in the current bash environment.
USAGE_INFO='
Starting shell...
Run "c COMMAND" to execute a command on the bitcoin node
Run "c" to start a shell session inside the node
Example:
c systemctl status bitcoind
'
# BASH_ENVIRONMENT contains definitions of read-only variables like 'BASHOPTS' that
# cause warnings on evaluation. Suppress these warnings while sourcing.
#
# shellcheck disable=SC2016
BASH_ENVIRONMENT=<(declare -p; declare -pf) \
USAGE_INFO="$USAGE_INFO" \
bash --rcfile <(echo '
source $BASH_ENVIRONMENT 2>/dev/null
echo "$USAGE_INFO"
')
-46
View File
@@ -1,46 +0,0 @@
#!/usr/bin/env nix-shell
#!nix-shell -i bash -p bash coreutils curl jq gnupg gnugrep
set -euo pipefail
scriptDir=$(cd "${BASH_SOURCE[0]%/*}" && pwd)
trap 'echo "Error at ${BASH_SOURCE[0]}:$LINENO"' ERR
repo=fort-nix/nix-bitcoin
if [[ ! -v version ]]; then
version=$(curl -fsS "https://api.github.com/repos/$repo/releases/latest" | jq -r '.tag_name' | tail -c +2)
fi
TMPDIR=$(mktemp -d)
trap 'rm -rf $TMPDIR' EXIT
export GNUPGHOME=$TMPDIR/gpg-home
mkdir -m 700 "$GNUPGHOME"
# Import key
gpg --import "$scriptDir/key-jonasnick.bin" &> /dev/null
# Check that exactly one key was imported
(($(gpg --list-keys --with-colons | grep -c pub) == 1))
# Verify key fingerprint
gpg --list-keys "36C7 1A37 C9D9 88BD E825 08D9 B1A7 0E4F 8DCD 0366" > /dev/null
# Fetch nar-hash of release
cd "$TMPDIR"
baseUrl=https://github.com/$repo/releases/download/v$version
curl -fsS -L -O "$baseUrl/nar-hash.txt"
curl -fsS -L -O "$baseUrl/nar-hash.txt.asc"
# Verify signature for nar-hash
gpg --verify nar-hash.txt.asc nar-hash.txt &> /dev/null || {
>&2 echo "Error: Signature verification failed. Please open an issue in the project repository."
exit 1
}
>&2 echo "Fetched and verified release $version"
cat <<EOF
builtins.fetchTarball {
url = "https://github.com/$repo/archive/v$version.tar.gz";
sha256 = "$(cat nar-hash.txt)";
}
EOF
Binary file not shown.
-159
View File
@@ -1,159 +0,0 @@
{ configDir, shellVersion ? null, extraShellInitCmds ? (pkgs: "") }:
let
pinned = import ../pkgs/nixpkgs-pinned.nix;
pkgs = import nixpkgs { config = {}; overlays = []; };
inherit (pkgs) lib;
inherit (pinned) nixpkgs;
nbPkgs = import ../pkgs { inherit pkgs; };
cfgDir = toString configDir;
setPath = lib.optionalString pkgs.stdenv.isLinux ''
export PATH="${lib.makeBinPath [ nbPkgs.pinned.extra-container ]}''${PATH:+:}$PATH"
'';
in
pkgs.stdenv.mkDerivation {
name = "nix-bitcoin-environment";
helpMessage = ''
nix-bitcoin path: ${toString ../.}
Available commands
==================
deploy
Run krops-deploy and eval-config in parallel.
This ensures that eval failures appear quickly when deploying.
In this case, deployment is stopped.
krops-deploy
Deploy your node via krops
eval-config
Evaluate your node system configuration
build-config
Build your node system on your local machine
generate-secrets
Create secrets required by your node configuration.
Secrets are written to ./secrets/
This function is automatically called by krops-deploy.
update-nix-bitcoin
Fetch and use the latest version of nix-bitcoin
'';
shellHook = ''
export NIX_PATH="nixpkgs=${nixpkgs}:nix-bitcoin=${toString ../.}:."
${setPath}
export NIX_BITCOIN_EXAMPLES_DIR="${cfgDir}"
export nixpkgsUnstable="${pinned.nixpkgs-unstable}"
# Set isInteractive=1 if
# 1. stdout is a TTY, i.e. we're not piping the output
# 2. the shell is interactive
if [[ -t 1 && $- == *i* ]]; then isInteractive=1; else isInteractive=; fi
# Make this a non-environment var
export -n helpMessage
help() { echo "$helpMessage"; }
h() { help; }
fetch-release() {
${toString ./fetch-release}
}
update-nix-bitcoin() {(
set -euo pipefail
releaseFile="${cfgDir}/nix-bitcoin-release.nix"
current=$(cat "$releaseFile" 2>/dev/null || true)
new=$(fetch-release)
if [[ $new == $current ]]; then
echo "nix-bitcoin-release.nix already contains the latest release"
else
echo "$new" > "$releaseFile"
echo "Updated nix-bitcoin-release.nix"
if [[ $isInteractive ]]; then
exec nix-shell
fi
fi
)}
generate-secrets() {(
set -euo pipefail
config="${cfgDir}/krops/krops-configuration.nix"
if [[ ! -e $config ]]; then
config="${cfgDir}/configuration.nix"
fi
genSecrets=$(nix-build --no-out-link -I nixos-config="$config" \
'<nixpkgs/nixos>' -A config.nix-bitcoin.generateSecretsScript)
mkdir -p "${cfgDir}/secrets"
(cd "${cfgDir}/secrets"; $genSecrets)
)}
deploy() {(
set -euo pipefail
krops-deploy &
kropsPid=$!
if eval-config; then
wait $kropsPid
else
# Kill all subprocesses
kill $(pidClosure $kropsPid)
return 1
fi
)}
krops-deploy() {(
set -euo pipefail
generate-secrets
# Ensure strict permissions on secrets/ directory before rsyncing it to
# the target machine
chmod 700 "${cfgDir}/secrets"
$(nix-build --no-out-link "${cfgDir}/krops/deploy.nix")
)}
eval-config() {(
set -euo pipefail
system=$(getNodeSystem)
NIXOS_CONFIG="${cfgDir}/krops/krops-configuration.nix" \
nix-instantiate --eval ${nixpkgs}/nixos $system -A system.outPath | tr -d '"'
echo
)}
build-config() {(
set -euo pipefail
system=$(getNodeSystem)
NIXOS_CONFIG="${cfgDir}/krops/krops-configuration.nix" \
nix-build --no-out-link ${nixpkgs}/nixos $system -A system
)}
getNodeSystem() {
if [[ -e '${cfgDir}/krops/system' ]]; then
echo -n "--argstr system "; cat '${cfgDir}/krops/system'
elif [[ $OSTYPE == darwin* ]]; then
# On macOS, `builtins.currentSystem` (`*-darwin`) can never equal
# the node system (`*-linux`), so we can always provide a helpful error message:
>&2 echo "Error, node system not set. See here how to fix this:"
>&2 echo "https://github.com/fort-nix/nix-bitcoin/blob/master/docs/install.md#optional-specify-the-system-of-your-node"
return 1
fi
};
pidClosure() {
echo "$1"
for pid in $(ps -o pid= --ppid "$1"); do
pidClosure "$pid"
done
}
if [[ $isInteractive ]]; then
${pkgs.figlet}/bin/figlet "nix-bitcoin"
echo 'Enter "h" or "help" for documentation.'
fi
# Don't run this hook when another nix-shell is run inside this shell
unset shellHook
${extraShellInitCmds pkgs}
'';
}
-119
View File
@@ -1,119 +0,0 @@
#!/usr/bin/env bash
set -euo pipefail
REPO=fort-nix/nix-bitcoin
BRANCH=master
GIT_REMOTE=origin
OAUTH_TOKEN=
DRY_RUN=
releaseVersion=
trap 'echo "Error at ${BASH_SOURCE[0]}:$LINENO"' ERR
cd "${BASH_SOURCE[0]%/*}"
for arg in "$@"; do
case $arg in
--dry-run|-n)
DRY_RUN=1
;;
*)
releaseVersion="$arg"
;;
esac
done
latestVersion=$(curl -fsS https://api.github.com/repos/$REPO/releases/latest | jq -r '.tag_name' | tail -c +2)
if [[ ! $releaseVersion ]]; then
# Increment the lowest/last part of `latestVersion`
releaseVersion=$(echo "$latestVersion" | awk -F. '/[0-9]+\./{$NF++;print}' OFS=.)
fi
if [[ $DRY_RUN ]]; then
echo "Dry run"
else
OAUTH_TOKEN=$(pass show nix-bitcoin/github/oauth-token)
if [[ ! $OAUTH_TOKEN ]]; then
echo "Error fetching OAUTH_TOKEN"
exit 1
fi
fi
echo "Latest release: $latestVersion"
if [[ ! $DRY_RUN ]]; then
while true; do
read -rp "Create release ${releaseVersion}? [yn] " yn
case $yn in
[Yy]* ) break;;
[Nn]* ) exit;;
* ) echo "Please answer y or n.";;
esac
done
fi
nixosVersion=$(sed -nE 's|.*system.stateVersion = "(.*?)".*|\1|p' ../examples/configuration.nix)
if [[ ! $nixosVersion ]]; then
echo "Error fetching NixOS version"
exit 1
fi
nixosVersionBranch=nixos-$nixosVersion
TMPDIR=$(mktemp -d)
if [[ ! $DRY_RUN ]]; then trap 'rm -rf $TMPDIR' EXIT; fi
ARCHIVE_NAME=nix-bitcoin-$releaseVersion.tar.gz
ARCHIVE=$TMPDIR/$ARCHIVE_NAME
# Need to be in the repo root directory for archiving
(cd "$(git rev-parse --show-toplevel)"; git archive --format=tar.gz -o "$ARCHIVE" "$BRANCH")
SHA256SUMS=$TMPDIR/SHA256SUMS.txt
# Use relative path with sha256sums because it'll output the first
# argument
(cd "$TMPDIR"; sha256sum "$ARCHIVE_NAME" > "$SHA256SUMS")
gpg -o "$SHA256SUMS.asc" -a --detach-sig "$SHA256SUMS"
pushd "$TMPDIR" >/dev/null
nix hash to-sri --type sha256 "$(nix-prefetch-url --unpack "file://$ARCHIVE" 2> /dev/null)" > nar-hash.txt
gpg -o nar-hash.txt.asc -a --detach-sig nar-hash.txt
if [[ $DRY_RUN ]]; then
echo "Created v$releaseVersion in $TMPDIR"
echo "NixOS version branch: $nixosVersionBranch"
exit 0
fi
#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
# Create release
POST_DATA="{ \"tag_name\": \"v$releaseVersion\", \"name\": \"nix-bitcoin-$releaseVersion\", \"body\": \"nix-bitcoin-$releaseVersion\", \"target_comitish\": \"$BRANCH\" }"
RESPONSE=$(curl -fsS -H "Authorization: token $OAUTH_TOKEN" -d "$POST_DATA" https://api.github.com/repos/$REPO/releases)
ID=$(echo "$RESPONSE" | jq -r '.id')
if [[ $ID == null ]]; then
echo "Failed to create release with $POST_DATA"
exit 1
fi
post_asset() {
GH_ASSET="https://uploads.github.com/repos/$REPO/releases/$ID/assets?name="
curl -fsS -H "Authorization: token $OAUTH_TOKEN" --data-binary "@$1" -H "Content-Type: application/octet-stream" \
"$GH_ASSET/$(basename "$1")"
}
post_asset nar-hash.txt
post_asset nar-hash.txt.asc
# Post additional assets for backwards compatibility.
# This allows older nix-bitcoin installations to upgrade via `fetch-release`.
post_asset "$ARCHIVE"
post_asset "$SHA256SUMS"
post_asset "$SHA256SUMS.asc"
popd >/dev/null
if [[ ! $DRY_RUN ]]; then
git push "$GIT_REMOTE" "$BRANCH:release"
git push "$GIT_REMOTE" "$BRANCH:$nixosVersionBranch"
fi
echo "Successfully created" "$(echo "$POST_DATA" | jq -r .tag_name)"
-20
View File
@@ -1,20 +0,0 @@
#!/usr/bin/env bash
# Usage:
# source "path/to/run-in-nix-env" "pkg1 pkg2 ..." "$@"
#
# Runs the calling script with pkgs1, pkg2, ... in PATH.
# The packages are sourced from the nixpkgs input of the nix-bitcoin root flake.
if [[ ${_NIX_BITCOIN_ENV_PKGS:-} != "$1" ]]; then
export _NIX_BITCOIN_ENV_PKGS=$1
shift
_shell_pkgs=()
for _pkg in $_NIX_BITCOIN_ENV_PKGS; do
_shell_pkgs+=("nixpkgs#$_pkg")
done
# BASH_SOURCE[0] is this file
# BASH_SOURCE[-1] is the root src file
exec nix shell --inputs-from "${BASH_SOURCE[0]%/*}/.." "${_shell_pkgs[@]}" -c "${BASH_SOURCE[-1]}" "$@"
fi
-12
View File
@@ -1,12 +0,0 @@
# Start an interactive bash session in the current bash environment.
# This is helpful for debugging bash scripts like pkg update scripts,
# by adding `source <path-to>/start-bash-session.sh` at the location to
# be inspected.
# BASH_ENVIRONMENT contains definitions of read-only variables like 'BASHOPTS' that
# cause warnings on evaluation. Suppress these warnings while sourcing.
#
# shellcheck disable=SC2016
BASH_ENVIRONMENT=<(declare -p; declare -pf) \
bash --rcfile <(echo 'source $BASH_ENVIRONMENT 2>/dev/null')
-84
View File
@@ -1,84 +0,0 @@
The [`run-tests.sh`](./run-tests.sh) command is the most convenient and versatile way to run tests.\
It leave no traces (outside of `/nix/store`) on the host system.
`run-tests.sh` requires Nix with [Flakes](https://wiki.nixos.org/wiki/Flakes).
### Summary
```bash
./run-tests.sh [--scenario|-s <scenario>] [build|vm|debug|container]
```
See the top of [run-tests.sh](../test/run-tests.sh) for a complete documentation.\
Test scenarios are defined in [tests.nix](./tests.nix) and [tests.py](tests.py).
### Tutorial
#### Running tests
```bash
# Run the basic set of tests. These tests are also run on the GitHub CI server.
./run-tests.sh
# Run the test for scenario `regtest`.
# The test is run via the Nix build system. Successful runs are cached.
./run-tests.sh -s regtest build
./run-tests.sh -s regtest # Shorthand, equivalent
# To test a single service, use its name as a scenario.
./run-tests.sh -s clightning
# When no scenario is specified, scenario `default` is used.
./run-tests.sh build
```
#### Debugging
```bash
# Start a shell inside a test VM. No tests are executed.
./run-tests.sh -s bitcoind vm
systemctl status bitcoind
# Run a Python NixOS test shell inside a VM.
# See https://nixos.org/manual/nixos/stable/#ssec-machine-objects for available commands.
./run-tests.sh debug
print(succeed("systemctl status bitcoind"))
run_test("bitcoind")
# Start a shell in a container node. Requires systemd and root privileges.
./run-tests.sh container
# In the container shell: Run command in container (with prefix `c`)
c systemctl status bitcoind
# Explore a single feature
./run-tests.sh -s electrs container
# Run a command in a container.
# The container is deleted afterwards.
./run-tests.sh -s clightning container --run c lightning-cli getinfo
# Define a custom scenario
./run-tests.sh --scenario '{
services.clightning.enable = true;
nix-bitcoin.nodeinfo.enable = true;
}' container --run c nodeinfo
```
# Running tests with Flakes
Tests can also be accessed via the nix-bitcoin flake:
```bash
# Build test
nix build --no-link ..#tests.default
# Run a node in a VM. No tests are executed.
nix run ..#tests.default.vm
# Run a Python test shell inside a VM node
nix run ..#tests.default.run -- --debug
# Run a node in a container. Requires extra-container, systemd and root privileges
nix run ..#tests.default.container
nix run ..#tests.default.containerLegacy # For NixOS with `system.stateVersion` <22.05
# Run a command in a container
nix run ..#tests.default.container -- --run c nodeinfo
nix run ..#tests.default.containerLegacy -- --run c nodeinfo # For NixOS with `system.stateVersion` <22.05
```
-50
View File
@@ -1,50 +0,0 @@
#!/usr/bin/env bash
# Build a single-output derivation and store it in 'cachixCache'.
# Skip the build if it is already cached.
# Accepts the same arguments as nix-instantiate.
set -euo pipefail
CACHIX_SIGNING_KEY="${CACHIX_SIGNING_KEY:-}"
cachixCache=nix-bitcoin
trap 'echo "Error at ${BASH_SOURCE[0]}:$LINENO"' ERR
tmpDir=$(mktemp -d -p /tmp)
trap 'rm -rf $tmpDir' EXIT
## Instantiate
time nix-instantiate "$@" --add-root "$tmpDir/drv" --indirect > /dev/null
drv=$(realpath "$tmpDir/drv")
echo "instantiated $drv"
outPath=$(nix-store --query "$drv")
if nix path-info --store "https://${cachixCache}.cachix.org" "$outPath" &>/dev/null; then
echo "$outPath has already been built successfully."
exit 0
fi
## Build
if [[ -v GITHUB_ACTIONS ]]; then
# Avoid cachix warning message
mkdir -p ~/.config/nix && touch ~/.config/nix/nix.conf
cachix use "$cachixCache"
fi
if [[ $CACHIX_SIGNING_KEY ]]; then
# Speed up task by uploading store paths as soon as they are created
buildCmd="cachix watch-exec $cachixCache nix -- build"
else
buildCmd="nix build"
fi
$buildCmd --out-link "$tmpDir/result" --print-build-logs "$drv^*"
if [[ $CACHIX_SIGNING_KEY ]]; then
cachix push "$cachixCache" "$outPath"
fi
echo "$outPath"
-20
View File
@@ -1,20 +0,0 @@
#!/usr/bin/env bash
# This script can also be run locally for testing:
# ./build.sh <scenario>
#
# When variable GITHUB_ACTIONS is unset, this script leaves no persistent traces on the host system.
set -euo pipefail
scenario=$1
if [[ -v GITHUB_ACTIONS ]]; then
if [[ ! -e /dev/kvm ]]; then
>&2 echo "No KVM available on VM host."
exit 1
fi
fi
cd "${BASH_SOURCE[0]%/*}"
exec ./build-to-cachix.sh --expr "(builtins.getFlake (toString ../..)).legacyPackages.\${builtins.currentSystem}.tests.$scenario"
-61
View File
@@ -1,61 +0,0 @@
#!/usr/bin/env bash
set -euo pipefail
cd "${BASH_SOURCE[0]%/*}"
cachixCache=nix-bitcoin
# Declare variables for shellcheck
driverDrvs=()
drivers=()
scenarioTests=()
echo '::group::Eval test drivers'
# Call ./test-info.nix
testInfo=$(time nix eval --raw --show-trace ../..#ciTestInfo)
# This sets variables `driverDrvs`, `drivers`, `scenarioTests`
eval "$testInfo"
for i in "${!drivers[@]}"; do
echo "${drivers[$i]}"
echo "${driverDrvs[$i]%^*}"
done
echo '::endgroup::'
if nix path-info --store "https://${cachixCache}.cachix.org" "${scenarioTests[@]}" &>/dev/null; then
echo
echo "All tests have already been built successfully:"
printf '%s\n' "${scenarioTests[@]}"
exit 0
fi
echo "run_scenario_tests=true" >> "$GITHUB_OUTPUT"
## Build test drivers
if nix path-info --store "https://${cachixCache}.cachix.org" "${drivers[@]}" &>/dev/null; then
echo
echo "All test drivers have already been built successfully:"
exit 0
fi
echo '::group::Build test drivers'
if [[ -v GITHUB_ACTIONS ]]; then
# Avoid cachix warning message
mkdir -p ~/.config/nix && touch ~/.config/nix/nix.conf
cachix use "$cachixCache"
fi
if [[ $CACHIX_SIGNING_KEY ]]; then
# Speed up task by uploading store paths as soon as they are created
buildCmd="cachix watch-exec $cachixCache nix -- build"
else
buildCmd="nix build"
fi
$buildCmd --no-link --print-build-logs "${driverDrvs[@]}"
if [[ $CACHIX_SIGNING_KEY ]]; then
cachix push "$cachixCache" "${drivers[@]}"
fi
-29
View File
@@ -1,29 +0,0 @@
pkgs: instantiateTests:
let
scenarioNames = let
inherit (pkgs) lib;
workflowSrc = builtins.readFile ../../.github/workflows/test.yml;
matches = builtins.match ".*scenario:(([ \n]+-[ ]+[^ \n]+)+).*" workflowSrc;
scenariosStr = builtins.head matches;
particles = builtins.split "[ \n]+-[ ]+" scenariosStr;
# The first split particle is always an empty str
particles' = builtins.tail particles;
in
builtins.filter lib.isString particles';
# `instantiateTests` prints the test name before evaluating, which is useful for debugging
ciTests = instantiateTests scenarioNames;
drivers = map (x: x.driver) ciTests;
driverDrvs = map (x: ''"${x.drvPath}^*"'') drivers;
in ''
driverDrvs=(
${builtins.concatStringsSep "\n" driverDrvs}
)
drivers=(
${builtins.concatStringsSep "\n" drivers}
)
scenarioTests=(
${builtins.concatStringsSep "\n" ciTests}
)
''
-158
View File
@@ -1,158 +0,0 @@
# You can run this test via `run-tests.sh -s clightning-replication`
makeTestVM: pkgs:
with pkgs.lib;
let
keyDir = pkgs.path + "/nixos/tests/initrd-network-ssh";
keys = {
server = keyDir + "/ssh_host_ed25519_key";
client = keyDir + "/id_ed25519";
serverPub = readFile (keys.server + ".pub");
clientPub = readFile (keys.client + ".pub");
};
clientBaseConfig = {
imports = [ ../modules/modules.nix ];
system.switch.enable = true;
nixpkgs.pkgs = pkgs;
nix-bitcoin.generateSecrets = true;
services.clightning = {
enable = true;
replication.enable = true;
# TODO-EXTERNAL:
# When WAN is disabled, DNS bootstrapping slows down service startup by ~15 s.
extraConfig = ''
disable-dns
'';
};
};
in
makeTestVM {
name = "clightning-replication";
nodes = let nodes = {
replicationLocal = {
imports = [ clientBaseConfig ];
services.clightning.replication.local.directory = "/var/backup/clightning";
};
replicationLocalEncrypted = {
imports = [ nodes.replicationLocal ];
services.clightning.replication.encrypt = true;
};
replicationRemote = {
imports = [ clientBaseConfig ];
nix-bitcoin.generateSecretsCmds.clightning-replication-ssh-key = mkForce ''
install -m 600 ${keys.client} clightning-replication-ssh-key
'';
programs.ssh.knownHosts."server".publicKey = keys.serverPub;
services.clightning.replication.sshfs.destination = "nb-replication@server:writable";
};
replicationRemoteEncrypted = {
imports = [ nodes.replicationRemote ];
services.clightning.replication.encrypt = true;
};
server = {
nixpkgs.pkgs = pkgs;
environment.etc."ssh-host-key" = {
source = keys.server;
mode = "400";
};
services.openssh = {
enable = true;
extraConfig = ''
Match user nb-replication
ChrootDirectory /var/backup/nb-replication
AllowTcpForwarding no
AllowAgentForwarding no
ForceCommand internal-sftp
PasswordAuthentication no
X11Forwarding no
'';
hostKeys = mkForce [
{
path = "/etc/ssh-host-key";
type = "ed25519";
}
];
};
users.users.nb-replication = {
isSystemUser = true;
group = "nb-replication";
shell = "${pkgs.coreutils}/bin/false";
openssh.authorizedKeys.keys = [ keys.clientPub ];
};
users.groups.nb-replication = {};
systemd.tmpfiles.rules = [
# Because this directory is chrooted by sshd, it must only be writable by user/group root
"d /var/backup/nb-replication 0755 root root - -"
"d /var/backup/nb-replication/writable 0700 nb-replication - - -"
];
};
}; in nodes;
testScript = { nodes, ... }: let
systems = builtins.concatStringsSep ", "
(mapAttrsToList (name: node: ''"${name}": "${node.system.build.toplevel}"'') nodes);
in ''
systems = { ${systems} }
def switch_to_system(system):
cmd = f"{systems[system]}/bin/switch-to-configuration test >&2"
client.succeed(cmd)
client = replicationLocal
if not "is_interactive" in vars():
client.start()
server.start()
with subtest("local replication"):
client.wait_for_unit("clightning.service")
client.wait_until_succeeds("runuser -u clightning -- ls /var/backup/clightning/lightningd.sqlite3")
# No other user should be able to read the backup directory
client.fail("runuser -u bitcoin -- ls /var/backup/clightning")
# If `switch_to_system` succeeds then all services, including clightning,
# have started successfully
switch_to_system("replicationLocalEncrypted")
with subtest("local replication encrypted"):
replica_db = "/var/cache/clightning-replication/plaintext/lightningd.sqlite3"
client.wait_until_succeeds(f"runuser -u clightning -- ls {replica_db}")
# No other user should be able to read the unencrypted files
client.fail(f"runuser -u bitcoin -- ls {replica_db}")
# A gocryptfs has been created
client.succeed("ls /var/backup/clightning/lightningd-db/gocryptfs.conf")
switch_to_system("replicationRemote")
server.wait_for_unit("sshd.service")
with subtest("remote replication"):
replica_db = "/var/cache/clightning-replication/sshfs/lightningd.sqlite3"
client.wait_until_succeeds(f"runuser -u clightning -- ls {replica_db}")
# No other user should be able to read the unencrypted files
client.fail(f"runuser -u bitcoin -- ls {replica_db}")
# A clighting db exists on the server
server.succeed("ls /var/backup/nb-replication/writable/lightningd.sqlite3")
switch_to_system("replicationRemoteEncrypted")
with subtest("remote replication encrypted"):
replica_db = "/var/cache/clightning-replication/plaintext/lightningd.sqlite3"
client.wait_until_succeeds(f"runuser -u clightning -- ls {replica_db}")
# No other user should be able to read the unencrypted files
client.fail(f"runuser -u bitcoin -- ls {replica_db}")
# A gocryptfs has been created on the server
server.succeed("ls /var/backup/nb-replication/writable/lightningd-db/gocryptfs.conf")
'';
}
-21
View File
@@ -1,21 +0,0 @@
# Re-run run-tests.sh in a snapshot copy of the source.
# Maintain /tmp/nix-bitcoin-src as a source cache to minimize copies.
tmp=$(mktemp -d '/tmp/nix-bitcoin-src.XXXXX')
# Move source cache if it exists (atomic)
mv /tmp/nix-bitcoin-src "$tmp/src" 2>/dev/null || true
atExit() {
# Set the current src as the source cache (atomic)
mv -T "$tmp/src" /tmp/nix-bitcoin-src 2>/dev/null || true
rm -rf "$tmp"
}
trap "atExit" EXIT
# shellcheck disable=SC2154
rsync -a --delete "$scriptDir/../" "$tmp/src"
echo "Copied src"
# shellcheck disable=SC2154
_nixBitcoinInCopiedSrc=1 "$tmp/src/test/run-tests.sh" "${args[@]}"
-13
View File
@@ -1,13 +0,0 @@
containerBin=$(type -P extra-container) || true
if [[ ! ($containerBin && $(realpath "$containerBin") == *extra-container-0.14*) ]]; then
echo
echo "Building extra-container. Skip this step by adding extra-container 0.14 to PATH."
nix build --out-link /tmp/extra-container "${BASH_SOURCE[0]%/*}"/../..#extra-container
# When this script is run as root, e.g. when run in an extra-container shell,
# chown the gcroot symlink to the regular (login) user so that the symlink can be
# overwritten when this script is run without root.
if [[ $EUID == 0 ]]; then
chown "$(logname):" --no-dereference /tmp/extra-container
fi
export PATH="/tmp/extra-container/bin${PATH:+:}$PATH"
fi
-24
View File
@@ -1,24 +0,0 @@
# FIXME:
# Remove this file, along with the imports in ../../dev/dev.sh,
# ../../examples/container/flake.nix, ../../examples/deploy-container.sh and
# ./make-test.nix, as soon as extra-container declares these options itself
# (https://github.com/erikarvstedt/extra-container/blob/master/eval-config.nix).
#
# extra-container evaluates the container host with a minimal module set to keep
# eval times low. NixOS 26.05 added references to the following options to
# `system/boot/systemd.nix`, which is part of that module set, while their
# declaring modules are not.
#
# The defaults match the ones from the declaring modules. Like extra-container's
# own dummy options, these declarations have no type because they only exist to
# make host eval succeed. They don't affect the resulting container units.
{ lib, pkgs, ... }: {
options = {
environment.variables = lib.mkOption { default = {}; };
i18n.imperativeLocale = lib.mkOption { default = false; };
services.openssh.enable = lib.mkOption { default = false; };
system.nixos-init.package = lib.mkOption { default = pkgs.nixos-init; };
time.timeZone = lib.mkOption { default = null; };
};
}
-76
View File
@@ -1,76 +0,0 @@
#!/usr/bin/env bash
# Usage:
#
# run-tests.sh [--scenario|-s <scenario>] container
#
# Start container and start a shell session with helper commands
# for accessing the container.
# A short command documentation is printed at the start of the session.
# The container is destroyed after exiting the shell.
# An existing container is destroyed before starting.
#
# Supported arguments:
#
# --destroy|-d to destroy
#
# When `run-tests.sh container` from inside an existing shell session,
# the current container is updated without restarting by switching
# its NixOS configuration.
# Use this arg to destroy and restart the container instead.
#
# --no-destroy|-n
#
# By default, all commands destroy an existing container before starting and,
# when appropriate, before exiting.
# This ensures that containers start with no leftover filesystem state from
# previous runs and that containers don't consume system resources after use.
# This args disables auto-destructing containers.
#
#
# run-tests.sh container --run c systemctl status bitcoind
#
# Run a command in the shell session environmentand exit.
# Destroy the container afterwards.
# All arguments following `--run` are used as a command.
# Supports argument '--no-destroy|-n' (see above for an explanation).
#
# Example: Start shell inside container
# run-tests.sh container --run c
#
#
# run-tests.sh [--scenario|-s <scenario>] container --command|-c
#
# Provide a custom extra-container command.
#
# Example:
# run-tests.sh container --command create -s
# Create and start a container without a shell.
#
#
# All extra args are passed to extra-container (unless --command is used):
# run-tests.sh container --build-args --builders 'ssh://worker - - 8'
set -euo pipefail
# These vars are set by ../run-tests.sh
: "${container:=}"
: "${scriptDir:=}"
containerCommand=shell
while [[ $# -gt 0 ]]; do
case $1 in
--command|-c)
shift
containerCommand=$1
shift
;;
*)
break
esac
done
. "${BASH_SOURCE[0]%/*}"/extra-container-check-version.sh
exec "$container"/bin/container "$containerCommand" "$@"
-35
View File
@@ -1,35 +0,0 @@
pkgs:
let
pythonTesting = import (pkgs.path + "/nixos/lib/testing-python.nix") {
system = pkgs.stdenv.hostPlatform.system;
inherit pkgs;
};
in
module:
let
test = (pythonTesting.evalTest module).config;
runTest = pkgs.stdenv.mkDerivation {
name = "vm-test-run-${test.name}";
requiredSystemFeatures = [ "kvm" "nixos-test" ];
# 1. Save test logging output
# 2. Add link to driver so that a gcroot to a test prevents the driver from
# being garbage-collected
buildCommand = ''
mkdir "$out"
LOGFILE=$out/output.xml tests='exec(os.environ["testScript"])' ${test.driver}/bin/nixos-test-driver
ln -s ${test.driver} "$out/driver"
'';
inherit (test) meta passthru;
} // test;
in
runTest // {
# A VM runner for interactive use
run = pkgs.writers.writeBashBin "run-vm" ''
. ${./run-vm.sh} ${runTest.driver} "$@"
'';
}
-151
View File
@@ -1,151 +0,0 @@
flake: pkgs: makeTestVM:
let
inherit (flake.inputs) extra-container;
inherit (pkgs.stdenv.hostPlatform) system;
in
{ name ? "nix-bitcoin-test", config }:
let
inherit (pkgs) lib;
testConfig = config;
test = makeTestVM {
inherit name;
nodes.machine = { config, ... }: {
imports = [
testConfig
commonVmConfig
];
test.shellcheckServices.enable = true;
};
testScript = { nodes, ... }: let
cfg = nodes.machine;
data = {
data = cfg.test.data;
tests = cfg.tests;
};
dataFile = pkgs.writeText "test-data" (builtins.toJSON data);
initData = ''
import json
with open("${dataFile}") as f:
data = json.load(f)
enabled_tests = set(test for (test, enabled) in data["tests"].items() if enabled)
test_data = data["data"]
'';
in
builtins.concatStringsSep "\n\n" [
initData
(builtins.readFile ./../tests.py)
cfg.test.extraTestScript
# Don't run tests in interactive mode.
# is_interactive is set in ./run-vm.sh
''
if not "is_interactive" in vars():
nb_run_tests()
''
];
};
mkContainer = legacyInstallDirs:
extra-container.lib.buildContainers {
inherit system legacyInstallDirs;
config = {
imports = [ ./extra-container-workaround.nix ];
# The container name has a 11 char length limit
containers.nb-test = { config, ... }: {
imports = [
{
config = {
extra = {
# Defined here instead of in the container config because NixOS
# 26.05 derives the container's `networking.interfaces` from
# `localAddress`, which extra-container derives from
# `addressPrefix`. Reading it from the container config would
# thus be circular.
addressPrefix = "10.225.255";
inherit (config.config.test.container)
enableWAN firewallAllowHost exposeLocalhost;
};
config = testConfig;
};
}
# Enable FUSE inside the container when clightning replication
# is enabled.
(
let
s = config.config.services;
in
lib.mkIf (s ? clightning && s.clightning.enable && s.clightning.replication.enable) {
allowedDevices = [ { node = "/dev/fuse"; modifier = "rw"; } ];
}
)
];
};
};
};
container = mkContainer false;
containerLegacy = mkContainer true;
# This allows running a test scenario in a regular NixOS VM.
# No tests are executed.
vm = (pkgs.nixos ({ config, ... }: {
imports = [
testConfig
commonVmConfig
(pkgs.path + "/nixos/modules/virtualisation/qemu-vm.nix")
];
virtualisation.graphics = false;
services.getty.autologinUser = "root";
# Avoid lengthy build of the nixos manual
documentation.nixos.enable = false;
# Power off VM when the user exits the shell
systemd.services."serial-getty@".preStop = ''
echo o >/proc/sysrq-trigger
'';
system.stateVersion = lib.mkDefault config.system.nixos.release;
})).config.system.build.vm.overrideAttrs (old: {
meta = old.meta // { mainProgram = "run-vm-in-tmpdir"; };
buildCommand = old.buildCommand + "\n" + ''
install -m 700 ${./run-vm-without-tests.sh} $out/bin/run-vm-in-tmpdir
patchShebangs $out/bin/run-vm-in-tmpdir
'';
});
commonVmConfig = {
virtualisation = {
# Needed because duplicity requires 270 MB of free temp space, regardless of backup size
diskSize = 1024;
# The `netns` scenarios need more than 2 GiB: netns-isolation adds a
# network namespace per service, which costs a few hundred MiB of slab.
memorySize = lib.mkDefault 4096;
# There are no perf gains beyond 3 cores.
# Benchmark: Ryzen 7 2700 (8 cores), VM test `default` as of 34f6eb90.
# Num. Cores | 1 | 2 | 3 | 4 | 6
# Runtime (sec) | 125 | 95 | 89 | 89 | 90
cores = lib.mkDefault 3;
};
};
in
test // {
inherit
vm
container
# For NixOS with `system.stateVersion` <22.05
containerLegacy;
config = testConfig;
}
-30
View File
@@ -1,30 +0,0 @@
#!/usr/bin/env bash
set -euo pipefail
# This script uses the following env vars:
# NIX_BITCOIN_VM_ENABLE_NETWORK
# NIX_BITCOIN_VM_DATADIR
# QEMU_OPTS
# QEMU_NET_OPTS
if [[ ${NIX_BITCOIN_VM_DATADIR:-} ]]; then
dataDir=$NIX_BITCOIN_VM_DATADIR
else
dataDir=$(mktemp -d /tmp/nix-bitcoin-vm.XXX)
trap 'rm -rf "$dataDir"' EXIT
fi
if [[ ! ${NIX_BITCOIN_VM_ENABLE_NETWORK:-} ]]; then
QEMU_NET_OPTS='restrict=on'
fi
# TODO-EXTERNAL:
# Pass PATH because run-*-vm is impure (requires coreutils from PATH)
env -i \
PATH="$PATH" \
USE_TMPDIR=1 \
TMPDIR="$dataDir" \
NIX_DISK_IMAGE="$dataDir/img.qcow2" \
QEMU_OPTS="${QEMU_OPTS:-}" \
QEMU_NET_OPTS="${QEMU_NET_OPTS:-}" \
"${BASH_SOURCE[0]%/*}"/run-*-vm
-50
View File
@@ -1,50 +0,0 @@
#!/usr/bin/env bash
set -euo pipefail
# This script uses the following env vars:
# NIX_BITCOIN_VM_ENABLE_NETWORK
# NIX_BITCOIN_VM_DATADIR
# QEMU_OPTS
# QEMU_NET_OPTS
if [[ ${NIX_BITCOIN_VM_DATADIR:-} ]]; then
dataDir=$NIX_BITCOIN_VM_DATADIR
else
dataDir=$(mktemp -d /tmp/nix-bitcoin-vm.XXX)
trap 'rm -rf "$dataDir"' EXIT
fi
testDriver=$1
shift
# Variable 'tests' contains the Python code that is executed by the driver on startup
if [[ ${1:-} == --debug ]]; then
shift
echo "Running interactive testing environment"
# Start REPL.
# Use `code.interact` for the REPL instead of the builtin test driver REPL
# because it supports low featured terminals like Emacs' shell-mode.
tests='
is_interactive = True
exec(open(os.environ["testScript"]).read())
if "machine" in vars(): machine.start()
import code
code.interact(local=globals())
'
echo
echo "Starting VM, data dir: $dataDir"
else
tests='exec(open(os.environ["testScript"]).read())'
fi
if [[ ! ${NIX_BITCOIN_VM_ENABLE_NETWORK:-} ]]; then
QEMU_NET_OPTS='restrict=on'
fi
# The VM creates a VDE control socket in $PWD
env --chdir "$dataDir" -i \
USE_TMPDIR=1 \
TMPDIR="$dataDir" \
QEMU_OPTS="-nographic ${QEMU_OPTS:-}" \
QEMU_NET_OPTS="${QEMU_NET_OPTS:-}" \
"$testDriver/bin/nixos-test-driver" <(echo "$tests") "$@"
-127
View File
@@ -1,127 +0,0 @@
{ config, pkgs, lib, extendModules, ... }@args:
with lib;
let
options.test.shellcheckServices = {
enable = mkOption {
type = types.bool;
default = false;
description = ''
Whether to shellcheck services during system build time.
'';
};
sourcePrefix = mkOption {
type = with types; nullOr str;
default = null;
description = ''
The definition source path prefix of services to include in the shellcheck.
'';
};
runShellcheck = mkOption {
readOnly = true;
description = ''
A derivation that runs shellcheck on all bash scripts included
in nix-bitcoin services.
'';
default = shellcheckServices;
};
};
cfg = config.test.shellcheckServices;
# A list of all service names that are defined in source paths prefixed by
# `sourcePrefix`.
# [ "bitcoind", "clightning", ... ]
#
# Algorithm: Parse defintions of `systemd.services` and return all services
# that only have definitions located within `sourcePrefix`.
servicesToCheck = let
inherit (cfg) sourcePrefix;
systemdServices = args.options.systemd.services;
configSystemdServices = args.config.systemd.services;
matchingServices = collectServices true;
nonMatchingServices = collectServices false;
# Return set of services ({ service1 = true; service2 = true; ... })
# which are either defined or not defined within `sourcePrefix`, depending
# on `shouldMatch`.
collectServices = shouldMatch: lib.listToAttrs (builtins.concatLists (map (def:
let
services = def.value;
inherit (def) file;
isMatching = lib.hasPrefix sourcePrefix file;
in
# Nix has no boolean XOR, so use `if`
lib.optionals (if shouldMatch then isMatching else !isMatching) (
(map (service: { name = service; value = true; }) (builtins.attrNames services))
)
) systemdServices.definitionsWithLocations));
in
# Calculate set difference: matchingServices - nonMatchingServices
# and exclude unavailable services (defined via `mkIf false ...`) by checking `configSystemdServices`.
builtins.filter (prefixedService:
configSystemdServices ? ${prefixedService} && (! nonMatchingServices ? ${prefixedService})
) (builtins.attrNames matchingServices);
# The concatenated list of values of ExecStart, ExecStop, ... (`scriptAttrs`) of all `servicesToCheck`.
serviceCmds = let
scriptAttrs = [
"ExecStartPre"
"ExecStart"
"ExecStartPost"
"ExecStop"
"ExecStopPost"
"ExecCondition"
"ExecReload"
];
services = config.systemd.services;
in
builtins.concatMap (serviceName: let
serviceCfg = services.${serviceName}.serviceConfig;
in
builtins.concatMap (attr:
lib.optionals (serviceCfg ? ${attr}) (
let
cmd = serviceCfg.${attr};
in
if builtins.typeOf cmd == "list" then cmd else [ cmd ]
)
) scriptAttrs
) servicesToCheck;
# A list of all binaries included in `serviceCmds`
serviceBinaries = map (cmd: builtins.head (
# Extract the first component (the binary).
# cmd can start with extra modifiers like `+`
builtins.match "[^/]*([^[:space:]]+).*" (toString cmd)
)) serviceCmds;
shellcheckServices = pkgs.runCommand "shellcheck-services" {
inherit serviceBinaries;
# The `builtins.match` in `serviceBinaries` discards the string context, so we
# also have to add `serviceCmds` to the derivation. This ensures that all
# referenced nix paths are available to the builder.
inherit serviceCmds;
} ''
echo "Checked binaries:"
# Find and check all binaries that have a bash shebang
grep -Pl '\A#! *\S+bash\b' $serviceBinaries | while IFS= read -r script; do
echo "$script"
${pkgs.shellcheck}/bin/shellcheck --shell bash "$script"
done | tee "$out"
'';
in
{
inherit options;
config = mkIf (cfg.enable && cfg.sourcePrefix != null) {
assertions = [
{
assertion = builtins.length servicesToCheck > 0;
message = "test.shellcheckServices: No services found with source prefix `${cfg.sourcePrefix}`";
}
];
system.extraDependencies = [ shellcheckServices ];
};
}
-47
View File
@@ -1,47 +0,0 @@
{ config, lib, ... }:
with lib;
{
imports = [
./shellcheck-services.nix
];
options = {
test = {
noConnections = mkOption {
type = types.bool;
default = !config.test.container.enableWAN;
description = ''
Whether services should be configured to not connect to external hosts.
This can silence some warnings while running the test in an offline environment.
'';
};
data = mkOption {
type = types.attrs;
default = {};
description = ''
Attrs that are available in the Python test script under the global
dictionary variable {var}`test_data`. The data is exported via JSON.
'';
};
extraTestScript = mkOption {
type = types.lines;
default = "";
description = "Extra lines added to the Python test script.";
};
container = {
# Forwarded to extra-container. For descriptions, see
# https://github.com/erikarvstedt/extra-container/blob/master/eval-config.nix
# `addressPrefix` is not settable here, see ./make-test.nix.
enableWAN = mkOption { default = false; };
firewallAllowHost = mkOption { default = true; };
exposeLocalhost = mkOption { default = false; };
};
};
tests = mkOption {
type = with types; attrsOf bool;
default = {};
description = "Python tests that should be run.";
};
};
}
-25
View File
@@ -1,25 +0,0 @@
#!/usr/bin/env bash
set -euo pipefail
cd "${BASH_SOURCE[0]%/*}"
nbFlake=$(realpath ../..)
# Use cachix to cache the `flake-info` build
cachixCache=nix-bitcoin
nix run .#cachix -- use "$cachixCache"
# shellcheck disable=SC2016
PATH=$(nix shell -L .#{flake-info,cachix,jq} -c sh -c 'echo $PATH')
# flake-info uses `nixpkgs` from NIX_PATH
NIX_PATH="nixpkgs=$(nix flake metadata --json --inputs-from "$nbFlake" nixpkgs | jq -r .path)"
export NIX_PATH
if [[ ${CACHIX_SIGNING_KEY:-} ]]; then
cachix push "$cachixCache" "$(type -P flake-info)";
fi
echo "Running flake-info (nixos-search)"
flake-info --json flake ../.. >/dev/null
-48
View File
@@ -1,48 +0,0 @@
#!/usr/bin/env bash
set -euo pipefail
# Run flake-info for the nix-bitcoin flake in an offline sandbox:
# - Adds a consistent, reproducible runtime environment
# - Removes the need to trust the flake-info binary
#
# Use bubblewrap instead of a sandboxed Nix build so that we don't have to copy
# the whole repo to the sandbox when running this test.
cd "${BASH_SOURCE[0]%/*}"
nbFlake=$(realpath ../..)
# shellcheck disable=SC2016
PATH=$(nix shell -L .#{flake-info,bubblewrap,jq} -c sh -c 'echo $PATH')
# flake-info uses `nixpkgs` from NIX_PATH
NIX_PATH="nixpkgs=$(nix flake metadata --json --inputs-from "$nbFlake" nixpkgs | jq -r .path)"
export NIX_PATH
tmpDir=$(mktemp -d /tmp/nix-bitcoin-flake-info.XXX)
trap 'rm -rf $tmpDir' EXIT
echo '
experimental-features = nix-command flakes
flake-registry = /dev/null
' > "$tmpDir/nix.conf"
echo "Running flake-info (nixos-search)"
bwrap \
--unshare-all \
--clearenv \
--setenv PATH "$PATH" \
--setenv NIX_PATH "$NIX_PATH" \
--bind "$tmpDir" / \
--proc /proc \
--dev /dev \
--tmpfs /tmp \
--ro-bind "$nbFlake" "$nbFlake" \
--ro-bind /nix /nix \
--ro-bind /etc /etc \
--tmpfs /etc/nix \
--ro-bind "$tmpDir/nix.conf" /etc/nix/nix.conf \
--ro-bind /usr /usr \
--ro-bind-try /run /run \
-- flake-info --json flake "$nbFlake" >/dev/null
-136
View File
@@ -1,136 +0,0 @@
{
"nodes": {
"flake-parts": {
"inputs": {
"nixpkgs-lib": [
"nixos-search",
"nixpkgs"
]
},
"locked": {
"lastModified": 1785627969,
"narHash": "sha256-4dtXQk/NMePegK/nWp5NSeuZKLATItOq61lpEvmXqGw=",
"owner": "hercules-ci",
"repo": "flake-parts",
"rev": "427bf4bd9435fdf21321c8cc628c24efc14c0f7a",
"type": "github"
},
"original": {
"owner": "hercules-ci",
"repo": "flake-parts",
"type": "github"
}
},
"flake-schemas": {
"locked": {
"lastModified": 1780327564,
"narHash": "sha256-HiRPtA0spK+Dkgbhz/1zW9glXxNVB+L4Rj2VYmdawb8=",
"owner": "DeterminateSystems",
"repo": "flake-schemas",
"rev": "6cc9bd98891b1fc6bb2b8cb3277df8bc72799ca6",
"type": "github"
},
"original": {
"owner": "DeterminateSystems",
"repo": "flake-schemas",
"type": "github"
}
},
"nixos-infra": {
"flake": false,
"locked": {
"lastModified": 1785876137,
"narHash": "sha256-maIa1tcvLYFyedzvWApdpaMLzDyTWktCXeugLOEZzDs=",
"owner": "NixOS",
"repo": "infra",
"rev": "952d0cfaf5d2ae350f9a2746c61e03d53a15b8db",
"type": "github"
},
"original": {
"owner": "NixOS",
"repo": "infra",
"type": "github"
}
},
"nixos-search": {
"inputs": {
"flake-parts": "flake-parts",
"flake-schemas": "flake-schemas",
"nixos-infra": "nixos-infra",
"nixpkgs": "nixpkgs",
"systems": "systems",
"treefmt-nix": "treefmt-nix"
},
"locked": {
"lastModified": 1786265380,
"narHash": "sha256-JX5Q9o03xYMUpAoHB4nz/0Pf3SeL7GrXoKKJhkUMNps=",
"owner": "nixos",
"repo": "nixos-search",
"rev": "7507fd6accc65981f02f66f5c6c328e09efc1221",
"type": "github"
},
"original": {
"owner": "nixos",
"repo": "nixos-search",
"type": "github"
}
},
"nixpkgs": {
"locked": {
"lastModified": 1785967620,
"narHash": "sha256-929m7iW8q2uv3mZHNwY8Um6XKj99rbIcZsWS9cT1vaI=",
"rev": "b7c2ada94fe99c15b0dbcf4d11fd7850b957a436",
"type": "tarball",
"url": "https://releases.nixos.org/nixos/unstable/nixos-26.11pre1048607.b7c2ada94fe9/nixexprs.tar.xz"
},
"original": {
"type": "tarball",
"url": "https://channels.nixos.org/nixos-unstable/nixexprs.tar.xz"
}
},
"root": {
"inputs": {
"nixos-search": "nixos-search"
}
},
"systems": {
"flake": false,
"locked": {
"lastModified": 1681028828,
"narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
"owner": "nix-systems",
"repo": "default",
"rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
"type": "github"
},
"original": {
"owner": "nix-systems",
"repo": "default",
"type": "github"
}
},
"treefmt-nix": {
"inputs": {
"nixpkgs": [
"nixos-search",
"nixpkgs"
]
},
"locked": {
"lastModified": 1785945821,
"narHash": "sha256-NLSyTCW4K4ofhNBllt3omPasm6QpralXH1DBZOc91Dw=",
"owner": "numtide",
"repo": "treefmt-nix",
"rev": "ae7910970dddc408fe6ab1c8e4b277bb21d72dc0",
"type": "github"
},
"original": {
"owner": "numtide",
"repo": "treefmt-nix",
"type": "github"
}
}
},
"root": "root",
"version": 7
}
-34
View File
@@ -1,34 +0,0 @@
# This flake just mirrors input `nixos-search`.
# Because `nixos-search` is a dev-only dependency, we don't add
# it to the main flake.
{
inputs.nixos-search.url = "github:nixos/nixos-search";
outputs = { self, nixos-search }: let
systems = [
"x86_64-linux"
"aarch64-linux"
];
inherit (nixos-search.inputs.nixpkgs) lib;
in {
packages = lib.genAttrs systems (system: {
# In flake-info, Rust calls into Nix code which uses `nixpkgs` from NIX_PATH.
# Don't set `nixpkgs` to a tarball URL, use the default value from the environment instead.
# This allows running flake-info in an offline environment (./flake-info-sandboxed.sh).
flake-info = nixos-search.packages.${system}.flake-info.overrideAttrs (old: {
postPatch = (old.postPatch or "") + ''
file=src/commands/nix_flake_attrs.rs
old_size=$(stat -c%s "$file")
sed -zi 's|command.add_arg_pair([ \n]*"-I",[ \n]*"nixpkgs=https://github.com/NixOS/nixpkgs/archive/refs/heads/nixpkgs-unstable.tar.gz",[ \n]*);||' "$file"
if (($(stat -c%s "$file") == $old_size)); then
echo "String substitution failed"
exit 1
fi
'';
});
});
# Used by ./ci-test.sh
inherit (nixos-search.inputs.nixpkgs) legacyPackages;
};
}
-362
View File
@@ -1,362 +0,0 @@
#!/usr/bin/env bash
# Modules integration test runner.
# The tests (defined in ./tests.nix) use the NixOS testing framework and are executed in a VM.
#
# Usage:
# Run the basic set of tests. These are also run on the CI server.
# ./run-tests.sh
#
# Test specific scenario
# ./run-tests.sh --scenario|-s <scenario>
#
# - When <scenario> contains a space, <scenario> is treated as nix code defining
# a scenario. It is evaluated in the same context as other scenarios in ./tests.nix
#
# Example:
# ./run-tests.sh -s "{ nix-bitcoin.nodeinfo.enable = true; }" container --run c nodeinfo
#
# - When <scenario> does not name a scenario, the test is run with an adhoc scenario
# where services.<scenario> is enabled.
#
# Example:
# ./run-tests.sh -s electrs
#
# Run test(s) and link results to avoid garbage collection
# ./run-tests.sh [--scenario <scenario>] --out-link-prefix /tmp/nix-bitcoin-test
#
# Pass extra args to nix-build
# ./run-tests.sh build --builders 'ssh://mybuildhost - - 15'
#
# Run interactive test debugging
# ./run-tests.sh [--scenario <scenario>] debug
#
# This starts the testing VM and drops you into a Python REPL where you can
# manually execute the tests from ./tests.py
#
# Run a test scenario in a container
# sudo ./run-tests.sh [--scenario <scenario>] container
#
# This is useful for quick experiments; containers start much faster than VMs.
# Running the Python test suite in containers is not yet supported.
# For now, creating NixOS containers requires root permissions.
# See ./lib/make-container.sh for a complete documentation.
#
# Run a test scenario in a regular NixOS VM.
# No tests are executed, the machine's serial console is attached to your terminal.
# ./run-tests.sh [--scenario <scenario>] vm
#
# This is useful for directly exploring a test configuration without the
# intermediate Python REPL layer.
# Run command 'q' inside the machine for instant poweroff.
#
# Run tests from a snapshot copy of the source files
# ./run-tests.sh --copy-src|-c ...
#
# This allows you to continue editing the nix-bitcoin sources while tests are running
# and reading source files.
# Files are copied to /tmp, a caching scheme helps minimizing copies.
#
# Add custom scenarios from a file
# ./run-tests.sh --extra-scenarios ~/my/scenarios.nix ...
set -eo pipefail
scriptDir=$(cd "${BASH_SOURCE[0]%/*}" && pwd)
args=("$@")
scenario=
outLinkPrefix=
scenarioOverridesFile=
while :; do
case $1 in
--scenario|-s)
if [[ $2 ]]; then
scenario=$2
shift
shift
else
>&2 echo "Error: $1 requires an argument."
exit 1
fi
;;
--out-link-prefix|-o)
if [[ $2 ]]; then
outLinkPrefix=$2
shift
shift
else
>&2 echo "Error: $1 requires an argument."
exit 1
fi
;;
--extra-scenarios)
if [[ $2 ]]; then
scenarioOverridesFile=$2
shift
shift
else
>&2 echo "Error: $1 requires an argument."
exit 1
fi
;;
--copy-src|-c)
shift
if [[ ! $_nixBitcoinInCopiedSrc ]]; then
. "$scriptDir/lib/copy-src.sh"
exit
fi
;;
*)
break
esac
done
tmpDir=
# Sets global var `tmpDir`
makeTmpDir() {
if [[ ! $tmpDir ]]; then
tmpDir=$(mktemp -d /tmp/nix-bitcoin-tests.XXX)
# shellcheck disable=SC2064
trap "rm -rf '$tmpDir'" EXIT
fi
}
# Support explicit scenario definitions
if [[ $scenario = *' '* ]]; then
makeTmpDir
scenarioOverridesFile=$tmpDir/scenario-overrides.nix
echo "{ scenarios, pkgs, lib, nix-bitcoin }: with lib; { tmp = $scenario; }" > "$scenarioOverridesFile"
scenario=tmp
fi
# Run the test. No temporary files are left on the host system.
run() {
makeTmpDir
buildTestAttr .run --out-link "$tmpDir/run-vm"
NIX_BITCOIN_VM_DATADIR=$tmpDir "$tmpDir/run-vm/bin/run-vm" "$@"
}
debug() {
run --debug
}
container() {
local nixosContainer
if ! nixosContainer=$(type -p nixos-container) \
|| grep -q '"/etc/nixos-containers"' "$nixosContainer"; then
local attr=container
else
# NixOS with `system.stateVersion` <22.05
local attr=containerLegacy
fi
echo "Building container"
makeTmpDir
export container=$tmpDir/container
buildTestAttr ".$attr" --out-link "$container"
export scriptDir
"$scriptDir/lib/make-container.sh" "$@"
}
# Run a regular NixOS VM
vm() {
makeTmpDir
buildTestAttr .vm --out-link "$tmpDir/vm"
NIX_BITCOIN_VM_DATADIR=$tmpDir "$tmpDir/vm/bin/run-vm-in-tmpdir"
}
# Run the test by building the test derivation
buildTest() {
buildTestAttr "" "$@"
}
evalTest() {
nixInstantiateTest "" "$@"
# Print out path
nix-store -q "$drv"
# Print drv path
realpath "$drv"
}
buildTestAttr() {
local attr=$1
shift
# TODO-EXTERNAL:
# Simplify and switch to pure build when `nix build` can build flake function outputs
nixInstantiateTest "$attr"
nixBuild "$scenario" "$drv" "$@"
}
buildTests() {
local -n tests=$1
shift
makeTmpDir
# TODO-EXTERNAL:
# Simplify and switch to pure build when `nix build` can instantiate flake function outputs
# shellcheck disable=SC2207
drvs=($(nixInstantiate "pkgs.instantiateTestsFromStr \"${tests[*]}\""))
for i in "${!tests[@]}"; do
testName=${tests[$i]}
drv=${drvs[$i]}
echo
echo "Building test '$testName'"
nixBuild "$testName" "$drv" "$@"
done
}
# Instantiate an attr of the test defined in global var `scenario`
nixInstantiateTest() {
local attr=$1
shift
if [[ $scenarioOverridesFile ]]; then
local file="extraScenariosFile = \"$scenarioOverridesFile\";"
else
local file=
fi
nixInstantiate "(pkgs.getTest { name = \"$scenario\"; $file })$attr" "$@" >/dev/null
}
drv=
# Sets global var `drv` to the gcroot link of the instantiated derivation
nixInstantiate() {
local expr=$1
shift
makeTmpDir
drv="$tmpDir/drv"
nix-instantiate --add-root "$drv" -E "
let
pkgs = (builtins.getFlake \"git+file://$scriptDir/..\").legacyPackages.\${builtins.currentSystem};
in
$expr
" "$@"
}
nixBuild() {
local outLinkName=$1
local drv=$2
shift
shift
args=(--print-out-paths -L)
if [[ $outLinkPrefix ]]; then
args+=(--out-link "$outLinkPrefix-$outLinkName")
else
args+=(--no-link)
fi
if isNixVersionGreaterEqual_2_15; then
# This syntax is supported by Nix ≥ 2.13
drv="$(realpath "$drv")^*"
fi
nix build "$drv" "${args[@]}" "$@"
}
isNixGE_2_15=undefined
isNixVersionGreaterEqual_2_15() {
if [[ $isNixGE_2_15 == undefined ]]; then
isNixGE_2_15=
if {
echo '2.15'
nix --version | awk '{print $NF}'
} | sort -C -V; then
isNixGE_2_15=1
fi
fi
[[ $isNixGE_2_15 ]]
}
flake() {
nix flake check --all-systems "$scriptDir/.."
}
# Test generating module documentation for search.nixos.org
nixosSearch() {
if [[ $outLinkPrefix ]]; then
# Add gcroots for flake-info
nix build "$scriptDir/nixos-search#flake-info" -o "$outLinkPrefix-flake-info"
fi
"$scriptDir/nixos-search/flake-info-sandboxed.sh"
}
persistentContainerExample() {
. "$scriptDir/lib/extra-container-check-version.sh"
nix run "$scriptDir/../examples/container" --override-input nix-bitcoin "$scriptDir/.." -- --run c systemctl status electrs
}
# A basic subset of tests to keep the total runtime within
# manageable bounds.
# These are also run on the CI server.
basic=(
default
netns
netnsRegtest
)
basic() { buildTests basic "$@"; }
# All tests that only consist of building a nix derivation.
# shellcheck disable=2034
buildable=(
"${basic[@]}"
full
regtest
hardened
clightning-replication
lndPruned
wireguard-lndconnect
trustedcoin
joinmarket-bitcoind-29
)
buildable() { buildTests buildable "$@"; }
examples() {
# shellcheck disable=SC2016
script='
set -e
runExample() { echo; echo Running example $1; ./$1; }
runExample deploy-container.sh
runExample deploy-container-minimal.sh
runExample deploy-qemu-vm.sh
runExample deploy-krops.sh
'
(cd "$scriptDir/../examples" && nix-shell --run "$script")
echo
echo "Running example 'Persistent container'"
persistentContainerExample
}
shellcheck() {
"$scriptDir/shellcheck.sh"
}
all() {
buildable "$@"
shellcheck
examples
flake
# FIXME: Re-enable when the nixos-search input is usable again.
# flake-info at the currently locked rev supplies nixpkgs to its inner eval
# via `builtins.getFlake` instead of NIX_PATH. This breaks the postPatch in
# ./nixos-search/flake.nix and both runners in ./nixos-search, which pass
# nix-bitcoin's pinned nixpkgs through NIX_PATH.
# Run explicitly with `./run-tests.sh nixosSearch`.
# nixosSearch
}
# An alias for buildTest
build() {
buildTest "$@"
}
if [[ $# -gt 0 && $1 != -* ]]; then
# An explicit command was provided
command=$1
shift
if [[ $command == eval ]]; then
command=evalTest
fi
: "${scenario:=default}"
elif [[ $scenario ]]; then
command=buildTest
else
command=basic
fi
$command "$@"
-22
View File
@@ -1,22 +0,0 @@
#!/usr/bin/env bash
set -euo pipefail
. "${BASH_SOURCE[0]%/*}/../helper/run-in-nix-env" "shellcheck findutils gnugrep" "$@"
# Shellcheck all bash sources in this repo
cd "${BASH_SOURCE[0]%/*}/.."
{
# Skip .git dir in all find commands
find . -type f ! -path './.git/*' -name '*.sh'
# Find files without extensions that have a shell shebang
find . -type f ! -path './.git/*' ! -name "*.*" -exec grep -lP '\A^#! */usr/bin/env (?:nix-shell|bash)' {} \;
} | while IFS= read -r path; do
echo "$path"
file=${path##*/}
dir=${path%/*}
# Switch working directory so that shellcheck can access external sources
# (via arg `--external-sources`)
pushd "$dir" > /dev/null
shellcheck --external-sources --shell bash "$file"
popd > /dev/null
done
-483
View File
@@ -1,483 +0,0 @@
# Integration tests, can be run without internet access.
lib: nixBitcoinModule:
let
# Included in all scenarios
baseConfig = { config, pkgs, ... }: with lib; let
cfg = config.services;
inherit (config.nix-bitcoin.lib.test) mkIfTest;
in {
imports = [
./lib/test-lib.nix
nixBitcoinModule
{
# Features required by the Python test suite
nix-bitcoin.secretsDir = "/secrets";
nix-bitcoin.generateSecrets = true;
nix-bitcoin.operator.enable = true;
environment.systemPackages = with pkgs; [ jq ];
}
];
options.test.features = {
clightningPlugins = mkEnableOption "all clightning plugins";
};
config = mkMerge [{
environment.systemPackages = mkMerge (with pkgs; [
# Needed to test macaroon creation
(mkIfTest "btcpayserver" [ openssl xxd ])
# Needed to test certificate creation
(mkIfTest "lnd" [ openssl ])
]);
tests.bitcoind = cfg.bitcoind.enable;
services.bitcoind = {
enable = true;
extraConfig = mkIf config.test.noConnections "connect=0";
};
tests.clightning = cfg.clightning.enable;
test.data.clightning-replication = cfg.clightning.replication.enable;
tests.trustedcoin = cfg.clightning.plugins.trustedcoin.enable;
# TODO-EXTERNAL:
# When WAN is disabled, DNS bootstrapping slows down service startup by ~15 s.
services.clightning.extraConfig = ''
${optionalString config.test.noConnections "disable-dns"}
'';
test.data.clightning-plugins = let
plugins = config.services.clightning.plugins;
removed = [
# Only defined via `obsolete-options.nix`
"commando"
"helpme"
"prometheus"
"summary"
];
available = subtractLists removed (builtins.attrNames plugins);
enabled = builtins.filter (plugin: plugins.${plugin}.enable) available;
nbPkgs = config.nix-bitcoin.pkgs;
pluginPkgs = nbPkgs.clightning-plugins // {
clboss.path = "${plugins.clboss.package}/bin/clboss";
clnrest.path = "${plugins.clnrest.package}/bin/clnrest";
trustedcoin.path = "${plugins.trustedcoin.package}/bin/trustedcoin";
};
in map (plugin: pluginPkgs.${plugin}.path) enabled;
tests.clightning-rest = cfg.clightning-rest.enable;
tests.rtl = cfg.rtl.enable;
services.rtl = {
nodes = {
lnd = {
enable = mkDefault true;
loop = mkDefault true;
extraConfig.Settings.userPersona = "MERCHANT";
};
clightning.enable = mkDefault true;
};
extraCurrency = mkDefault "CHF";
};
# Use a simple, non-random password for manual web interface tests
nix-bitcoin.generateSecretsCmds.rtl = mkIf cfg.rtl.enable (mkForce ''
echo a > rtl-password
'');
tests.mempool = cfg.mempool.enable;
services.mempool = {
electrumServer = "fulcrum";
settings.MEMPOOL.POOLS_JSON_URL = mkIf config.test.noConnections "disable-pool-fetching";
};
tests.lnd = cfg.lnd.enable;
services.lnd = {
port = 9736;
certificate = {
extraIPs = [ "10.0.0.1" "20.0.0.1" ];
extraDomains = [ "example.com" ];
};
};
nix-bitcoin.onionServices.lnd.public = true;
tests.lndconnect-onion-lnd = with cfg.lnd.lndconnect; enable && onion;
tests.lnconnect-onion-clnrest = with cfg.clightning.plugins.clnrest.lnconnect; enable && onion;
tests.lndconnect-onion-clightning = with cfg.clightning-rest.lndconnect; enable && onion;
tests.lightning-loop = cfg.lightning-loop.enable;
services.lightning-loop.certificate.extraIPs = [ "20.0.0.1" ];
tests.lightning-pool = cfg.lightning-pool.enable;
tests.charge-lnd = cfg.charge-lnd.enable;
tests.electrs = cfg.electrs.enable;
services.fulcrum.port = 50002;
tests.fulcrum = cfg.fulcrum.enable;
tests.liquidd = cfg.liquidd.enable;
services.liquidd.extraConfig = mkIf config.test.noConnections "connect=0";
tests.btcpayserver = cfg.btcpayserver.enable;
services.btcpayserver = {
lightningBackend = mkDefault "lnd";
lbtc = mkDefault true;
};
test.data.btcpayserver-lbtc = config.services.btcpayserver.lbtc;
tests.joinmarket = cfg.joinmarket.enable;
tests.joinmarket-yieldgenerator = cfg.joinmarket.yieldgenerator.enable;
tests.joinmarket-ob-watcher = cfg.joinmarket-ob-watcher.enable;
services.joinmarket.yieldgenerator = {
enable = config.services.joinmarket.enable;
# Test a smattering of custom parameters
ordertype = "absoffer";
cjfee_a = 300;
cjfee_r = 0.00003;
};
tests.nodeinfo = config.nix-bitcoin.nodeinfo.enable;
tests.backups = cfg.backups.enable;
# To test that unused secrets are made inaccessible by 'setup-secrets'
systemd.services.setup-secrets.preStart = mkIfTest "security" ''
install -D -o nobody -g nogroup -m777 <(:) /secrets/dummy
'';
# Avoid timeout failures on slow CI nodes
systemd.services.postgresql.serviceConfig.TimeoutStartSec = "5min";
}
(mkIf config.services.clightning.plugins.clboss.enable {
# Torified 'dig' subprocesses of clboss don't respond to SIGTERM and keep
# running for a long time when WAN is disabled, which prevents clightning units
# from stopping quickly.
# Set TimeoutStopSec for faster stopping.
systemd.services.clightning.serviceConfig.TimeoutStopSec = "500ms";
})
(mkIf config.test.features.clightningPlugins {
services.clightning.plugins = {
clboss.enable = true;
feeadjuster.enable = true;
monitor.enable = true;
rebalance.enable = true;
zmq = let tcpEndpoint = "tcp://127.0.0.1:5501"; in {
enable = true;
channel-opened = tcpEndpoint;
connect = tcpEndpoint;
disconnect = tcpEndpoint;
invoice-payment = tcpEndpoint;
warning = tcpEndpoint;
forward-event = tcpEndpoint;
sendpay-success = tcpEndpoint;
sendpay-failure = tcpEndpoint;
};
};
})
];
};
scenarios = with lib; {
# Included in all scenarios by ./lib/make-test.nix
base = baseConfig;
default = scenarios.secureNode;
# All available basic services and tests
full = {
tests.security = true;
services.clightning.enable = true;
services.clightning.replication = {
enable = true;
encrypt = true;
local.directory = "/var/backup/clightning";
};
services.clightning.plugins.clnrest = {
enable = true;
lnconnect = { enable = true; onion = true; };
};
test.features.clightningPlugins = true;
services.rtl.enable = true;
services.clightning-rest.enable = true;
services.clightning-rest.lndconnect = { enable = true; onion = true; };
services.lnd.enable = true;
services.lnd.lndconnect = { enable = true; onion = true; };
services.lightning-loop.enable = true;
services.lightning-pool.enable = true;
services.charge-lnd.enable = true;
services.mempool.enable = true;
services.electrs.enable = true;
services.fulcrum.enable = true;
services.liquidd.enable = true;
services.btcpayserver.enable = true;
services.joinmarket-ob-watcher.enable = true;
services.backups.enable = true;
nix-bitcoin.nodeinfo.enable = true;
services.hardware-wallets = {
trezor = true;
ledger = true;
};
};
secureNode = {
imports = [
scenarios.full
../modules/presets/secure-node.nix
];
tests.secure-node = true;
tests.restart-bitcoind = true;
nix-bitcoin.onionServices.mempool-frontend.enable = true;
# Stop electrs from spamming the test log with 'WARN - wait until IBD is over' messages
tests.stop-electrs = true;
};
netns = {
imports = with scenarios; [ netnsBase secureNode ];
# This test is rather slow and unaffected by netns settings
tests.backups = mkForce false;
};
# All regtest-enabled services
regtest = {
imports = [ scenarios.regtestBase ];
services.clightning.enable = true;
test.features.clightningPlugins = true;
services.clightning-rest.enable = true;
services.liquidd.enable = true;
services.rtl.enable = true;
services.mempool.enable = true;
services.lnd.enable = true;
services.lightning-loop.enable = true;
services.lightning-pool.enable = true;
services.charge-lnd.enable = true;
services.electrs.enable = true;
services.fulcrum.enable = true;
services.btcpayserver.enable = true;
};
# netns and regtest, without secure-node.nix
netnsRegtest = {
imports = with scenarios; [ netnsBase regtest ];
};
hardened = {
imports = [
scenarios.secureNode
../modules/presets/hardened-extended.nix
];
};
netnsBase = { config, pkgs, ... }: {
nix-bitcoin.netns-isolation.enable = true;
test.data.netns = config.nix-bitcoin.netns-isolation.netns;
tests.netns-isolation = true;
environment.systemPackages = [ pkgs.fping ];
# Used for testing that `netns-exec` is not executable by users other than
# the operator. Like all normal users, this user is a member of group `users`.
users.users.unauthorized.isNormalUser = true;
};
regtestBase = { config, pkgs, ... }: {
tests.regtest = true;
test.data.num_blocks = 100;
services.bitcoind.regtest = true;
systemd.services.bitcoind.postStart = mkAfter ''
cli=${config.services.bitcoind.cli}/bin/bitcoin-cli
if ! $cli listwallets | ${pkgs.jq}/bin/jq -e 'index("test")'; then
"$cli" -named createwallet wallet_name=test load_on_startup=true
address=$($cli -rpcwallet=test getnewaddress)
"$cli" generatetoaddress ${toString config.test.data.num_blocks} "$address"
fi
'';
# lightning-loop contains no builtin swap server for regtest.
# Add a dummy definition.
services.lightning-loop.extraConfig = ''
server.host=127.0.0.1
'';
# lightning-pool contains no builtin auction server for regtest.
# Add a dummy definition
services.lightning-pool.extraConfig = ''
auctionserver=127.0.0.1
'';
# `validatepegin` is incompatible with regtest
services.liquidd.validatepegin = mkForce false;
# TODO-EXTERNAL:
# Reenable `btcpayserver.lbtc` in regtest (and add test in tests.py)
# when nbxplorer can parse liquidd regtest blocks.
#
# When `btcpayserver.lbtc` is enabled in regtest, nxbplorer tries to
# generate regtest blocks, which fails because no liquidd wallet exists.
# When blocks are pre-generated via `liquidd.postStart`, nbxplorer
# fails to parse the blocks:
# info: NBXplorer.Indexer.LBTC: Full node version detected: 210002
# info: NBXplorer.Indexer.LBTC: NBXplorer is correctly whitelisted by the node
# fail: NBXplorer.Indexer.LBTC: Unhandled exception in the indexer, retrying in 10 seconds
# System.IO.EndOfStreamException: No more byte to read
# at NBitcoin.BitcoinStream.ReadWriteBytes(Span`1 data)
services.btcpayserver.lbtc = mkForce false;
};
# Test the special bitcoin RPC setup that lnd uses when bitcoin is pruned
lndPruned = {
services.lnd.enable = true;
services.bitcoind.prune = 1000;
};
trustedcoin = {
imports = [ scenarios.regtestBase ];
services.clightning = {
enable = true;
plugins.trustedcoin.enable = true;
};
};
# The full regtest test with bitcoind 29 and joinmarket enabled.
# Joinmarket only supports bitcoind 29.
joinmarket-bitcoind-29 = { config, ... }: {
imports = [ scenarios.regtest ];
services.joinmarket.enable = true;
services.bitcoind.package = config.nix-bitcoin.pkgs.bitcoind_29;
};
} // (import ../dev/dev-scenarios.nix {
inherit lib scenarios;
});
## Example scenarios that showcase extra features
exampleScenarios = with lib; {
# Run a selection of tests in scenario 'netns'
selectedTests = {
imports = [ scenarios.netns ];
tests = mkForce {
btcpayserver = true;
netns-isolation = true;
};
};
# Container-specific features
containerFeatures = {
# Container has WAN access and bitcoind connects to external nodes
test.container.enableWAN = true;
# See ./lib/test-lib.nix for a description
test.container.exposeLocalhost = true;
};
## Scenarios with a custom Python test
# Variant 1: Define testing code that always runs
customTestSimple = {
networking.hostName = "myhost";
# Variant 1: Define testing code that always runs
test.extraTestScript = ''
succeed("[[ $(hostname) == myhost ]]")
'';
};
# Variant 2: Define a test that can be enabled/disabled
# via the Nix module system.
customTestExtended = {
networking.hostName = "myhost";
tests.hostName = true;
test.extraTestScript = ''
@test("hostName")
def _():
succeed("[[ $(hostname) == myhost ]]")
'';
};
};
in {
inherit scenarios;
pkgs = flake: pkgs: rec {
# A basic test using the nix-bitcoin test framework
makeTestBasic = import ./lib/make-test.nix flake pkgs makeTestVM;
# Wraps `makeTest` in NixOS' testing-python.nix so that the drv includes the
# log output and the test driver
makeTestVM = import ./lib/make-test-vm.nix pkgs;
# A test using the nix-bitcoin test framework, with some helpful defaults
makeTest = { name ? "nix-bitcoin-test", config }:
makeTestBasic {
inherit name;
config = {
imports = [
scenarios.base
config
];
# Share the same pkgs instance among tests
# Set priority slightly higher (i.e. to a slightly lower number) than `mkDefault`,
# so that this module can be used with function `pkgs.nixos`, which already
# sets `nixpkgs.pkgs` with prio `mkDefault`.
nixpkgs.pkgs = lib.mkOverride 900 pkgs;
};
};
# A test using the nix-bitcoin test framework, with defaults specific to nix-bitcoin
makeTestNixBitcoin = { name, config }:
makeTest {
name = "nix-bitcoin-${name}";
config = {
imports = [ config ];
test.shellcheckServices.sourcePrefix = toString ./..;
};
};
makeTests = scenarios: let
mainTests = builtins.mapAttrs (name: config:
makeTestNixBitcoin { inherit name config; }
) scenarios;
in
{
clightning-replication = import ./clightning-replication.nix makeTestVM pkgs;
wireguard-lndconnect = import ./wireguard-lndconnect.nix makeTestVM pkgs;
} // mainTests;
tests = makeTests scenarios;
## Helper for ./run-tests.sh
getTest = { name, extraScenariosFile ? null }:
let
tests = makeTests (scenarios // (
lib.optionalAttrs (extraScenariosFile != null)
(import extraScenariosFile {
inherit scenarios lib pkgs;
nix-bitcoin = flake;
})
));
in
tests.${name} or (makeTestNixBitcoin {
inherit name;
config = {
services.${name}.enable = true;
};
});
instantiateTestsFromStr = testNamesStr: instantiateTests (lib.splitString " " testNamesStr);
instantiateTests = testNames:
map (name:
let
test = tests.${name};
in
builtins.seq (builtins.trace "Evaluating test '${name}'" test.outPath)
test
) testNames;
};
}
-474
View File
@@ -1,474 +0,0 @@
from collections import OrderedDict
import json
import os
import re
def succeed(*cmds):
"""Returns the concatenated output of all cmds"""
return machine.succeed(*cmds)
def assert_matches(cmd, regexp):
assert_str_matches(succeed(cmd), regexp)
def assert_str_matches(str, regexp):
if not re.search(regexp, str):
raise Exception(f"Pattern '{regexp}' not found in '{str}'")
def assert_full_match(cmd, regexp):
out = succeed(cmd)
if not re.fullmatch(regexp, out):
raise Exception(f"Pattern '{regexp}' doesn't match '{out}'")
def log_has_string(unit, str):
return f"journalctl -b --output=cat -u {unit} --grep='{str}'"
def assert_no_failure(unit):
"""Unit should not have failed since the system is running"""
machine.fail(log_has_string(unit, "Failed with result"))
def assert_running(unit):
with machine.nested(f"waiting for unit: {unit}"):
machine.wait_for_unit(unit)
assert_no_failure(unit)
def wait_for_open_port(address, port):
def is_port_open(_):
status, _ = machine.execute(f"nc -z {address} {port}")
return status == 0
with machine.nested(f"Waiting for TCP port {address}:{port}"):
retry(is_port_open)
### Test runner
tests = OrderedDict()
def test(name):
def x(fn):
tests[name] = fn
return x
# `run_tests` is already defined by the NixOS test driver
def nb_run_tests():
enabled = enabled_tests.copy()
to_run = []
for test in tests:
if test in enabled:
enabled.remove(test)
to_run.append(test)
if enabled:
raise RuntimeError(f"The following tests are enabled but not defined: {enabled}")
machine.connect() # Visually separate boot output from the test output
for test in to_run:
with machine.nested(f"test: {test}"):
tests[test]()
def run_test(test):
tests[test]()
### Tests
# All tests are executed in the order they are defined here
@test("security")
def _():
assert_running("setup-secrets")
# Unused secrets should be inaccessible
succeed('[[ $(stat -c "%U:%G %a" /secrets/dummy) = "root:root 440" ]]')
if "secure-node" in enabled_tests:
machine.wait_for_unit("bitcoind")
# `systemctl status` run by unprivileged users shouldn't leak cgroup info
assert_matches(
"runuser -u electrs -- systemctl status bitcoind 2>&1 >/dev/null",
"Failed to dump process list for 'bitcoind.service', ignoring: Access denied",
)
# The 'operator' with group 'proc' has full access
assert_full_match("runuser -u operator -- systemctl status bitcoind 2>&1 >/dev/null", "")
@test("bitcoind")
def _():
assert_running("bitcoind")
machine.wait_until_succeeds("bitcoin-cli getnetworkinfo")
assert_matches("runuser -u operator -- bitcoin-cli getnetworkinfo | jq", '"version"')
regtest = "regtest/" if "regtest" in enabled_tests else ""
assert_full_match(f"stat -c '%a' /var/lib/bitcoind/{regtest}.cookie", "640\n")
# RPC access for user 'public' should be restricted
machine.fail(
"bitcoin-cli -rpcuser=public -rpcpassword=$(cat /secrets/bitcoin-rpcpassword-public) stop"
)
machine.wait_until_succeeds(
log_has_string("bitcoind", "RPC User public not allowed to call method stop")
)
@test("electrs")
def _():
assert_running("electrs")
wait_for_open_port(ip("electrs"), 4224) # prometeus metrics provider
# Check RPC connection to bitcoind
if not "regtest" in enabled_tests:
machine.wait_until_succeeds(
log_has_string("electrs", "waiting for 0 blocks to download")
)
@test("fulcrum")
def _():
assert_running("fulcrum")
machine.wait_until_succeeds(log_has_string("fulcrum", "started ok"))
# Impure: Stops electrs
# Stop electrs from spamming the test log with 'waiting for 0 blocks to download' messages
@test("stop-electrs")
def _():
succeed("systemctl stop electrs")
@test("liquidd")
def _():
assert_running("liquidd")
machine.wait_until_succeeds("elements-cli getnetworkinfo")
assert_matches("runuser -u operator -- elements-cli getnetworkinfo | jq", '"version"')
succeed("runuser -u operator -- liquidswap-cli --help")
@test("clightning")
def _():
assert_running("clightning")
assert_matches("runuser -u operator -- lightning-cli getinfo | jq", '"id"')
enabled_plugins = test_data["clightning-plugins"]
if enabled_plugins:
plugin_list = succeed("lightning-cli plugin list")
plugins = json.loads(plugin_list)["plugins"]
active = set(plugin["name"] for plugin in plugins if plugin["active"])
failed = set(enabled_plugins).difference(active)
if failed:
raise Exception(
f"The following clightning plugins are inactive:\n{failed}.\n\n"
f"Output of 'lightning-cli plugin list':\n{plugin_list}"
)
active = [os.path.splitext(os.path.basename(p))[0] for p in enabled_plugins]
machine.log("\n".join(["Active clightning plugins:", *active]))
if "feeadjuster" in active:
# This is a one-shot service, so this command only succeeds if the service succeeds
succeed("systemctl start clightning-feeadjuster")
if test_data["clightning-replication"]:
replica_db = "/var/cache/clightning-replication/plaintext/lightningd.sqlite3"
succeed(f"runuser -u clightning -- ls {replica_db}")
# No other user should be able to read the unencrypted files
machine.fail(f"runuser -u bitcoin -- ls {replica_db}")
# A gocryptfs has been created
succeed("ls /var/backup/clightning/lightningd-db/gocryptfs.conf")
@test("lnd")
def _():
assert_running("lnd")
assert_matches("runuser -u operator -- lncli getinfo | jq", '"version"')
assert_no_failure("lnd")
# Test certificate generation
cert_alt_names = succeed("</secrets/lnd-cert openssl x509 -noout -ext subjectAltName")
assert_str_matches(cert_alt_names, '10.0.0.1')
assert_str_matches(cert_alt_names, '20.0.0.1')
assert_str_matches(cert_alt_names, 'example.com')
@test("lndconnect-onion-lnd")
def _():
assert_running("lnd")
assert_matches("runuser -u operator -- lndconnect --url", ".onion")
@test("lnconnect-onion-clnrest")
def _():
assert_running("clightning")
assert_matches("runuser -u operator -- lnconnect-clnrest --url", ".onion")
@test("lndconnect-onion-clightning")
def _():
assert_running("clightning-rest")
assert_matches("runuser -u operator -- lndconnect-clightning --url", ".onion")
@test("lightning-loop")
def _():
assert_running("lightning-loop")
assert_matches("runuser -u operator -- loop --version", "version")
# Check that lightning-loop fails with the right error, making sure
# lightning-loop can connect to lnd
machine.wait_until_succeeds(
log_has_string(
"lightning-loop",
"Waiting for lnd to be fully synced to its chain backend, this might take a while",
)
)
@test("lightning-pool")
def _():
assert_running("lightning-pool")
assert_matches("su operator -c 'pool --version'", "version")
# Check that lightning-pool fails with the right error, making sure
# lightning-pool can connect to lnd
machine.wait_until_succeeds(
log_has_string(
"lightning-pool",
"Waiting for lnd to be fully synced to its chain backend, this might take a while",
)
)
@test("charge-lnd")
def _():
# charge-lnd is a oneshot service that is started by a timer under regular operation
succeed("systemctl start charge-lnd")
assert_no_failure("charge-lnd")
@test("btcpayserver")
def _():
assert_running("nbxplorer")
machine.wait_until_succeeds(log_has_string("nbxplorer", "BTC: RPC connection successful"))
if test_data["btcpayserver-lbtc"]:
machine.wait_until_succeeds(log_has_string("nbxplorer", "LBTC: RPC connection successful"))
wait_for_open_port(ip("nbxplorer"), 24444)
assert_running("btcpayserver")
machine.wait_until_succeeds(log_has_string("btcpayserver", "Now listening on"))
wait_for_open_port(ip("btcpayserver"), 23000)
# test lnd custom macaroon
assert_matches(
"runuser -u btcpayserver -- curl -fsS --cacert /secrets/lnd-cert "
'--header "Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 /run/lnd/btcpayserver.macaroon)" '
f"-X GET https://{ip('lnd')}:8080/v1/getinfo | jq",
'"version"',
)
# Test web server response
assert_matches(f"curl -fsS -L {ip('btcpayserver')}:23000", "Welcome to BTCPay Server")
@test("rtl")
def _():
assert_running("rtl")
machine.wait_until_succeeds(
log_has_string("rtl", "Server is up and running")
)
@test("clightning-rest")
def _():
assert_running("clightning-rest")
machine.wait_until_succeeds(
log_has_string("clightning-rest", "cl-rest api server is ready and listening")
)
@test("mempool")
def _():
assert_running("mempool")
assert_running("nginx")
machine.wait_until_succeeds(
log_has_string("mempool", "Mempool Server is running on port 8999")
)
assert_matches(f"curl -L {ip('nginx')}:60845", "mempool - Bitcoin Explorer")
@test("joinmarket")
def _():
assert_running("joinmarket")
machine.wait_until_succeeds(
log_has_string("joinmarket", "JMDaemonServerProtocolFactory starting on 27183")
)
@test("joinmarket-yieldgenerator")
def _():
if "regtest" in enabled_tests:
expected_log_msg = "You do not have the minimum required amount of coins to be a maker"
else:
expected_log_msg = "Critical error updating blockheight."
machine.wait_until_succeeds(log_has_string("joinmarket-yieldgenerator", expected_log_msg))
@test("joinmarket-ob-watcher")
def _():
assert_running("joinmarket-ob-watcher")
machine.wait_until_succeeds(log_has_string("joinmarket-ob-watcher", "Starting ob-watcher"))
@test("nodeinfo")
def _():
status, _ = machine.execute("systemctl is-enabled --quiet onion-addresses 2> /dev/null")
if status == 0:
machine.wait_for_unit("onion-addresses")
json_info = succeed("runuser -u operator -- nodeinfo")
info = json.loads(json_info)
assert info["bitcoind"]["local_address"]
@test("secure-node")
def _():
assert_running("onion-addresses")
# Run this test before the following tests that shut down services
# (and their corresponding network namespaces).
@test("netns-isolation")
def _():
def get_ips(services):
enabled = enabled_tests.intersection(services)
return " ".join(ip(service) for service in enabled)
def assert_reachable(src, dests):
dest_ips = get_ips(dests)
if src in enabled_tests and dest_ips:
machine.succeed(f"ip netns exec nb-{src} fping -c1 -t100 {dest_ips}")
def assert_unreachable(src, dests):
dest_ips = get_ips(dests)
if src in enabled_tests and dest_ips:
machine.fail(
# This fails when no host is reachable within 100 ms
f"ip netns exec nb-{src} fping -c1 -t100 --reachable=1 {dest_ips}"
)
# These reachability tests are non-exhaustive
assert_reachable("bitcoind", ["clightning", "lnd", "liquidd"])
assert_unreachable("bitcoind", ["btcpayserver", "rtl", "lightning-loop"])
assert_unreachable("btcpayserver", ["bitcoind", "lightning-loop"])
# netns addresses can not be bound to in the main netns.
# This prevents processes in the main netns from impersonating nix-bitcoin services.
assert_matches(
f"nc -l {ip('bitcoind')} 1080 2>&1 || true", "nc: Cannot assign requested address"
)
# netns-exec should fail for unauthorized namespaces
assert_matches(
"runuser -u operator -- netns-exec nb-clightning ip a 2>&1 || true",
"nb-clightning is not an allowed netns",
)
# netns-exec should only be executable by the operator user.
# User `unauthorized` is a member of group `users`, like all normal users.
# Netns `nb-clightning` is rejected by netns-exec before it accesses the
# netns, so the error below can only originate from the exec permissions.
assert_matches(
"runuser -u unauthorized -- netns-exec nb-clightning ip a 2>&1 || true",
"Permission denied",
)
if "joinmarket" in enabled_tests:
# netns-exec should drop capabilities
assert_matches(
"runuser -u operator -- netns-exec nb-joinmarket capsh --print | grep Current",
re.compile("^Current: =$", re.MULTILINE),
)
# Impure: stops bitcoind (and dependent services)
@test("backups")
def _():
# For testing that bitcoind wallets are backed up
succeed("bitcoin-cli -named createwallet wallet_name=test blank=true >/dev/null")
succeed("systemctl stop bitcoind")
assert_matches("systemctl show -p ExecMainStatus --value bitcoind", "^0$")
succeed("systemctl start duplicity")
machine.wait_until_succeeds(log_has_string("duplicity", "duplicity.service: Deactivated successfully."))
run_duplicity = "export $(cat /secrets/backup-encryption-env); duplicity"
# Files in backup and /var/lib should be identical
assert_matches(
f"{run_duplicity} verify --archive-dir /var/lib/duplicity file:///var/lib/localBackups /var/lib",
"no sync needed",
)
# Backup should include important files
files = {
"bitcoind": "var/lib/bitcoind/test/wallet.dat",
"clightning": "var/lib/clightning/bitcoin/hsm_secret",
"lnd": "var/lib/lnd/lnd-seed-mnemonic",
"joinmarket": "var/lib/joinmarket/jm-wallet-seed",
"btcpayserver": "var/backup/postgresql/btcpaydb.sql.gz",
}
actual_files = succeed(f"{run_duplicity} list-current-files file:///var/lib/localBackups")
def assert_file_exists(file):
if file not in actual_files:
raise Exception(f"Backup file '{file}' is missing.")
for test, file in files.items():
if test in enabled_tests:
assert_file_exists(file)
assert_file_exists("secrets/lnd-wallet-password")
# Impure: restarts services
@test("restart-bitcoind")
def _():
# Sanity-check system by restarting bitcoind.
succeed("systemctl restart bitcoind")
@test("regtest")
def _():
def enabled(unit):
if unit in enabled_tests:
# Wait because the unit might have been restarted in the preceding
# 'restart-bitcoind' test
machine.wait_for_unit(unit)
return True
else:
return False
def get_block_height(ip, port):
return (
"""echo '{"method": "blockchain.headers.subscribe", "id": 0}'"""
f" | nc {ip} {port} | head -1 | jq -M .result.height"
)
num_blocks = test_data["num_blocks"]
if enabled("electrs"):
machine.wait_until_succeeds(log_has_string("electrs", "serving Electrum RPC"))
assert_full_match(get_block_height(ip('electrs'), 50001), f"{num_blocks}\n")
if enabled("fulcrum"):
machine.wait_until_succeeds(log_has_string("fulcrum", "listening for connections"))
assert_full_match(get_block_height(ip('fulcrum'), 50002), f"{num_blocks}\n")
if enabled("clightning"):
machine.wait_until_succeeds(
f"[[ $(runuser -u operator -- lightning-cli getinfo | jq -M .blockheight) == {num_blocks} ]]"
)
if enabled("lnd"):
machine.wait_until_succeeds(
f"[[ $(runuser -u operator -- lncli getinfo | jq -M .block_height) == {num_blocks} ]]"
)
if enabled("lightning-loop"):
machine.wait_until_succeeds(
log_has_string("lightning-loop", f"Starting event loop at height {num_blocks}")
)
succeed("runuser -u operator -- loop getparams")
if enabled("lightning-pool"):
machine.wait_until_succeeds(
log_has_string("lightning-pool", "lnd is now fully synced to its chain backend")
)
succeed("runuser -u operator -- pool orders list")
if enabled("btcpayserver"):
machine.wait_until_succeeds(log_has_string("nbxplorer", f"At height: {num_blocks}"))
if enabled("mempool"):
assert_running("nginx")
assert_full_match(
f"curl -fsS http://{ip('nginx')}:60845/api/v1/blocks/tip/height", str(num_blocks)
)
@test("trustedcoin")
def _():
def expect_clightning_log(str):
machine.wait_until_succeeds(log_has_string("clightning", str))
expect_clightning_log(r"plugin-trustedcoin\b.*?\bbitcoind RPC working")
if "regtest" in enabled_tests:
num_blocks = test_data["num_blocks"]
expect_clightning_log(rf"plugin-trustedcoin\b.*?\breturning block {num_blocks}")
if "netns-isolation" in enabled_tests:
def ip(name):
return test_data["netns"][name]["address"]
else:
def ip(_):
return "127.0.0.1"
-126
View File
@@ -1,126 +0,0 @@
# You can run this test via `run-tests.sh -s wireguard-lndconnect`
makeTestVM: pkgs:
with pkgs.lib;
makeTestVM {
name = "wireguard-lndconnect";
nodes = {
server = {
imports = [
../modules/modules.nix
../modules/presets/wireguard.nix
];
nixpkgs.pkgs = pkgs;
nix-bitcoin.generateSecrets = true;
nix-bitcoin.operator.enable = true;
services.clightning = {
enable = true;
plugins.clnrest = {
enable = true;
lnconnect.enable = true;
};
};
services.clightning-rest = {
enable = true;
lndconnect.enable = true;
};
# TODO-EXTERNAL:
# When WAN is disabled, DNS bootstrapping slows down service startup by ~15 s.
services.clightning.extraConfig = ''
disable-dns
'';
services.lnd = {
enable = true;
lndconnect.enable = true;
port = 9736;
};
};
client = {
nixpkgs.pkgs = pkgs;
environment.systemPackages = with pkgs; [
wireguard-tools
];
};
};
testScript = ''
import base64
import urllib.parse as Url
from types import SimpleNamespace
def parse_lndconnect_url(url):
u = Url.urlparse(url)
data = {'host': u.hostname, 'port': u.port}
queries = Url.parse_qs(u.query)
if url.startswith("clnrest"):
data['rune'] = queries['rune'][0]
else:
macaroon = queries['macaroon'][0]
if url.startswith("c-lightning-rest"):
data['macaroon_hex'] = macaroon
else:
# lnd
data['macaroon_hex'] = base64.urlsafe_b64decode(macaroon + '===').hex().upper()
return SimpleNamespace(**data)
client.start()
server.connect()
if not "is_interactive" in vars():
with subtest("connect client to server via WireGuard"):
server.wait_for_unit("wireguard-wg-nb-peer-peer0.service")
# Get WireGuard config from server and save it to `/tmp/wireguard.conf` on the client
wg_config = server.succeed("runuser -u operator -- nix-bitcoin-wg-connect server --text")
# Encode to base64
b64 = base64.b64encode(wg_config.encode('utf-8')).decode()
client.succeed(f"install -m 400 <(echo -n {b64} | base64 -d) /tmp/wireguard.conf")
# Connect to server via WireGuard
client.succeed("wg-quick up /tmp/wireguard.conf")
# Ping server from client
print(client.succeed("ping -c 1 -W 0.5 10.10.0.1"))
with subtest("lndconnect-wg"):
server.wait_for_unit("lnd.service")
lndconnect_url = server.succeed("runuser -u operator -- lndconnect-wg --url")
api = parse_lndconnect_url(lndconnect_url)
# Make lnd REST API call
client.succeed(
f"curl -fsS --max-time 3 --insecure --header 'Grpc-Metadata-macaroon: {api.macaroon_hex}' "
f"-X GET https://{api.host}:{api.port}/v1/getinfo"
)
with subtest("lnconnect-clnrest-wg"):
server.wait_for_unit("clightning.service")
lndconnect_url = server.succeed("runuser -u operator -- lnconnect-clnrest-wg --url")
api = parse_lndconnect_url(lndconnect_url)
# Make clnrest API call
client.succeed(
f"curl -fsS --max-time 3 --insecure --header 'rune: {api.rune}' "
f"-X POST https://{api.host}:{api.port}/v1/getinfo"
)
with subtest("lndconnect-clightning-wg"):
server.wait_for_unit("clightning-rest.service")
lndconnect_url = server.succeed("runuser -u operator -- lndconnect-clightning-wg --url")
api = parse_lndconnect_url(lndconnect_url)
# Make clightning-rest API call
client.succeed(
f"curl -fsS --max-time 3 --insecure --header 'macaroon: {api.macaroon_hex}' "
f"--header 'encodingtype: hex' -X GET https://{api.host}:{api.port}/v1/getinfo"
)
'';
}