Project:AMD64/32-bit Chroot Guide

This guide provides instructions on how to create a 32-bit chroot.

Introduction

Introduction to 64-bit system

This 32-bit chroot guide will help users setting up a true 32-bit chroot on amd64 systems.

64-bit systems do not run 32-bit applications natively (yet) (at least not with Portage) so you need to use emulation libraries to make them working or create a true 32-bit system inside a chroot to install and run native 32-bit applications. For the most common uses you do not need do build a 32-bit chroot system. However, if you want to run applications that don't have a binary available to run with 32-bit libraries, you should use a 32-bit chroot. This guide will teach you how to set up a 32-bit chroot and how to install and run applications inside the chroot.

Installation of a 32-bit chroot

To install a 32-bit chroot you need to follow many footsteps that you use to install Gentoo Linux on a x86 operating system. For now you need the latest stage3 available on the mirrors.

user $cd /home/user/downloads

user $wget -c <i686_stage3_url_here>

Note
Be sure to download a stage for x86, not for AMD64.

After downloading the stage3 create a new directory to build the chroot:

root #cd /mnt

root #mkdir gentoo32

Then move the stage that has been downloaded, unpack it, and set it up:

root #cd /mnt/gentoo32

root #tar -xvjpf /path/to/downloaded/<i686_stage3>

root #cp -L /etc/resolv.conf /mnt/gentoo32/etc/

root #cp -L /etc/passwd /mnt/gentoo32/etc/

Now the chroot is ready to be setup.

Setup

The next step is to configure new /mnt/gentoo32/etc/make.conf:

FILE /mnt/gentoo32/etc/make.confConfiguring the make.conf

CFLAGS="-O2 -march=athlon-xp -msse2 -pipe -fomit-frame-pointer"
CHOST="i686-pc-linux-gnu"
CXXFLAGS="${CFLAGS}"
MAKEOPTS="-j2"

Now mount the various bogus file systems:

root #mount --rbind /dev /mnt/gentoo32/dev

root #mount --rbind /sys /mnt/gentoo32/sys

root #mount -t proc none /mnt/gentoo32/proc

The true 32-bit chroot installed in the 64-bit system is almost ready for use. Next, a link must be created from the Portage available in your 64-bit system to the 32-bit chroot. This way, you only need to update it in one installation instead of duplicating a lot of data.

Link Portage to /usr/portage inside the 32-bit chroot:

root #mkdir -p /mnt/gentoo32/usr/portage/

root #mount -o bind /usr/portage /mnt/gentoo32/usr/portage/

Note
Every time Portage has been synced, the 32-bit chroot's Portage must be updated as well.

To run 32-bit applications which use X, /tmp must be mounted:

root #mount -o bind /tmp /mnt/gentoo32/tmp

Before chrooting verify sys-apps/util-linux has been installed. Emerge the package if it has not been installed:

root #emerge --ask sys-apps/util-linux

It is now time to chroot into the 32-bit chroot.

root #linux32 chroot /mnt/gentoo32 /bin/bash

Verify that the environment is now 32-bit:

root #uname -m

Warning
The linux32 utility is needed to change the CHOST value. Forgetting it will most likely cause the inability to compile anything inside the chroot environment.

Now you have a new 32-bit chroot system ready to be updated. Follow the next steps to update it:

root #. /etc/profile

root #env-update

root #emerge --sync

root #emerge -auDN @world

The setup process of the 32-bit chroot almost complete. To make things more suitable create a new file in the 64-bit system to enable the 32-bit chroot when booting. The file should be located in /etc/init.d:

FILE /etc/init.d/gentoo32Creating a 32-bit chroot switcher

#!/sbin/openrc-run

chroot_dir=/mnt/gentoo32

depend() {
   need localmount bootmisc
}

start() {
    ebegin "Mounting 32-bit chroot directories"
    mount --rbind /dev "${chroot_dir}/dev" >/dev/null
    mount --rbind /sys "${chroot_dir}/sys" >/dev/null
    mount -t proc none "${chroot_dir}/proc" >/dev/null
    mount -o bind /tmp "${chroot_dir}/tmp" >/dev/null
    mount -o bind /usr/portage "${chroot_dir}/usr/portage/" >/dev/null
    mount -t tmpfs -o nosuid,nodev,noexec,mode=755 none "${chroot_dir}/run" > /dev/null
    eend $? "An error occured while attempting to mount 32bit chroot directories"
    ebegin "Copying 32bit chroot files"
    cp -pf /etc/resolv.conf /etc/passwd /etc/shadow /etc/group \
           /etc/gshadow /etc/hosts "${chroot_dir}/etc" >/dev/null
    cp -Ppf /etc/localtime "${chroot_dir}/etc" >/dev/null
    eend $? "An error occured while attempting to copy 32 bits chroot files."
}

stop() {
    ebegin "Unmounting 32-bit chroot directories"
    umount -fR "${chroot_dir}/dev" >/dev/null
    umount -fR "${chroot_dir}/sys" >/dev/null
    umount -f "${chroot_dir}/proc" >/dev/null
    umount -f "${chroot_dir}/tmp" >/dev/null
    umount -f "${chroot_dir}/usr/portage/" >/dev/null
    umount -f "${chroot_dir}/run"
    eend $? "An error occured while attempting to unmount 32bit chroot directories"
}

Execute the following command to enter the 32-bit environment during the next system boot:

root #rc-update add gentoo32 default

Whenever you want to switch to the 32-bit chroot environment it is simply a matter of running the following command:

user $linux32 chroot /mnt/gentoo32 /bin/bash

The 32-bit chroot is ready to install new packages.

Packages

Every package must be installed in 32-bit mode:

root #linux32 chroot /mnt/gentoo32 /bin/bash

root #source /etc/profile

root #env-update

root #emerge <package/atom>

Note
Always remember to source /etc/profile and env-update after switching into the chroot.

The new package should now be installed in the 32-bit chroot. The package will only be available to the system while inside the chroot. To run X applications the best solution is to use the xhost trick. When a X application is needed in the 32-bit environment, run the following command in the 64-bit environment before entering the chroot:

root #xhost local:localhost

It now should be possible to run every X application inside the 32-bit chroot.

Conclusion

Following this guide has enabled the installation of many packages available only for the x86 architecture. Some packages like app-office/openoffice-bin can be installed by using the binary available for the amd64 architecture since the 64-bit version of the package is really only 32-bit. Some of the codecs available for MPlayer need a 32-bit chroot to install win32codecs.

---

This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: Luis Medinas (Author) last updated on November 16, 2012
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.