Funtoo franken-chroot tool.
fchroot, 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.
fchroot itself 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 run
fchroot just like
chroot, 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.xz my64bitpc # fchroot arm64-root >>> arm-64bit frankenchroot B]... #
# 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.
fchroot Does For You
fchroot command does lots of things automatically for you to make your
franken-chroot experience as seamless as possible. First, note that
designed to have a similar calling convention to the standard Linux
chroot command --
in fact, at the very end of doing all its magic, it passes all of its arguments to
chroot to get you inside the frankenchroot. But
fchroot does quite a bit of
grunt-work to make the
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.
gccto 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's
binfmt_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.
/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.
chrootcommand to place you inside the franken-chroot environment.
This section lists the prerequisites for getting
fchroot running -- in other words,
the things that you are responsible for ensuring are done.
fchroot takes care
of the rest.
Host and Emulated System
fchroot has 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.
QEMU will need to be installed with the
arm user targets enabled.
In addition, it will need to be compiled as a static binary. In Funtoo Linux and
Gentoo Linux, this can be accomplished by adding the following configuration
prior to running
app-emulation/qemu static-user dev-libs/glib static-libs sys-apps/attr static-libs sys-libs/zlib static-libs dev-libs/libpcre static-libs
In addition, you will need to ensure that
binfmt_misc functionality is enabled
in-kernel or as a module. By default, this is the case when using Funtoo Linux with
The easiest way to set up
fchroot is to clone it directly from https://code.funtoo.org:
# git clone https://code.funtoo.org/bitbucket/scm/~drobbins/fchroot.git
You can then simply run
fchroot directly from the git repository:
# fchroot/bin/fchroot /path/to/chroot
fchroot command automates a process that was documented at the following locations:
Many thanks to Sakaki and others who documented this process.
To contribute, please visit https://code.funtoo.org/bitbucket/users/drobbins/repos/fchroot/browse and 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=V6PfB64oMWo
Author and Copyright
Copyright 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 at
Unless 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.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size fchroot-0.1.2.tar.gz (8.4 kB)||File type Source||Python version None||Upload date||Hashes View|