mirror of
https://github.com/lightningd/plugins.git
synced 2026-08-17 13:07:22 +02:00
110 lines
4 KiB
Markdown
110 lines
4 KiB
Markdown
# A simple and reliable backup plugin
|
|
|
|
**This version only supports the default SQLite3 database**
|
|
|
|
This plugin will maintain clean database backups to another location. It uses
|
|
the `db_write` hook to make sure to always have a backup that is not missing any
|
|
state updates and is not potentially harmful.
|
|
|
|
Related info about backup solutions: https://github.com/ElementsProject/lightning/blob/master/doc/beginners-guide/backup.md
|
|
|
|
## Installation
|
|
|
|
You need [uv](https://docs.astral.sh/uv/getting-started/installation/) to run this
|
|
plugin and `backup-cli` like a binary. After `uv` is installed and you followed the
|
|
[Setup](#setup) step you can simply run
|
|
|
|
```
|
|
lightning-cli plugin start /path/to/backup.py
|
|
```
|
|
|
|
If you use `systemd` to start CLN, you must have `uv` in the `PATH` that `systemd` uses, which is likely different than the `PATH` from your shell. Most `uv` installation methods install `uv` into your user's home directory (`~/.local/bin` or `~/.cargo/bin`), which `systemd` cannot access.
|
|
|
|
You can either:
|
|
|
|
**Option 1: Install `uv` system-wide** (recommended):
|
|
```bash
|
|
curl -LsSf https://astral.sh/uv/install.sh | sudo env UV_INSTALL_DIR="/usr/local/bin" sh
|
|
```
|
|
|
|
**Option 2: Copy your existing user installation**:
|
|
```bash
|
|
sudo cp "$(command -v uv)" /usr/local/bin/uv
|
|
```
|
|
|
|
**Option 3: Configure your systemd service** to use a custom `PATH` (see systemd documentation).
|
|
|
|
To verify `uv` is accessible to systemd:
|
|
```bash
|
|
sudo systemd-run --user --wait command -v uv
|
|
```
|
|
This should output `/usr/local/bin/uv`.
|
|
|
|
For general plugin installation instructions see the repos main
|
|
[README.md](https://github.com/lightningd/plugins/blob/master/README.md#Installation)
|
|
|
|
|
|
## Setup
|
|
|
|
Before the backup plugin can be used it has to be initialized once. The following
|
|
command will create /mnt/external/location/file.sql as backup file and reference it
|
|
in `backup.lock` in the lightning directory that stores the internal state, and
|
|
which makes sure no two instances are using the same backup. (Make sure to stop
|
|
your Lightning node before running this command)
|
|
|
|
```bash
|
|
./backup-cli init --lightning-dir ~/.lightning/bitcoin file:///mnt/external/location/file.bkp
|
|
```
|
|
|
|
Notes:
|
|
- If you are not using the default lightning directory you'll need to
|
|
change `~/.lightning/bitcoin` in the command line to point to that
|
|
directory instead.
|
|
- You should use some non-local SSH or NFS mount as destination,
|
|
otherwise any failure of the disk may result in both the original
|
|
as well as the backup being corrupted.
|
|
- There is support for local filesystems with the `file:///` URL scheme and
|
|
remote support with the `socket:` URL scheme (see [remote](remote.md)).
|
|
|
|
## IMPORTANT note about hsm_secret
|
|
|
|
**You need to secure `~/.lightning/bitcoin/hsm_secret` once! This
|
|
file will not change, but without this file, the database backup will be
|
|
unusable!**
|
|
|
|
Make sure it has user read only permissions, otherwise `lightningd` will refuse
|
|
to work: `chmod 0400 hsm_secret`
|
|
|
|
|
|
## Running
|
|
|
|
In order to tell `lightningd` to use the plugin you either need to tell it
|
|
via the startup option `--plugin /path/to/backup.py` or by placing it (or a
|
|
symlink to it) in the lightning plugin directory (`~/.lightning/plugins`) or
|
|
by adding it to the `lightningd` configuration (`important-plugin=/path/to/backup.py`).
|
|
|
|
On daemon startup the plugin will check the integrity of the existing backup
|
|
and complain if there is a version mismatch.
|
|
|
|
|
|
## Performing backup compaction
|
|
|
|
A backup compaction incorporates incremental updates into a single snapshot.
|
|
This will reduce the size of the backup file and reduce the time needed to
|
|
restore the backup. This can be done through the plugin command `backup-compact`:
|
|
|
|
```
|
|
lightning-cli backup-compact
|
|
```
|
|
|
|
Be aware that this can take a long time depending on the size of the backup
|
|
and I/O speeds, during which the daemon will not be reachable.
|
|
|
|
## Restoring a backup
|
|
|
|
If things really messed up and you need to reinstall clightning, you can
|
|
restore the database backup by using the `backup-cli` utility:
|
|
|
|
```bash
|
|
./backup-cli restore file:///mnt/external/location ~/.lightning/bitcoin/lightningd.sqlite3
|
|
```
|