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

Guides
1

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!

2 Likes
2

Hi,
Thank you for this great tuto.

Part 1 for Bitcoin-core is working like a charm.

Before going through Part 2, LND, I wanted to check with you the goal: is it only for recovering funds, and not channels, right?
As I read in this documentation, channel.backup restore will help to force close the channels.

Regards,

1 Like
3

The LND section of this guide transfers the entire LND node, channels and all. It worked perfectly for me.

1 Like
4

Great, I’m gonna test it then.

update: My mistake, it’s not only channel.backup, but all Lightning data. I’m aligned with the guide theory, and I’m gonna verify on preprod.

Thank you.

1 Like
5

Your channels will remain open if you do this correctly.

1 Like
6

Hi,
I confirm this procedure is working perfectly fine! Thank you!

I used it on my bitcoin-core / lnd infra, hence I changed a bit the command:

sudo rsync -rav --progress --rsync-path="sudo rsync" /data/lnd bitcoin-admin@XXX.XXX.XXX.XXX:/data/

Cheers,
RH

1 Like
7

I’m planning to a full hardware upgrade and initially thought I could use the Migration Assistant tool in UmbrelOS. Doesn’t it serve this same purpose? Did you give it a try? Thank you in advance for sharing your thoughts

1 Like
8

2025-02-02 15_53_52-Window
2025-02-02 15_53_52-Window1336×912 55.2 KB

Hello. I did everything as you described. The node has been launching for several hours now. The same thing happens if you transfer the specified files manually

9

Hi, could you check logs?

Right click on Bitcoin Node icon and select Troubleshoot. It is possible that the database was corrupted during the copying process.

10

bitcoin_bitcoind_1 | 2025-02-06T03:02:00Z Cache configuration:
bitcoin_bitcoind_1 | 2025-02-06T03:02:00Z * Using 2.0 MiB for block index database
bitcoin_bitcoind_1 | 2025-02-06T03:02:00Z * Using 53.4 MiB for transaction index database
bitcoin_bitcoind_1 | 2025-02-06T03:02:00Z * Using 46.7 MiB for basic block filter index database
bitcoin_bitcoind_1 | 2025-02-06T03:02:00Z * Using 8.0 MiB for chain state database
bitcoin_bitcoind_1 | 2025-02-06T03:02:00Z * Using 318.9 MiB for in-memory UTXO set (plus up to 286.1 MiB of unused mempool space)
bitcoin_bitcoind_1 | 2025-02-06T03:02:00Z [error] Failed to initialize ChainstateManager: AutoFile::read: file handle is nullptr: iostream error
bitcoin_bitcoind_1 | Error: Failed to initialize ChainstateManager: AutoFile::read: file handle is nullptr: iostream error
bitcoin_bitcoind_1 | 2025-02-06T03:02:00Z Shutdown: In progress…
bitcoin_bitcoind_1 | 2025-02-06T03:02:00Z scheduler thread exit
bitcoin_bitcoind_1 | 2025-02-06T03:02:00Z Flushed fee estimates to fee_estimates.dat.
bitcoin_bitcoind_1 | 2025-02-06T03:02:00Z Shutdown: done

11

It looks like an issue with chainstate db. Could you try rsyncing it again?

New Umbrel:

 rm -r /home/umbrel/umbrel/app-data/bitcoin/data/bitcoin/chainstate

Old umbrel:

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

Hello. I did as you said, but it didn’t help.

umbrel_bitcoin_2025-02-06_23-48.log (58.9 KB)

13

That’s weird. I have no better advice than to reinstall bitcoin Node and rsync all the data again. :slightly_frowning_face:

14

I have already tried to make a transfer several times, first completely reinstalling the system on a new disk. Tried RSYNC and manual transfer. I am transferring data from a 2tb SSD to a 1tb HDD. Could this be the problem (both drives are fine)? I also noticed that after synchronization the Bitcoin node is not deleted, it endlessly shows that the deletion is in progress, but it does not stop. If you do synchronization from scratch, then on the HDD it will take forever =((

15

Hello! Did you utilize the Migration Assistant? I’m approaching the state where I need to use one of these approaches to migrate my node.

16

Thank you for this detailed guide!
Question: For step 6, if I wanted the block data saved to my external drive (/dev/sda1), would the rest of the steps work as outlined? I started the sync process already not realizing the data was being saved to my smaller drive.