Getting Started with an Ubuntu or Debian .img.xz File

These instructions assume you have downloaded the most recent prepackaged BeagleBone Black image. All instructions are executed as full root sudo su

A note about permissions and sudo:
The instructions presented here assume full root sudo su permissions and not sudo <command> permissions alone.
Why does it matter? A command like sudo xz -cd ./ubuntu-13.04-armhf-minfs-*.img.xz > /dev/sdX is actually two commands. First, xz is executed to perform a decompression operation and emit the byte stream to stdout. Second, the shell takes the byte stream and writes it to the specified device. Using the sudo command will only elevate the first xz command to root, which we don’t actually need, and leave the /dev/sdX stdout redirection to be performed by your unelevated shell (the part we do need root permissions to do). The operation will fail with a permission denied error. Elevating the shell to root via sudo su allows this command to succeed.
An alternative is to use the tee command and elevate it with sudo like so: xz -cd ./ubuntu-13.04-armhf-minfs-*.img.xz | sudo tee /dev/sdX > /dev/null


Once you have downloaded an Ubuntu or Debian .img.xz file, write it to a microSD card.

LZMA compression (7z aka xz) is used throughout this site. Many of the downloads available here are 100MB or more in size, so differences in compression algorithms add up quickly.

Install xz if you do not already have it.

# apt-get install xz-utils

This example decompresses the image and writes it to the sdb device. Also note these instructions apply equally to mmc block devices such as /dev/mmcblk0 if you are booted to a device with an SD card. Please be careful as writing this image to the wrong device will corrupt the device. Run an ls /dev/sd* command before and after inserting the microSD card so you can be 100% certain which device is your microSD. It is recommended that you download VirtualBox and do this procedure using an Ubuntu VM to make the process easier.

NOTE: If you are using an x86 Ubuntu distribution to write the microSD, the device will be seen as /dev/sdX. If you are following along booted from the BeagleBone, the device will be /dev/mmcblk1 instead.

# xz -cd ./ubuntu-13.10-armhf-minfs-*.img.xz > /dev/sdX

After the file has finished decompressing and copying to the microSD card, we’ll need to reload the partition table.

# partprobe /dev/sdX

Note that if you don’t have partprobe installed the above command will fail. You can either apt-get install parted or just remove and reinstall the microSD card at this point.

Confirm that two partitions now exist on the target microSD card.

# ls -al /dev/sdb*
brw-rw---- 1 root disk 179, 0 Apr 26 20:48 /dev/sdb0
brw-rw---- 1 root disk 179, 1 Apr 26 20:49 /dev/sdb1
brw-rw---- 1 root disk 179, 2 Apr 26 20:49 /dev/sdb2

We can now mount the media to make any changes before we boot the filesystem (optional).

# mkdir /media/b1
# mkdir /media/b2
# mount /dev/sdb1 /media/b1
# mount /dev/sdb2 /media/b2

That’s it — sync and remove the microSD card.

# sync
# umount /dev/sdb1
# umount /dev/sdb2

NOTE: The beaglebone black will try to boot the internal Angstrom image by default. To boot from microSD, you’ll need to hold down the USER/BOOT button (located near the microSD end of the board) while powering-on the device.


Ubuntu Logon ubuntu-armhf as user ubuntu with a password of ubuntu
login as: ubuntu
ubuntu@ubuntu-armhf's password: ubuntu


Debian Wheezy Logon debian-armhf as user debian with a password of debian
login as: debian
debian@debian-armhf's password: debian


apt-get update

Once you have booted, execute apt-get update to update the package cache and then apt-get upgrade to refresh any updated binaries. It is good practice to execute apt-get update to refresh the package cache before trying to apt-get install packages.


Writing to Internal eMMC

The prebuilt image is sized to exactly 1832MB to allow it to fit into the BeagleBone Black’s on-board 2GB NAND storage. This size also allows it to fit on a wide variety of external microSD cards. The image can be resized to take advantage of additional space available on larger microSD cards. To install the image to the internal eMMC, boot from the SD card. While booted from an external SD card, the internal eMMC will be available as /dev/mmcblk1. To write the image to eMMC, execute: # xz -cd ubuntu-12.04-armhf-minfs-*.img.xz > /dev/mmcblk1 (ubuntu 12.04 in this example) as full root: sudo su.


Expanding the Image

To exapand the image to use the whole SD card (e.g. 4GB, 8GB, 16GB, etc), see: Expanding Linux Partitions