.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "FAKECHROOT 1" .TH FAKECHROOT 1 "16 Mar 2019" fakechroot " " .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME fakechroot \- gives a fake chroot environment .SH SYNOPSIS .IX Header "SYNOPSIS" \&\fBfakechroot\fR [\fB\-s\fR|\fB\-\-use\-system\-libs\fR] [\fB\-l\fR|\fB\-\-lib\fR\ \fIlibrary\fR] [\fB\-d\fR|\fB\-\-elfloader\fR\ \fIldso\fR] [\fB\-e\fR|\fB\-\-environment\fR\ \fItype\fR] [\fB\-c\fR|\fB\-\-config\-dir\fR\ \fIdirectory\fR] [\fB\-b\fR|\fB\-\-bindir\fR\ \fIdirectory\fR] [\fB\-\-\fR] [\fIcommand\fR] .PP \&\fBfakechroot\fR \&\fB\-h\fR|\fB\-\-help\fR .PP \&\fBfakechroot\fR \&\fB\-v\fR|\fB\-\-version\fR .SH DESCRIPTION .IX Header "DESCRIPTION" fakechroot runs a command in an environment where is additional possibility to use \fBchroot\fR\|(8) command without root privileges. This is useful for allowing users to create own chrooted environment with possibility to install another packages without need for root privileges. .PP fakechroot replaces some C library functions (\fBchroot\fR\|(2), \fBopen\fR\|(2), etc.) by ones that simulate the effect of being called with root privileges. .PP These wrapper functions are provided as a shared library \fIlibfakechroot.so\fR which is loaded through the \f(CW\*(C`LD_PRELOAD\*(C'\fR mechanism of the dynamic loader. (See \fBld.so\fR\|(8)) .PP In fake chroot you can install i.e. Debian bootstrap with \fBdebootstrap\fR\|(8) command. In such environment you can run i.e. \fBapt\-get\fR\|(8) command to install another packages. You don't need a special privileges and you can run it on common user's account. .SH OPTIONS .IX Header "OPTIONS" .IP "\fB\-b\fR|\fB\-\-bindir\fR \fIdirectory\fR" 4 .IX Item "-b|--bindir directory" Specify a directory which contains the replacement executables shipped with fakechroot. Those are script files with the extension \f(CW\*(C`.fakechroot\*(C'\fR. By default they are distributed over the \&\f(CW\*(C`bin\*(C'\fR and \f(CW\*(C`sbin\*(C'\fR directories in fakechroot's install prefix, but sometimes a fixed location at build time is not feasible. .IP "\fB\-c\fR|\fB\-\-config\-dir\fR \fIdirectory\fR" 4 .IX Item "-c|--config-dir directory" Specify a directory which contains additional configuration for fakechroot. The default directory are \f(CW\*(C`$HOME/.fakechroot\*(C'\fR and \f(CW\*(C`/etc/fakechroot\*(C'\fR. .IP "\fB\-d\fR \fIldso\fR|\fB\-\-elfloader\fR \fIldso\fR" 4 .IX Item "-d ldso|--elfloader ldso" Specify an alternative dynamic linker. This dynamic linker will be invoked directly. .IP "\fB\-e\fR|\fB\-\-environment\fR \fItype\fR" 4 .IX Item "-e|--environment type" Load additional configuration with environment. This configuration file is a shell script which is executed before calling \fIcommand\fR. The script can set additional environment variables, like i.e.: \&\f(CW\*(C`FAKECHROOT_EXCLUDE_PATH\*(C'\fR, \f(CW\*(C`FAKECHROOT_CMD_SUBST\*(C'\fR or \f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR. .Sp The environment type is guessed based on command name with optional extension removed (e.g. running \fIgettext.sh\fR loads \f(CW\*(C`gettext\*(C'\fR environment file). If \&\fIcommand\fR argument is \fBfakeroot\fR\|(1) this argument is omitted and next argument is taken as environment type. .Sp The configuration file name is \fItype.env\fR and is searched at \&\fR\f(CI$HOME\fR\fI/.fakechroot\fR and \fI/etc/fakechroot\fR directories. .Sp The default environment type is \fBdefault\fR and its configuration file name is \&\f(CW\*(C`default.env\*(C'\fR. .Sp The special environment \fBnone\fR means that no environment settings are loaded at all. .IP "\fB\-l\fR \fIlibrary\fR|\fB\-\-lib\fR \fIlibrary\fR" 4 .IX Item "-l library|--lib library" Specify an alternative wrapper library. The default is \fIlibfakechroot.so\fR .IP \fB\-h\fR|\fB\-\-help\fR 4 .IX Item "-h|--help" Display help. .IP \fB\-s\fR|\fB\-\-use\-system\-libs\fR 4 .IX Item "-s|--use-system-libs" Use system libraries before chroot's libraries. This might be a workaround if system dynamic linker cannot load \fIlibc.so\fR from fake chroot. .Sp Try this setting if you noticed following errors: .Sp .Vb 4 \& $ fakechroot /usr/sbin/chroot /tmp/sarge /bin/true \& /bin/true: relocation error: /srv/sarge/lib/tls/libc.so.6: symbol _dl \& _starting_up, version GLIBC_PRIVATE not defined in file ld\-linux.so.2 \& with link time reference \& \& $ fakechroot /usr/sbin/chroot /tmp/centos4 /bin/true \& Segmentation fault .Ve .IP \fB\-v\fR|\fB\-\-version\fR 4 .IX Item "-v|--version" Display version. .IP "[\fB\-\-\fR] \fIcommand\fR" 4 .IX Item "[--] command" Any command you want to be run as fakechroot. Use '\fB\-\-\fR' if in the command you have other options that may confuse fakechroot's option parsing. .SH EXAMPLES .IX Header "EXAMPLES" An example session with fakechroot: .PP .Vb 2 \& $ id \& uid=1000(dexter) gid=1000(dexter) groups=1000(dexter) \& \& $ fakechroot fakeroot debootstrap sid /tmp/sid \& I: Retrieving Release \& I: Retrieving Release.gpg \& I: Checking Release signature \& ... \& I: Base system installed successfully. \& \& $ fakechroot fakeroot chroot /tmp/sid apt\-get install \-q hello \& Reading package lists... \& Building dependency tree... \& Reading state information... \& The following NEW packages will be installed: \& hello \& 0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded. \& Need to get 57.4 kB of archives. \& After this operation, 558 kB of additional disk space will be used. \& Get:1 http://ftp.us.debian.org/debian/ sid/main hello amd64 2.8\-4 [57.4 kB] \& Fetched 57.4 kB in 0s (127 kB/s) \& Selecting previously unselected package hello. \& (Reading database ... 24594 files and directories currently installed.) \& Unpacking hello (from .../archives/hello_2.8\-4_amd64.deb) ... \& Processing triggers for man\-db ... \& Processing triggers for install\-info ... \& Setting up hello (2.8\-4) ... \& \& $ fakechroot chroot /tmp/sid hello \& Hello, world! .Ve .SH FAKEROOT .IX Header "FAKEROOT" \&\fBfakeroot\fR\|(1) is a complementary tool which emulates root environment. fakeroot and fakechroot might wrap the same C library functions, i.e. \fBmknod\fR\|(2) function. It is important to start fake environment in proper order. fakeroot should be started inside fakechroot: .PP .Vb 1 \& $ fakechroot fakeroot chroot /tmp/sid /bin/mknod /tmp/device c 1 2 .Ve .SH "SECURITY ASPECTS" .IX Header "SECURITY ASPECTS" fakechroot is a regular, non-setuid program. It does not enhance a user's privileges. .PP fakechroot should not be used as a tool for enhancing system security i.e. by separating (sandboxing) applications. It is very easy to escape from a fake chroot environment. .PP fakechroot should not be run with real root privileges. It might decrease the security of the system because the fakechroot provides own version of core functions with behavior depended on some environment variables. .SH FILES .IX Header "FILES" .IP \fIlibfakechroot.so\fR 4 .IX Item "libfakechroot.so" The shared library containing the wrapper functions. .SH ENVIRONMENT .IX Header "ENVIRONMENT" .IP \fBFAKECHROOT\fR 4 .IX Item "FAKECHROOT" The value is true for fake chroot environment. .IP \fBFAKECHROOT_AF_UNIX_PATH\fR 4 .IX Item "FAKECHROOT_AF_UNIX_PATH" The root directory for unix sockets. The default value is the same as \&\f(CW\*(C`FAKECHROOT_BASE\*(C'\fR and it can be set separately if the \f(CW\*(C`FAKECHROOT_BASE\*(C'\fR is too long and the unix socket path could exceed the limit of \fB108\fR bytes. .IP \fBFAKECHROOT_BASE\fR 4 .IX Item "FAKECHROOT_BASE" The root directory of fake chroot environment. .IP \fBFAKECHROOT_CMD_SUBST\fR 4 .IX Item "FAKECHROOT_CMD_SUBST" A list of command substitutions. If a program tries to execute one of the commands given (path relative to the chroot, trailing dot is removed) then the substitute command runs instead (path to substitute command is not chrooted). .Sp The substituted command inherits \f(CW\*(C`FAKECHROOT_*\*(C'\fR variables but the original \&\f(CW\*(C`FAKECHROOT_BASE\*(C'\fR variable which is saved as \f(CW\*(C`FAKECHROOT_BASE_ORIG\*(C'\fR. It means that substituted command runs outside fakechroot environment. Also original command name is saved as \f(CW\*(C`FAKECHROOT_CMD_ORIG\*(C'\fR. .Sp For example: .Sp .Vb 1 \& export FAKECHROOT_CMD_SUBST=/usr/bin/mkfifo=/bin/true .Ve .Sp will substitute \f(CW\*(C`/bin/true\*(C'\fR for \f(CW\*(C`/usr/bin/mkfifo\*(C'\fR and will make possible to install sysvinit binary package. .Sp Give as many substitute commands as you want, separated by \f(CW\*(C`:\*(C'\fR (colon) characters. .Sp It is suggested to substitute at least: .RS 4 .IP \(bu 2 \&\f(CW\*(C`/bin/mount=/bin/true\*(C'\fR .IP \(bu 2 \&\f(CW\*(C`/sbin/insserv=/bin/true\*(C'\fR .IP \(bu 2 \&\f(CW\*(C`/sbin/ldconfig=/bin/true\*(C'\fR .IP \(bu 2 \&\f(CW\*(C`/usr/bin/env=/usr/bin/env.fakechroot\*(C'\fR .IP \(bu 2 \&\f(CW\*(C`/usr/bin/ischroot=/bin/true\*(C'\fR .IP \(bu 2 \&\f(CW\*(C`/usr/bin/ldd=/usr/bin/ldd.fakechroot\*(C'\fR .IP \(bu 2 \&\f(CW\*(C`/usr/bin/mkfifo=/bin/true\*(C'\fR .RE .RS 4 .Sp to make \fBdebootstrap\fR\|(8) working correctly. .Sp To prevent some looping, the command substitution is done only if \&\f(CW\*(C`FAKECHROOT_CMD_ORIG\*(C'\fR variable is not set currently. .RE .IP \fBFAKECHROOT_DEBUG\fR 4 .IX Item "FAKECHROOT_DEBUG" The fakechroot library will dump some debugging info if this variable is set. .IP \fBFAKECHROOT_DETECT\fR 4 .IX Item "FAKECHROOT_DETECT" If this variable is set then \f(CW\*(C`fakechroot \fR\f(CIversion\fR\f(CW\*(C'\fR string is printed to standard output and the current process is terminated with status taken from this variable. It can be a method to check if fakechroot is preloaded correctly. .Sp .Vb 1 \& $ case "\`FAKECHROOT_DETECT=1 /bin/echo\`" in fakechroot*) echo LOADED;; esac .Ve .IP \fBFAKECHROOT_ELFLOADER\fR 4 .IX Item "FAKECHROOT_ELFLOADER" A path to another dynamic linker (i.e. \fI/lib/ld\-linux.so.2\fR for i386 architecture, \fI/lib64/ld\-linux\-x86\-64.so.2\fR for x86_64 architecture). .Sp This dynamic linker will be invoked directly. The dynamic linker don't allow to change \f(CW\*(C`argv[0]\*(C'\fR besides the file name of the executable file, so some application won't work correctly, i.e. \fBbusybox\fR\|(1). .IP \fBFAKECHROOT_EXCLUDE_PATH\fR 4 .IX Item "FAKECHROOT_EXCLUDE_PATH" The list of directories which are excluded from being chrooted. The elements of list are separated with colon. .Sp The \fI/dev\fR, \fI/proc\fR and \fI/sys\fR directories are excluded by default if this environment variable is not set. .Sp This list has to contain at most 100 elements. .IP \fBFAKECHROOT_EXTRA_LIBRARY_PATH\fR 4 .IX Item "FAKECHROOT_EXTRA_LIBRARY_PATH" The list of extra directories in fake chroot environment that are added to \&\f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR variable. The directories might be used by some important commands which use libraries placed in the \fIrunpath\fR. In that case dynamic linker can't find correct directory in a fake chroot environment without the extra library path. .Sp The default value is \f(CW\*(C`/lib/systemd:/usr/lib/man\-db\*(C'\fR for \fBsystemctl\fR\|(1) and \&\fBman\fR\|(1) commands. .IP \fBFAKECHROOT_VERSION\fR 4 .IX Item "FAKECHROOT_VERSION" The version number of the current fakechroot library. .IP "\fBLD_LIBRARY_PATH\fR, \fBLD_PRELOAD\fR" 4 .IX Item "LD_LIBRARY_PATH, LD_PRELOAD" Fakechroot is implemented by wrapping system calls. This is accomplished by setting \f(CW\*(C`LD_PRELOAD=libfakechroot.so\*(C'\fR. If this library can't be found by dynamic linker, the \fI/etc/ld.so.conf\fR file or \f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR variable have to be modified. .SH LIMITATIONS .IX Header "LIMITATIONS" .IP \(bu 4 \&\fI/lib/ld\-linux.so.2\fR and \fI/lib64/ld\-linux\-x86\-64.so.2\fR are always loaded from real environment. This path is hardcoded by linker for all binaries. You can set the \f(CW\*(C`FAKECHROOT_ELFLOADER\*(C'\fR environment variable or use \&\f(CW\*(C`\-\-elfloader\*(C'\fR option. .IP \(bu 4 Every command executed within fakechroot needs to be linked to the same version of the dynamic linker from real environment. If the libraries in chroot are not compatible, try to use \f(CW\*(C`\-\-use\-system\-libs\*(C'\fR option. .IP \(bu 4 You can provide symlinks to the outside. The symlink have to be created before chroot is called. It can be useful for accessing the real \fI/proc\fR and \fI/dev\fR directory. You can also set the \f(CW\*(C`FAKECHROOT_EXCLUDE_PATH\*(C'\fR environment variable: .Sp .Vb 1 \& $ export FAKECHROOT_EXCLUDE_PATH=/tmp:/proc:/dev:/sys:/var/run:/home .Ve .IP \(bu 4 Statically linked binaries doesn't work, especially \fBldconfig\fR\|(8), so you have to wrap this command with dummy version and set the proper \&\f(CW\*(C`FAKECHROOT_CMD_SUBST\*(C'\fR environment variable. .IP \(bu 4 \&\fBldd\fR\|(1) also doesn't work. You have to use \f(CW\*(C`alias ldd=\*(AqLD_TRACE_LOADED_OBJECTS=1\*(Aq\*(C'\fR or to use a wrapper instead. The wrapper is installed as \fIldd.fakechroot\fR and can be used with \f(CW\*(C`FAKECHROOT_CMD_SUBST\*(C'\fR environment variable. .IP \(bu 4 The full screen applications hangs up if \fI/dev/tty\fR file is not a real device. Link \fI/dev/tty\fR file or whole \fI/dev\fR directory to the real one or remove it from fake chroot environment with \f(CW\*(C`FAKECHROOT_EXCLUDE_PATH\*(C'\fR variable. .IP \(bu 4 \&\fBlckpwdf\fR\|(3) and \fBulckpwdf\fR\|(3) are ignored so \fBpasswd\fR\|(1) command should work .IP \(bu 4 Your real uid should exist in \fI/etc/passwd\fR. Create it with adduser \-\-uid \&\fIrealuid\fR \fIrealuser\fR inside fake chroot environment. .IP \(bu 4 \&\fBdebuild\fR\|(1) cleans environment. Use \-\-preserve\-env option to prevent this behavior. .IP \(bu 4 \&\fBrpmbuild\fR\|(8) uses own \fBglob\fR\|(3) implementation which breaks fakechroot so buildroot directory have to be the same inside and outside fakechroot. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBfakeroot\fR\|(1), \fBdebuild\fR\|(1), \fBdebootstrap\fR\|(8), \fBrinse\fR\|(8), http://fakechroot.alioth.debian.org/ .SH BUGS .IX Header "BUGS" If you find the bug or want to implement new features, please report it at .SH AUTHORS .IX Header "AUTHORS" Copyright (c) 2003\-2017, 2019 Piotr Roszatycki .PP Copyright (c) 2007 Mark Eichin .PP Copyright (c) 2006, 2007 Alexander Shishkin .PP Copyright (c) 2006, 2007 Lionel Tricon .SH COPYING .IX Header "COPYING" fakechroot is distributed under the GNU Lesser General Public License (LGPL 2.1 or greater).