BeagleBone Black USB hard drive boot setup


I’m assuming that you have a USB hard drive. It must be self powered or getting its power from
a USB hub. Mine is USB 3 plugged into a USB 2 powered hub. A powered hub will have a wall wart that you plug into an electrical outlet. If your hard drive is USB 3 and your regular computer (Linux, Windows, etc.) has a USB 3 port you won’t need the hub while the USB hard drive is plugged into your regular computer.

I’m also assuming that you’ll be using Debian Linux. I agree with William Hermans that it looks to be the most stable and is well documented. It’s been around the longest and it probably has any and every package that you’ll ever need.

We’ll be modifying the uEnv.txt that’s tells the bootstrap software what’s where. I prefer to not fiddle with the provided Linux system that’s in the onboard flash so I’m using a micro SD (µSD) flash card. A 4 gig one is sufficient.

Warning: You may be able to edit the script on a Windows system and it’ll work. But if you edit the uEnv.txt file on a Windows system it will not work. Windows ends lines differently than Unix and u-boot requires lines that end the Unix way, not the Windows way.

Useful Linux disk commands. Read their man pages.

lsblk: lists all filesystems and drives.
sfdisk, parted: disk partitioning and partition resizing programs.
fdisk: disk partitioning. fdisk -l lists partitions and disk geometry.
mke2fs: initializes Linux filesystems (not needed for the swap partition).
mkswap: sets up a swap partition for swapping

Set up the µSD flash card for booting

Follow the instructions at where it says “Demo Image, Debian Stable (Wheezy)” and it runs the shell script This makes a bootable µSD flash card with boot and root filesystems on the µSD card.

With my µSD card in my laptop I used the command

./ --mmc /dev/sdb --uboot bone

On my laptop /dev/sda is the laptop’s drive and /dev/sdb is the µSd card.

After running this the first partition on the flash card is the boot filesystem, in DOS format (one of the FAT flavors, most likely FAT16) and the second filesystem is the root filesystem in Linux ext4 format. After these instructions you’ll continue to use the µSD card’s boot filesystem but its Linux ext4 root filesystem won’t be used because you’ll be using the Linux ext4 root filesystem on the USB hard drive. The reason I’m going this route with an eventually unnecessary and unused root filesystem on the µSD card is that the procedure is easy and straightforward, and it produces an µSD card that’s testable, and as I said previously, I want to leave the onboard flash memory filesystems unchanged.

After the installation finishes put the card in the BBB’s µSD slot (if you were using another computer to set up the card) and boot the BBB (being sure to properly shut down the BBB Linux that may have been running with the halt or shutdown commands). The BBB should sense the µSD card and boot to it instead of the onboard flash memory. You can verify that it’s booted to the µSD card by using the lsblk command. Its output should be

mmcblk1boot0 179:16 0 1M 1 disk
mmcblk1boot1 179:24 0 1M 1 disk
mmcblk0 179:0 0 14.6G 0 disk
+-mmcblk0p1 179:1 0 96M 0 part /boot/uboot
+-mmcblk0p2 179:2 0 14.5G 0 part /
mmcblk1 179:8 0 1.8G 0 disk
+-mmcblk1p1 179:9 0 70.6M 0 part
+-mmcblk1p2 179:10 0 1.7G 0 part

mmcblk0 is the µSD card while mmcblk1 is the onboard flash memory. It shows mmcblk1boot0 and mmcblk1boot1 because it starts booting from the onboard flash memory but switches over to the µSD flash card to finish booting. If your USB hard drive is connected there may be lines for it as well. The important lines are the ones that end with /boot/uboot and /; they say that those two mounts are coming from mmcblk0, the µSD flash card.

Set up the USB hard drive

Before you can set up the USB hard drive you need to make a modified version of the shell script. Use the diffs below to see what needs to be changed. Make a copy of and give it the name

After you’ve made the modified you set up the USB hard drive the same way you set up the µSD flash card; plug the drive in and run the script with the same options, except that if you’re doing this on the BBB the drive’s name is /dev/sda.

Final notes

After changing the uEnv.txt file the µSD card will no longer boot to itself and expects there to be a USB hard drive connected to the BBB. When you update your Linux system on the hard drive, the files on the SD card’s boot partition and Linux partitions won’t get updated unless you do that specifically. I’d keep a copy of the original uEnv.txt on the µSD card’s boot filesystem in case you’d like to boot to the card, for example, to fix something on the hard drive if it becomes unbootable. The ext4 root filesystem on the µSD card is unused when you’ve booted to the USB hard drive.

In some ways editing and running the script might seem odd, but for me it seemed the most straightforward. Since we know it will give us a good running system on the µSD card we can be reasonably confident that it will do the same for the USB hard drive. I’ve written many shell scripts so it wasn’t scary for me to modify

Diffs for and uEnv.txt

In the following diffs on pastebin, for the normal diff the brown lines are the old lines and the green lines are the new lines with the less than signs preceding the old lines and the greater sign preceding the new or added lines. For the context diffs changed and added lines are in blue and preceded by an exclamation mark. Some added lines are preceded with a plus sign and are green.

Diffs for are on pastebin at with the context diff at . The context diff gives 3 lines of context so that you can more easily find where to make the changes.

The first change is to add a line to the lines fed to sfdisk; the added line is for the swap partition, size at 1000 megabytes. Next are the changes for the partition number change; where there is a ${media_prefix}N where N is a 2, it’s changed to 3 for the root partition (1 is the DOS boot partition, 2 is the swap partition, and 3 is the ext4 root partition). Then there’s the added mkswap command, to enable swapping on the second partition. Next are changes and additions to the /etc/fstab file, to use sda3 for the root filesystem and to add sda2 for the swap partition.

Diffs for uEnv.txt are on pastebin at with the context diffs at .

First we create a variable bootdev for specifying the usb drive. Next we change the root to /dev/sda3. Then we change the load lines to use load usb instead of load mmc and use bootdev instead of mmcdev and mmcpart. Finally we change the uenvcmd and add usb start at the beginning.

The modifications to the uEnv.txt file I figured out from reading William Hermans’ Embedded Hobbyist web page; I wouldn’t have had a clue otherwise.


Robert C. Nelson’s web page for the BeagleBone Black at eewiki (Digi-Key).

Robert C. Nelson’s web page at

William Hermans’ Embedded Hobbyist web pages. The only instructions I’ve found for booting with a USB hard drive.

Texas Instruments Wiki pages.’s_Guide

Some u-boot and potentially other useful stuff.

U-boot home page. Useful stuff under the Documentation link. The Introductory Presentation was informative for me even though it’s marked as quite old. It explains how commands can be stored in environment variables which I had found confusing until I’d read this.