Ubuntu Manpage: PRoot - chroot, mount --bind, and binfmt

NAME

       PRoot - chroot, mount --bind, and binfmt_misc without privilege/setup

SYNOPSIS

       proot [option] ... [command]

DESCRIPTION

PRoot is a user-space implementation of chroot, mount --bind, and binfmt_misc. This means that users
don't need any privileges or setup to do things like using an arbitrary directory as the new root
filesystem, making files accessible somewhere else in the filesystem hierarchy, or executing programs
built for another CPU architecture transparently through QEMU user-mode. Also, developers can add their
own features or use PRoot as a Linux process instrumentation engine thanks to its extension mechanism.
Technically PRoot relies on ptrace, an unprivileged system-call available in every Linux kernel.

The new root file-system, a.k.a guest rootfs, typically contains a Linux distribution. By default PRoot
confines the execution of programs to the guest rootfs only, however users can use the built-in
mount/bind mechanism to access files and directories from the actual root file-system, a.k.a host rootfs,
just as if they were part of the guest rootfs.

When the guest Linux distribution is made for a CPU architecture incompatible with the host one, PRoot
uses the CPU emulator QEMU user-mode to execute transparently guest programs. It's a convenient way to
develop, to build, and to validate any guest Linux packages seamlessly on users' computer, just as if
they were in a native guest environment. That way all of the cross-compilation issues are avoided.

PRoot can also mix the execution of host programs and the execution of guest programs emulated by QEMU
user-mode. This is useful to use host equivalents of programs that are missing from the guest rootfs and
to speed up build-time by using cross-compilation tools or CPU-independent programs, like interpreters.

It is worth noting that the guest kernel is never involved, regardless of whether QEMU user-mode is used
or not. Technically, when guest programs perform access to system resources, PRoot translates their
requests before sending them to the host kernel. This means that guest programs can use host resources
(devices, network, ...) just as if they were "normal" host programs.

OPTIONS

The command-line interface is composed of two parts: first PRoot's options (optional), then the command
to launch (/bin/sh if not specified). This section describes the options supported by PRoot, that is,
the first part of its command-line interface.

Regular options
-r path, --rootfs=path
Use path as the new guest root file-system, default is /.

The specified path typically contains a Linux distribution where all new programs will be
confined. The default rootfs is / when none is specified, this makes sense when the bind
mechanism is used to relocate host files and directories, see the -b option and the Examples
section for details.

-b path, --bind=path, -m path, --mount=path
Make the content of path accessible in the guest rootfs.

This option makes any file or directory of the host rootfs accessible in the confined environment
just as if it were part of the guest rootfs. By default the host path is bound to the same path
in the guest rootfs but users can specify any other location with the syntax: -b
*host_path*:*guest_location*. If the guest location is a symbolic link, it is dereferenced to
ensure the new content is accessible through all the symbolic links that point to the overlaid
content. In most cases this default behavior shouldn't be a problem, although it is possible to
explicitly not dereference the guest location by appending it the ! character: -b
*host_path*:*guest_location!*.

-q command, --qemu=command
Execute guest programs through QEMU as specified by command.

Each time a guest program is going to be executed, PRoot inserts the QEMU user-mode command in
front of the initial request. That way, guest programs actually run on a virtual guest CPU
emulated by QEMU user-mode. The native execution of host programs is still effective and the
whole host rootfs is bound to /host-rootfs in the guest environment.

This option is automatically enabled by the -Q option.

-w path, --pwd=path, --cwd=path
Set the initial working directory to path.

Some programs expect to be launched from a given directory but do not perform any chdir by
themselves. This option avoids the need for running a shell and then entering the directory
manually.

-v value, --verbose=value
Set the level of debug information to value.

The higher the integer value is, the more detailled debug information is printed to the standard
error stream. A negative value makes PRoot quiet except on fatal errors.

-V, --version, --about
Print version, copyright, license and contact, then exit.

-h, --help, --usage
Print the version and the command-line usage, then exit.

Extension options
The following options enable built-in extensions. Technically developers can add their own features to
PRoot or use it as a Linux process instrumentation engine thanks to its extension mechanism, see the
sources for further details.

-k string, --kernel-release=string
Set the kernel release and compatibility level to string.

If a program is run on a kernel older than the one expected by its GNU C library, the following
error is reported: "FATAL: kernel too old". To be able to run such programs, PRoot can emulate
some of the syscalls that are available in the kernel release specified by string but that are
missing in the current kernel.

-0, --root-id
Force some syscalls to behave as if executed by "root".

Some programs will refuse to work if they are not run with "root" privileges, even if there is no
technical reason for that. This is typically the case with package managers. This option allows
users to bypass this kind of limitation by faking the user/group identity, and by faking the
success of some operations like changing the ownership of files, changing the root directory to /,
... Note that this option is quite limited compared to fakeroot.

Alias options
The following options are aliases for handy sets of options.

-B, -M Alias: -b for each path of a recommended list

There are a couple of bindings that are needed for most guest programs to behave correctly
regarding the configuration part of the host computer which is not specific to the host Linux
distribution, such as: user/group information, network setup, run-time information, users' files,
... This highly recommended option enables the following bindings:

• /etc/host.conf

• /etc/hosts

• /etc/hosts.equiv

• /etc/mtab

• /etc/netgroup

• /etc/networks

• /etc/passwd

• /etc/group

• /etc/nsswitch.conf

• /etc/resolv.conf

• /etc/localtime

• /dev/

• /sys/

• /proc/

• /tmp/

• $HOME

-Q command
Alias: -q *command* -B

This option is highly recommended when using QEMU user-mode; it enables all the recommended
bindings.

EXIT STATUS

       If  an  internal error occurs, proot returns a non-zero exit status, otherwise it returns the exit status
       of the last terminated program. When an error has occurred, the only way to know if  it  comes  from  the
       last terminated program or from proot itself is to have a look at the error message.

FILES

       PRoot reads links in /proc/<pid>/fd/ to support openat(2)-like syscalls made by the guest programs.

EXAMPLES

       In  the  following  examples  the  directories /mnt/slackware-8.0 and /mnt/armslack-12.2/ contain a Linux
       distribution respectively made for x86 CPUs and ARM CPUs.

   chroot equivalent
       To execute a command inside a given Linux distribution, just give proot the  path  to  the  guest  rootfs
       followed  by  the  desired command.  The example below executes the program cat to print the content of a
       file:

          proot -r /mnt/slackware-8.0/ cat /etc/motd

          Welcome to Slackware Linux 8.0

       The default command is /bin/sh when none is specified. Thus the shortest way to  confine  an  interactive
       shell and all its sub-programs is:

          proot -r /mnt/slackware-8.0/

          $ cat /etc/motd
          Welcome to Slackware Linux 8.0

   mount --bind equivalent
       The bind mechanism permits to relocate files and directories.  This is typically useful to cheat programs
       that perform access to hard-coded locations, like some installation scripts:

          proot -b /tmp/alternate_opt:/opt

          $ cd to/sources
          $ make install
          [...]
          install -m 755 prog "/opt/bin"
          [...] # prog is installed in "/tmp/alternate_opt/bin" actually

       As shown in this example, it is possible to bind over files not even owned by the user.  This can be used
       to overlay system configuration files, for instance the DNS setting:

          ls -l /etc/hosts
          -rw-r--r-- 1 root root 675 Mar  4  2011 /etc/hosts

          proot -b ~/alternate_hosts:/etc/hosts

          $ echo '1.2.3.4 google.com' > /etc/hosts
          $ resolveip google.com
          IP address of google.com is 1.2.3.4
          $ echo '5.6.7.8 google.com' > /etc/hosts
          $ resolveip google.com
          IP address of google.com is 5.6.7.8

       Another  example:  on most Linux distributions /bin/sh is a symbolic link to /bin/bash, whereas it points
       to /bin/dash on Debian and Ubuntu.  As a consequence a #!/bin/sh script tested with Bash might  not  work
       with Dash.  In this case, the binding mechanism of PRoot can be used to set non-disruptively /bin/bash as
       the default /bin/sh on these two Linux distributions:

          proot -b /bin/bash:/bin/sh [...]

       Because  /bin/sh  is  initially  a symbolic link to /bin/dash, the content of /bin/bash is actually bound
       over this latter:

          proot -b /bin/bash:/bin/sh

          $ md5sum /bin/sh
          089ed56cd74e63f461bef0fdfc2d159a  /bin/sh
          $ md5sum /bin/bash
          089ed56cd74e63f461bef0fdfc2d159a  /bin/bash
          $ md5sum /bin/dash
          089ed56cd74e63f461bef0fdfc2d159a  /bin/dash

       In most cases this shouldn't be a problem, but it is still  possible  to  strictly  bind  /bin/bash  over
       /bin/sh -- without dereferencing it -- by specifying the ! character at the end:

          proot -b '/bin/bash:/bin/sh!'

          $ md5sum /bin/sh
          089ed56cd74e63f461bef0fdfc2d159a  /bin/sh
          $ md5sum /bin/bash
          089ed56cd74e63f461bef0fdfc2d159a  /bin/bash
          $ md5sum /bin/dash
          c229085928dc19e8d9bd29fe88268504  /bin/dash

   chroot + mount --bind equivalent
       The  two  features above can be combined to make any file from the host rootfs accessible in the confined
       environment just as if it were initially part of the guest rootfs.   It  is  sometimes  required  to  run
       programs that rely on some specific files:

          proot -r /mnt/slackware-8.0/

          $ ps -o tty,command
          Error, do this: mount -t proc none /proc

       works better with:

          proot -r /mnt/slackware-8.0/ -b /proc

          $ ps -o tty,command
          TT       COMMAND
          ?        -bash
          ?        proot -b /proc /mnt/slackware-8.0/
          ?        /lib/ld-linux.so.2 /bin/sh
          ?        /lib/ld-linux.so.2 /usr/bin/ps -o tty,command

       Actually  there's  a  bunch  of  such  specific  files,  that's  why PRoot provides the option -B to bind
       automatically a pre-defined list of recommended paths:

          proot -r /mnt/slackware-8.0/ -B

          $ ps -o tty,command
          TT       COMMAND
          pts/6    -bash
          pts/6    proot -B /mnt/slackware-8.0/
          pts/6    /lib/ld-linux.so.2 /bin/sh
          pts/6    /lib/ld-linux.so.2 /usr/bin/ps -o tty,command

   chroot + mount --bind + binfmt_misc equivalent
       PRoot uses QEMU user-mode to execute programs built for a CPU architecture  incompatible  with  the  host
       one.   From  users'  point-of-view,  guest programs handled by QEMU user-mode are executed transparently,
       that is, just like host programs.  To enable this feature users just have to specify  which  instance  of
       QEMU user-mode they want to use with the option -q or -Q (this latter implies -B):

          proot -r /mnt/armslack-12.2/ -Q qemu-arm

          $ cat /etc/motd
          Welcome to ARMedSlack Linux 12.2

       The  parameter of the -q/-Q option is actually a whole QEMU user-mode command, for instance to enable its
       GDB server on port 1234:

          proot -r /mnt/armslack-12.2/ -Q "qemu-arm -g 1234" emacs

       PRoot allows to mix transparently the emulated execution of guest programs and the  native  execution  of
       host  programs  in the same file-system namespace.  It's typically useful to extend the list of available
       programs and to speed up build-time significantly.  This mixed-execution feature is  enabled  by  default
       when using QEMU user-mode, and the content of the host rootfs is made accessible through /host-rootfs:

          proot -r /mnt/armslack-12.2/ -Q qemu-arm

          $ file /bin/echo
          [...] ELF 32-bit LSB executable, ARM [...]
          $ /bin/echo 'Hello world!'
          Hello world!

          $ file /host-rootfs/bin/echo
          [...] ELF 64-bit LSB executable, x86-64 [...]
          $ /host-rootfs/bin/echo 'Hello mixed world!'
          Hello mixed world!

       Since  both  host  and  guest programs use the guest rootfs as /, users may want to deactivate explicitly
       cross-filesystem support found in most GNU cross-compilation tools.  For example with GCC  configured  to
       cross-compile to the ARM target:

          proot -r /mnt/armslack-12.2/ -Q qemu-arm

          $ export CC=/host-rootfs/opt/cross-tools/arm-linux/bin/gcc
          $ export CFLAGS="--sysroot=/"   # could be optional indeed
          $ ./configure; make

       As  with  regular  files,  a host instance of a program can be bound over its guest instance.  Here is an
       example where the guest binary of make is overlaid by the host one:

          proot -r /mnt/armslack-12.2/ -Q qemu-arm -b /usr/bin/make

          $ which make
          /usr/bin/make
          $ make --version # overlaid
          GNU Make 3.82
          Built for x86_64-slackware-linux-gnu

       It's worth mentioning that even when mixing the native  execution  of  host  programs  and  the  emulated
       execution  of  guest  programs,  they still believe they are running in a native guest environment.  As a
       demonstration, here is a partial output of a typical ./configure script:

          checking whether the C compiler is a cross-compiler... no

DOWNLOADS

   PRoot
       The latest  release  of  PRoot  is  packaged  on  http://packages.proot.me  and  sources  are  hosted  on
       http://github.proot.me.   Also,  highly compatible binaries are available on http://static.proot.me for a
       couple of architectures.

   Rootfs
       Here follows a couple of URLs where some rootfs archives can be freely downloaded.  Note that the  errors
       reported  by  tar  when  extracting  these archives can be safely ignored.  Obviously these files are not
       required when PRoot is used as a mount --bind equivalent only.

       • Slackware, Arch, Fedora for ARM:

         • ftp://ftp.armedslack.org/slackwarearm/slackwarearm-devtools/minirootfs/roots/

         • http://archlinuxarm.org/developers/downloads

         • http://ftp.linux.org.uk/pub/linux/arm/fedora/rootfs/

       • CentOS, Debian, Fedora,  Scientific,  Suse,  Ubuntu,  ALT,  Arch,  CERN,  Gentoo,  OpenSuse,  Openwall,
         Slackware, SLES, and etc. for x86 and x86_64 CPUs:

         • http://download.openvz.org/template/precreated/

         • http://cdimage.ubuntu.com/ubuntu-core/releases/

       • Gentoo for a lot of architectures:

         • http://distfiles.gentoo.org/releases/

       Technically  such  rootfs  archive  can be created by running the following command on the expected Linux
       distribution:

          tar --one-file-system --create --gzip --file my_rootfs.tar.gz /

   QEMU user-mode
       QEMU user-mode is required only if the guest rootfs was made for a CPU architecture incompatible with the
       host one, for instance when using a ARM rootfs on a x86_64  computer.   This  package  can  be  installed
       either  from  http://qemu.proot.me or from the host package manager under the name of "qemu-user" on most
       Linux distro.  In case one would like to build  QEMU  user-mode  from  sources,  the  --enable-linux-user
       option has to be specified to the ./configure script.

COLOPHON

       Visit   http://proot.me   for   help,   bug   reports,  suggestions,  patchs,  ...   Copyright  (C)  2013
       STMicroelectronics, licensed under GPL v2 or later.

3.0.2                                              2013-06-14                                           PROOT(1)