Gentoo Logo

Gentoo on the BeagleBone Black


1.  Overview

Installing Gentoo in the BeagleBone Black is pretty simple if you're already a Gentoo user. You need to use a microSD card, at least of 2 GB of size. If you are familar with the Gentoo Linux installation process, there is not much different here.

2.  Requirements

To be able to install Gentoo, you'll need the following:

  • An x86/amd64 based PC with Gentoo and SD card reader on it
  • A BeagleBone Black
  • One microSD card (2 GB is enough)
  • A network connection

3.  Preparing to install your BeagleBone Black


Before we start the installation process, we need to get/build a kernel and a bootloader for the BeagleBone Black.

Emerging needed tools

For building the stuff needed to boot our BeagleBone Black, we need the following tools emerged on the host system where we're going to build them.

  • dev-vcs/git - to download U-Boot, X-Loader and the kernel
  • sys-devel/crossdev - to create a crosscompiler
  • dev-embedded/u-boot-tools - to create a kernel image U-Boot can understand
  • sys-fs/dosfstools - to create FAT32 filesystems
  • app-arch/lzop - required by the kernel build

Code Listing 3.1: Emerge needed tools

# emerge dev-vcs/git sys-devel/crossdev dev-embedded/u-boot-tools sys-fs/dosfstools app-arch/lzop

Build a crosscompiler

Code Listing 3.2: Building a crosscompiler

# crossdev -S armv7a-hardfloat-linux-gnueabi

Obtaining/Building U-Boot

Code Listing 3.3: Obtaining U-Boot

# wget

(Extract and change to the directory)
# tar xjpf u-boot-2013.04.tar.bz2 && cd u-boot-2013.04

We need to apply some patches to U-Boot that enhances support for the BeagleBone Black

Code Listing 3.4: Obtaining patches and applying them

# git clone

(Apply the patches)
# for i in meta-beagleboard/common-bsp/recipes-bsp/u-boot/u-boot-denx/00*; do patch -p1 < $i; done

Code Listing 3.5: Compiling U-Boot

# make ARCH=arm CROSS_COMPILE=armv7a-hardfloat-linux-gnueabi- am335x_evm_config
# make ARCH=arm CROSS_COMPILE=armv7a-hardfloat-linux-gnueabi-

Obtaining/Building a kernel

For booting the BeagleBone Black we need a kernel. The vanilla doesn't support the BeagleBone Black as of April 2013, for this reason we'll use a kernel provided by the project.

The repository only contains patches to be applied onto the source. For doing so, it downloads the kernel source from's repositories.

Code Listing 3.6: Obtaining the kernel

# git clone

(Change to the directory)
# cd kernel

(Switch to an up-to-date branch)
# git checkout origin/3.8 -b 3.8

(Download a and patch it, may take a while)
# ./

(You may get the following error)
fatal: unable to auto-detect email address (got 'user@nowhere.(none)')
You need to set your committer info first

(You can fix it by simply running the following command)
# git config --global
(Now run again)

(Change to the directory inside the kernel directory)
# cd kernel

Code Listing 3.7: Obtaining needed firmware

# wget ";a=blob_plain;f=bin/am335x-pm-firmware.bin;hb=HEAD" -O firmware/am335x-pm-firmware.bin

Code Listing 3.8: Configuring the kernel

# cp ../configs/beaglebone .config

Code Listing 3.9: Cross-compiling the kernel

(Replace 9 with the number of cores you have on your computer)
# make -j9 ARCH=arm CROSS_COMPILE=armv7a-hardfloat-linux-gnueabi- uImage dtbs

Once it gets built we'll have a kernel image on arch/arm/boot/uImage.

4.  microSD card setup


OMAP-based systems need a special setup of the microSD card to boot from it. For more information please check this link.

Formatting the microSD card

The following script will format your microSD card accordingly, creating two partitions. The first partition size is based on the size of the microSD card itself, and it's formatted in vfat. The second partition is the free space left on the card after the first partition, and it's formatted in ext4.

Code Listing 4.1: Formatting the microSD card

# wget

(Replace sdd with the name of the device of your microSD card)
# bash /dev/sdd

5.  Installing Gentoo


The installation on this device is a bit different, and therefore easy, as we can't install Gentoo on it by booting an installation environment. For installing Gentoo (and any other distro, really) you need to put the microSD card on your PC and prepare there the minimal installation.

What we'll have to do to setup our installation is:

  1. Extract stage3 to the 2nd partition of the microSD card
  2. Extract portage snapshot (required to emerge things, ntp and using the eMMC(see below))
  3. Setup fstab
  4. Setup root password
  5. Configure hostname and networking (optional, but recommended)
  6. Enable SSH access (optional, but recommended)
  7. Enable serial console access (optional, but recommended)

Stages information

Here's some information about the stages.

  • Architecture: arm
  • Subarchitecture: armv7a_hardfp
  • CHOST: armv7a-hardfloat-linux-gnueabi
  • Profile: default/linux/arm/10.0

We'll be using the new EABI, also called gnueabi.

Therefore, we need an armv7a-hardfloat-linux-gnueabi stage3 for best performance, available under the releases/arm/autobuilds directory in your favorite mirror

Optionally you can also grab a portage snapshot unless you want to install Gentoo into the eMMC later on, for which a working portage tree is needed

Extracting a stage3

Mount the second partition of the microSD card and extract the stage3 you downloaded.

Code Listing 5.1: Mounting the partition and extracting the stage3

(Make sure you're root)
# mkdir /mnt/p2
# mount /dev/sdd2 /mnt/p2

(Extract the stage3, it may take a while)
# tar xjpf stage3-armv7a_hardfp-20121006.tar.bz2 -C /mnt/p2

Extracting a portage snapshot (optional unless you want to install Gentoo into the eMMC later on)

Code Listing 5.2: Extracting the snapshot

(Extract the snapshot, it may take a while)
# tar xjpf portage-latest.tar.bz2 -C /mnt/p2/usr

Setup fstab

Edit the /mnt/p2/etc/fstab file to look like this:

Code Listing 5.3: /mnt/p2/etc/fstab

(Comment/Remove this line)
/dev/BOOT               /boot           ext2            noauto,noatime  1 2

(This is the important part)
/dev/mmcblk0p2		/		ext4		noatime		0 1

(Remove the following lines as we don't have SWAP, cdrom, or floppy)
/dev/SWAP		none		swap		sw		0 0
/dev/cdrom		/mnt/cdrom	auto		noauto,ro	0 0
#/dev/fd0		/mnt/floppy	auto		noauto		0 0

Setting the default root password

This is the most important part of the installation. As without the root password we won't be able to login!

For setting the password, we need to be able to run passwd. However that's not possible since our PC can't run ARM binaries. Therefore we need to modify the file that contains the passwords (/etc/shadow) inside the chroot, so we can set a default root password.

Code Listing 5.4: Change the default root password

(Generate a password)
# openssl passwd -1

# nano -w /mnt/p2/etc/shadow

(Replace the first line with the following line)
(Replace s3cr3t with the output the openssl command gave you)

(For example, this line makes the password be gentoo)

Setup hostname and networking

Please read the network configuration chapter of the ARM handbook to configure the network.

Using swclock

One of the problems the BeagleBone Black has, is that it doesn't have a battery to save the clock time. To mitigate this, on Gentoo we have an option in our init system called swclock which sets the date of the system upon boot from a last modified date of a file.

Code Listing 5.5: Adding swclock to the startup

# ln -sf /etc/init.d/swclock /mnt/p2/etc/runlevels/boot

We remove hwclock from the startup because it sets the date from the RTC, which is 2000-01-01 upon startup and overrides swclock's date.

Code Listing 5.6: Removing hwclock from the startup

# rm /mnt/p2/etc/runlevels/boot/hwclock

swclock uses the /sbin/rc's modification time to set the date, therefore we update it to have the current date and time.

Code Listing 5.7: Setting the correct date

# touch /mnt/p2/sbin/rc

Although this doesn't fix the issue, at least helps to set a sane date and time.

Note: Consider using NTP, documented on the next chapter

Enabling SSH access (optional)

We can add sshd to the startup of our system so we can access our BeagleBone Black using ssh.

Code Listing 5.8: Adding sshd to the startup

# ln -sf /etc/init.d/sshd /mnt/p2/etc/runlevels/default

Enabling serial console access (optional)

By default the ttyS0 port is configured at 9600 bps. However, almost all of the ARM devices run the serial port at 115200 bps. Also, in the case of the BeagleBone Black, the port is ttyO0(that is a t-t-y-capitalO-zero) instead of the normal ttyS0. So this should be added to the /etc/inittab file:

Code Listing 5.9: Configuring serial console

# nano -w /mnt/p2/etc/inittab

(Replace 9600 with 115200 on the ttyS0 line, and replace ttyS0 with ttyO0)
s0:12345:respawn:/sbin/agetty 115200 ttyO0 vt100

Copying U-Boot, MLO and the kernel to the microSD card

Now we'll mount the first partition on the card and copy the needed files (the ones that we built before) to boot our BeagleBone Black.

Code Listing 5.10: Copying U-Boot, MLO and the kernel to the microSD card

(Make sure you're root)
# mkdir /mnt/p1 ; mount /dev/sdd1 /mnt/p1

# cp u-boot-2013.04/{MLO,u-boot.img} /mnt/p1
# cp kernel/kernel/arch/arm/boot/{uImage,/dts/am335x-boneblack.dtb} /mnt/p2/boot/

Finishing the installation

Let's unmount the microSD card

Code Listing 5.11: Unmounting the microSD card

(May take a while depending the speed of your microSD card)
# umount /mnt/p1 /mnt/p2

This is pretty much all of the installation. I'd highly recommend that you read all the recommendations of the handbook.

6.  Booting up our new system

By default, the BeagleBone Black will use the MLO and bootloader on the internal eMMC storage. The bootloader should be able to detect the SD card and use the kernel and root filesystem from it.

However, you can use the bootloader from the microSD card simply holding the USR1 button on the board(the one near the microSD slot) while you provide power to the board.

Once you have the card ready, put it into the BeagleBone Black... and you should be able to boot it.

7.  After booting

Keeping the clock up to date

One of the problems of the BeagleBone Black is that it doesn't save the date because it doesn't have a battery for the clock.

After logging into our new Gentoo on BeagleBone Black installation, I'd recommend setting a date and emerging net-misc/ntp to keep the clock up-to-date. Also it's recommended to put both ntp-client and ntpd to boot on startup, so you get a proper date setup.

However, keep in mind that NTP requires a network connection and a NTP server being reachable, either on the local network or on the Internet.

Code Listing 7.1: Emerging net-misc/ntp

(Make sure you're root)
# emerge net-misc/ntp

(Put both ntp-client and ntpd to boot on startup)
# rc-update add ntpd default
# rc-update add ntp-client default

(Start ntp-client and ntpd)
# /etc/init.d/ntp-client start
# /etc/init.d/ntpd start

Using the eMMC

The BeagleBone Black has a 2GB eMMC device that can be used for storing the bootloader and the root filesystem, so you don't need an microSD card to use the BeagleBone Black.

For doing so, first you need follow this guide, once you have your system booted you can check the following guide which is a copy of this one but modified slightly: Installing Gentoo on the BeagleBone Black's eMMC

8.  References

You may find more documentation about the device itself and Linux-related at the following links:

9.  Thanks


Page updated August 10, 2013

Summary: This guide shows you how to install Gentoo on the BeagleBone Black.

Raúl Porcel

John L. Poole

Donate to support our development efforts.

Copyright 2001-2015 Gentoo Foundation, Inc. Questions, Comments? Contact us.