fakechroot(1)

1FAKECHROOT(1)                                                    FAKECHROOT(1)
2
3
4

NAME

6       fakechroot - gives a fake chroot environment
7

SYNOPSIS

9       fakechroot [-s|--use-system-libs] [-l|--lib library] [--] [command]
10

DESCRIPTION

12       fakechroot runs a command in an environment were is additional
13       possibility to use chroot(8) command without root privileges.  This is
14       useful for allowing users to create own chrooted environment with
15       possibility to install another packages without need for root
16       privileges.
17
18       fakechroot replaces more library functions (chroot(2), open(2), etc.)
19       by ones that simulate the effect the real library functions would have
20       had, had the user really been in chroot.  These wrapper functions are
21       in a shared library /usr/lib/fakechroot/libfakechroot.so which is
22       loaded through the LD_PRELOAD mechanism of the dynamic loader.  (See
23       ld.so(8))
24
25       In fake chroot you can install Debian bootstrap with `debootstrap
26       --variant=fakechroot' command.  In this environment you can use i.e.
27       apt-get(8) command to install another packages from common user's
28       account.
29
30       In the current version, the fakechroot does not provide the fakeroot(1)
31       functionality! You might to call fakechroot with fakeroot command, if
32       you want to emulate root environment, i.e.:
33
34        $ fakeroot fakechroot /usr/sbin/chroot /tmp/debian /bin/sh
35        # id
36        uid=0(root) gid=0(root) groups=0(root)
37

OPTIONS

39       -l library|--lib library
40           Specify an alternative wrapper library.
41
42       -s|--use-system-libs
43           Use system libraries before chroot's libraries.  This might be a
44           workaround if system dynamic linker (/lib/ld-linux.so.2 for Linux)
45           can not load libc.so from fake chroot.
46
47           Try this setting if you noticed following errors:
48
49            $ fakechroot /usr/sbin/chroot /tmp/sarge /bin/true
50            /bin/true: relocation error: /srv/sarge/lib/tls/libc.so.6: symbol _dl
51            _starting_up, version GLIBC_PRIVATE not defined in file ld-linux.so.2
52             with link time reference
53
54            $ fakechroot /usr/sbin/chroot /tmp/centos4 /bin/true
55            Segmentation fault
56
57       [--] command
58           Any command you want to be ran as fakechroot.  Use '--' if in the
59           command you have other options that may confuse fakechroot's option
60           parsing.
61
62       -h  Display help.
63
64       -v  Display version.
65

EXAMPLES

67       An example session with fakechroot:
68
69        $ export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin
70        :/bin:/usr/bin/X11
71        $ fakeroot -s fakechroot.save fakechroot debootstrap --variant=fakech
72        root lenny /tmp/lenny
73
74        $ fakeroot -i fakechroot.save fakechroot chroot /tmp/lenny /bin/bash
75        # cd /
76        # sh /usr/share/doc/fakechroot/examples/savemode.sh
77        # echo deb http://ftp.debian.org/debian lenny main contrib non-free >
78        /etc/apt/sources.list
79        # echo deb-src http://ftp.debian.org/debian lenny main contrib non-fr
80        ee >> /etc/apt/sources.list
81        # apt-get update
82        # apt-get install adduser whiptail build-essential devscripts
83        # adduser --uid 1001 user
84        # cd /tmp
85        # apt-get source hello
86        # cd hello-*
87        # debuild --preserve-env -b
88        # exit
89

SECURITY ASPECTS

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

FILES

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

ENVIRONMENT

99       FAKECHROOT
100           The value is true for fake chroot environment.
101
102       FAKECHROOT_VERSION
103           The version of current fakechroot library.
104
105       FAKECHROOT_BASE
106           The root directory for fake chroot environment.
107
108       FAKECHROOT_EXCLUDE_PATH
109           The list of directories which are excluded from being chrooted.
110           The elements of list are separated with colon.
111
112       FAKECHROOT_CMD_SUBST
113           A list of command substitutions.  If a program tries to execute one
114           of the commands given (path relative to the chroot) then the
115           substitute command runs instead (path to substitute command is not
116           chrooted).
117
118           For example:
119
120            FAKECHROOT_CMD_SUBST=/sbin/ldconfig=/tmp/ldconfig-wrapper
121
122           will substitute "/tmp/ldconfig-wrapper" for "/sbin/ldconfig".
123
124           Give as many substitute commands as you want, separated by ":"
125           (colon) characters.
126
127       LD_LIBRARY_PATH, LD_PRELOAD
128           Fakechroot is implemented by wrapping system calls.  This is
129           accomplished by setting LD_LIBRARY_PATH=/usr/lib/fakechroot and
130           LD_PRELOAD=libfakechroot.so.  That library is loaded before the
131           system's C library, and so most of the library functions are
132           intercepted by it.  If you need to set either LD_LIBRARY_PATH or
133           LD_PRELOAD from within a fakechroot environment, it should be set
134           relative to the given paths, as in
135           LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/foo/bar/
136

LIMITATIONS

138       o   /lib/ld-linux.so.2 is always loaded from real environment.  This
139           path is hardcoded by linker for all binaries.
140
141       o   Every command executed within fakechroot needs to be linked to the
142           same version of the C library as fakechroot itself.  If the
143           libraries in chroot are not compatible, try to use
144           --use-system-libs option.
145
146       o   You can provide symlinks to the outside.  The symlink have to be
147           created before chroot is called.  It can be useful for accessing
148           the real /proc and /dev directory.  You can also set the
149           FAKECHROOT_EXCLUDE_PATH environment variable:
150
151            $ export FAKECHROOT_EXCLUDE_PATH=/tmp:/proc:/dev:/var/run
152
153       o   Statically linked binaries doesn't work, especially ldconfig(8), so
154           you have to wrap this command with dummy version and i.e. set the
155           dpkg diversion, see: dpkg-divert(8).
156
157       o   ldd(1) also doesn't work.  You have to use "alias
158           ldd='LD_TRACE_LOADED_OBJECTS=1'" or to use a wrapper instead.  The
159           example wrapper is available at scripts/ directory in fakechroot's
160           source package and it is located at
161           /usr/share/doc/fakechroot/examples directory.
162
163       o   The full screen applications hangs up if /dev/tty file is not a
164           real device.  Link /dev/tty file or whole /dev directory to the
165           real one or remove it from fake chroot environment.
166
167       o   lckpwdf() and ulckpwdf() are ignored so passwd(1) command should
168           work
169
170       o   Your real uid should exist in /etc/passwd.  Create it with adduser
171           --uid realuid realuser.
172
173       o   debuild(1) cleans environment.  Use --preserve-env option to
174           prevent this behaviour.
175

COPYING

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

AUTHORS

181       Copyright (c) 2003-2008 Piotr Roszatycki <dexter@debian.org>
182
183       Copyright (c) 2006-2007 Lionel Tricon <lionel.tricon@free.fr>
184
185       Copyright (c) 2007 Mark Eichin <eichin@metacarta.com>
186