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
-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;
```