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]
10       [-d|--elfloader ldso] [-e|--environment type]
11       [-c|--config-dir directory] [-b|--bindir directory] [--] [command]
12
13       fakechroot -h|--help
14
15       fakechroot -v|--version
16

DESCRIPTION

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
24       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
27       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
31       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

OPTIONS

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
44       -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
49       -d ldso|--elfloader ldso
50           Specify an alternative dynamic linker. This dynamic linker will be
51           invoked directly.
52
53       -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
60           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
65           The configuration file name is type.env and is searched at
66           $HOME/.fakechroot and /etc/fakechroot directories.
67
68           The default environment type is default and its configuration file
69           name is "default.env".
70
71           The special environment none means that no environment settings are
72           loaded at all.
73
74       -l library|--lib library
75           Specify an alternative wrapper library. The default is
76           libfakechroot.so
77
78       -h|--help
79           Display help.
80
81       -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
86           Try this setting if you noticed following errors:
87
88            $ 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
93            $ fakechroot /usr/sbin/chroot /tmp/centos4 /bin/true
94            Segmentation fault
95
96       -v|--version
97           Display version.
98
99       [--] 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

EXAMPLES

105       An example session with fakechroot:
106
107         $ id
108         uid=1000(dexter) gid=1000(dexter) groups=1000(dexter)
109
110         $ 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
117         $ 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
135         $ fakechroot chroot /tmp/sid hello
136         Hello, world!
137

FAKEROOT

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
144         $ fakechroot fakeroot chroot /tmp/sid /bin/mknod /tmp/device c 1 2
145

SECURITY ASPECTS

147       fakechroot is a regular, non-setuid program. It does not enhance a
148       user's privileges.
149
150       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
154       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

FILES

160       libfakechroot.so
161           The shared library containing the wrapper functions.
162

ENVIRONMENT

164       FAKECHROOT
165           The value is true for fake chroot environment.
166
167       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
173       FAKECHROOT_BASE
174           The root directory of fake chroot environment.
175
176       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
182           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
188           For example:
189
190             export FAKECHROOT_CMD_SUBST=/usr/bin/mkfifo=/bin/true
191
192           will substitute "/bin/true" for "/usr/bin/mkfifo" and will make
193           possible to install sysvinit binary package.
194
195           Give as many substitute commands as you want, separated by ":"
196           (colon) characters.
197
198           It is suggested to substitute at least:
199
200           · "/bin/mount=/bin/true"
201
202           · "/sbin/insserv=/bin/true"
203
204           · "/sbin/ldconfig=/bin/true"
205
206           · "/usr/bin/env=/usr/bin/env.fakechroot"
207
208           · "/usr/bin/ischroot=/bin/true"
209
210           · "/usr/bin/ldd=/usr/bin/ldd.fakechroot"
211
212           · "/usr/bin/mkfifo=/bin/true"
213
214           to make debootstrap(8) working correctly.
215
216           To prevent some looping, the command substitution is done only if
217           "FAKECHROOT_CMD_ORIG" variable is not set currently.
218
219       FAKECHROOT_DEBUG
220           The fakechroot library will dump some debugging info if this
221           variable is set.
222
223       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
229             $ case "`FAKECHROOT_DETECT=1 /bin/echo`" in fakechroot*) echo LOADED;; esac
230
231       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
235           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
240       FAKECHROOT_EXCLUDE_PATH
241           The list of directories which are excluded from being chrooted. The
242           elements of list are separated with colon.
243
244           The /dev, /proc and /sys directories are excluded by default if
245           this environment variable is not set.
246
247           This list has to contain at most 100 elements.
248
249       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
256           The default value is "/lib/systemd:/usr/lib/man-db" for
257           systemctl(1) and man(1) commands.
258
259       FAKECHROOT_VERSION
260           The version number of the current fakechroot library.
261
262       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

LIMITATIONS

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
274       ·   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
279       ·   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
284             $ export FAKECHROOT_EXCLUDE_PATH=/tmp:/proc:/dev:/sys:/var/run:/home
285
286       ·   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
290       ·   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
295       ·   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
300       ·   lckpwdf(3) and ulckpwdf(3) are ignored so passwd(1) command should
301           work
302
303       ·   Your real uid should exist in /etc/passwd. Create it with adduser
304           --uid realuid realuser inside fake chroot environment.
305
306       ·   debuild(1) cleans environment. Use --preserve-env option to prevent
307           this behavior.
308
309       ·   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

SEE ALSO

314       fakeroot(1), debuild(1), debootstrap(8), rinse(8),
315       http://fakechroot.alioth.debian.org/
316

BUGS

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

AUTHORS

322       Copyright (c) 2003-2017, 2019 Piotr Roszatycki <dexter@debian.org>
323
324       Copyright (c) 2007 Mark Eichin <eichin@metacarta.com>
325
326       Copyright (c) 2006, 2007 Alexander Shishkin <virtuoso@slind.org>
327
328       Copyright (c) 2006, 2007 Lionel Tricon <lionel.tricon@free.fr>
329

COPYING

331       fakechroot is distributed under the GNU Lesser General Public License
332       (LGPL 2.1 or greater).
333
334
335
336fakechroot                        16 Mar 2019                    FAKECHROOT(1)
Impressum