.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "FAKECHROOT 1"
.TH FAKECHROOT 1 "27 Nov 2011" "Debian" " "
.\" 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\-e\fR|\fB\-\-environment\fR\ \fItype\fR]
[\fB\-c\fR|\fB\-\-config\-dir\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 were is additional possibility to
use \fIchroot\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 more library functions (\fIchroot\fR\|(2), \fIopen\fR\|(2), etc.) by ones
that simulate the effect the real library functions would have had, had the
user really been in chroot.  These wrapper functions are in a shared library
\&\fI/usr/lib/fakechroot/libfakechroot.so\fR which is loaded through the
\&\f(CW\*(C`LD_PRELOAD\*(C'\fR mechanism of the dynamic loader.  (See \fIld.so\fR\|(8))
.PP
In fake chroot you can install Debian bootstrap with \fIdebootstrap\fR\|(8)
command.  In this environment you can use i.e. \fIapt\-get\fR\|(8) command to install
another packages from common user's account.
.PP
In the current version, the fakechroot does not provide the \fIfakeroot\fR\|(1)
functionality! You might to call fakechroot with fakeroot command, if you
want to emulate root environment, i.e.:
.PP
.Vb 3
\& $ fakechroot fakeroot /usr/sbin/chroot /tmp/debian /bin/sh
\& # id
\& uid=0(root) gid=0(root) groups=0(root)
.Ve
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-l\fR \fIlibrary\fR|\fB\-\-lib\fR \fIlibrary\fR" 4
.IX Item "-l library|--lib library"
Specify an alternative wrapper library.
.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 (\fI/lib/ld\-linux.so.2\fR for Linux) can not 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\-e\fR|\fB\-\-environment\fR \fItype\fR" 4
.IX Item "-e|--environment type"
Load additional confguration 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 or \f(CW\*(C`FAKECHROOT_CMD_SUBST\*(C'\fR.  The variable
\&\f(CW\*(C`paths\*(C'\fR should be used instead \f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR and variable \f(CW\*(C`lib\*(C'\fR
should be used instead \f(CW\*(C`LD_PRELOAD\*(C'\fR.
.Sp
The environment type is guessed based on command name with optional extension
removed (i.e.: \fI.sh\fR).  If \fIcommand\fR argument is \fIfakeroot\fR\|(1) this argument
is ommited and next argument is taken as environment type.
.Sp
The configuration file name is \fI\fItype\fI.env\fR and can be located at
\&\fI\f(CI$HOME\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.
.IP "\fB\-c\fR|\fB\-\-config\-dir\fR \fIdirectory\fR" 4
.IX Item "-c|--config-dir directory"
Specify a directory which contains additional configuraton for fakechroot. The
default directory are \f(CW\*(C`$HOME/.fakechroot\*(C'\fR and \f(CW\*(C`/etc/fakechroot\*(C'\fR.
.IP "[\fB\-\-\fR] \fIcommand\fR" 4
.IX Item "[--] command"
Any command you want to be ran as fakechroot.  Use '\fB\-\-\fR' if in the command
you have other options that may confuse fakechroot's option parsing.
.IP "\fB\-h\fR" 4
.IX Item "-h"
Display help.
.IP "\fB\-v\fR" 4
.IX Item "-v"
Display version.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
An example session with fakechroot:
.PP
.Vb 2
\& $ export PATH=/usr/sbin:/sbin:$PATH
\& $ fakechroot fakeroot debootstrap sid /tmp/sid
\&
\& $ fakechroot fakeroot chroot /tmp/sid
\& # cd /
\& # echo deb http://ftp.debian.org/debian sid main contrib non\-free >
\& /etc/apt/sources.list
\& # echo deb\-src http://ftp.debian.org/debian sid main contrib non\-free
\&  >> /etc/apt/sources.list
\& # apt\-get update
\& # apt\-get install adduser whiptail build\-essential devscripts
\& # adduser \-\-uid 1001 user
\& # exit
\&
\& $ fakechroot chroot /tmp/sid
\& $ cd /tmp
\& $ apt\-get source hello
\& $ cd hello\-*
\& $ debuild \-\-preserve\-env \-b
\& $ exit
.Ve
.SH "FAKEROOT"
.IX Header "FAKEROOT"
\&\fIfakeroot\fR\|(1) is a complementary tool which emulates root environment.
fakeroot and fakechroot might wrap the same C library functions, i.e.
\&\fImknod\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, or decrease the host's system security.
.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.
.SH "FILES"
.IX Header "FILES"
.IP "\fI/usr/lib/fakechroot/libfakechroot.so\fR" 4
.IX Item "/usr/lib/fakechroot/libfakechroot.so"
The shared library containing the wrapper functions.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
.IP "\fB\s-1FAKECHROOT\s0\fR" 4
.IX Item "FAKECHROOT"
The value is true for fake chroot environment.
.IP "\fB\s-1FAKECHROOT_VERSION\s0\fR" 4
.IX Item "FAKECHROOT_VERSION"
The version of current fakechroot library.
.IP "\fB\s-1FAKECHROOT_BASE\s0\fR" 4
.IX Item "FAKECHROOT_BASE"
The root directory for fake chroot environment.
.IP "\fB\s-1FAKECHROOT_DETECT\s0\fR" 4
.IX Item "FAKECHROOT_DETECT"
If this variable is set then \f(CW\*(C`fakechroot \f(CIversion\f(CW\*(C'\fR string is printed
to standard output and current process is terminated with status 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 "\fB\s-1FAKECHROOT_DEBUG\s0\fR" 4
.IX Item "FAKECHROOT_DEBUG"
The fakechroot library will dump some debugging info is this variable is set.
.IP "\fB\s-1FAKECHROOT_AF_UNIX_PATH\s0\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 can exceed the limit of \fB108\fR chars.
.IP "\fB\s-1FAKECHROOT_EXCLUDE_PATH\s0\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.
.IP "\fB\s-1FAKECHROOT_CMD_SUBST\s0\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/ldconfig\*(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 \fIdebootstrap\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 "\fB\s-1LD_LIBRARY_PATH\s0\fR, \fB\s-1LD_PRELOAD\s0\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_LIBRARY_PATH=/usr/lib/fakechroot\*(C'\fR and
LD_PRELOAD=libfakechroot.so.  That library is loaded before the
system's C library, and so most of the library functions are intercepted by
it.  If you need to set either \fB\s-1LD_LIBRARY_PATH\s0\fR or \fB\s-1LD_PRELOAD\s0\fR from within
a fakechroot environment, it should be set relative to the given paths, as in
\&\f(CW\*(C`LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/foo/bar/\*(C'\fR
.SH "LIMITATIONS"
.IX Header "LIMITATIONS"
.IP "o" 4
.IX Item "o"
\&\fI/lib/ld\-linux.so.2\fR is always loaded from real environment.  This path is
hardcoded by linker for all binaries.
.IP "o" 4
.IX Item "o"
Every command executed within fakechroot needs to be linked to the same
version of the C library as fakechroot itself.  If the libraries in chroot
are not compatible, try to use \fB\-\-use\-system\-libs\fR option.
.IP "o" 4
.IX Item "o"
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 \fB\s-1FAKECHROOT_EXCLUDE_PATH\s0\fR
environment variable:
.Sp
.Vb 1
\& $ export FAKECHROOT_EXCLUDE_PATH=/tmp:/proc:/dev:/var/run
.Ve
.IP "o" 4
.IX Item "o"
Statically linked binaries doesn't work, especially \fIldconfig\fR\|(8), so you have
to wrap this command with dummy version and i.e. set the dpkg diversion (see:
\&\fIdpkg\-divert\fR\|(8)) or use \fB\s-1FAKECHROOT_CMD_SUBST\s0\fR environment variable.
.IP "o" 4
.IX Item "o"
\&\fIldd\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 "o" 4
.IX Item "o"
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.
.IP "o" 4
.IX Item "o"
\&\fIlckpwdf\fR\|(3) and \fIulckpwdf\fR\|(3) are ignored so \fIpasswd\fR\|(1) command should work
.IP "o" 4
.IX Item "o"
Your real uid should exist in \fI/etc/passwd\fR.  Create it with adduser \-\-uid
\&\fIrealuid\fR \fIrealuser\fR.
.IP "o" 4
.IX Item "o"
\&\fIdebuild\fR\|(1) cleans environment.  Use \-\-preserve\-env option to prevent this
behaviour.
.IP "o" 4
.IX Item "o"
\&\fIrpmbuild\fR\|(8) uses own \fIglob\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"
\&\fIfakeroot\fR\|(1), \fIdebuild\fR\|(1), \fIdebootstrap\fR\|(8), \fIfebootstrap\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
<https://github.com/fakechroot/fakechroot/issues>
.SH "AUTHORS"
.IX Header "AUTHORS"
Copyright (c) 2003, 2005, 2007\-2011 Piotr Roszatycki <dexter@debian.org>
.PP
Copyright (c) 2007 Mark Eichin <eichin@metacarta.com>
.PP
Copyright (c) 2006, 2007 Alexander Shishkin <virtuoso@slind.org>
.PP
Copyright (c) 2006, 2007 Lionel Tricon <lionel.tricon@free.fr>
.SH "COPYING"
.IX Header "COPYING"
fakechroot is distributed under the \s-1GNU\s0 Lesser General Public License (\s-1LGPL\s0
2.1 or greater).
.PP
Additional copyrights:
.IP "\(bu" 2
execl function taken from \s-1GNU\s0 C Library.
Copyright (C) 1991,92,94,97,98,99,2002,2005 Free Software Foundation, Inc.
.IP "\(bu" 2
execle function taken from \s-1GNU\s0 C Library.
Copyright (C) 1991,97,98,99,2002,2005 Free Software Foundation, Inc.
.IP "\(bu" 2
execlp function taken from \s-1GNU\s0 C Library.
Copyright (C) 1991,93,96,97,98,99,2002,2005 Free Software Foundation, Inc.
.IP "\(bu" 2
execvp function taken from \s-1GNU\s0 C Library.
Copyright (C) 1991,92, 1995\-99, 2002, 2004, 2005, 2007, 2009
Free Software Foundation, Inc.
.IP "\(bu" 2
fts_* functions taken from OpenBSD.
Copyright (c) 1990, 1993, 1994
The Regents of the University of California.
This software is distributed under the BSD-style license.
.IP "\(bu" 2
ftw function taken from \s-1GNU\s0 C Library.
Copyright (C) 1996\-2004, 2006\-2008, 2010 Free Software Foundation, Inc.
This file is part of the \s-1GNU\s0 C Library.
Contributed by Ulrich Drepper <drepper@cygnus.com>, 1996.
.IP "\(bu" 2
_\|_opendir2 function taken from FreeBSD.
Copyright (c) 1983, 1993 The Regents of the University of California.
Copyright (c) 2000 Daniel Eischen.
This software is distributed under the BSD-style license.
.IP "\(bu" 2
popen function taken from OpenBSD.
Copyright (c) 1988, 1993 The Regents of the University of California.
.IP "\(bu" 2
rawmemchr function taken from uClibc
Copyright (C) 2002 Manuel Novoa \s-1III\s0
Copyright (C) 2000\-2005 Erik Andersen <andersen@uclibc.org>
.IP "\(bu" 2
realpath function taken from Gnulib.
Copyright (c) 1996\-2010 Free Software Foundation, Inc.
.IP "\(bu" 2
rpl_lstat function taken from Gnulib.
Copyright (C) 1997\-2006, 2008\-2010 Free Software Foundation, Inc.
.IP "\(bu" 2
stpcpy function taken from Gnulib.
Copyright (C) 1992, 1995, 1997\-1998, 2006, 2009\-2010 Free Software
Foundation, Inc.
.IP "\(bu" 2
strchrnul function taken from Gnulib.
Copyright (C) 2003, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.