Package: fchroot
fchrootIntroductionfchroot, also known as "Franken-Chroot" or "Funtoo Chroot", is a utility that helps
you to leverage the magic of QEMU to chroot into a non-native system. For example,
on your x86-compatible 64-bit PC, it is possible to chroot into a 32-bit or 64-bit
ARM environment and have it actually work.This is accomplished by leveraging the
"binfmt-misc" functionality built-in to the Linux kernel, combined with QEMU to
perform emulation of non-native instruction sets.fchrootitself doesn't do any
magic except provide a very easy-to-use mechanism to get this to work, typically
requiring little or no manual configuration. You simply runfchrootjust likechroot, and everything works. Well, I suppose that is a bit magical :) Here's an
example of how things work with fchroot. Let's say you are on your 64-bit x86-64
PC, and want to enter a 64-bit ARM environment. Do this:my64bitpc# tar xpvf stage3-arm64bit.tar.xzmy64bitpc# fchroot arm64-root>>>arm-64bitfrankenchrootB]...#That last#prompt may not look like anything special, but you are now inside a
64-bit ARM frankenchroot. A 64-bit ARM shell is providing that prompt to you, and
if you run a standard Linux command, it will be running the 64-bit ARM variant of
that command using QEMU emulation. Pretty cool stuff.WhatfchrootDoes For YouThefchrootcommand does lots of things automatically for you to make your
franken-chroot experience as seamless as possible. First, note thatfchrootis
designed to have a similar calling convention to the standard Linuxchrootcommand --
in fact, at the very end of doing all its magic, it passes all of its arguments tochrootto get you inside the frankenchroot. Butfchrootdoes quite a bit of
grunt-work to make thechrootwork:fchrootwill look inside the specified directory and attempt to auto-detect
what kind of non-native environment it's dealing with. It will currently recognize arm-32bit
and arm-64bit environments.fchrootwill check to see if QEMU is available for the detected non-native
architecture and abort with a (hopefully) useful error message if it is not.fchrootwill usegccto compile a special wrapper that will be used inside
the chrooted environment, and store it in/usr/share/fchroot/wrappersso it is
available for later use.fchrootwill leverage Linux'sbinfmt_miscfunctionality and register a handler
so that the kernel will know to use our wrapper (and QEMU) to run non-native binaries.fchrootwill copy the necessary QEMU binary as well as its wrapper into/usr/local/bin/inside the chrooted environment.fchrootwill mount/proc,/dev(bind-mount) and/sys(bind-mount) within the
chroot environment automatically if they are not already mounted.fchrootwill copy the local system's/etc/resolv.confto the chroot environment
so that DNS resolution will work properly.fchrootwill thenexecvpthechrootcommand to place you inside the franken-chroot
environment.PrerequisitesThis section lists the prerequisites for gettingfchrootrunning -- in other words,
the things thatyouare responsible for ensuring are done.fchroottakes care
of the rest.Host and Emulated Systemfchroothas been used on x86-compatible 64-bit systems, and currently supports
arm-32bit and arm-64bit chrooted environments. It is relatively easy to add support
for new native and emulated systems -- the code is designed to accept patches for
new architectures -- but for now, be aware of the current architectures supported.QEMUQEMU will need to be installed with theaarch64andarmuser targets enabled.
In addition, it will need to be compiled as astaticbinary. In Funtoo Linux and
Gentoo Linux, this can be accomplished by adding the following configuration
prior to runningemerge qemu:Add to/etc/make.conf:QEMU_USER_TARGETS="aarch64 arm"Add to/etc/portage/package.use:app-emulation/qemustatic-user
dev-libs/glibstatic-libs
sys-apps/attrstatic-libs
sys-libs/zlibstatic-libs
dev-libs/libpcrestatic-libsbinfmt_miscIn addition, you will need to ensure thatbinfmt_miscfunctionality is enabled
in-kernel or as a module. By default, this is the case when using Funtoo Linux with
its defaultdebian-sources-ltskernel.SetupThe easiest way to set upfchrootis to clone it directly fromhttps://code.funtoo.org:# git clone https://code.funtoo.org/bitbucket/scm/~drobbins/fchroot.gitYou can then simply runfchrootdirectly from the git repository:# fchroot/bin/fchroot /path/to/chrootAcknowledgementsThefchrootcommand automates a process that was documented at the following locations:https://wiki.gentoo.org/wiki/Embedded_Handbook/General/Compiling_with_qemu_user_chroothttps://github.com/sakaki-/gentoo-on-rpi3-64bit/wiki/Build-aarch64-Packages-on-your-PC%2C-with-User-Mode-QEMU-and-binfmt_miscMany thanks to Sakaki and others who documented this process.ContributingTo contribute, please visithttps://code.funtoo.org/bitbucket/users/drobbins/repos/fchroot/browseand submit a pull request.
For more information on how to submit pull requests on code.funtoo.org, see the following YouTube video:https://www.youtube.com/watch?v=V6PfB64oMWoAuthor and CopyrightCopyright 2020 Daniel Robbins, Funtoo Solutions, Inc.Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License athttp://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.