.\" Man page generated from reStructuredText. . .TH PROOT 1 "2014-12-12" "5.1.0" "" .SH NAME PRoot \- chroot, mount \-\-bind, and binfmt_misc without privilege/setup . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH SYNOPSIS .sp \fBproot\fP [\fIoption\fP] ... [\fIcommand\fP] .SH DESCRIPTION .sp PRoot is a user\-space implementation of \fBchroot\fP, \fBmount \-\-bind\fP, and \fBbinfmt_misc\fP\&. This means that users don\(aqt 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 use PRoot as a generic Linux process instrumentation engine thanks to its extension mechanism, see \fI\%CARE\fP for an example. Technically PRoot relies on \fBptrace\fP, an unprivileged system\-call available in every Linux kernel. .sp The new root file\-system, a.k.a \fIguest rootfs\fP, 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 \fImount/bind\fP mechanism to access files and directories from the actual root file\-system, a.k.a \fIhost rootfs\fP, just as if they were part of the guest rootfs. .sp 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\(aqs a convenient way to develop, to build, and to validate any guest Linux packages seamlessly on users\(aq computer, just as if they were in a \fInative\fP guest environment. That way all of the cross\-compilation issues are avoided. .sp PRoot can also \fImix\fP 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. .sp 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. .SH OPTIONS .sp The command\-line interface is composed of two parts: first PRoot\(aqs options (optional), then the command to launch (\fB/bin/sh\fP if not specified). This section describes the options supported by PRoot, that is, the first part of its command\-line interface. .SS Regular options .INDENT 0.0 .TP .BI \-r \ path\fP,\fB \ \-\-rootfs\fB= path Use \fIpath\fP as the new guest root file\-system, default is \fB/\fP\&. .sp The specified \fIpath\fP typically contains a Linux distribution where all new programs will be confined. The default rootfs is \fB/\fP when none is specified, this makes sense when the bind mechanism is used to relocate host files and directories, see the \fB\-b\fP option and the \fBExamples\fP section for details. .sp It is recommended to use the \fB\-R\fP or \fB\-S\fP options instead. .TP .BI \-b \ path\fP,\fB \ \-\-bind\fB= path\fP,\fB \ \-m \ path\fP,\fB \ \-\-mount\fB= path Make the content of \fIpath\fP accessible in the guest rootfs. .sp 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: \fB\-b *host_path*:*guest_location*\fP\&. 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\(aqt be a problem, although it is possible to explicitly not dereference the guest location by appending it the \fB!\fP character: \fB\-b *host_path*:*guest_location!*\fP\&. .TP .BI \-q \ command\fP,\fB \ \-\-qemu\fB= command Execute guest programs through QEMU as specified by \fIcommand\fP\&. .sp Each time a guest program is going to be executed, PRoot inserts the QEMU user\-mode \fIcommand\fP 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 \fB/host\-rootfs\fP in the guest environment. .TP .BI \-w \ path\fP,\fB \ \-\-pwd\fB= path\fP,\fB \ \-\-cwd\fB= path Set the initial working directory to \fIpath\fP\&. .sp Some programs expect to be launched from a given directory but do not perform any \fBchdir\fP by themselves. This option avoids the need for running a shell and then entering the directory manually. .TP .BI \-v \ value\fP,\fB \ \-\-verbose\fB= value Set the level of debug information to \fIvalue\fP\&. .sp The higher the integer \fIvalue\fP is, the more detailed debug information is printed to the standard error stream. A negative \fIvalue\fP makes PRoot quiet except on fatal errors. .TP .B \-V\fP,\fB \-\-version\fP,\fB \-\-about Print version, copyright, license and contact, then exit. .TP .B \-h\fP,\fB \-\-help\fP,\fB \-\-usage Print the version and the command\-line usage, then exit. .UNINDENT .SS Extension options .sp 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. .INDENT 0.0 .TP .BI \-k \ string\fP,\fB \ \-\-kernel\-release\fB= string Make current kernel appear as kernel release \fIstring\fP\&. .sp 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 features that are available in the kernel release specified by \fIstring\fP but that are missing in the current kernel. .TP .B \-0\fP,\fB \-\-root\-id Make current user appear as "root" and fake its privileges. .sp 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 \fB/\fP, ... Note that this option is quite limited compared to \fBfakeroot\fP\&. .TP .BI \-i \ string\fP,\fB \ \-\-change\-id\fB= string Make current user and group appear as \fIstring\fP "uid:gid". .sp This option makes the current user and group appear as \fIuid\fP and \fIgid\fP\&. Likewise, files actually owned by the current user and group appear as if they were owned by \fIuid\fP and \fIgid\fP instead. Note that the \fB\-0\fP option is the same as \fB\-i 0:0\fP\&. .UNINDENT .SS Alias options .sp The following options are aliases for handy sets of options. .INDENT 0.0 .TP .BI \-R \ path Alias: \fB\-r *path*\fP + a couple of recommended \fB\-b\fP\&. .sp Programs isolated in \fIpath\fP, a guest rootfs, might still need to access information about the host system, as it is illustrated in the \fBExamples\fP section of the manual. These host information are typically: user/group definition, network setup, run\-time information, users\(aq files, ... On all Linux distributions, they all lie in a couple of host files and directories that are automatically bound by this option: .INDENT 7.0 .IP \(bu 2 /etc/host.conf .IP \(bu 2 /etc/hosts .IP \(bu 2 /etc/hosts.equiv .IP \(bu 2 /etc/mtab .IP \(bu 2 /etc/netgroup .IP \(bu 2 /etc/networks .IP \(bu 2 /etc/passwd .IP \(bu 2 /etc/group .IP \(bu 2 /etc/nsswitch.conf .IP \(bu 2 /etc/resolv.conf .IP \(bu 2 /etc/localtime .IP \(bu 2 /dev/ .IP \(bu 2 /sys/ .IP \(bu 2 /proc/ .IP \(bu 2 /tmp/ .IP \(bu 2 /run/ .IP \(bu 2 /var/run/dbus/system_bus_socket .IP \(bu 2 $HOME .IP \(bu 2 \fIpath\fP .UNINDENT .TP .BI \-S \ path Alias: \fB\-0 \-r *path*\fP + a couple of recommended \fB\-b\fP\&. .sp This option is useful to safely create and install packages into the guest rootfs. It is similar to the \fB\-R\fP option expect it enables the \fB\-0\fP option and binds only the following minimal set of paths to avoid unexpected changes on host files: .INDENT 7.0 .IP \(bu 2 /etc/host.conf .IP \(bu 2 /etc/hosts .IP \(bu 2 /etc/nsswitch.conf .IP \(bu 2 /etc/resolv.conf .IP \(bu 2 /dev/ .IP \(bu 2 /sys/ .IP \(bu 2 /proc/ .IP \(bu 2 /tmp/ .IP \(bu 2 /run/shm .IP \(bu 2 $HOME .IP \(bu 2 \fIpath\fP .UNINDENT .UNINDENT .SH EXIT STATUS .sp If an internal error occurs, \fBproot\fP 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 \fBproot\fP itself is to have a look at the error message. .SH FILES .sp PRoot reads links in \fB/proc//fd/\fP to support \fIopenat(2)\fP\-like syscalls made by the guest programs. .SH EXAMPLES .sp In the following examples the directories \fB/mnt/slackware\-8.0\fP and \fB/mnt/armslack\-12.2/\fP contain a Linux distribution respectively made for x86 CPUs and ARM CPUs. .SS \fBchroot\fP equivalent .sp To execute a command inside a given Linux distribution, just give \fBproot\fP the path to the guest rootfs followed by the desired command. The example below executes the program \fBcat\fP to print the content of a file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proot \-r /mnt/slackware\-8.0/ cat /etc/motd Welcome to Slackware Linux 8.0 .ft P .fi .UNINDENT .UNINDENT .sp The default command is \fB/bin/sh\fP when none is specified. Thus the shortest way to confine an interactive shell and all its sub\-programs is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proot \-r /mnt/slackware\-8.0/ $ cat /etc/motd Welcome to Slackware Linux 8.0 .ft P .fi .UNINDENT .UNINDENT .SS \fBmount \-\-bind\fP equivalent .sp The bind mechanism enables one to relocate files and directories. This is typically useful to trick programs that perform access to hard\-coded locations, like some installation scripts: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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 .ft P .fi .UNINDENT .UNINDENT .sp As shown in this example, it is possible to bind over files not even owned by the user. This can be used to \fIoverlay\fP system configuration files, for instance the DNS setting: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ls \-l /etc/hosts \-rw\-r\-\-r\-\- 1 root root 675 Mar 4 2011 /etc/hosts .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proot \-b ~/alternate_hosts:/etc/hosts $ echo \(aq1.2.3.4 google.com\(aq > /etc/hosts $ resolveip google.com IP address of google.com is 1.2.3.4 $ echo \(aq5.6.7.8 google.com\(aq > /etc/hosts $ resolveip google.com IP address of google.com is 5.6.7.8 .ft P .fi .UNINDENT .UNINDENT .sp Another example: on most Linux distributions \fB/bin/sh\fP is a symbolic link to \fB/bin/bash\fP, whereas it points to \fB/bin/dash\fP on Debian and Ubuntu. As a consequence a \fB#!/bin/sh\fP script tested with Bash might not work with Dash. In this case, the binding mechanism of PRoot can be used to set non\-disruptively \fB/bin/bash\fP as the default \fB/bin/sh\fP on these two Linux distributions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proot \-b /bin/bash:/bin/sh [...] .ft P .fi .UNINDENT .UNINDENT .sp Because \fB/bin/sh\fP is initially a symbolic link to \fB/bin/dash\fP, the content of \fB/bin/bash\fP is actually bound over this latter: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proot \-b /bin/bash:/bin/sh $ md5sum /bin/sh 089ed56cd74e63f461bef0fdfc2d159a /bin/sh $ md5sum /bin/bash 089ed56cd74e63f461bef0fdfc2d159a /bin/bash $ md5sum /bin/dash 089ed56cd74e63f461bef0fdfc2d159a /bin/dash .ft P .fi .UNINDENT .UNINDENT .sp In most cases this shouldn\(aqt be a problem, but it is still possible to strictly bind \fB/bin/bash\fP over \fB/bin/sh\fP \-\- without dereferencing it \-\- by specifying the \fB!\fP character at the end: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proot \-b \(aq/bin/bash:/bin/sh!\(aq $ md5sum /bin/sh 089ed56cd74e63f461bef0fdfc2d159a /bin/sh $ md5sum /bin/bash 089ed56cd74e63f461bef0fdfc2d159a /bin/bash $ md5sum /bin/dash c229085928dc19e8d9bd29fe88268504 /bin/dash .ft P .fi .UNINDENT .UNINDENT .SS \fBchroot\fP + \fBmount \-\-bind\fP equivalent .sp 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proot \-r /mnt/slackware\-8.0/ $ ps \-o tty,command Error, do this: mount \-t proc none /proc .ft P .fi .UNINDENT .UNINDENT .sp works better with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proot \-r /mnt/slackware\-8.0/ \-b /proc $ ps \-o tty,command TT COMMAND ? \-bash ? proot \-b /proc /mnt/slackware\-8.0/ ? \- ? ps \-o tty,command .ft P .fi .UNINDENT .UNINDENT .sp Actually there\(aqs a bunch of such specific files, that\(aqs why PRoot provides the option \fB\-R\fP to bind automatically a pre\-defined list of recommended paths: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proot \-R /mnt/slackware\-8.0/ $ ps \-o tty,command TT COMMAND pts/6 \-bash pts/6 proot \-R /mnt/slackware\-8.0/ pts/6 \- pts/6 ps \-o tty,command .ft P .fi .UNINDENT .UNINDENT .SS \fBchroot\fP + \fBmount \-\-bind\fP + \fBsu\fP equivalent .sp Some programs will not work correctly if they are not run by the "root" user, this is typically the case with package managers. PRoot can fake the root identity and its privileges when the \fB\-0\fP (zero) option is specified: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proot \-r /mnt/slackware\-8.0/ \-0 # id uid=0(root) gid=0(root) [...] # mkdir /tmp/foo # chmod a\-rwx /tmp/foo # echo \(aqI bypass file\-system permissions.\(aq > /tmp/foo/bar # cat /tmp/foo/bar I bypass file\-system permissions. .ft P .fi .UNINDENT .UNINDENT .sp This option is typically required to create or install packages into the guest rootfs. Note it is \fInot\fP recommended to use the \fB\-R\fP option when installing packages since they may try to update bound system files, like \fB/etc/group\fP\&. Instead, it is recommended to use the \fB\-S\fP option. This latter enables the \fB\-0\fP option and binds only paths that are known to not be updated by packages: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proot \-S /mnt/slackware\-8.0/ # installpkg perl.tgz Installing package perl... .ft P .fi .UNINDENT .UNINDENT .SS \fBchroot\fP + \fBmount \-\-bind\fP + \fBbinfmt_misc\fP equivalent .sp PRoot uses QEMU user\-mode to execute programs built for a CPU architecture incompatible with the host one. From users\(aq 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 \fB\-q\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proot \-R /mnt/armslack\-12.2/ \-q qemu\-arm $ cat /etc/motd Welcome to ARMedSlack Linux 12.2 .ft P .fi .UNINDENT .UNINDENT .sp The parameter of the \fB\-q\fP option is actually a whole QEMU user\-mode command, for instance to enable its GDB server on port 1234: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proot \-R /mnt/armslack\-12.2/ \-q "qemu\-arm \-g 1234" emacs .ft P .fi .UNINDENT .UNINDENT .sp PRoot allows one to mix transparently the emulated execution of guest programs and the native execution of host programs in the same file\-system namespace. It\(aqs 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 \fB/host\-rootfs\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proot \-R /mnt/armslack\-12.2/ \-q qemu\-arm $ file /bin/echo [...] ELF 32\-bit LSB executable, ARM [...] $ /bin/echo \(aqHello world!\(aq Hello world! $ file /host\-rootfs/bin/echo [...] ELF 64\-bit LSB executable, x86\-64 [...] $ /host\-rootfs/bin/echo \(aqHello mixed world!\(aq Hello mixed world! .ft P .fi .UNINDENT .UNINDENT .sp Since both host and guest programs use the guest rootfs as \fB/\fP, 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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 .ft P .fi .UNINDENT .UNINDENT .sp 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 \fBmake\fP is overlaid by the host one: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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 .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs 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 \fB\&./configure\fP script: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C checking whether the C compiler is a cross\-compiler... no .ft P .fi .UNINDENT .UNINDENT .SH DOWNLOADS .SS PRoot .sp The latest release of PRoot is packaged on \fI\%http://packages.proot.me\fP and sources are hosted on \fI\%http://github.proot.me\fP\&. It is also available as highly compatible static binaries: .INDENT 0.0 .IP \(bu 2 for x86_64: \fI\%http://static.proot.me/proot\-x86_64\fP .IP \(bu 2 for x86: \fI\%http://static.proot.me/proot\-x86\fP .IP \(bu 2 for ARM: \fI\%http://static.proot.me/proot\-arm\fP .IP \(bu 2 other architectures: on demand. .UNINDENT .SS Rootfs .sp Here follows a couple of URLs where some rootfs archives can be freely downloaded. Note that \fBmknod\fP errors reported by \fBtar\fP when extracting these archives can be safely ignored since special files are typically bound (see \fB\-R\fP option for details). .INDENT 0.0 .IP \(bu 2 \fI\%http://download.openvz.org/template/precreated/\fP .IP \(bu 2 \fI\%https://images.linuxcontainers.org/images/\fP .IP \(bu 2 \fI\%http://distfiles.gentoo.org/releases/\fP .IP \(bu 2 \fI\%http://cdimage.ubuntu.com/ubuntu\-core/releases/\fP .IP \(bu 2 \fI\%http://archlinuxarm.org/developers/downloads\fP .UNINDENT .sp Technically such rootfs archive can be created by running the following command on the expected Linux distribution: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tar \-\-one\-file\-system \-\-create \-\-gzip \-\-file my_rootfs.tar.gz / .ft P .fi .UNINDENT .UNINDENT .SS QEMU user\-mode .sp 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 \fI\%http://qemu.proot.me\fP 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 \fB\-\-enable\-linux\-user\fP option has to be specified to the \fB\&./configure\fP script. .SH SEE ALSO .sp chroot(1), mount(8), binfmt_misc, ptrace(2), qemu(1), sb2(1), bindfs(1), fakeroot(1), fakechroot(1) .SH COLOPHON .sp Visit \fI\%http://proot.me\fP for help, bug reports, suggestions, patches, ... Copyright (C) 2014 STMicroelectronics, licensed under GPL v2 or later. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C _____ _____ ___ | __ \e __ \e_____ _____| |_ | __/ / _ \e/ _ \e _| |__| |__|__\e_____/\e_____/\e____| .ft P .fi .UNINDENT .UNINDENT .\" Generated by docutils manpage writer. .