1FAKECHROOT(1) FAKECHROOT(1)
2
6 fakechroot - gives a fake chroot environment
7
9 fakechroot [-s|--use-system-libs] [-l|--lib library]
10 [-d|--elfloader ldso] [-e|--environment type]
11 [-c|--config-dir directory] [-b|--bindir directory] [--] [command]
12 fakechroot -h|--help
14 fakechroot -v|--version
16
18 fakechroot runs a command in an environment where is additional
19 possibility to use chroot(8) command without root privileges. This is
20 useful for allowing users to create own chrooted environment with
21 possibility to install another packages without need for root
22 privileges.
23 fakechroot replaces some C library functions (chroot(2), open(2), etc.)
25 by ones that simulate the effect of being called with root privileges.
26 These wrapper functions are provided as a shared library
28 libfakechroot.so which is loaded through the "LD_PRELOAD" mechanism of
29 the dynamic loader. (See ld.so(8))
30 In fake chroot you can install i.e. Debian bootstrap with
32 debootstrap(8) command. In such environment you can run i.e. apt-get(8)
33 command to install another packages. You don't need a special
34 privileges and you can run it on common user's account.
35
37 -l library|--lib library
38 Specify an alternative wrapper library. The default is
39 libfakechroot.so
40 -d ldso|--elfloader ldso
42 Specify an alternative dynamic linker. This dynamic linker will be
43 invoked directly.
44 -s|--use-system-libs
46 Use system libraries before chroot's libraries. This might be a
47 workaround if system dynamic linker cannot load libc.so from fake
48 chroot.
49 Try this setting if you noticed following errors:
51 $ fakechroot /usr/sbin/chroot /tmp/sarge /bin/true
53 /bin/true: relocation error: /srv/sarge/lib/tls/libc.so.6: symbol _dl
54 _starting_up, version GLIBC_PRIVATE not defined in file ld-linux.so.2
55 with link time reference
56 $ fakechroot /usr/sbin/chroot /tmp/centos4 /bin/true
58 Segmentation fault
59 -e|--environment type
61 Load additional configuration with environment. This configuration
62 file is a shell script which is executed before calling command.
63 The script can set additional environment variables, like i.e.:
64 "FAKECHROOT_EXCLUDE_PATH", "FAKECHROOT_CMD_SUBST" or
65 "LD_LIBRARY_PATH".
66 The environment type is guessed based on command name with optional
68 extension removed (e.g. running gettext.sh loads "gettext"
69 environment file). If command argument is fakeroot(1) this argument
70 is omitted and next argument is taken as environment type.
71 The configuration file name is type.env and is searched at
73 $HOME/.fakechroot and /etc/fakechroot directories.
74 The default environment type is default and its configuration file
76 name is "default.env".
77 The special environment none means that no environment settings are
79 loaded at all.
80 -c|--config-dir directory
82 Specify a directory which contains additional configuration for
83 fakechroot. The default directory are "$HOME/.fakechroot" and
84 "/etc/fakechroot".
85 -b|--bindir directory
87 Specify a directory which contains the replacement executables
88 shipped with fakechroot. Those are script files with the extension
89 ".fakechroot". By default they are distributed over the "bin" and
90 "sbin" directories in fakechroot's install prefix, but sometimes a
91 fixed location at build time is not feasible.
92 [--] command
94 Any command you want to be run as fakechroot. Use '--' if in the
95 command you have other options that may confuse fakechroot's option
96 parsing.
97 -h Display help.
99 -v Display version.
101
103 An example session with fakechroot:
104 $ id
106 uid=1000(dexter) gid=1000(dexter) groups=1000(dexter)
107 $ fakechroot fakeroot debootstrap sid /tmp/sid
109 I: Retrieving Release
110 I: Retrieving Release.gpg
111 I: Checking Release signature
112 ...
113 I: Base system installed successfully.
114 $ fakechroot fakeroot chroot /tmp/sid apt-get install -q hello
116 Reading package lists...
117 Building dependency tree...
118 Reading state information...
119 The following NEW packages will be installed:
120 hello
121 0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded.
122 Need to get 57.4 kB of archives.
123 After this operation, 558 kB of additional disk space will be used.
124 Get:1 http://ftp.us.debian.org/debian/ sid/main hello amd64 2.8-4 [57.4 kB]
125 Fetched 57.4 kB in 0s (127 kB/s)
126 Selecting previously unselected package hello.
127 (Reading database ... 24594 files and directories currently installed.)
128 Unpacking hello (from .../archives/hello_2.8-4_amd64.deb) ...
129 Processing triggers for man-db ...
130 Processing triggers for install-info ...
131 Setting up hello (2.8-4) ...
132 $ fakechroot chroot /tmp/sid hello
134 Hello, world!
135
137 fakeroot(1) is a complementary tool which emulates root environment.
138 fakeroot and fakechroot might wrap the same C library functions, i.e.
139 mknod(2) function. It is important to start fake environment in proper
140 order. fakeroot should be started inside fakechroot:
141 $ fakechroot fakeroot chroot /tmp/sid /bin/mknod /tmp/device c 1 2
143
145 fakechroot is a regular, non-setuid program. It does not enhance a
146 user's privileges.
147 fakechroot should not be used as a tool for enhancing system security
149 i.e. by separating (sandboxing) applications. It is very easy to escape
150 from a fake chroot environment.
151 fakechroot should not be run with real root privileges. It might
153 decrease the security of the system because the fakechroot provides own
154 version of core functions with behavior depended on some environment
155 variables.
156
158 libfakechroot.so
159 The shared library containing the wrapper functions.
160
162 FAKECHROOT
163 The value is true for fake chroot environment.
164 FAKECHROOT_VERSION
166 The version number of the current fakechroot library.
167 FAKECHROOT_BASE
169 The root directory of fake chroot environment.
170 FAKECHROOT_DETECT
172 If this variable is set then "fakechroot version" string is printed
173 to standard output and the current process is terminated with
174 status taken from this variable. It can be a method to check if
175 fakechroot is preloaded correctly.
176 $ case "`FAKECHROOT_DETECT=1 /bin/echo`" in fakechroot*) echo LOADED;; esac
178 FAKECHROOT_DEBUG
180 The fakechroot library will dump some debugging info if this
181 variable is set.
182 FAKECHROOT_AF_UNIX_PATH
184 The root directory for unix sockets. The default value is the same
185 as "FAKECHROOT_BASE" and it can be set separately if the
186 "FAKECHROOT_BASE" is too long and the unix socket path could exceed
187 the limit of 108 bytes.
188 FAKECHROOT_EXCLUDE_PATH
190 The list of directories which are excluded from being chrooted. The
191 elements of list are separated with colon.
192 The /dev, /proc and /sys directories are excluded by default if
194 this environment variable is not set.
195 This list has to contain at most 100 elements.
197 FAKECHROOT_ELFLOADER
199 A path to another dynamic linker (i.e. /lib/ld-linux.so.2 for i386
200 architecture, /lib64/ld-linux-x86-64.so.2 for x86_64 architecture).
201 This dynamic linker will be invoked directly. The dynamic linker
203 don't allow to change "argv[0]" besides the file name of the
204 executable file, so some application won't work correctly, i.e.
205 busybox(1).
206 FAKECHROOT_CMD_SUBST
208 A list of command substitutions. If a program tries to execute one
209 of the commands given (path relative to the chroot, trailing dot is
210 removed) then the substitute command runs instead (path to
211 substitute command is not chrooted).
212 The substituted command inherits "FAKECHROOT_*" variables but the
214 original "FAKECHROOT_BASE" variable which is saved as
215 "FAKECHROOT_BASE_ORIG". It means that substituted command runs
216 outside fakechroot environment. Also original command name is saved
217 as "FAKECHROOT_CMD_ORIG".
218 For example:
220 export FAKECHROOT_CMD_SUBST=/usr/bin/mkfifo=/bin/true
222 will substitute "/bin/true" for "/usr/bin/mkfifo" and will make
224 possible to install sysvinit binary package.
225 Give as many substitute commands as you want, separated by ":"
227 (colon) characters.
228 It is suggested to substitute at least:
230 · "/bin/mount=/bin/true"
232 · "/sbin/insserv=/bin/true"
234 · "/sbin/ldconfig=/bin/ldconfig"
236 · "/usr/bin/env=/usr/bin/env.fakechroot"
238 · "/usr/bin/ischroot=/bin/true"
240 · "/usr/bin/ldd=/usr/bin/ldd.fakechroot"
242 · "/usr/bin/mkfifo=/bin/true"
244 to make debootstrap(8) working correctly.
246 To prevent some looping, the command substitution is done only if
248 "FAKECHROOT_CMD_ORIG" variable is not set currently.
249 LD_LIBRARY_PATH, LD_PRELOAD
251 Fakechroot is implemented by wrapping system calls. This is
252 accomplished by setting "LD_PRELOAD=libfakechroot.so". If this
253 library can't be found by dynamic linker, the /etc/ld.so.conf file
254 or "LD_LIBRARY_PATH" variable have to be modified.
255
257 · /lib/ld-linux.so.2 and /lib64/ld-linux-x86-64.so.2 are always
258 loaded from real environment. This path is hardcoded by linker for
259 all binaries. You can set the "FAKECHROOT_ELFLOADER" environment
260 variable or use "--elfloader" option.
261 · Every command executed within fakechroot needs to be linked to the
263 same version of the dynamic linker from real environment. If the
264 libraries in chroot are not compatible, try to use
265 "--use-system-libs" option.
266 · You can provide symlinks to the outside. The symlink have to be
268 created before chroot is called. It can be useful for accessing the
269 real /proc and /dev directory. You can also set the
270 "FAKECHROOT_EXCLUDE_PATH" environment variable:
271 $ export FAKECHROOT_EXCLUDE_PATH=/tmp:/proc:/dev:/sys:/var/run:/home
273 · Statically linked binaries doesn't work, especially ldconfig(8), so
275 you have to wrap this command with dummy version and set the proper
276 "FAKECHROOT_CMD_SUBST" environment variable.
277 · ldd(1) also doesn't work. You have to use "alias
279 ldd='LD_TRACE_LOADED_OBJECTS=1'" or to use a wrapper instead. The
280 wrapper is installed as ldd.fakechroot and can be used with
281 "FAKECHROOT_CMD_SUBST" environment variable.
282 · The full screen applications hangs up if /dev/tty file is not a
284 real device. Link /dev/tty file or whole /dev directory to the real
285 one or remove it from fake chroot environment with
286 "FAKECHROOT_EXCLUDE_PATH" variable.
287 · lckpwdf(3) and ulckpwdf(3) are ignored so passwd(1) command should
289 work
290 · Your real uid should exist in /etc/passwd. Create it with adduser
292 --uid realuid realuser inside fake chroot environment.
293 · debuild(1) cleans environment. Use --preserve-env option to prevent
295 this behavior.
296 · rpmbuild(8) uses own glob(3) implementation which breaks fakechroot
298 so buildroot directory have to be the same inside and outside
299 fakechroot.
300
302 fakeroot(1), debuild(1), debootstrap(8), rinse(8),
303 http://fakechroot.alioth.debian.org/
304
306 If you find the bug or want to implement new features, please report it
307 at <https://github.com/fakechroot/fakechroot/issues>
308
310 Copyright (c) 2003-2016 Piotr Roszatycki <dexter@debian.org>
311 Copyright (c) 2007 Mark Eichin <eichin@metacarta.com>
313 Copyright (c) 2006, 2007 Alexander Shishkin <virtuoso@slind.org>
315 Copyright (c) 2006, 2007 Lionel Tricon <lionel.tricon@free.fr>
317
319 fakechroot is distributed under the GNU Lesser General Public License
320 (LGPL 2.1 or greater).
321fakechroot 17 Nov 2016 FAKECHROOT(1)