How to Create a GENTOO Distro CHROOT ENVIRONMENT

This article describes how to build a chroot environment for Gentoo distribution.

NOTE: Debian GNU/Linux will be our host system, but these steps should also work for most other Linux based distributions (e.g: Ubuntu).


DOWNLOAD A SMALL MINIMUM GENTOO SYSTEM

First we are going to download a minimal Gentoo system, called STAGE3.

We choose our architecture, in my case x86, and i686 specifically.
http://mirrors.kernel.org/gentoo/releases/x86/autobuilds/current-stage3/
$ wget http://mirrors.kernel.org/gentoo/releases/x86/autobuilds/current-stage3/stage3-i686-*.tar.bz2

There is a list of mirrors here: http://www.gentoo.org/main/en/mirrors.xml

We could download directly from gentoo page too:
$ wget ftp://distfiles.gentoo.org/pub/gentoo/releases/x86/current-stage3/stage3-i686-*.tar.bz2



BUILDING OUR GENTOO DIRECTORY

We create a directory where we will place Gentoo files:
$ mkdir gentoo_chroot
and uncompress there the stage3 archive.
# tar xvjf stage3-i686-20100216.tar.bz2 -C gentoo_chroot/

Copy resolv.conf file to resolve names:
# cp -L /etc/resolv.conf gentoo_chroot/etc/resolv.conf
We will be able to resolve addresses.


Copy /etc/host file:
# cp /etc/hosts gentoo_chroot/etc/
or we could create a new one:
e.g: # echo "127.0.0.1 mybox.at.myplace mybox localhost" > gentoo_chroot/etc/hosts

I like using same hostname as the host one because if we change it in chroot, it also changes in the host.

When we will enter in the chroot jail we will be able to exec:
# hostname -f # shows mybox.at.myplace.
# ping mybox.at.myplace



MOUNTING NEEDED DIRECTORIES

We use bind option to duplicate some host directories in the chroot filesystem:

# mount --bind /dev gentoo_chroot/dev
# mount --bind /proc gentoo_chroot/proc
# mount --bind /sys gentoo_chroot/sys
# mount --bind /dev/pts gentoo_chroot/dev/pts # Needed for agetty login and screen command.
# mount --bind /tmp gentoo_chroot/tmp # If we want share X windows between host and guest.


ENTERING THE CHROOT ENVIRONMENT

# chroot gentoo_chroot /bin/bash
We are in the gentoo chroot envirionment!!
Unless told, every command from now on is executed within the chroot env.


To update and configure some environment variables:
# env-update
# source /etc/profile # To configure our current shell environment.


CUSTOMIZING YOUR PROMPT

We can also customize our prompt to show we are in the chroot jail.
# export PS1="(chroot) $PS1"

If we want to customize every login prompt we have to change /etc/profile.
# echo "export PS1=\"(chroot) \$PS1\"" >> /etc/profile
For non login shells you have to edit .bashrc file.


CREATE /etc/mtab FILE

# cp /proc/mounts gentoo_chroot/etc/mtab

Some mtab file lines are useless so we edit them:
# nano -w /etc/mtab

We leave something like that:

udev /dev tmpfs rw,relatime,size=10240k,mode=755 0 0
none /sys sysfs rw,nosuid,nodev,noexec,relatime 0 0
none /proc proc rw,nosuid,nodev,noexec,relatime 0 0
devpts /dev/pts devpts rw,relatime,mode=600,ptmxmode=000 0 0

Now we are able to exec mount and df commands.



SETTING THE TIMEZONE

# ls /usr/share/zoneinfo # Shows all available timezones.
# cp /usr/share/zoneinfo/Europe/Madrid /etc/localtime # I use Madrid timezone.



CONFIGURE LOCALES

$ cd /etc
# nano -w locale.gen
I add: es_ES.UTF-8 UTF-8 # Spanish specific locales, choose the ones which suit you.
# locale-gen # we generate locales.
We change locale:
# export LANG=es_ES.UTF-8
# locale



CHANGE ROOT PASSWORD

# passwd root

edit /etc/securetty file
# nano -w /etc/securetty
Add there all tty where you want to login as root from. e.g: add pts/5 if you want to login from /dev/pts/5 tty.
Exec $ echo $(tty) in your host to show which tty you are in.



ADDING A NEW USER

We are going to create an user called new_user:
# useradd -m new_user # -m option to create home directory.
# passwd new_user # change the user password.
# su new_user # become that user.



LOGIN IN ANOTHER WAY

Entering the chroot environment using the already told way mixes host and guest env variables.

A better way is using agetty command, execute in the host system:
# chroot gentoo_chroot/ /sbin/agetty $(tty) 38400

We can login as root or as the new user we have just created.

NOTE: The standard user wont be able to gain root privileges using su command unless he pertains to wheel group, so:

# usermod -a -G wheel new_user
# su new_user
$ su root
If not we will get "su: permission denied error".

Now user new_user can exec su command and become root.



DOWNLOAD PORTAGE SNAPSHOT

Portage is the Gentoo package management system.

We are going to install portage subsystem because we want to install more gentoo available packages.

# cd /usr # Portage is placed in /usr directory.
# wget http://distfiles.gentoo.org/snapshots/portage-latest.tar.bz2 # (35 MBytes)
or we could choose download it from a mirror: http://www.gentoo.org/main/en/mirrors.xml

Uncompress it:
# tar xvjf portage-latest.tar.bz2



EMERGE TOOL

Emerge is the command line tool which allow us to search, install, update, remove, etc gentoo packages.

Install less pager:
$ emerge --search less
We see: sys-apps/less
# emerge less # we install less pager.
less tool is compiled and installed.

Install screen terminal manager:
$ emerge --color y --search screen | less
# emerge -v screen

Now we are going to install a text web client:
Searching into categories. e.g: www-client
$ emerge --search @www-client --color y | less
# emerge -v links
$ links http://linuxclues.blogspot.com


My favourite text editor:
$ emerge --color y --search emacs | less
$ emerge --pretend emacs # To see what is going to happen without installing anything.
# emerge -v emacs
# tail -f /var/log/emerge-fetch.log # to see package downloading status.



SHARING X BETWEEN HOST AND CHROOT GUEST

# emerge -v xclock # we will use xclock tool to test the X system.

We need to obtain permissions and store it in .Xauthority file.
In the host machine exec:
$ xauth list
we obtain something like:

mybox/unix:0  MIT-MAGIC-COOKIE-1  5e20455a59909d2f911d73b8d7d8cba5

As I am using unix socket X display :0, I copy that line.

In the chroot env.
# emerge xauth
# xauth add mybox/unix:0 MIT-MAGIC-COOKIE-1 5e20455a59909d2f911d73b8d7d8cba5
# DISPLAY=:0.0 xclock # we can exec X apps as root.
$ xauth add mybox/unix:0 MIT-MAGIC-COOKIE-1 5e20455a59909d2f911d73b8d7d8cba5
$ DISPLAY=:0.0 xclock # we can exec X apps as a standard user.



INSTALLING MPLAYER TO TEST VIDEO AND SOUND

# emerge -v mplayer

After installation it runs correctly as root, but not as a standard user. We need to give him audio privileges.

As I use alsa sound drivers:
$ ls -l /dev/snd
I see in files owned by group 29 (legacy from host machine)
We edit /etc/group file and change audio group gid into 29.
# nano -w /etc/group
audio::29:

Add the standard user to audio group:
# usermod -a -G audio new_user
# su new_user
$ mplayer -vo xv -framedrop foo.avi



EXITING THE CHROOT JAIL

Simply type:
$ exit



UMOUNT

After exit we unmount binded directories:
# umount gentoo_chroot/dev/pts
# umount gentoo_chroot/dev
# umount gentoo_chroot/proc
# umount gentoo_chroot/sys
# umount gentoo_chroot/tmp

NOTE: when unmounting if it complains about a bind mount busy. You can use mount -M to move it to another place instead.
It is an ugly workaround, I know. :-D



REFERENCE:

Gentoo Quick Install Guide
Portage (Wikipedia)

$man emerge

Gentoo Documentation