FAKECHROOT(1)															     FAKECHROOT(1)

NAME

       fakechroot - gives a fake chroot environment

SYNOPSIS

       fakechroot [-s|--use-system-libs] [-l|--lib library] [-e|--environment type] [-c|--config-dir directory] [--] [command]

       fakechroot [-h|--help]

       fakechroot [-v|--version]

DESCRIPTION

       fakechroot runs a command in an environment were is additional possibility to use chroot(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.

       fakechroot replaces more library functions (chroot(2), open(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 /usr/lib/fakechroot/libfakechroot.so which
       is loaded through the "LD_PRELOAD" mechanism of the dynamic loader.  (See ld.so(8))

       In fake chroot you can install Debian bootstrap with debootstrap(8) command.  In this environment you can use i.e. apt-get(8) command to
       install another packages from common user's account.

       In the current version, the fakechroot does not provide the fakeroot(1) functionality! You might to call fakechroot with fakeroot command,
       if you want to emulate root environment, i.e.:

	$ fakechroot fakeroot /usr/sbin/chroot /tmp/debian /bin/sh
	# id
	uid=0(root) gid=0(root) groups=0(root)

OPTIONS

       -l library|--lib library
	   Specify an alternative wrapper library.

       -s|--use-system-libs
	   Use system libraries before chroot's libraries.  This might be a workaround if system dynamic linker (/lib/ld-linux.so.2 for Linux) can
	   not load libc.so from fake chroot.

	   Try this setting if you noticed following errors:

	    $ 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

       -e|--environment type
	   Load additional confguration with environment.  This configuration file is a shell script which is executed before calling command.
	   The script can set additional environment variables, like i.e.: "FAKECHROOT_EXCLUDE_PATH" or "FAKECHROOT_CMD_SUBST".  The variable
	   "paths" should be used instead "LD_LIBRARY_PATH" and variable "lib" should be used instead "LD_PRELOAD".

	   The environment type is guessed based on command name with optional extension removed (i.e.: .sh).  If command argument is fakeroot(1)
	   this argument is ommited and next argument is taken as environment type.

	   The configuration file name is type.env and can be located at $HOME/.fakechroot and /etc/fakechroot directories.

	   The default environment type is default and its configuration file name is "default.env".

       -c|--config-dir directory
	   Specify a directory which contains additional configuraton for fakechroot. The default directory are "$HOME/.fakechroot" and
	   "/etc/fakechroot".

       [--] command
	   Any command you want to be ran as fakechroot.  Use '--' if in the command you have other options that may confuse fakechroot's option
	   parsing.

       -h  Display help.

       -v  Display version.

EXAMPLES

       An example session with fakechroot:

	$ 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

FAKEROOT

       fakeroot(1) is a complementary tool which emulates root environment.  fakeroot and fakechroot might wrap the same C library functions, i.e.
       mknod(2) function.  It is important to start fake environment in proper order. fakeroot should be started inside fakechroot:

	$ fakechroot fakeroot chroot /tmp/sid /bin/mknod /tmp/device c 1 2

SECURITY ASPECTS

       fakechroot is a regular, non-setuid program.  It does not enhance a user's privileges, or decrease the host's system security.

       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.

FILES

       /usr/lib/fakechroot/libfakechroot.so
	   The shared library containing the wrapper functions.

ENVIRONMENT

       FAKECHROOT
	   The value is true for fake chroot environment.

       FAKECHROOT_VERSION
	   The version of current fakechroot library.

       FAKECHROOT_BASE
	   The root directory for fake chroot environment.

       FAKECHROOT_DETECT
	   If this variable is set then "fakechroot version" 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.

	    $ case "`FAKECHROOT_DETECT=1 /bin/echo`" in fakechroot*) echo LOADED;; esac

       FAKECHROOT_DEBUG
	   The fakechroot library will dump some debugging info is this variable is set.

       FAKECHROOT_AF_UNIX_PATH
	   The root directory for unix sockets.  The default value is the same as "FAKECHROOT_BASE" and it can be set separately if the
	   "FAKECHROOT_BASE" is too long and the unix socket path can exceed the limit of 108 chars.

       FAKECHROOT_EXCLUDE_PATH
	   The list of directories which are excluded from being chrooted.  The elements of list are separated with colon.

       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).

	   The substituted command inherits "FAKECHROOT_*" variables but the original "FAKECHROOT_BASE" variable which is saved as
	   "FAKECHROOT_BASE_ORIG".  It means that substituted command runs outside fakechroot environment.  Also original command name is saved as
	   "FAKECHROOT_CMD_ORIG".

	   For example:

	    export FAKECHROOT_CMD_SUBST=/usr/bin/mkfifo=/bin/true

	   will substitute "/bin/true" for "/usr/bin/mkfifo" and will make possible to install sysvinit binary package.

	   Give as many substitute commands as you want, separated by ":" (colon) characters.

	   It is suggested to substitute at least:

	   o "/bin/mount=/bin/true"

	   o "/sbin/insserv=/bin/true"

	   o "/sbin/ldconfig=/bin/ldconfig"

	   o "/usr/bin/ischroot=/bin/true"

	   o "/usr/bin/ldd=/usr/bin/ldd.fakechroot"

	   o "/usr/bin/mkfifo=/bin/true"

	   to make debootstrap(8) working correctly.

	   To prevent some looping, the command substitution is done only if "FAKECHROOT_CMD_ORIG" variable is not set currently.

       LD_LIBRARY_PATH, LD_PRELOAD
	   Fakechroot is implemented by wrapping system calls.	This is accomplished by setting "LD_LIBRARY_PATH=/usr/lib/fakechroot" 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 LD_LIBRARY_PATH or LD_PRELOAD from within a fakechroot environment, it should be set
	   relative to the given paths, as in "LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/foo/bar/"

LIMITATIONS

       o   /lib/ld-linux.so.2 is always loaded from real environment.  This path is hardcoded by linker for all binaries.

       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 --use-system-libs option.

       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 /proc and /dev directory.  You can also set the FAKECHROOT_EXCLUDE_PATH environment variable:

	    $ export FAKECHROOT_EXCLUDE_PATH=/tmp:/proc:/dev:/var/run

       o   Statically linked binaries doesn't work, especially ldconfig(8), so you have to wrap this command with dummy version and i.e. set the
	   dpkg diversion (see: dpkg-divert(8)) or use FAKECHROOT_CMD_SUBST environment variable.

       o   ldd(1) also doesn't work.  You have to use "alias ldd='LD_TRACE_LOADED_OBJECTS=1'" or to use a wrapper instead.  The wrapper is
	   installed as ldd.fakechroot and can be used with "FAKECHROOT_CMD_SUBST" environment variable.

       o   The full screen applications hangs up if /dev/tty file is not a real device.  Link /dev/tty file or whole /dev directory to the real
	   one or remove it from fake chroot environment.

       o   lckpwdf(3) and ulckpwdf(3) are ignored so passwd(1) command should work

       o   Your real uid should exist in /etc/passwd.  Create it with adduser --uid realuid realuser.

       o   debuild(1) cleans environment.  Use --preserve-env option to prevent this behaviour.

       o   rpmbuild(8) uses own glob(3) implementation which breaks fakechroot so buildroot directory have to be the same inside and outside
	   fakechroot.

SEE ALSO

       fakeroot(1), debuild(1), debootstrap(8), febootstrap(8), http://fakechroot.alioth.debian.org/

BUGS

       If you find the bug or want to implement new features, please report it at <https://github.com/fakechroot/fakechroot/issues>

AUTHORS

       Copyright (c) 2003, 2005, 2007-2011 Piotr Roszatycki <dexter@debian.org>

       Copyright (c) 2007 Mark Eichin <eichin@metacarta.com>

       Copyright (c) 2006, 2007 Alexander Shishkin <virtuoso@slind.org>

       Copyright (c) 2006, 2007 Lionel Tricon <lionel.tricon@free.fr>

COPYING

       fakechroot is distributed under the GNU Lesser General Public License (LGPL 2.1 or greater).

       Additional copyrights:

       o execl function taken from GNU C Library.  Copyright (C) 1991,92,94,97,98,99,2002,2005 Free Software Foundation, Inc.

       o execle function taken from GNU C Library.  Copyright (C) 1991,97,98,99,2002,2005 Free Software Foundation, Inc.

       o execlp function taken from GNU C Library.  Copyright (C) 1991,93,96,97,98,99,2002,2005 Free Software Foundation, Inc.

       o execvp function taken from GNU C Library.  Copyright (C) 1991,92, 1995-99, 2002, 2004, 2005, 2007, 2009 Free Software Foundation, Inc.

       o 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.

       o ftw function taken from GNU C Library.  Copyright (C) 1996-2004, 2006-2008, 2010 Free Software Foundation, Inc.  This file is part of the
	 GNU C Library.  Contributed by Ulrich Drepper <drepper@cygnus.com>, 1996.

       o __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.

       o popen function taken from OpenBSD.  Copyright (c) 1988, 1993 The Regents of the University of California.

       o rawmemchr function taken from uClibc Copyright (C) 2002 Manuel Novoa III Copyright (C) 2000-2005 Erik Andersen <andersen@uclibc.org>

       o realpath function taken from Gnulib.  Copyright (c) 1996-2010 Free Software Foundation, Inc.

       o rpl_lstat function taken from Gnulib.	Copyright (C) 1997-2006, 2008-2010 Free Software Foundation, Inc.

       o stpcpy function taken from Gnulib.  Copyright (C) 1992, 1995, 1997-1998, 2006, 2009-2010 Free Software Foundation, Inc.

       o strchrnul function taken from Gnulib.	Copyright (C) 2003, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.

Debian								    27 Nov 2011 						     FAKECHROOT(1)