|
|
|
|
@ -1,832 +0,0 @@
|
|
|
|
|
.\" Man page generated from reStructuredText.
|
|
|
|
|
.
|
|
|
|
|
.TH PROOT 1 "2016-08-09" "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\&.
|
|
|
|
|
.TP
|
|
|
|
|
.BI \-p \ string\fP,\fB \ \-\-port\fB= string
|
|
|
|
|
Map ports to others with the syntax as \fIstring\fP "port_in:port_out ...".
|
|
|
|
|
.sp
|
|
|
|
|
This option makes PRoot intercept bind and connect system calls,
|
|
|
|
|
and change the port they use. The port map is specified
|
|
|
|
|
with the syntax: \fB\-b *port_in*:*port_out*\fP\&. For example,
|
|
|
|
|
an application that runs a MySQL server binding to 5432 wants
|
|
|
|
|
to cohabit with other similar application, but doesn\(aqt have an
|
|
|
|
|
option to change its port. PRoot can be used here to modify
|
|
|
|
|
this port: \fBproot \-p 5432:5433 myapplication\fP\&. With this command,
|
|
|
|
|
the MySQL server will be bound to the port 5433.
|
|
|
|
|
This command can be repeated multiple times to map multiple ports.
|
|
|
|
|
.TP
|
|
|
|
|
.B \-n\fP,\fB \-\-netcoop
|
|
|
|
|
Activates the network cooperation mode.
|
|
|
|
|
.sp
|
|
|
|
|
This option makes PRoot intercept bind() system calls and
|
|
|
|
|
change the port they are binding to to 0. With this, the system will
|
|
|
|
|
allocate an available port. Each time this is done, a new entry is added
|
|
|
|
|
to the port mapping entries, so that corresponding connect() system calls
|
|
|
|
|
use the same resulting port.
|
|
|
|
|
.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 except 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/<pid>/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/
|
|
|
|
|
? sh
|
|
|
|
|
? 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 sh
|
|
|
|
|
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 source code for PRoot and CARE are hosted in the same repository on \fI\%GitHub\fP\&.
|
|
|
|
|
Previous PRoot releases were packaged at \fI\%https://github.com/proot\-me/proot\-static\-build/releases\fP, however, that
|
|
|
|
|
repository has since been archived. The latest builds can be found under the job artifacts for the \fI\%GitLab CI/CD Pipelines\fP for each commit.
|
|
|
|
|
.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\%https://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\fP
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
\fI\%https://archlinuxarm.org/about/downloads\fP
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
\fI\%https://alpinelinux.org/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
|
|
|
|
|
.SH ECOSYSTEM
|
|
|
|
|
.sp
|
|
|
|
|
The following ecosystem has developed around PRoot since it has been
|
|
|
|
|
made publicly available.
|
|
|
|
|
.SS Projects using PRoot or CARE
|
|
|
|
|
.INDENT 0.0
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
\fI\%CARE\fP: archive material used during an execution to make it
|
|
|
|
|
reproducible on any Linux system.
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
\fI\%GNURoot\fP:
|
|
|
|
|
use several Linux distros on Android without root access.
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
\fI\%Debian noroot\fP:
|
|
|
|
|
use Debian Linux on Android without root access.
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
\fI\%Polysquare Travis Container\fP:
|
|
|
|
|
use several Linux distros on Travis\-CI without root access.
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
\fI\%JuNest\fP:
|
|
|
|
|
use Arch Linux on any Linux distros without root access.
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
\fI\%Portable PyPy\fP:
|
|
|
|
|
portable 32 and 64 bit x86 PyPy binaries.
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
\fI\%OpenMOLE\fP:
|
|
|
|
|
execute programs on distributed computing environments.
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
\fI\%ATOS\fP:
|
|
|
|
|
find automatically C/C++ compiler options that provide best
|
|
|
|
|
optimizations.
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
\fI\%OPAM2Debian\fP:
|
|
|
|
|
create Debian packages which contains a fully compiled OPAM
|
|
|
|
|
installation.
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
\fI\%SIO Workers\fP:
|
|
|
|
|
batch long\-term computations with Python.
|
|
|
|
|
.UNINDENT
|
|
|
|
|
.SS Third party packages
|
|
|
|
|
.sp
|
|
|
|
|
Binaries from the \fI\%Downloads\fP section are likely more up\-to\-date.
|
|
|
|
|
.INDENT 0.0
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
\fI\%Alpine Linux\fP
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
\fI\%Arch Linux\fP
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
\fI\%Void Linux\fP
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
\fI\%Gentoo\fP
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
\fI\%Debian\fP
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
\fI\%Ubuntu\fP
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
\fI\%NixOS\fP
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
\fI\%University of Chicago RCC\fP
|
|
|
|
|
.UNINDENT
|
|
|
|
|
.SS Public material about PRoot or CARE
|
|
|
|
|
.INDENT 0.0
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
articles on \fI\%Rémi\(aqs blog\fP\&. Rémi (a.k.a Ivoire)
|
|
|
|
|
is one of the PRoot developers.
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
presentation "\fI\%Software engineering tools based on syscall
|
|
|
|
|
instrumentation\fP" during
|
|
|
|
|
FOSDEM 2014.
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
presentation "\fI\%SW testing & Reproducing a LAVA failures locally
|
|
|
|
|
using CARE\fP"
|
|
|
|
|
during Linaro Connect USA 2014
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
presentation and essay "\fI\%CARE: the Comprehensive Archiver for
|
|
|
|
|
Reproducible Execution\fP"
|
|
|
|
|
(\fI\%essay\fP)
|
|
|
|
|
during TRUST 2014
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
presentation "\fI\%An Introduction to the CARE tool (dead link)\fP"
|
|
|
|
|
during HiPEAC CSW 2013
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
presentation and essay "\fI\%PRoot: a Step Forward for QEMU User\-Mode\fP" (\fI\%proceedings\fP) during
|
|
|
|
|
QUF\(aq11
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
tutorial "\fI\%How to install nix in home (on another distribution)\fP"
|
|
|
|
|
.UNINDENT
|
|
|
|
|
.SS Companies using PRoot or CARE internally
|
|
|
|
|
.INDENT 0.0
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
STMicroelectronics
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
Sony
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
Ericsson
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
Cisco
|
|
|
|
|
.IP \(bu 2
|
|
|
|
|
Gogo
|
|
|
|
|
.UNINDENT
|
|
|
|
|
.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\%https://proot\-me.github.io\fP for help, bug reports, suggestions, patches, ...
|
|
|
|
|
Copyright (C) 2015 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.
|
|
|
|
|
.
|
Lucas Ramage