Important Disclaimer
This guide is experimental and should not be used unless you know exactly what you are doing and are prepared to take on the risks of potentially losing important data.
If you want to add external storage to your Umbrel or other device running umbrelOS in a way that persists between reboots and doesn’t require any scripts, etc. Then this is the guide for you, until full support for external storage devices is added in umbrelOS.
Prerequisites
The commands in this section are safe to use and only provide you with information.
First you need to connect the drive you want to use, to your Umbrel.
If you are using a connection method that is not hot-pluggabale (eg SATA / NVMe / PCIe or anything that isn’t USB) then you may need to reboot the Umbrel for the kernel to detect it.
Next, check to see if the drive has been auto-mounted already by running the following in the umbrelOS Terminal:
sudo df -h
You will probably get something like this; as expected - your drive is not yet mounted.
Next, check to see if the drive has been detected:
sudo lsblk
In my case, the external drive would be sdb.
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS
sda 8:0 0 64G 0 disk
|-sda1 8:1 0 200M 0 part /mnt/root/boot/efi
| /boot/efi
|-sda2 8:2 0 9.8G 0 part
|-sda3 8:3 0 9.8G 0 part /mnt/root
| /
`-sda4 8:4 0 44.1G 0 part /mnt/root/var/log
/var/log
/mnt/root/var/lib/systemd/timesync
/var/lib/systemd/timesync
/mnt/root/var/lib/docker
/var/lib/docker
/mnt/root/home
/home
/mnt/root/data
/data
sdb 8:16 0 64G 0 disk
sr0 11:0 1 2.3G 0 rom
Next, check if your drive has a block identifier. If your drive has this it means that it has been formatted / has data on it already and is ready to use.
sudo blkid
Below, in my example, we can see the identifiers for various devices but there is nothing that begins with /dev/sdbX, where X is a number. This means the drive is not ready to use and must be prepared.
If you do see your drive there, but do not see a TYPE, UUID or PARTUUID attribute, then the drive still needs to be prepared.
If you see all three attributes (or more) then you don’t need to prepare your drive. At this stage, take a note of the TYPE, UUID and PARTUUID unless you wish to destroy all the data on it and wipe it to start from a clean slate.
If you’ve done Step 4 of Prerequisites and have a PARTUUID available then you’re ready to mount your drive. Otherwise, skip to the next section Preparing your drive and come back once you’ve prepared your drive.
The commands in this section will modify the system configuration in a way that may affect system stability / ability to boot. You may want to backup important data and test the configuration before using it on your main device.
Create a mount point somewhere on the filesystem of your Umbrel. This can be in the /mnt folder or even in the /home/umbrel/ directory. For my example I’m using the /mnt folder like so:
sudo mkdir -p /mnt/harddrive1
Next, create an entry in the /etc/fstab file to define the mount point for the system. You will need to know the PARTUUID of the partition on the drive you want to mount.
echo "/dev/disk/by-partuuid/<PARTUUID> /mnt/harddrive1 auto rw,user,auto 0 0" | sudo tee --append /etc/fstab
Once you’ve added this information to the fstab. Tell the system to mount the filesystem immediately and inform systemd of the change:
sudo mount /mnt/harddrive1
sudo systemctl daemon-reload
And that’s that! If you reboot, the drive should auto mount at the point you specified in the fstab.
If you update umbrelOS, you will need to repeat the steps in this section again as the OTA update will clear these custom configs.
Permission denied errors when accessing the mount point
You may get permission errors when accessing the mount directory and its contents as a non-root user. If this is the case run the following to fix it:
This will set the appropriate access permissions on all items and give ownership of the mount point to the umbrel user.
Preparing your drive (only if necessary)
The commands in this section might be dangerous to use and can cause data loss and/or corruption of umbrelOS if used incorrectly. For this section, /dev/sdX is used instead of /dev/sdb. Remember to substitute the correct device path when executing the commands in the terminal.
Firstly, install fdisk and gdisk packages on umbrelOS.
sudo apt install fdisk gdisk
Next, erase the drive you want to mount.
sudo wipefs -a /dev/sdX
This command will DESTROY the parition table on the disk, making all data on it inaccessible!
Next, you want to create a new parition table. Most users will want to use a GPT-based disk. You can do this by using the gdisk utility we installed before:
Information about this command gdisk is an interactive command line program that works by letting the user make selections by pressing specific keys on their keyboard to carry out actions on the disk. The echo command simulates this input to quickly achieve the same result in one command. Here’s what we’re doing:
o This command in gdisk starts the creation of a new empty GUID partition table (GPT).
y This confirms the operation (assumes “yes” to the prompt).
n This command creates a new partition.
1 This specifies that it’s the first partition.
\n This represents newlines, which simulate pressing Enter to confirm default values.
w This command writes the changes to disk.
y This confirms the write operation.
If you want to use an MBR-based disk you can use fdisk instead.
echo -e "o\nn\np\n1\n\n\nw" | sudo fdisk /dev/sdX
Information about this command fdisk is a very similar program to gdisk but it is meant to be used for MBR-based disks. The command structure is similar:
o This command initialises a new empty partition table on the specified disk (/dev/sdX in this case).
n This command creates a new partition.
p This command selects the primary partition type.
1 Specifies that this is the first partition.
\n Represents newlines, which simulate pressing Enter to confirm default values.
w This command writes the changes to disk.
Next, you’ll want to create a filesystem on the first parition on the disk. Because umbrelOS is Linux based, I’m going to use ext4 but you can use any filesystem that is supported.
sudo mkfs.ext4 /dev/sdX1
Make sure you create the filesystem on the first partition path /dev/sdX1 and not the device path/dev/sdX.
Verify the drive has been correctly prepared by running blkid again.
sudo blkid
You should see something like shown below. Make a note of the UUID, TYPE and PARTUUID.
This does get overwritten unfortunately so that’s why after each update the steps must be repeated to set up the mount until the feature is supported natively in umbrelOS.
I didn’t have any luck either. Got the drives to auto mount but could never get them to be able to be accessed by Plex, getting the access to the docker container never worked.
I just gave up and am just about to ditch umbrel as whats the point of running a home server where your storage is limited to one drive. I’ve been holding out waiting for an update or communication but theres nothing.
I totally understand your frustration re this. External storage support is certainly on the way and we are working on it. That being said, I can’t offer a timeline or say when exactly it will be released.
If you would like some guidance on setting up your auto-mounted drive with a particular app, please don’t hesitate to reach out to us, or ask the community (including the team directly).
We will help you where possible and hopefully get Plex or any other app working with the custom setup you have.
Even if my drive was formated to ext4 and had a PARTUUID, my first attempt failed. It was better after formating the drive with fdisk and gdisk
I created and mounted my drive inside umbrel/data/storage/ (complete path: umbrel/data/storage/drive1) so it’s next to the downloads folder. Installed apps like File Browser can access more easily the new mounted location
I applied another set of permissions at step 4.: sudo chmod -R 775 umbrel/data/storage/drive1/ (not sure it is necessary but I had some issue allowing umbrel user with chown command)
I edited the docker-compose.yml file of plex with (please see the full tutorial, it will be more comprehensive):
Locate the volume entry for the app’s configuration and data, and add a new volume mapping for the external drive: volumes: - ${UMBREL_ROOT}/data/storage/drive1:/drive1
Don’t forget to restart your apps to take the new mounted location into account
However, I still haven’t been able to do the same for Bitcoin. The Bitcoin Docker Compose file doesn’t include a volume parameter for the blocks. Does anyone have a solution for this?
I don’t use Bitcoin but if the Docker Compose file doesn’t include a volume parameter for blocks, I suppose that you would have to edit the Bitcoin app code source to handle external storage which is really not ideal.
I’ve gone through these steps and could use some help. I copied some files to 2 folders on an external drive. I mounted to a folder in ~/umbrel/data/storage/ because this is where the downloads folder is in the File Browser app and I want to be able to browse the contents of the drive in the GUI. The issue is that as far as I can tell the drive is mounted to the folder I created, but I don’t see any of the folders or files on that drive in the mount folder, either in terminal of in the File Browser app.
When I use the sudo df -h command I do see the mount path for that drive. I also see multiple paths for that drive with the sudo lsblk command, including the path I specified.
Any ideas? This is way too complicated. Why can’t we just have all external drives automatically mount like in Windows or MacOS? It would make using this so much easier.
Update. If I put fstab back to how it was and use the command sudo mount /dev/sdb2 ~/umbrel/data/storage/Plex then I can see my folders and files that are on the external drive in terminal. However, they don’t appear in File Browser or in Plex.
I’m considering using the Umbrel for a combined Bitcoin full node, Plex server, and homebridge server. Not being able to easily configure external drives makes the Umbrel not very useful for things like a Plex server. I’m not really understanding why there’s a Plex server app if working with external drives is so difficult. Same goes for Jellyfin and other media apps.
Still trying to get this to work. The external drive that I’m connecting is formatted as ExFAT. I originally used the command echo "/dev/disk/by-partuuid/de43612a-6adc-48e6-b7b8-4c2efa68b097 ~/umbrel/data/storage/Plex auto rw,user,auto 0 0" | sudo tee --append /etc/fstab , following the directions above, but that didn’t work. So then I tried using the command echo "/dev/disk/by-partuuid/de43612a-6adc-48e6-b7b8-4c2efa68b097 ~/umbrel/data/storage/Plex exfat rw,user,auto 0 0" | sudo tee --append /etc/fstab, replacing auto with exfat, but that didn’t work either. Still, the contents of the drive don’t appear in the Plex folder even with the command sudo mount /dev/sdb2 ~/umbrel/data/storage/Plex. Could anyone help with this?
I finally got it working with some help from ChatGPT. In the process of getting this to work I installed an NVME drive into my mini PC. After partitioning and creating the filesystem on the drive, here are the commands I used:
Backup fstab: sudo cp /etc/fstab /etc/fstab.bak
Create the folder where I want access to the files in File Browser: sudo mkdir -p /home/umbrel/umbrel/data/storage/NVME
Update fstab: echo "UUID=<UUID, not PARTUUID> /home/umbrel/umbrel/data/storage/NVME ext4 defaults 0 2" | sudo tee -a /etc/fstab
Test the fstab modification: sudo mount -a
Confirm it worked: df -h
I then went and did the same for the external Plex drive.
Now I just need to figure out how to make Bitcoin Core use the NVME drive and Plex to use the external drive…
That did help. Thank you. I got as far as the drives mounted to the folders. But couldn’t really get anything working past that. I think I’ll wait and see what happens with the new Files feature from 1.4 beta.
This let me get Plex to recognize the Plex files in the Downloads folder in the Files app. The Downloads folder appears as “downloads” in Plex for some reason.
This issue I’ve run into is Bitcoin Node not installing. When I click Install it starts, but immediately stops. It did add folders and files to the correct folder, so the installation did start, but then aborted.
ChatGPT solved it for me. For anyone else trying to do this, here is the updated /etc/fstab entries. This needed to be done a certain way because the drive is exfat.
This guide will help you add a new storage drive to your Umbrel and move your apps to use this new storage. No programming or Linux experience required!
Prerequisites
A new storage drive (USB, SSD, or HDD)
Your Umbrel device
Access to the Umbrel web interface
Step 1: Connect Your Drive
Connect your storage drive to your Umbrel device
Wait about 30 seconds for the drive to be recognized
Step 2: Format and Mount the Drive
Copy and paste these commands one at a time into your Umbrel terminal. Press Enter after each command:
bash
CopyInsert
# Check your drive name (look for sdb, sdc, etc. - it will be the size of your new drive)
sudo lsblk
# Create mount point
sudo mkdir -p /home/umbrel/umbrel/home/Storage
# Add drive to system
echo "/dev/disk/by-partuuid/$(sudo blkid -s PARTUUID -o value /dev/sdb1) /home/umbrel/umbrel/home/Storage ext4 rw,user,auto 0 0" | sudo tee --append /etc/fstab
# Mount the drive
sudo mount /home/umbrel/umbrel/home/Storage
# Set permissions
sudo chown -R umbrel:umbrel /home/umbrel/umbrel/home/Storage
sudo chmod -R 0755 /home/umbrel/umbrel/home/Storage
You should now see a “Storage” folder in your Umbrel Files tab.
Step 3: Move Apps to New Storage
Copy and paste these commands one at a time:
bash
CopyInsert
# Create Apps directory
sudo mkdir -p /home/umbrel/umbrel/home/Storage/Apps
# Move each app (copy and run one line at a time)
cd /home/umbrel/umbrel/app-data
# For each app folder you see, run these commands, replacing APP_NAME with the actual app name:
sudo rsync -av APP_NAME/ /home/umbrel/umbrel/home/Storage/Apps/APP_NAME/
sudo mv APP_NAME APP_NAME.bak
sudo ln -s /home/umbrel/umbrel/home/Storage/Apps/APP_NAME APP_NAME
I updated my umbrelOS to 1.4.0 yesterday and noticed it messed up additional storage and even internal Umbrel internal storage for some apps.
Plex has lost track of the additional storage. To solve this, I followed the first steps:
# Check your drive name (look for sdb, sdc, etc. - it will be the size of your new drive)
# My drive is named 'Untitled' ¯\_(ツ)_/¯
sudo lsblk
# Create mount point
sudo mkdir -p /home/umbrel/umbrel/home/blue-storage
# Add drive to system
echo "/dev/disk/by-partuuid/$(sudo blkid -s PARTUUID -o value /dev/sdb1) /home/umbrel/umbrel/home/blue-storage ext4 rw,user,auto 0 0" | sudo tee --append /etc/fstab
# Bind the system mount point location to my newly created location
sudo mount --bind /home/umbrel/umbrel/external/Untitled /home/umbrel/umbrel/home/blue-storage
# If you want this bind mount to persist across reboots, you can add an entry to /etc/fstab
echo "/home/umbrel/umbrel/external/Untitled /home/umbrel/umbrel/home/blue-storage none bind 0 0" | sudo tee -a /etc/fstab
Restarted Plex and now my external storage is correctly recognized
Some additional context:
Maybe I should not have unplugged my additional external storage drive before the system update to 1.4.0?
Some apps has lost track of the system Downloads folder: For example the File Browser app does not see the Downloads folder anymore (well, we have the new integrated Umbrel’s Files in backup)
I noticed that the permissions of the mounted storage by the system (Umbrel 1.4.0) is drwx--x--x (751 in octal) • So if you try to add the mount point to Plex’s docker-composer.yml, it won’t be able to access it as is
Since I bound the storage to /home/blue-storage, the permission changed to drwxrwxr-x (775 in octal)
Important Disclaimer
The commands in this section are safe to use and only provide you with information.
If you update umbrelOS, you will need to repeat the steps in this section again as the OTA update will clear these custom configs.
Permission denied errors when accessing the mount pointThe commands in this section might be dangerous to use and can cause data loss and/or corruption of umbrelOS if used incorrectly. For this section,
This command will DESTROY the parition table on the disk, making all data on it inaccessible!
