Unofficial Guide: How to add more storage

Support and Troubleshooting
1

Unofficial Guide: How to add more storage

:information_source: 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

:white_check_mark: The commands in this section are safe to use and only provide you with information.

  1. 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.

  2. 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.

    Filesystem      Size  Used Avail Use% Mounted on
udev            3.9G     0  3.9G   0% /dev
tmpfs           794M  3.0M  791M   1% /run
/dev/sda3       9.6G  3.7G  5.5G  41% /
tmpfs           3.9G     0  3.9G   0% /dev/shm
tmpfs           5.0M     0  5.0M   0% /run/lock
/dev/sda4        43G   13G   29G  31% /data
/dev/sda1       200M   46M  154M  23% /boot/efi

  3. 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

  4. 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.

    /dev/sr0: BLOCK_SIZE="2048" UUID="2024-05-22-12-14-21-00" LABEL="UMBRELINSTALLER" TYPE="iso9660" PTTYPE="PMBR"
/dev/sda4: UUID="589f7922-80c3-4f0d-986b-73a36b8e177e" BLOCK_SIZE="1024" TYPE="ext4" PARTLABEL="primary" PARTUUID="d1d36e34-2753-4dc7-96eb-3c9b5584e867"
/dev/sda2: UUID="d895003e-19b9-466a-a223-f9aeaa078ad5" BLOCK_SIZE="4096" TYPE="ext4" PARTLABEL="primary" PARTUUID="2fe5a278-9b55-4266-8220-6665aa96940b"
/dev/sda3: UUID="3f6a0c6f-363f-4945-95e2-527250f91a26" BLOCK_SIZE="4096" TYPE="ext4" PARTLABEL="primary" PARTUUID="f5e6d27c-4a25-447b-8e08-a9d2e738345a"
/dev/sda1: SEC_TYPE="msdos" LABEL_FATBOOT="ESP" LABEL="ESP" UUID="FB30-6DF7" BLOCK_SIZE="512" TYPE="vfat" PARTLABEL="ESP" PARTUUID="14a31e9d-a8d7-4da0-9eb2-f268dd9d7ad9"

Mounting your drive

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.

:information_source: 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.

  1. 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

  2. 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

  3. 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

  4. And that’s that! If you reboot, the drive should auto mount at the point you specified in the fstab.

    :exclamation: If you update umbrelOS, you will need to repeat the steps in this section again as the OTA update will clear these custom configs.

    :closed_lock_with_key: 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:

    sudo chmod -R 0711 /mnt/harddrive1
sudo chown umbrel /mnt/harddrive1

    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)

:warning: 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.

  1. Firstly, install fdisk and gdisk packages on umbrelOS.

    sudo apt install fdisk gdisk

  2. Next, erase the drive you want to mount.

    sudo wipefs -a /dev/sdX

    :rotating_light: This command will DESTROY the parition table on the disk, making all data on it inaccessible!

  3. 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:

    echo -e "o\ny\nn\n1\n\n\n\nw\ny" | sudo gdisk /dev/sdX

    :information_source: 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_source: 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.

  4. 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

    :information_source: Make sure you create the filesystem on the first partition path /dev/sdX1 and not the device path/dev/sdX.

  5. 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.

    ...
/dev/sdX1: UUID="3aab1b5c-4a28-43f4-b26e-51cac719560a" BLOCK_SIZE="4096" TYPE="ext4" PARTUUID="f64b920e-01"
...

  6. Proceed with mounting the drive.

4 Likes
2

You might want to verify that all of this isnt overwritten when a person updates.

3

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.

1 Like
4

I followed these steps, but my Umbrel Home has been stuck on the restart screen for 12 hours and counting.

Help.

Screenshot 2024-09-01 at 11.32.21 AM
Screenshot 2024-09-01 at 11.32.21 AM1084×390 53.8 KB

5

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.

1 Like
6

Hey @focused

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.

1 Like
7

I followed the steps and it’s finally working :tada:

Notes:

  • 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):

    • sudo nano ~/umbrel/app-data/plex/docker-compose.yml
    • 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

1 Like
8

That worked with Jellyfin, thank you!

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?