docs: add doc 'Configuration and maintenance'
- Move section `updating` from `usage.md` to `configuration.md` and rename `usage.md` -> `services.md`. `services.md` documents how enable and interact with node services. - README: Move `docs` below `Get started`. The `docs` section is short and should be easily accessible.
This commit is contained in:
Erik Arvstedt
parent
94aee8174d
commit
f52059ce3c
15
README.md
15
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.\
|
||||
|
||||
240
docs/configuration.md
Normal file
240
docs/configuration.md
Normal file
@ -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/<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
|
||||
|
||||
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.<service>.enable = false`.
|
||||
|
||||
Use the following approach:
|
||||
```
|
||||
systemd.services.<service>.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.
|
||||
@ -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)
|
||||
|
||||
@ -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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user