How to migrate LND (or other app) to new installation of umbrelOS

Recently, I had to move my Umbrel server to brand-new hardware. Since my Lightning Node has over 40 open channels, I was determined not to close them because of the migration. This presented the challenge of safely transferring the Lightning Node and Bitcoin Core to a new umbrelOS installation while minimizing downtime. After some research and testing, I came up with a reliable process, which I’d like to share here. This method should also work similarly for migrating other Umbrel apps.

:warning: Important Safety Warning :warning:

If you attempt this migration, proceed with extreme caution. Double-check every step to ensure you are not doing anything stupid. Above all, ensure that LND is never running simultaneously on both the old and new Umbrel instances. Broadcasting old or invalid channel states may result in penalty transactions, causing the loss of all funds in the affected channels.

DISCLAIMER: I take no responsibility for any losses caused by mistakes during this migration. Proceed at your own risk.

Migration Steps

1) New Umbrel: Install umbrelOS

Set up umbrelOS on your new device.

2) New Umbrel: Initial Setup

Log in via the web interface, create an account, set a password, and install the Bitcoin app from the App Store.

3) New Umbrel: SSH Access

While Bitcoin is installing, access the new umbrelOS via SSH. Open a terminal on your computer and connect using:

ssh umbrel@NEW_UMBREL_IP

Enter your password when prompted.

4) New Umbrel: Stop Bitcoin App

Wait for Bitcoin to finish installing and let it run for about a minute. Then stop the Bitcoin app via the web interface or SSH:

umbreld client apps.stop.mutate --appId bitcoin

5) New Umbrel: Modify sudoers File

Run the following command to edit the sudoers file:

sudo visudo

Add the following line to the end of the file:

umbrel ALL=(ALL) NOPASSWD: ALL

Save the changes by pressing CTRL+X , then Y , and finally Enter to confirm.

6) Old Umbrel: Transfer Bitcoin Data

You’ll now transfer the blockchain data (/blocks and /chainstate directories) from the old Umbrel to the new one. It is not necessary to stop Bitcoin on the old Umbrel.

Access the old Umbrel via SSH:

ssh umbrel@OLD_UMBREL_IP

Run the following rsync command to transfer the data:

rsync -rav --progress --rsync-path="sudo rsync" /home/umbrel/umbrel/app-data/bitcoin/data/bitcoin/chainstate /home/umbrel/umbrel/app-data/bitcoin/data/bitcoin/blocks umbrel@NEW_UMBREL_IP:/home/umbrel/umbrel/app-data/bitcoin/data/bitcoin

Wait for the data transfer to complete. It took 2 or 3 hours in my case.

7) New Umbrel: Start Bitcoin

Start the Bitcoin app on the new Umbrel via the web interface or SSH:

umbreld client apps.start.mutate --appId bitcoin

Your new node should sync quickly.

8) New Umbrel: Install Lightning

Install the Lightning app from the App Store, then stop it via the web interface or SSH:

umbreld client apps.stop.mutate --appId lightning

9) [CRITICAL] Old Umbrel: Backup Recovery Data

Write down your recovery seed phrase and ensure you have an up-to-date copy of the Static Channel Backup (SCB) file in case anything goes wrong.

10) Old Umbrel: Stop Lightning

Stop the Lightning app on the old Umbrel via the web interface or SSH:

umbreld client apps.stop.mutate --appId lightning

11) Old Umbrel: Transfer Lightning Data

Use rsync to transfer LND data from the old Umbrel to the new one:

rsync -rav --progress --rsync-path="sudo rsync" /home/umbrel/umbrel/app-data/lightning umbrel@NEW_UMBREL_IP:/home/umbrel/umbrel/app-data

This should take only few short minutes, depending on the size of your channel.db file.

12) New Umbrel: Verify channel.db Checksum

Calculate the checksum of the channel.db file on the new Umbrel:

sha256sum /home/umbrel/umbrel/app-data/lightning/data/lnd/data/graph/mainnet/channel.db

13) Old Umbrel: Verify channel.db Checksum

Do the same on the old Umbrel:

sha256sum /home/umbrel/umbrel/app-data/lightning/data/lnd/data/graph/mainnet/channel.db

14) New Umbrel: Start Lightning (DO NOT START THE OLD ONE!)

If the checksums match, start the Lightning app on the new Umbrel via the web interface or SSH:

umbreld client apps.start.mutate --appId lightning

15) Old Umbrel: Uninstall Lightning

If the new Umbrel is functioning correctly and channels are online, uninstall the Lightning app from the old Umbrel.
:warning: Important: Never run the Lightning app on the old Umbrel again.

16) New Umbrel: Revert sudoers Changes

Remove the line you added in Step 5 by running:

sudo visudo

Remove the corresponding line and save by pressing CTRL+X , then Y and Enter.


Congratulations! Your migration is now complete. :white_check_mark:
I hope you found this guide helpful.

Please let me know if you spot any mistakes or if you know of any improvements to this guide!