FAKECHROOT(1)

💅 FAKECHROOT — the manual page, but make it make sense

okay bestie, sit down, grab a boba, because we're about to talk about fakechroot and honestly? it's giving genius. this is the FAKECHROOT(1) page, section 1 of your manual, and by the end you're gonna be running a whole fake root environment from your regular little user account like it's nothing. no sudo, no cap. 👑

---

✨ NAME ✨

fakechroot — gives a fake chroot environment 💖

---

✨ SYNOPSIS ✨

lowkey the shapes you can call it in:

fakechroot [-s|--use-system-libs] [-l|--lib library]
[-d|--elfloader ldso] [-e|--environment type]
[-c|--config-dir directory] [-b|--bindir directory] [--] [command]

fakechroot -h|--help

fakechroot -v|--version

---

✨ DESCRIPTION ✨

so here's the tea: fakechroot runs a command in an environment where you get the extra ability to use the chroot(8) command without root privileges. that's the whole vibe. it means regular users can create their own chrooted environment and even install other packages in it, no root required, no asking permission, no drama. 🫶

how does it do it? it replaces some C library functions — think chroot(2), open(2), etc. — with versions that simulate the effect of being called with root privileges. it's fake it till you make it, but for syscalls. 💅

these wrapper functions ship as a shared library called libfakechroot.so, and it gets loaded through the "LD_PRELOAD" mechanism of the dynamic loader. (peep ld.so(8) if you wanna know more about that.) ✨

inside a fake chroot you can install, like, a Debian bootstrap with the debootstrap(8) command. and then in that environment you can run stuff like apt-get(8) to install even more packages. you don't need special privileges at all — you can literally run it on a common user's account. iconic behavior honestly. 👑

---

✨ OPTIONS ✨

• -b, --bindir directory — point at a directory that holds the replacement executables that ship with fakechroot. those are script files with the extension ".fakechroot". by default they're spread across the "bin" and "sbin" directories in fakechroot's install prefix, but sometimes a fixed location at build time just isn't feasible, yk? 🎀
• -c, --config-dir directory — point at a directory that holds additional configuration for fakechroot. the default directories are "$HOME/.fakechroot" and "/etc/fakechroot". 💜
• -d ldso, --elfloader ldso — specify an alternative dynamic linker. this dynamic linker will be invoked directly. 🦋
• -e, --environment type — load additional configuration with environment. this configuration file is a shell script that gets executed before calling command. the script can set additional environment variables, like i.e.: "FAKECHROOT_EXCLUDE_PATH", "FAKECHROOT_CMD_SUBST" or "LD_LIBRARY_PATH".

the environment type is guessed based on command name with the optional extension removed (e.g. running gettext.sh loads the "gettext" environment file). if the command argument is fakeroot(1), this argument is omitted and the next argument is taken as the environment type. sneaky but slay.

the configuration file name is type.env and it's searched at $HOME/.fakechroot and /etc/fakechroot directories.

the default environment type is default and its configuration file name is "default.env".

the special environment none means that no environment settings are loaded at all. periodt. 🚫

• -l library, --lib library — specify an alternative wrapper library. the default is libfakechroot.so. 🌸
• -h, --help — display help. we love a helpful queen. 💖
• -s, --use-system-libs — use system libraries before chroot's libraries. this might be a workaround if the system dynamic linker can't load libc.so from the fake chroot. 🧚

try this setting if you noticed following errors:

 $ fakechroot /usr/sbin/chroot /tmp/sarge /bin/true
 /bin/true: relocation error: /srv/sarge/lib/tls/libc.so.6: symbol _dl
 _starting_up, version GLIBC_PRIVATE not defined in file ld-linux.so.2
  with link time reference

 $ fakechroot /usr/sbin/chroot /tmp/centos4 /bin/true
 Segmentation fault

yeah bestie that segfault is not the vibe. try -s. 😭

• -v, --version — display version. ✨
• [--] command — any command you want to be run as fakechroot. use '--' if in the command you have other options that may confuse fakechroot's option parsing. protect the parsing, protect the peace. 🫶

---

✨ EXAMPLES ✨

an example session with fakechroot, bestie, watch this:

 $ id
 uid=1000(dexter) gid=1000(dexter) groups=1000(dexter)

 $ fakechroot fakeroot debootstrap sid /tmp/sid
 I: Retrieving Release
 I: Retrieving Release.gpg
 I: Checking Release signature
 ...
 I: Base system installed successfully.

 $ fakechroot fakeroot chroot /tmp/sid apt-get install -q hello
 Reading package lists...
 Building dependency tree...
 Reading state information...
 The following NEW packages will be installed:
   hello
 0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded.
 Need to get 57.4 kB of archives.
 After this operation, 558 kB of additional disk space will be used.
 Get:1 http://ftp.us.debian.org/debian/ sid/main hello amd64 2.8-4 [57.4 kB]
 Fetched 57.4 kB in 0s (127 kB/s)
 Selecting previously unselected package hello.
 (Reading database ... 24594 files and directories currently installed.)
 Unpacking hello (from .../archives/hello_2.8-4_amd64.deb) ...
 Processing triggers for man-db ...
 Processing triggers for install-info ...
 Setting up hello (2.8-4) ...

 $ fakechroot chroot /tmp/sid hello
 Hello, world!

hello world but make it a whole chroot moment. 🌈

---

✨ FAKEROOT ✨

fakeroot(1) is a complementary tool which emulates root environment. so like, they're besties, not twins. fakeroot and fakechroot might wrap the same C library functions, i.e. the mknod(2) function. and the way that they overlap means it's important to start the fake environment in the proper order. fakeroot should be started inside fakechroot. 🎀

 $ fakechroot fakeroot chroot /tmp/sid /bin/mknod /tmp/device c 1 2

order matters, bestie. don't flip it. 🙈

---

✨ SECURITY ASPECTS ✨

okay this part is serious, put the phone down for a sec. 🔥

fakechroot is a regular, non-setuid program. it does not enhance a user's privileges.

fakechroot should not be used as a tool for enhancing system security, i.e. by separating (sandboxing) applications. it is very easy to escape from a fake chroot environment. 💀

fakechroot should not be run with real root privileges. it might decrease the security of the system because fakechroot provides its own version of core functions with behavior depended on some environment variables.

like, this is a convenience tool, not a containment tool. it's a vibe, not a jail. no cap. 🚨

---

✨ FILES ✨

• libfakechroot.so — the shared library containing the wrapper functions. the whole main character of this operation. 👑

---

✨ ENVIRONMENT ✨

• FAKECHROOT — the value is true for fake chroot environment. ✅
• FAKECHROOT_AF_UNIX_PATH — the root directory for unix sockets. the default value is the same as "FAKECHROOT_BASE", and it can be set separately if the "FAKECHROOT_BASE" is too long and the unix socket path could exceed the limit of 108 bytes. (108 bytes! the limit is real and it's rude.) 📏
• FAKECHROOT_BASE — the root directory of fake chroot environment. 🌳
• FAKECHROOT_CMD_SUBST — a list of command substitutions. if a program tries to execute one of the commands given (path relative to the chroot, trailing dot is removed) then the substitute command runs instead (path to substitute command is not chrooted). 🎭

the substituted command inherits "FAKECHROOT_*" variables, but the original "FAKECHROOT_BASE" variable which is saved as "FAKECHROOT_BASE_ORIG". it means that substituted command runs outside fakechroot environment. also the original command name is saved as "FAKECHROOT_CMD_ORIG".

for example:

   export FAKECHROOT_CMD_SUBST=/usr/bin/mkfifo=/bin/true

will substitute "/bin/true" for "/usr/bin/mkfifo" and will make possible to install sysvinit binary package. slay. ✨

give as many substitute commands as you want, separated by ":" (colon) characters.

it is suggested to substitute at least:

• "/bin/mount=/bin/true"
• "/sbin/insserv=/bin/true"
• "/sbin/ldconfig=/bin/true"
• "/usr/bin/env=/usr/bin/env.fakechroot"
• "/usr/bin/ischroot=/bin/true"
• "/usr/bin/ldd=/usr/bin/ldd.fakechroot"
• "/usr/bin/mkfifo=/bin/true"

to make debootstrap(8) working correctly. 🫶

to prevent some looping, the command substitution is done only if "FAKECHROOT_CMD_ORIG" variable is not set currently. (loop protection, we love her.) 🔁🚫

• FAKECHROOT_DEBUG — the fakechroot library will dump some debugging info if this variable is set. 🐛
• FAKECHROOT_DETECT — if this variable is set then the "fakechroot version" string is printed to standard output and the current process is terminated with status taken from this variable. it can be a method to check if fakechroot is preloaded correctly. 👀

   $ case "`FAKECHROOT_DETECT=1 /bin/echo`" in fakechroot*) echo LOADED;; esac

• FAKECHROOT_ELFLOADER — a path to another dynamic linker (i.e. /lib/ld-linux.so.2 for i386 architecture, /lib64/ld-linux-x86-64.so.2 for x86_64 architecture). 🧚

this dynamic linker will be invoked directly. the dynamic linker don't allow to change "argv[0]" besides the file name of the executable file, so some application won't work correctly, i.e. busybox(1). 🙈

• FAKECHROOT_EXCLUDE_PATH — the list of directories which are excluded from being chrooted. the elements of list are separated with colon.

the /dev, /proc and /sys directories are excluded by default if this environment variable is not set.

this list has to contain at most 100 elements. (one hundred, bestie. count them.) 💯

• FAKECHROOT_EXTRA_LIBRARY_PATH — the list of extra directories in fake chroot environment that are added to the "LD_LIBRARY_PATH" variable. the directories might be used by some important commands which use libraries placed in the runpath. in that case the dynamic linker can't find correct directory in a fake chroot environment without the extra library path. 🔍

the default value is "/lib/systemd:/usr/lib/man-db" for systemctl(1) and man(1) commands. 📚

• FAKECHROOT_VERSION — the version number of the current fakechroot library. 🏷️
• LD_LIBRARY_PATH, LD_PRELOAD — fakechroot is implemented by wrapping system calls. this is accomplished by setting "LD_PRELOAD=libfakechroot.so". if this library can't be found by the dynamic linker, the /etc/ld.so.conf file or the "LD_LIBRARY_PATH" variable have to be modified. ⚙️

---

okay that's a lot of environment variables, i know, but we're not done yet bestie — there's more of this page coming. stay tuned. 💖

😭 LIMITATIONS 😭

okay bestie, vibe check: these are the things that are just not it. No cap. 💅

• /lib/ld-linux.so.2 and /lib64/ld-linux-x86-64.so.2 are always loaded from the real environment. This path is hardcoded by linker for all binaries. You can set the FAKECHROOT_ELFLOADER environment variable or use the --elfloader option. ✨
• Every command executed within fakechroot needs to be linked to the same version of the dynamic linker from real environment. If the libraries in chroot are not compatible, try to use the --use-system-libs option. 🫶
• You can provide symlinks to the outside. The symlink have to be created before chroot is called. It can be useful for accessing the real /proc and /dev directory. You can also set the FAKECHROOT_EXCLUDE_PATH environment variable:

$ export FAKECHROOT_EXCLUDE_PATH=/tmp:/proc:/dev:/sys:/var/run:/home

• Statically linked binaries doesn't work, especially ldconfig(8), so you have to wrap this command with dummy version and set the proper FAKECHROOT_CMD_SUBST environment variable. 💀
• ldd(1) also doesn't work. You have to use alias ldd='LD_TRACE_LOADED_OBJECTS=1' or to use a wrapper instead. The wrapper is installed as ldd.fakechroot and can be used with FAKECHROOT_CMD_SUBST environment variable. 🙈
• The full screen applications hangs up if /dev/tty file is not a real device. Link /dev/tty file or whole /dev directory to the real one or remove it from fake chroot environment with FAKECHROOT_EXCLUDE_PATH variable. 😭
• lckpwdf(3) and ulckpwdf(3) are ignored so passwd(1) command should work. ✨
• Your real uid should exist in /etc/passwd. Create it with adduser --uid realuid realuser inside fake chroot environment. 👑
• debuild(1) cleans environment. Use --preserve-env option to prevent this behavior. 🧚
• rpmbuild(8) uses own glob(3) implementation which breaks fakechroot so buildroot directory have to be the same inside and outside fakechroot. 🍓

---

💜 SEE ALSO 💜

• fakeroot(1)
• debuild(1)
• debootstrap(8)
• rinse(8)
• http://fakechroot.alioth.debian.org/

---

🦋 BUGS 🦋

If you find the bug or want to implement new features, please report it at <https://github.com/fakechroot/fakechroot/issues> — the devs wanna know, fr fr. 🫶

---

👑 AUTHORS 👑

• Copyright (c) 2003-2017, 2019 Piotr Roszatycki <dexter@debian.org>
• Copyright (c) 2007 Mark Eichin <eichin@metacarta.com>
• Copyright (c) 2006, 2007 Alexander Shishkin <virtuoso@slind.org>
• Copyright (c) 2006, 2007 Lionel Tricon <lionel.tricon@free.fr>

---

🌈 COPYING 🌈

fakechroot is distributed under the GNU Lesser General Public License (LGPL 2.1 or greater). Slay, open source. 💖

---

okay bye bestie! This page is fakechroot, dated 16 Mar 2019, and it's FAKECHROOT(1) — periodt. 💅