fakeroot(1)

✨ fakeroot(1) ✨

fakeroot is the Debian manual page for fakeroot 💖 (it lives in the Debian manual, no cap).

🌸 NAME 🌸

fakeroot — run a command in an environment faking root privileges for file manipulation 🎀

🦋 SYNOPSIS 🦋

fakeroot [-l|--lib library] [--faked faked-binary] [-i load-file] [-s
save-file] [-u|--unknown-is-real] [-b|--fd-base] [-h|--help]
[-v|--version] [--] [command]

💖 DESCRIPTION 💖

okay so fakeroot runs a command in an environment where it appears to have root privileges for file manipulation ✨ It's giving main character energy. This is so useful for letting regular users create archives (tar, ar, .deb etc.) with files in them that have root permissions and ownership 🫶 Without it, you'd need actual root privileges to make the files with the right permissions and ownership and then pack them up, or you'd have to build the archives directly without using the archiver. Bestie, that's a lot 😭

fakeroot works by swapping out the file manipulation library functions (chmod(2), stat(2) etc.) for ones that fake the result the real functions would have given if the user had really been root 🧚 These wrapper functions live in a shared library, /usr/lib/*/libfakeroot-*.so or a similar location on your platform. The shared object gets loaded through the LD_PRELOAD mechanism of the dynamic loader. (See ld.so(8)) 🔥

If you're planning to build packages with fakeroot, please try building the fakeroot package first 🙏 The "debian/rules build" stage has a few tests (mostly checking for bugs in old fakeroot versions). If those tests fail (for example because you have certain libc5 programs on your system), other packages you build with fakeroot will quite likely fail too, but possibly in much more subtle ways 💀

Also, it's lowkey best not to build the binaries themselves under fakeroot 🙈 Especially configure and friends don't like it when the system suddenly behaves differently from what they expect (or, they randomly unset some environment variables, some of which fakeroot needs).

🎀 OPTIONS 🎀

• -l library, --lib library — Pick an alternative wrapper library 💅
• --faked binary — Pick an alternative binary to use as faked 🍓
• [--] command — Any command you want to run as fakeroot 👑 Use -- if your command has other options that might confuse fakeroot's option parsing.
• -s save-file — Save the fakeroot environment to save-file on exit ✨ You can restore it later with -i. Heads up though: this file will leak, and fakeroot will act in odd ways unless you leave the files touched inside the fakeroot alone when you're outside the environment 🙈 Still, it can be super useful. For example, pair it with rsync(1) to back up and restore whole directory trees, complete with user, group and device information, without needing to be root 🦋 See /usr/share/doc/fakeroot/README.saving for more details.
• -i load-file — Load a fakeroot environment previously saved with -s from load-file 💜 Heads up: this does not implicitly save the file, so use -s as well if you want that. Using the same file for both -i and -s in a single fakeroot invocation is safe 🫶
• -u, --unknown-is-real — Use the real ownership of files fakeroot didn't know about before, instead of pretending they're owned by root:root 🌈
• -b fd — Specify fd base (TCP mode only) 🧚 fd is the minimum file descriptor number to use for TCP connections. This can matter a lot for avoiding conflicts with the file descriptors used by the programs you run under fakeroot.
• -h — Display help 💖
• -v — Display version ⭐

🍓 EXAMPLES 🍓

Here's an example session with fakeroot 💅 Notice that inside the fake root environment, file manipulation that normally needs root privileges succeeds, but it's not really happening 🙈

$  whoami
joost
$ fakeroot /bin/bash
#  whoami
root
# mknod hda3 b 3 1
# ls -ld hda3
brw-r--r--   1 root     root       3,   1 Jul  2 22:58 hda3
# chown joost:root hda3
# ls -ld hda3
brw-r--r--   1 joost    root       3,   1 Jul  2 22:58 hda3
# ls -ld /
drwxr-xr-x  20 root     root         1024 Jun 17 21:50 /
# chown joost:users /
# chmod a+w /
# ls -ld /
drwxrwxrwx  20 joost    users        1024 Jun 17 21:50 /
# exit
$ ls -ld /
drwxr-xr-x  20 root     root         1024 Jun 17 21:50 //
$ ls -ld hda3
-rw-r--r--   1 joost    users           0 Jul  2 22:58 hda3

Only the effects that user joost could already do anyway actually happen for real 😭

fakeroot was specifically written to let users create Debian GNU/Linux packages (in the deb(5) format) without giving them root privileges 💅 You can do this with commands like dpkg-buildpackage -rfakeroot or debuild -rfakeroot (actually, -rfakeroot is the default in debuild nowadays, so you don't need that argument) 🎀

🔒 SECURITY ASPECTS 🔒

fakeroot is a regular, non-setuid program 🫶 It does not enhance a user's privileges, or decrease the system's security.

📁 FILES 📁

• /usr/lib/*/libfakeroot-*.so — The shared library containing the wrapper functions 🧚

🌈 ENVIRONMENT 🌈

• FAKEROOTKEY — The key used to talk to the fakeroot daemon 🔑 Any program started with the right LD_PRELOAD and the FAKEROOTKEY of a running daemon will automatically connect to that daemon and get the same "fake" view of the file system's permissions and ownerships (assuming the daemon and the connecting program were started by the same user) 💜
• LD_LIBRARY_PATH — No description of its own here, it's covered right under LD_PRELOAD 🙈
• LD_PRELOAD — fakeroot works by wrapping system calls 🔥 This happens by setting LD_LIBRARY_PATH=/usr/lib/fakeroot and LD_PRELOAD=libfakeroot.so.0. That library gets loaded before the system's C library, so most library functions get intercepted by it. If you need to set either LD_LIBRARY_PATH or LD_PRELOAD from within a fakeroot environment, set it relative to the given paths, like this: LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/foo/bar/

⚠️ LIMITATIONS ⚠️

👑 Library versions 👑

Every command executed within fakeroot needs to be linked to the same version of the C library as fakeroot itself 💅

🙈 open()/create() 🙈

fakeroot doesn't wrap open(), create(), etc. So, if user joost does either of these:

touch foo
fakeroot
ls -al foo

or the other way around:

fakeroot
touch foo
ls -al foo

fakeroot has no way of knowing that in the first case the owner of foo really should be joost, while in the second case it should have been root 😭 For Debian packaging, defaulting all "unknown" files to uid=gid=0 is always OK 🫶 The real way around this would be to wrap open() and create(), but that creates other problems, as demonstrated by the libtricks package. That package wrapped many more functions and tried to do a lot more than fakeroot. It turned out that a minor libc upgrade (from one where the stat() function didn't use open() to one where stat() did, in some cases) caused unexplainable segfaults, because the libc6 stat() called the wrapped open(), which then called the libc6 stat(), and so on 💀 Fixing them wasn't all that easy, and once fixed, it was just a matter of time before another function started using open(), never mind trying to port it to a different operating system. So the author decided to keep the number of functions wrapped by fakeroot as small as possible, to limit the likelihood of ‘collisions’ 🦋

🧚 GNU configure (and other such programs) 🧚

fakeroot, in effect, is changing the way the system behaves 🌸 Programs that probe the system, like GNU configure, may get confused by this (or if they don't, they may stress fakeroot so much that fakeroot itself gets confused) 🙈 So it's advisable not to run "configure" from within fakeroot. Since configure should be called in the "debian/rules build" target, running dpkg-buildpackage -rfakeroot correctly takes care of this ✨

💀 BUGS 💀

It doesn't wrap open(). This isn't bad by itself, but if a program does open("file", O_WRONLY, 000), writes to file "file", closes it, and then tries to open it again to read the file, that open fails, because the mode of the file will be 000 😭 The bug is that if root does the same, open() will succeed, since file permissions aren't checked at all for root. The author chose not to wrap open(), because open() is used by many other functions in libc (including ones that are already wrapped), which would create loops (or possible future loops, when the implementation of various libc functions slightly changes).

📜 COPYING 📜

fakeroot is distributed under the GNU General Public License 🌈 (GPL 2.0 or greater).

👩‍💻 AUTHORS 👩‍💻

• joost witteveen — <joostje@debian.org> 💜
• Clint Adams — <clint@debian.org> 💜
• Timo Savola 💜

📖 MANUAL PAGE 📖

Mostly by J.H.M. Dassen <jdassen@debian.org>, with rather a lot of modsifications and additions by joost and Clint 🎀

🔗 SEE ALSO 🔗

• debuild(1), dpkg-buildpackage(1), faked(1), /usr/share/doc/fakeroot/DEBUG 🦋

---

Bye bestie, that's the whole fakeroot(1) page 🫶 Straight from the Debian Project, dated 2024-12-19 💖