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