Beginner guide

By the end of this guide you will have an encryption key stored safely, a working configuration, a first encrypted backup that has been checked, and a daily schedule.

The guide uses the monero-lws defaults from the example configuration: the server runs as the user monero-lws, and its database is in /home/monero-lws/.bitmonero/light_wallet_server. If your setup differs, change the paths as you go. For a database that is not monero-lws, see Back up other LMDB databases afterwards.

What you need

• lmdb-lws-backup installed at /usr/local/bin/lmdb-lws-backup. See Install.
• The repository's config.example.toml and the files in systemd/.
• A Linux server with systemd, where you can use sudo.
• A safe place outside the server for the key: a password manager, or paper in a locked drawer.
• Free memory roughly equal to the size of the database, for the check after each backup.

Create the encryption key

The key is 32 random bytes, written as base64 text. This step writes it straight into a file that only root can read, so it never appears on screen or in your shell history.

1. Create the configuration folder and an empty key file with mode 600 (owner only):

   sudo mkdir -p /etc/lmdb-lws-backup
   sudo install -m 600 /dev/null /etc/lmdb-lws-backup/key.env

2. Generate the key into it:

   echo "LWS_BACKUP_KEY=$(head -c 32 /dev/urandom | base64)" | sudo tee /etc/lmdb-lws-backup/key.env > /dev/null

   The file now holds one line, LWS_BACKUP_KEY= followed by the key.

3. Save a copy of the key somewhere safe, away from the server and away from the backups:

   sudo cat /etc/lmdb-lws-backup/key.env

   Copy the text after LWS_BACKUP_KEY= into your password manager, then clear the terminal.

DANGER

Without this key, no backup can ever be decrypted. Keep at least one copy outside the server: if the server's disk fails, the copy in /etc is lost with it. Never store the key next to the backups: anyone with both can read every user's view keys.

Write the configuration

1. Copy the example configuration:

   sudo cp config.example.toml /etc/lmdb-lws-backup/config.toml

2. Open it for editing:

   sudoedit /etc/lmdb-lws-backup/config.toml

3. Check these settings:

   [source]
   db_path = "/home/monero-lws/.bitmonero/light_wallet_server"
   
   [backup]
   destination_dir = "/var/backups/monero-lws"
   retention_days = 30
   
   [encryption]
   key_env_var = "LWS_BACKUP_KEY"
   
   [logging]
   log_path = "/var/log/lmdb-lws-backup.log"

   db_path is the folder holding data.mdb and lock.mdb (monero-lws's --db-path). destination_dir is where backups go. key_env_var names the environment variable that will hold the key; the systemd service fills it from key.env.

4. Save and close the editor.

Prepare folders for the service user

The backup runs as the monero-lws user. That user must be able to write the backup folder and the log file, and must have write access to lock.mdb in the database folder (LMDB records every reader there, even read-only ones). monero-lws's own user already has that.

sudo install -d -m 700 -o monero-lws -g monero-lws /var/backups/monero-lws
sudo install -m 600 -o monero-lws -g monero-lws /dev/null /var/log/lmdb-lws-backup.log

Install the systemd units

From the repository folder:

sudo cp systemd/lmdb-lws-backup.service systemd/lmdb-lws-backup.timer /etc/systemd/system/
sudo systemctl daemon-reload

The service runs one backup cycle as monero-lws, with the key loaded from /etc/lmdb-lws-backup/key.env. If your user, database folder or backup folder differ from the defaults, edit User, Group, BindPaths and ReadWritePaths in the service file first. See Schedule backups.

Take the first backup

1. Start one backup now:

   sudo systemctl start lmdb-lws-backup.service

   The command returns when the backup has finished. For a large database that can take a while.

2. Read the result:

   journalctl -u lmdb-lws-backup.service -n 20

   A successful run ends with a line in this form:

   backup ok: /var/backups/monero-lws/lws-backup-20261109.lmdbbak.enc (<size>, <n> accounts, <seconds>s)

   That is the backup file, its encrypted size, the number of wallet accounts it holds, and how long the whole cycle took. If you see backup failed: instead, the rest of the line says why; see Troubleshooting.

3. List your backups:

   sudo lmdb-lws-backup --config /etc/lmdb-lws-backup/config.toml --list

   You see one row per backup, newest first, with columns DATE, AGE, SIZE, ITEMS (accounts), SCAN-HEIGHTS and FILE.

In /var/backups/monero-lws there are now two files for today: lws-backup-YYYYMMDD.lmdbbak.enc, the encrypted backup, and lws-backup-YYYYMMDD.manifest.json, its summary. Both have mode 600.

Check a backup yourself

Every backup is checked automatically before it is kept, but you can check any backup again at any time. This needs the key, so the command loads key.env first:

sudo sh -c 'set -a; . /etc/lmdb-lws-backup/key.env; exec lmdb-lws-backup --config /etc/lmdb-lws-backup/config.toml --verify /var/backups/monero-lws/lws-backup-20261109.lmdbbak.enc'

Replace the date with your backup's. A good backup prints verify ok: with its profile, account count, scan heights, table and row counts, size and checksum, ending with manifest: matches.

Running this check now also proves that the copy of the key in /etc works. Test the copy in your password manager the same way from time to time.

Turn on the daily schedule

sudo systemctl enable --now lmdb-lws-backup.timer

The timer runs the backup every day at 03:00 (server time), with up to 5 minutes of random delay. If the server is off at that time, it runs at the next boot. Check the next run with systemctl list-timers lmdb-lws-backup.timer.

What you learned

• The key lives in /etc/lmdb-lws-backup/key.env and, just as important, in a safe place off the server.
• The configuration is /etc/lmdb-lws-backup/config.toml.
• Each backup is an encrypted .lmdbbak.enc file plus a .manifest.json summary.
• --list shows backups, --verify checks one, and a systemd timer runs the backup daily.

Next steps

• Restore a backup
• Keys and security
• Schedule backups