Configuring the Drive

Plug in the Drive

Hardware hookup here is pretty simple:

  1. Plug USB hub into a free USB port on the Pi.
  2. Plug power cable into powered USB hub.
  3. Plug external drive into USB hub.

In the case where you're using a USB thumb drive, you can likely just plug right into the Pi.

Power on the Pi, if you haven't already, and bring up a terminal. Next, let's see if the drive showed up. First, try lsusb:

The line Bus 001 Device 005: ID 0bc2:ab24 Seagate RSS LLC looks promising. You'll likely see something similar, although the device isn't guaranteed to have a manufacturer string.

So next let's figure out where the drive actually shows up on the filesystem. Try using dmesg:

Here're the lines of interest:

Download: file
[    8.822011] sd 0:0:0:0: [sda] Write cache: enabled, read cache: enabled, doesn't support DPO or FUA
[    8.849001]  sda: sda1
[    8.862459] sd 0:0:0:0: [sda] Attached SCSI disk

Your output will probably look a little different, but unless you have another USB drive plugged in, your drive is almost certain to be /dev/sda.

Configure a New Root Filesystem

Once you know what drive to target, you can use a helper script we've written called adafruit-pi-externalroot-helper. The source for this script can be found here on GitHub.

If you're already using our package repository, you can install the script and run it like so:

Download: file
sudo apt-get install adafruit-pi-externalroot-helper
sudo adafruit-pi-externalroot-helper -d /dev/sda

Want to use our packages? Check out this guide to using the Adafruit Raspberry Pi package repository.

If you're using a stock Raspbian install, and would rather not mess around with the package manager, try this instead:

Download: file
git clone https://github.com/adafruit/Adafruit-Pi-ExternalRoot-Helper.git
cd Adafruit-Pi-ExternalRoot-Helper
./adafruit-pi-externalroot-helper -d /dev/sda

You'll be prompted to continue - double-check that the script is pointed at the right drive, and press y to continue.

This will take a long time.

It first creates a new filesystem on the target drive and copies everything on your root filesystem there using rsync. Lastly, it alters the kernel boot parameters in /boot/cmdline.txt and modifies a file called /etc/fstab to stop mounting the old root partition on the SD card.

adafruit-pi-externalroot-helper WILL destroy the existing contents of its target drive - make sure you want to proceed here!

Check the New Configuration and Reboot

Once the script is finished, you might want to check the contents of the following files:

/mnt/etc/fstab: the old /dev/mmcblk0p2 entry for root should be commented out, and there should be a new one for your external device, identified by a path including a long unique id. Mine looks like this:

Download: file
proc            /proc           proc    defaults          0       0
/dev/mmcblk0p1  /boot           vfat    defaults          0       2
#/dev/mmcblk0p2  /               ext4    defaults,noatime  0       1
# a swapfile is not a swap partition, so no using swapon|off from here on, use  dphys-swapfile swap[on|off]  for that
/dev/disk/by-uuid/8bc7fb29-43c4-4179-9a32-89df37badad3    /   ext4    defaults,noatime  0       1

/boot/cmdline.txt: Instead of root=/dev/mmcblk0p2, you should see a root=PARTUUID=... parameter. Mine looks like so:

Download: file
dwc_otg.lpm_enable=0 console=ttyAMA0,115200 console=tty1 root=PARTUUID=ED5E1D73-8EAA-4C40-99A6-1E3A3795F98C rootdelay=5 rootfstype=ext4 elevator=deadline rootwait fbcon=map:10 fbcon=font:VGA8x8

When you reboot, /mnt/etc/fstab will be the new /etc/fstab. (The Arch Linux wiki has a pretty good explanation of what this file does.)

If everything looks in order here, go ahead and reboot like so:

Download: file
sudo reboot

Verify You're Using the New Drive

Once your Pi boots, you can log in like normal and try a couple of commands.

Download: file
df -h

This should show /dev/root with its amount of drive space free, which should correspond to what's available on your new drive. This is probably a good enough indication, if you're using a drive bigger than your SD card, but you can also check that /dev/root points to /dev/sda1:

Download: file
readlink /dev/root

...and you should be able to look in /dev/disk/ and see that it's available by its unique ID:

Download: file
ls -l /dev/disk/by-uuid
ls -l /dev/disk/by-label

...and verify that it's mounted on /:

Download: file
mount | grep root

These should show that /dev/sda1 is

Recovering from a Failed Boot

If for some reason your Pi doesn't boot, you can restore things by opening the first partition on the SD card from another machine (Windows or OS X will work just fine) and editing cmdline.txt.

Just replace root=PARTUUID=... rootdelay=5 with root=/dev/mmcblk0p2, which will point the root partition back to the second partition on your SD card, looking something like this:

Download: file
dwc_otg.lpm_enable=0 console=ttyAMA0,115200 console=tty1 root=/dev/mmcblk0p2 rootfstype=ext4 elevator=deadline rootwait fbcon=map:10 fbcon=font:VGA8x8

Put the card back into the Pi, and it should boot like normal.

This guide was first published on Apr 13, 2015. It was last updated on Apr 13, 2015. This page (Configuring the Drive) was last updated on Nov 23, 2015.