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