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.
Important Safety 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.
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.
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!