diff --git a/README.md b/README.md index 8c9d614..e123ea4 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,14 @@ Get started - 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). +Docs +--- +* [Hardware Requirements](docs/hardware.md) +* [Installation](docs/install.md) +* [Configuration and maintenance](docs/configuration.md) +* [Using services](docs/services.md) +* [FAQ](docs/faq.md) + Features --- A [configuration preset](modules/presets/secure-node.nix) for setting up a secure node @@ -92,13 +100,6 @@ Security Note that if the machine you're deploying *from* is insecure, there is nothing nix-bitcoin can do to protect itself. -Docs ---- -* [Hardware Requirements](docs/hardware.md) -* [Install instructions](docs/install.md) -* [Usage instructions](docs/usage.md) -* [FAQ](docs/faq.md) - Troubleshooting --- If you are having problems with nix-bitcoin check the [FAQ](docs/faq.md) or submit an issue.\ diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..fa872d5 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,240 @@ +# 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.nix-bitcoin.port ]; +``` + +## Allow bitcoind RPC connections from LAN + +```nix +services.bitcoind = { + # Listen to connections on all interfaces + 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" # 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.nix-bitcoin.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 nodes +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/` 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 + +Use a bitcoind instance running on another node within a nix-bitcoin config. + +```nix +services.bitcoind = { + # Address of the other node + address = "10.10.0.2"; + 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; + }; +}; +# Disable the local bitcoind service +systemd.services.bitcoind.wantedBy = mkForce []; +``` + +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) + +# 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..enable = false`. + +Use the following approach: +``` +systemd.services..wantedBy = mkForce []; +``` +This way, the systemd service still exists, but is not automatically started. + +# 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: + - `/secrets` (if you're using the `secure-node.nix` template) + - `/etc/nix-bitcoin-secrets` (otherwise) + + `/secrets` only exists to provide backwards compatibility for users of the + `secure-node.nix` template. diff --git a/docs/install.md b/docs/install.md index b3c7fac..4aa2ee8 100644 --- a/docs/install.md +++ b/docs/install.md @@ -329,4 +329,7 @@ You can also build Nix from source by following the instructions at https://nixo 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 [usage.md](usage.md) for usage instructions, such as how to update. +See also: +- [Migrating existing services to bitcoind](configuration.md#migrate-existing-services-to-nix-bitcoin) +- [Managing your deployment](configuration.md#managing-your-deployment) +- [Using services](services.md) diff --git a/docs/usage.md b/docs/services.md similarity index 98% rename from docs/usage.md rename to docs/services.md index 08ba40b..572bc09 100644 --- a/docs/usage.md +++ b/docs/services.md @@ -1,11 +1,3 @@ -# Updating -In your deployment directory, enter the nix shell with `nix-shell` and run the -following to update `nix-bitcoin-release.nix`: - -``` -update-nix-bitcoin -``` - # Nodeinfo Run `nodeinfo` to see onion addresses and local addresses for enabled services.