Transform your Umbrel into an Embassy without losing your Lightning channels

For this guide you will need an interim device/drive to store the Umbrel data on and a GPIO speaker (optional — see below) but otherwise no additional hardware whatsoever.

If you have purchased an Embassy and are looking to migrate from an Umbrel this can be done within the Embassy UI with two clicks provided your Umbrel and Embassy are on the same local area network. That is far simpler but requires two sets of hardware. If you just want to turn your Umbrel into an Embassy, follow this guide.

The only additional equipment you may need is one of these speakers. You can build an Embassy without one, but that can make troubleshooting more difficult if something goes wrong. If you don’t have one it’s fine to proceed.

If you get stuck during this guide — please reach out to us in our Telegram channel.

Please note: This guide is for Umbrel v0.4.x. We made this as we heard people were losing their lightning channels upgrading from Umbrel 0.4.x to Umbrel v0.5.

This guide also requires EmbassyOS v0.3.1 — due for release any day. It can be done with the current version, the process is just a little different. Don’t attempt this without being aware of that — and if you decide to anyway, make sure to reach out to us.

Start by making a backup of your Umbrel — particularly your lightning channels, just in case anything goes wrong.

Next, let’s get things as ready as possible Embassy-wise so that you can minimize downtime for your lightning node.

Get EmbassyOS by either building it or purchasing it then downloading it. If you have a second SD card — flash EmbassyOS onto it as this will save some time on the other end. (You can simply follow this part of the DIY guide.)

Now we need to make a directory on our local machine (the interim device) to temporarily store the data from our Umbrel. How much room you need for LND depends on how many channels you had and how much activity they have had. My hardly used node was about 500mb. It can be multiple gigabytes. If you want to migrate bitcoind’s data as well that will be around ~500gb. This isn’t necessary but it can save you redoing the IBD on your Embassy.

We recommend migrating the bitcoin data too. Assuming you have gigabit ethernet and a fast SSD (>=128MB/s read/write), the data will take around an hour from your Umbrel to your laptop/desktop and then another hour from your laptop/desktop to your Embassy. With 100Mb/s (non-gigabit ethernet) it will take 12 hours both ways! (Still faster than redoing initial block download.)

If you would like to use an external drive instead of your laptop/desktop’s internal drive, please connect it to your laptop/desktop and create the directories there instead by modifying the commands in this guide as appropriate.

If you’re on Linux/Mac open up terminal and make the directory where you would like your Umbrel’s data to be temporarily stored:

mkdir -p ~/umbreldata/lnd
#if you would like to store this data on an external drive, make sure to create these directories there instead.
#if you'd like to copy over the bitcoin data too:
mkdir -p ~/umbreldata/bitcoin

On Windows, navigate to your home directory (or wherever you’d like to store this data), right click and create the folders lnd and bitcoin.

Now let’s grab the data from your Umbrel.

You will need SSH installed. On Mac/Linux it is by default. To set up ssh on Windows, please follow this guide — note: this was written by community member BrewsBitcoin.

Now open up a terminal (Mac/Linux) or PuTTY (Windows).

Run the following command to stop your bitcoin and lightning nodes:

ssh umbrel@umbrel.local
#you will be asked for your Umbrel's dashboard password
#then run:
sudo ./umbrel/scripts/stop

Note: You must make sure you have run this stop script and if your bitcoin or lightning nodes are not stopped before beginning the transfer of data, corruption will definitely occur.

You will see Umbrel stopping the containers:

Now exit the ssh session by typing exit.

Now we can grab the data:

#use SCP to securely copy the data from your Umbrel:
scp -r umbrel@umbrel.local:~/umbrel/lnd/ ~/umbreldata/lnd
#remember to modify ~/umbreldata to wherever you want the data stored in the interim
#If you are struggling with this in Windows - please reach out in Telegram.

If you wish to copy over the bitcoin blockchain too (this will take multiple hours — make sure you have a gigabit ethernet connection if you want to do this):

scp -r umbrel@umbrel.local:~/umbrel/bitcoin/ ~/umbreldata/bitcoin

With the data pulled from your Umbrel, check that the data ended up where it’s supposed to.

#take a look at the data on your local machine:
du -h ~/umbreldata/lnd/lnd
#for me it's 439M - it can be gigabytes in size.
#and if you grabbed bitcoin:
du -h ~/umbreldata/bitcoin/lnd
#On Windows, simply navigate to the folders you created and right click +  properties to see their sizes.

It should look something like this for LND

and this for bitcoin

Now let’s change the name of the directories to what they’ll need to be on your Embassy:

mv umbreldata/lnd/lnd umbreldata/lnd/main/
mv umbreldata/bitcoin/bitcoin umbreldata/bitcoin/main

You can now turn off your Umbrel and follow the remainder of the DIY guide here and power up your Embassy. You can follow the setup guide here.

Once built and powered on, set up SSH access to your Embassy like this.

ssh in to your Embassy:

ssh start9@xxx.local
#replace "xxx" with your Embassy's LAN address - you are given this at the end of the setup process.

Now we need to copy over the ssh key to root:

sudo -i
mkdir /root/.ssh
cp /home/start9/.ssh/authorized_keys /root/.ssh/

Now we can ssh in as root — this is needed because we need to be able to copy the files directly to the Embassy’s SSD.

Create the necessary directories.

For LND:

sudo mkdir -p /embassy-data/package-data/volumes/lnd/data/

For Bitcoin (if you pulled the bitcoin data from your Umbrel too):

sudo mkdir -p /embassy-data/package-data/volumes/bitcoind/data/

Now you can scp the data to your Embassy from your laptop/computer:

#exit sudo:
exit
#then exit the ssh session:
exit
#then scp the data (note the `root` rather than `start9`):
scp -r ~/umbreldata/lnd/main root@xxx.local:/embassy-data/package-data/volumes/lnd/data
#if you're doing bitcoin too:
scp -r ~/umbreldata/bitcoin/main root@xxx.local:/embassy-data/package-data/volumes/bitcoind/data

Then we’ll need the password for lncli unlock — on Umbrel this is moneyprintergobrrr by default, in which case:

echo -n 'moneyprintergobrrr' > /embassy-data/package-data/volumes/lnd/data/main/pwd.dat

If your LND unlock password was different, please change the above command as appropriate. On older versions of Umbrel (over a year old) this password was your dashboard password — NOT “moneyprintergobrrr”.

With all the data copied across, you are now good to install Bitcoin Core from the marketplace. When setting config ensure that “Transaction Index” is turned on before saving as this was done by your Umbrel anyway — might as well use that data.

Save the config *but before hitting start* ssh back in to your Embassy and check for the existence of this file: requires.reindex:

ssh root@xxx.local
cd /embassy-data/package-data/volumes/bitcoind/data/main
ls

The above will list the contents of your Embassy’s bitcoin directory. If you see the file requires.reindex remove it by typing:

rm requires.reindex

This is critical to do. If this file exists, bitcoin will reindex which can take a very long time and we want to minimize downtime as much as possible.

If this file exists and you started bitcoin already, you must redo the entire transfer or wait for reindexing to finish.

Once ready, start Bitcoin Core and let it catch up to the latest block. Once that’s done, install LND and accept the default config. Now you can start up LND.

If you did not copy across the bitcoin data you will need to start LND with Neutrino turned on. This is only possible in Embassy v0.3.1 and with the soon to be released LND — this is not currently available unless you have built EmbassyOS from source yourself but will be publicly available any day now. This guide will be updated once it is possible. Please hold off on this final part if you bought EmbassyOS and thus don’t have 0.3.1. Contact us if you are stuck here.

If you copied over bitcoin and all has gone smoothly, you can now install something like Ride The Lightning to check on your channels. They should be exactly as you left them on the Umbrel and you have successfully transformed your Umbrel into an Embassy.