Core Lightning Node Backup & Restore Guide

Upgrading your Core Lightning (CLN) node is routine, but a botched upgrade can leave you with a corrupted channel database or, worse, a loss of funds. This guide walks you through backing up your node’s critical files and restoring them if something goes wrong, so you can upgrade with confidence.

What You’ll Need

• Access to your node’s command line (SSH or local terminal).
• Your node’s data directory path (default is ~/.lightning, but it may vary).
• Enough free disk space to store a copy of the backup (at least the size of your .lightning directory).
• Optional but recommended: a second storage location (external drive, cloud storage) for off-node backups.

Step-by-Step

1. Stop the node cleanly. Run lightning-cli stop and wait for the process to exit. This ensures all databases are flushed and no new data is written during backup. Verify it stopped with pgrep -f lightningd (should return nothing).
2. Locate your data directory. The default is ~/.lightning. If you used a custom --lightning-dir or a systemd service, check the service file or your startup script. Confirm with ls -la ~/.lightning.
3. Create a timestamped backup folder. For example: mkdir -p ~/cln-backup/$(date +%Y%m%d-%H%M%S). This keeps multiple backups organized.
4. Copy the entire data directory. Use cp -a ~/.lightning/* ~/cln-backup/$(date +%Y%m%d-%H%M%S)/. The -a flag preserves permissions and timestamps. This includes hsm_secret, config, lightningd.sqlite3, and all channel files.
5. Verify the backup integrity. Compare file counts and sizes: du -sh ~/.lightning ~/cln-backup/$(date +%Y%m%d-%H%M%S). They should be close. Also check that hsm_secret exists in the backup: ls -la ~/cln-backup/$(date +%Y%m%d-%H%M%S)/hsm_secret.
6. Copy the backup off-node (optional but recommended). Use scp or rsync to a different machine or cloud storage. This protects against disk failure on the node.
7. Perform the upgrade. Install the new version of Core Lightning using your preferred method (source, package manager, etc.). Follow the official upgrade instructions.
8. Start the node. Run lightningd (or start via systemd). Check logs for errors: tail -f ~/.lightning/log.
9. Verify channels and funds. Run lightning-cli listfunds and lightning-cli listchannels to confirm your channels are intact and balances are correct.

Common Mistakes

• Backing up while the node is running. This can produce an inconsistent database, especially for SQLite. Always stop the node first.
• Only copying the seed phrase. The seed phrase can restore on-chain funds but not channel state. You need the full data directory.
• Ignoring the hsm_secret. This file signs your transactions. Without it, your node cannot spend funds even if you have the seed.
• Not testing the backup. A backup is only useful if you can restore it. Test the restore process on a spare machine before relying on it.

Tips

• Automate backups with a cron job that stops the node, copies the directory, and restarts it. For example, run nightly at 3 AM.
• Keep at least the last 3 backups. This protects against corruption that might go unnoticed for days.
• Use rsync instead of cp for incremental backups: rsync -a --delete ~/.lightning/ ~/cln-backup/current/.
• If you use a systemd service, stop it with sudo systemctl stop lightningd and start with sudo systemctl start lightningd.

Troubleshooting

• Node fails to start after upgrade. Check the log file for errors. If it mentions a database mismatch, you may need to restore from backup. Stop the node, move the current data directory aside (mv ~/.lightning ~/.lightning.broken), and copy the backup back.
• Channels appear but funds are zero. This can happen if the channel database is stale. If you have a recent backup, restore it. If not, you may need to force-close channels using lightning-cli close with the peer ID.
• hsm_secret missing or corrupted. If you have a backup, restore it. If not, you cannot recover funds without the seed phrase (and even then, only on-chain funds). Always keep multiple copies.
• Backup restore fails with permission errors. Ensure the user running lightningd owns the restored files: chown -R lightning:lightning ~/.lightning (adjust user/group as needed).
• SQLite database is corrupted. Try sqlite3 ~/.lightning/lightningd.sqlite3 ".recover" | sqlite3 new.db to salvage data, then replace the original. This is a last resort; a good backup is much better.

Frequently Asked Questions

• Can I back up while the node is running? Not safely. SQLite databases can be copied while running, but the channel state may be inconsistent. Always stop the node.
• Do I need to back up the entire directory or just certain files? The entire directory. The hsm_secret, config, and lightningd.sqlite3 are essential, but channel files and other data are also needed for full recovery.
• What is the difference between seed phrase and hsm_secret? The seed phrase (12 or 24 words) can generate your on-chain keys and recover on-chain funds. The hsm_secret is a file that holds the node’s identity and signs channel transactions. Without it, you cannot operate channels.
• How often should I back up? At least daily if you have active channels. Channel state changes frequently, so a backup from a week ago may miss recent updates and cause force-closes.
• Can I restore a backup on a different machine? Yes, as long as the data directory is placed in the same path and permissions are correct. You may need to update the config file if paths differ.
• What if I lost my backup and my node is corrupted? Without a backup, you can only recover on-chain funds using your seed phrase. Channels will be force-closed after a timeout, but you may lose some funds to penalties if the other party publishes a stale state. This is why backups are critical.

Related

• Red Shell Moles: Causes, Risks & Removal
• How to Check UPI Transaction Status: Pending, Success, Reversed
• Ninja Forms WordPress: Create, Publish & Fix