User:Spawns/Bootstrap with emerge

From Gentoo Wiki
Jump to:navigation Jump to:search

The ROOT variable

The ROOT environment variable will instruct portage to install packages into a specific directory. This allows installing arbitrary packages, including an entire system into a directory anywhere on the file system.

This can be used to create Gentoo systems from an already installed and running Gentoo system, without the use of prebuilt stage tarballs!

Bootstrapping the system

Setting up the environment

Use ROOT as the root of the bootstrapped system.

root #export ROOT=${HOME}/gentoo

Write logs to the the bootstrapped systems logs instead of the hosts.

root #export PORTAGE_LOGDIR=${ROOT}/var/log

Disable news popups.

root #export FEATURES='-news'

Installing baselayout

A Gentoo root filesystem structure can be created by installing sys-apps/baselayout. The USE=build flag is required in order to create a complete filesystem from scratch (as some directories/files can only be created when not running on a live system).

root #USE=build emerge -1 baselayout

Emerging the system

Emerging the system set will install the minimum required packages for the system to stand on it's own.

root #emerge -1 @system

Configure and update

It is expected that you have chrooted into the new system in this section.
The environment variables from prior sections should no longer be set.
Moving between certain profiles is non-trivial.

A bootstrapped system can run portage on it's own, so it can be configured without conflicting with the host. Updating the world will bring the system into the newly configured state.

root #emerge --update --deep --changed-use @world

Portage will remove anything that was unneeded, but required due to the host's config after a full system update and a depclean.

root #emerge --depclean

Bootstraping with custom configurations

Not using the hosts config is likely to result in blockers when running the initial emerge. It is less complicated to rebuild the system with a new config after it has been bootstrapped.

When bootstrapping from a desktop system, typically the system is using a desktop profile and has USE flags set that enable desktop functionality in packages. When bootstrapping a new system that is intended for headless use for example, this will cause the first emerge to install many unnecessary packages.

Since the first emerge relies on the hosts configuration and state, using a config that is too different can lead to difficult to solve blockers that may be impossible to solve without making changes to one of the configs or to the host.


Avoiding the hosts USE and ACCEPT_KEYWORDS may be accomplished using environment variables.

An example setup that strips all of the host's USE flags and resets ACCEPT_KEYWORDS:

root #export USE='-*' ACCEPT_KEYWORDS='-* amd64'

BOOTSTRAP_USE is defined in the base profile, these flags are required for the system to function at all.

root #USE=$(portageq envvar BOOTSTRAP_USE)


Another option is to configure the bootstrapped system directly.


Unprivileged bootstrapping

Portage supports running as a non-root user, but some features may not be available.

Using portage without root can be useful for creating unprivileged containers, or just for experimenting with Gentoo without the risk of breaking the host.

Portage variables

Portage will fail while attempting to write to system files unless setting variables such as PORTAGE_TMPDIR to paths owned by the user.

user $export PORTAGE_TMPDIR=${HOME}/gentoo/var/tmp/
user $export PORTAGE_LOGDIR=${HOME}/gentoo/var/log/portage
user $export DISTDIR=${HOME}/gentoo/var/cache/distfiles
user $export RO_DISTDIRs=$(portageq envvar DISTDIR)
user $export EMERGE_LOG_DIR=${HOME}/gentoo/var/log/

Portage user mode

Some features will not work in this mode, and certain operations that inherently require root privileges will fail.

The ROOT variable has an extra function that doesn't seem to be documented. Setting ROOT to a directory that is owned by a non-zero UID allows portage to run as the UID of the owner of the directory.

User namespaces

Using user namespaces as an unprivileged user requires the kernel to be built with CONFIG_USER_NS and having the sysctl setting kernel.unprivileged_userns_clone enabled

Another, more robust option is to use the kernel's user namespaces features.

User namespaces allow non-root users to gain root privileges inside of a namespace, while still being unprivileged outside of it. This will allow the initial emerge to perform privileged operations required for the system to function correctly, such as creating new users and groups when installing packages from acct-user and acct-group.

Using unshare

User namespaces seems to break the userpriv portage features.

user $export FEATURES='-userpriv -usersync -userfetch'

Start an instance of ${SHELL} with the current ids mapped to 0 and automatically map subordinate ids allocated by the system. This shell instance can be used to perform the bootstrap.

user $unshare --map-root --map-auto