iamroot

iamroot(7) emulates privileged syscalls such as chroot(2) for unprivileged processes in userspace.

TL;DR;

iamroot(7) provides a self-contained and an all-in-one alternative to both fakeroot(1) and fakechroot(1).

The project targets the Linux userlands glibc and musl. However, it works on FreeBSD (13.1), OpenBSD (7.2 and 7.3) and NetBSD (9.3) even if its usage is limited by some statically linked binaries (such as pkg-static, chroot...) and by none-executable dynamic loaders.

The project compiles on Intel x86 and ARM 64-bit, and it runs on Arch Linux, Debian, Alpine Linux, FreeBSD (13.1), OpenBSD (7.2 and 7.3) and NetBSD (9.3).

The Miscellaneous Binary Format on Linux allows to chroot(2) in a rootfs directory using a different architecture thanks to emulators (such as the QEMU user-mode emulation static binaries). The architectures x86_64, i386, aarch64, armhf, arm, and riscv64 are supported.

HOW IT WORKS

It consists of an ELF shim library which is preloaded using the environment variable LD_PRELOAD. It intercepts the calls to the libc functions with a filename or pathname in parameter (open(2), fopen(3), stat(2), readlink(2), chown(2), chdir(2), chroot(2)...).

The syscall chroot(2) changes a small ingredient in the pathname resolution process; it is visible via each process's symlink /proc/self/root. The environment variable IAMROOT_ROOT implements that behaviour in the world of iamroot(7). Basically, it replaces the leading / of an absolute pathname with the alternate root.

For the curious, the magic operates in files chroot.c for entering in chroot, in chdir.c and fchdir.c for exiting "chroot jail", in path_resolution.c for resolving pathnames, and in execve.c and dso.c for exec'ing executable files from chroot.

Of course, iamroot(7) cannot substitute itself to the superuser permissions, and commands will end with EACCESS or EPERM as of reading or writing files in /proc, /sys, /dev or /run, to name but a few.

HELPER SCRIPTS

iamroot(7) is configurable via environment variables to overcome specific situations of the whole variety of operation-systems (i.e. GNU/Linux, musl, *BSD...).

It comes with two shell scripts ido(1) and ish(1) to make the configuration easy via specific command line options. They are frontends to standard CLIs to either open an interactive shell or switch user. ish(1) provides a shell like sh(1), and ido(1) switches user like sudo(8).

BUILD ROOTFS

iamroot(7) aims to create any Linux rootfs using the package manager of the distribution (or its bootstrap script).

The table below lists the distributions and its tool that work with.

Tool	Distributions
pacstrap(8)	Arch Linux, Arch Linux ARM, Arch Linux 32, Manjaro
alpine-make-rootfs	Alpine Linux
dnf(8)	Fedora
zypper(8)	openSUSE
debootstrap(8)	Debian, Ubuntu, Devuan*
xbps-install(1)	Void Linux

*: Works with hacks.

FAKECHROOT

fakechroot(1) does not run well for creating rootfs. It has to be hacked to address the rootfs-creation related issues (i.e. fixing entering-exiting chroot and absolute symlink resolution in short).

DOCUMENTATION

Build the documentation using make(1)

$ make doc
asciidoctor -b manpage -o ido.1 ido.1.adoc
gzip -c ido.1 >ido.1.gz
asciidoctor -b manpage -o ish.1 ish.1.adoc
gzip -c ish.1 >ish.1.gz
asciidoctor -b manpage -o iamroot.7 iamroot.7.adoc
gzip -c iamroot.7 >iamroot.7.gz
rm iamroot.7 ish.1 ido.1

BUILD

Run the following command to build libiamroot.so

For your home directory (i.e. your user only)

$ make libiamroot.so PREFIX=$HOME/.local

Or, for your system (i.e. every users)

$ make libiamroot.so

INSTALL

Run the following command to install iamroot(7) and ish(1)

To your home directory (i.e. your user only)

$ make user-install

Or, to your system (i.e. every users)

$ sudo make install

The traditional variables DESTDIR and PREFIX can be overridden

$ sudo make install PREFIX=/opt/iamroot

$ make install DESTDIR=$PWD/pkg PREFIX=/usr

BUGS

Report bugs at https://github.com/gportay/iamroot/issues

AUTHOR

Written by Gaël PORTAY gael.portay@gmail.com

COPYRIGHT

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 2.1 of the License, or (at your option) any later version.

gportay / iamroot