A script to automatically build and setup a Gentoo Chroot environment (and run some commands into it)

GallaFrancesco authored 10 hours ago
files fixed wrong tar invocation 5 days ago
README.md README 4 days ago
chrooter.sh chrooter logs 10 hours ago
install_greatspn.sh installer 4 days ago


The aim of chrooter.sh is to provide an automated way of setting up a self-contained Gentoo Linux environment which can be used to generate binary packages by using Portage (Gentoo Linux package manager).

This script must be run as root (for the simple reason that chroot requires it). It can damage your filesystem if not configured properly. The default execution directory is in /tmp/, which is usually mounted as a tmpfs by the operative system and thus all the changes are executed in RAM, with the exception of the extraction of the binary packages (see tarball creation below).


user$ git clone https://github.com/gallafrancesco/chrooter.git
user$ cd chrooter

[... Configure variables in chrooter.sh and files/setup.sh ...]

root# ./chrooter.sh

First run

Most of the parameters given here can be configured by editing variable declarations in chrooter.sh.

  1. Checks for the latest portage stage3 tarball from the available Gentoo repositories
  2. Unpacks the stage3 to the given directory $chroot_name in /tmp -> this directory will be referred to as $root
  3. Fetches the latest Portage tree from Gentoo's Portage repositories
  4. Unpacks the portage tree to $root/usr
  5. Mounts the necessary partition to perform a chroot to $root: see the available documentation
  6. Copies the content of the files directory to $root: the directory is structured to respect the Linux filesystem (so that each configuration file is properly copied to the corresponding directory)
  7. Chroots in $root and executes files/setup.sh as root user in the freshly created Gentoo Environment.
  8. Once files/setup.sh terminates, chrooter.sh exits the chroot environment unmounting each partition.
  9. When partitions are unmounted, two tarballs are created in $ddir:
    • One containing the whole chroot filesystem (starting from $root)
    • Another containing the binary packages in /usr/local which have been compiled by setup.sh. In this case, the packages are statically linked GreatSPN binaries generated from their git sources.

Repeated runs

After the first run, the generated filesystem is not deleted from $root automatically, and can be used (by chrooting into it, exploring it, modifying it).

chrooter.sh checks if the filesystem exists and skips unpacking of stage3 and Portage tarballs if that's the case. The script will simply use the existing filesystem to run setup.sh into it. It does not overwrite any part of the filesystem, with the exception of:

  • Content of the files directory, which can be modified and will be copied to $root anyway.
  • Updates / actions executed by setup.sh, which are executed as root inside the chroot jail and are out of chrooter.sh control.

At the end of each execution, two new tarballs are created. Each tarball name is a string which contains the Unix Time of generation, so that older tarballs in $ddir are not overwritten.


This files/setup.sh is given as an example of the commands which can be run inside the Chroot jail. This example builds a statically-linked version of GreatSPN which can be extracted and used on a generic Linux system.


The GreatSPN packages are fetched from the corresponding local overlay. setup.sh takes care of building each dependency according to the configuration files in files and installing GreatSPN inside the environment. The installation is performed using layman to add the overlay to Portage's tree and emerge to install each package.

Each time it is run, setup.sh also checks for new version of the installed packages (necessary to build GreatSPN) by syncing the portage tree, and updating it if necessary, then proceeds to emerge greatspn following the ebuilds contained in the local overlay.