Reference

Every option, setting and file of lmdb-lws-backup 0.2.0.

Command line

lmdb-lws-backup --config <file> --once
lmdb-lws-backup --config <file> --daemon
lmdb-lws-backup --config <file> --verify <backup-file>
lmdb-lws-backup --config <file> --list
lmdb-lws-backup --config <file> --restore <backup-file> --to <path>

Modes

Give exactly one.

Mode	What it does	Needs the key
--once	One full cycle: copy, encrypt, verify, then retention. Exits.	Yes
--daemon	Runs until stopped, one cycle a day at schedule_time.	Yes
--verify <file>	Decrypts a backup in memory, reads every table, and compares it with its manifest.	Yes
--list	Lists the backups in destination_dir with the configured prefix, newest first.	No
--restore <file>	Decrypts a backup to <path>/data.mdb. Requires --to.	Yes

Options

Option	What it does
--config <file>	Configuration file. Default /etc/lmdb-lws-backup/config.toml.
--db-path <path>	Overrides [source] db_path.
--profile <p>	Overrides [source] profile: auto, monero-lws or generic.
--destination <dir>	Overrides [backup] destination_dir.
--retention-days <n>	Overrides [backup] retention_days. 1 to 3650.
--to <path>	Restore target folder. Only with --restore.
--help	Prints the usage text.
--version	Prints lmdb-lws-backup 0.2.0.

Every mode reads and checks the whole configuration, including that a key source is set, even --list.

Exit codes

Code	Meaning
0	Success.
1	The backup, verify or restore failed.
2	Bad command line or invalid configuration.

Output

Mode	On success prints
--once	backup ok: <file> (<size>, <n> accounts, <seconds>s), or total rows instead of accounts for the generic profile.
--verify	verify ok: <file>, then profile:, accounts: and scan height: (monero-lws), tables:, total rows:, plaintext bytes:, sha256: and manifest:.
--list	Columns DATE, AGE, SIZE, ITEMS, SCAN-HEIGHTS, FILE. ITEMS is accounts (monero-lws) or rows (generic).
--restore	restored <file> -> <path>/data.mdb, a count summary, and a note that the folder holds decrypted data.

Failures print backup failed:, verify FAILED: or error: with the reason on standard error.

Configuration file

TOML. Unknown sections and keys are ignored with a warning in the log. A value of the wrong type is an error.

[source]

Key	Default	What it sets
db_path	/home/monero-lws/.bitmonero/light_wallet_server	The LMDB environment to back up. Must not be empty.
profile	auto	auto, monero-lws or generic. See Profiles.
max_named_dbs	128	Named tables the tool can open, 1 to 4096.

[backup]

Key	Default	What it sets
destination_dir	/var/backups/monero-lws	Where backups are written. Created with mode 700 if missing.
filename_prefix	lws-backup	File name prefix, 1 to 100 characters from A-Za-z0-9._-, not starting with . or -.
retention_days	30	Days of backups to keep, 1 to 3650. See Retention.
schedule_time	03:00	Daily start time for --daemon, as HH:MM. Checked in every mode, used only by --daemon.
timezone	UTC	UTC, local or an IANA name such as Asia/Kolkata. Sets the date in file names and the --daemon clock.
chunk_size	1048576	Encryption chunk size in bytes (1 MiB). At most 64 MiB.

[encryption]

Exactly one of the two keys must be set.

Key	What it sets
key_env_var	Name of the environment variable holding the base64-encoded 32-byte key.
key_file	Path of a file holding the key, as 32 raw bytes or base64. Must be a regular file with no group or other permissions (mode 600).

[verify]

Key	Default	What it sets
scratch_dir	not set (verify in RAM)	Folder for the verify copy when RAM is short. Puts transient plaintext on that disk: use an encrypted volume.

[logging]

Key	Default	What it sets
log_path	not set (standard error only)	Log file, created with mode 600. Warnings and errors also go to standard error.
level	info	debug, info, warn or error.

[alerting]

Key	Default	What it sets
on_failure_webhook	not set	URL that receives a JSON POST when a backup or verify fails. Must start with http:// or https://. Needs the curl program.

The webhook body is:

{"event":"lmdb-lws-backup-failure","stage":"backup","error":"...","host":"...","timestamp":"..."}

stage is backup or verify. curl is given 15 seconds; a failed delivery is logged and does not change the exit code.

Files

File	Contents
<prefix>-YYYYMMDD.lmdbbak.enc	The encrypted backup. Mode 600.
<prefix>-YYYYMMDD.manifest.json	The manifest. Mode 600.
*.partial	A backup being written. Renamed into place only after it verifies; removed at the start of the next run if left behind.

One backup per day per prefix. A second run on the same day replaces that day's files after the new backup verifies.

Manifest fields

Field	Present	Meaning
timestamp	always	When the backup was made (UTC).
profile	always	monero-lws or generic.
account_count	monero-lws	Wallet accounts.
scan_height_min, scan_height_max	monero-lws	Lowest and highest account scan height, or null.
table_count	0.2 and later	Named tables.
total_rows	0.2 and later	Rows across all tables.
sha256_of_encrypted_file	always	SHA-256 of the .enc file, checked by --verify.
encrypted_size_bytes	always	Size of the .enc file.
tool_version	always	Version that made the backup.

Manifests written by version 0.1 have no profile field. They are still read by --verify and --list, and retention still manages their backups.

Retention

After a new backup has been written and verified, the tool deletes old backups with the configured prefix. A backup is deleted only when both are true:

1. Its file name date is older than retention_days days, counting today.
2. It is not one of the newest retention_days backups.

Deletion goes oldest first, and each backup's manifest is deleted with it. With one backup a day, the two rules agree. After an outage they differ: if backups stopped for two months, the newest 30 are still kept, so a long gap never wipes out the only good backups. Nothing is deleted when a backup fails.

systemd units

File	Purpose
lmdb-lws-backup.service	One --once run as monero-lws, key from /etc/lmdb-lws-backup/key.env, with filesystem hardening.
lmdb-lws-backup.timer	Starts the service daily at 03:00, up to 5 minutes random delay, catches up after downtime.
lmdb-lws-backup-daemon.service	Alternative: runs --daemon, restarts on failure after 30 seconds.

Requirements

Item	Requirement
System	Linux (uses memfd_create and /proc), x86-64 or ARM64
Prebuilt binary	x86-64; the project states glibc 2.38 or newer
Access	Write access to the source environment's lock.mdb; write access to the destination and log
Memory	About the compacted database size, for verify (unless scratch_dir is set)
Alerts	The curl program, if on_failure_webhook is set

Next steps

• Troubleshooting and FAQ
• Keys and security