Unofficial Guide: How to add more storage

473x31 · July 16, 2024, 4:22pm

Unofficial Guide: How to add more storage

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.

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

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.

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

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

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:
```
echo -e "o\ny\nn\n1\n\n\n\nw\ny" | sudo gdisk /dev/sdX
```
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.
```
...
/dev/sdX1: UUID="3aab1b5c-4a28-43f4-b26e-51cac719560a" BLOCK_SIZE="4096" TYPE="ext4" PARTUUID="f64b920e-01"
...
```
Proceed with mounting the drive.

my_bitcoin · July 17, 2024, 6:56am

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

473x31 · July 17, 2024, 7:05am

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.

rayvenj · September 1, 2024, 4:33pm

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

Help.

focused · September 3, 2024, 4:31pm

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.

473x31 · September 4, 2024, 12:22pm

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.

Topic		Replies	Views
External Storage: Mounting and usage for Docker Volumes Guides	6	1826	July 7, 2024
Recognition of new HD Support and Troubleshooting	3	951	July 10, 2024
Add a usb flash drive to existing UmbrelOS Support and Troubleshooting	0	41	August 24, 2024
Installing UmbrelOS 1.2.1 on 8tb Drive Support and Troubleshooting	9	107	July 24, 2024
How to use a second drive for your storage pool when not using a pi. Guides	2	1001	April 21, 2024

Unofficial Guide: How to add more storage

Unofficial Guide: How to add more storage

Prerequisites

Mounting your drive

Preparing your drive (only if necessary)

Related Topics