Expand internal storage on OpenWrt using USB with Extroot | Detailed Tutorial

I recently installed OpenWrt on my Amplifi HD router. Surprised by the possibilities, I wanted to try them all out. That’s when reality hit – the meagre internal storage on routers! Then, I learned of Extroot on OpenWrt, with which you can increase storage space on OpenWrt devices using USB drive. With Extroot setup on OpenWrt, you can virtually install unlimited OpenWrt packages.

In this tutorial, I will take you through steps to setup Extroot on OpenWrt. OpenWrt has an official guide on configuring Extroot. But, in this tutorial, we will see the configuration, even for devices with Extremely low flash storage. So, keep reading!

What is Extroot on OpenWrt?

For those curious, here’s how OpenWrt explains the method:-

Extroot works by setting another overlay partition in the external storage device, and during boot this new overlay partition will be mounted over the internal storage’s overlay partition. This approach also allows easy fallback in case the external storage device is removed, as your device will still have its own overlay partition and thus will load all configuration from there. Which means that it will behave exactly the same as just before you set up extroot.

Video tutorial: Expand internal storage for packages on OpenWrt with Extroot

If you prefer the textual tutorial, keep reading!

Setup Extroot to increase storage for packages on OpenWrt

Let’s begin with the requirements.

Requirements

• Device running OpenWrt with USB/Memory card port
  • Updated image for Amplifi HD (with inbuilt Luci, USB, Extroot dependencies)
• SSH/Terminal access to OpenWrt device
• USB Drive/Memory Cards (if supported) – Size depends on size and number of packages you want to install
• Linux distro (if using Method 2 in Step 2) – Full installation or Virtual Machine (Live CD is enough)

Once you have them ready, let’s begin with the process of increasing storage space on OpenWrt.

Step 1. Install packages for Extroot

1. Go to terminal/SSH (via Putty) and login to your router as root.
2. Type opkg update and press Enter.
3. Once done, decide if you want to prepare the USB drive (next step) on the router itself or on another Linux machine. This depends on the space left on your device. There are four options here:-
   1. If on an Amplifi HD Router, flash the image linked above, proceed to Step 2 and follow Method 1.
   2. On any other device, type opkg install block-mount kmod-fs-ext4 e2fsprogs parted kmod-usb-storage kmod-usb-storage-uas kmod-usb2 and press Enter. If your device has a USB 3.0 port, replace kmod-usb2 with kmod-usb3. If it completes successfully and doesn’t run out of disk space, proceed to Step 2 and follow Method 1. Else, continue to the next option.
   3. Type opkg install block-mount kmod-fs-ext4 kmod-usb-storage kmod-usb-storage-uas kmod-usb2 and press Enter. If your device has a USB 3.0 port, replace kmod-usb2 with kmod-usb3. Then, proceed to Step 2 and follow Method 2. If that fails as well, check the next option.
   4. For devices with extremely small flash size, try to make a custom OpenWrt image with 5 packages builtin – block-mount, kmod-fs-ext4, kmod-usb-storage, kmod-usb-storage-uas and kmod-usb2. If your device has a USB 3.0 port, replace kmod-usb2 with kmod-usb3. Flash that image, proceed to Step 2 and follow Method 2.

If that’s confusing, just follow the flowchart below:-

Step 2. Prepare USB for Extroot

Please note that this step will wipe your USB drive clean. So, backup any important information beforehand.

Method 1. Prepare USB using OpenWrt router/device

1. Plug your USB drive into OpenWrt router/device.
2. On terminal, type fdisk -l and press Enter. Identify your USB drive and get its ID, for example, /dev/sda. Make a note of it. You can also use the command ls -l /sys/block for this.
3. Next, to partition and format the USB drive, type these commands one by one onto the terminal and press Enter. N.B. Each new line is a command. Also, replace /dev/sda with your device’s identifier.

   DISK="/dev/sda"
   parted -s ${DISK} -- mklabel gpt mkpart extroot 2048s -2048s
   DEVICE="${DISK}1"
   mkfs.ext4 -L extroot ${DEVICE}
   

Method 2. Prepare USB using Linux machine

1. On another Linux machine (any distro), connect your USB drive.
2. On terminal, type fdisk -l and press Enter. Identify your USB drive and get its ID, for example, /dev/sda. Make a note of it. You can also use the command ls -l /sys/block for this.
3. If the distro automatically mounted your USB drive, unmount it (not eject) before proceeding.
4. Next, to partition and format the USB drive, type these commands one by one onto the terminal and press Enter. N.B. Each new line is a command. Also, replace /dev/sda with your device’s identifier.

   DISK="/dev/sda"
   parted -s ${DISK} -- mklabel gpt mkpart extroot 2048s -2048s
   DEVICE="${DISK}1"
   mkfs.ext4 -L extroot ${DEVICE}

Step 3. Configure Extroot on OpenWrt device

1. If you followed Method 2 above, plug the USB drive to the OpenWrt device. On terminal, type fdisk -l and press Enter. Identify your USB drive and get its ID, for example, /dev/sda. Make a note of it. You can also use the command ls -l /sys/block for this. Then, type DEVICE="/dev/sda1" and press Enter. If your device identifier is different, replace it accordingly, but do not miss the 1 at the end. If you followed Method 1, directly jump to the sub-step 2 below.
2. Following the official documentation, to setup the fstab entry for our Extroot USB, type these commands one by one onto OpenWrt terminal and press Enter. N.B. Each new line is a command.

   eval $(block info ${DEVICE} | grep -o -e 'UUID="\S*"')
   eval $(block info | grep -o -e 'MOUNT="\S*/overlay"')
   uci -q delete fstab.extroot
   uci set fstab.extroot="mount"
   uci set fstab.extroot.uuid="${UUID}"
   uci set fstab.extroot.target="${MOUNT}"
   uci commit fstab

3. Now, to create an fstab entry for the original overlay, type these commands one by one onto the terminal and press Enter. N.B. Each new line is a command.

   ORIG="$(block info | sed -n -e '/MOUNT="\S*\/overlay"/s/:\s.*$//p')"
   uci -q delete fstab.rwm
   uci set fstab.rwm="mount"
   uci set fstab.rwm.device="${ORIG}"
   uci set fstab.rwm.target="/rwm"
   uci commit fstab

4. Next, to transfer data from original overlay to the one created by our Extroot USB, type these commands one by one onto the terminal and press Enter. N.B. Each new line is a command.

   mount ${DEVICE} /mnt
   tar -C ${MOUNT} -cvf - . | tar -C /mnt -xf -

5. Finally, type reboot and press Enter.

If all went well, post reboot, go to OpenWrt Admin GUI (Luci), under System, go to Software. The Disk space should now correspond to your USB drive! If it does, you have successfully setup Extroot on OpenWrt, thus, increasing disk space on OpenWrt. Now, install all the packages you want.

Conclusion

The setup followed in this tutorial, thanks to OpenWrt’s official documentation has a fail safe mechanism. If your USB drive does fail at a later point, OpenWrt will automatically revert to the original overlay, allowing the router to still boot successfully. Anyways, this tutorial should work for a vast majority of population. If it doesn’t for some reason, check the troubleshooting steps on OpenWrt’s documentation.