-
Notifications
You must be signed in to change notification settings - Fork 0
/
fakeroot.1.html
282 lines (281 loc) · 14 KB
/
fakeroot.1.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
<!DOCTYPE html>
<html>
<!-- This is an automatically generated file. Do not edit.
Process this file with
groff -man -Tascii foo.1
"verbatim" environment (from strace.1)
-->
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
<title>fakeroot(1)</title>
</head>
<body>
<table class="head">
<tr>
<td class="head-ltitle">fakeroot(1)</td>
<td class="head-vol">Debian manual</td>
<td class="head-rtitle">fakeroot(1)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp">fakeroot - run a command in an environment faking root privileges
for file manipulation</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><b>fakeroot</b> <b>[-l|--lib</b> <i>library]</i> <b>[--faked</b>
<i>faked-binary</i><b>]</b> <b>[-i</b> <i>load-file</i><b>]</b> <b>[-s</b>
<i>save-file</i><b>]</b> <b>[-u|--unknown-is-real ]</b> <b>[-b|--fd-base
]</b> <b>[-h|--help ]</b> <b>[-v|--version ]</b> <b>[--]</b>
<b>[command]</b></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp"><b>fakeroot</b> runs a command in an environment wherein it
appears to have root privileges for file manipulation. This is useful for
allowing users to create archives (tar, ar, .deb etc.) with files in them
with root permissions/ownership. Without <b>fakeroot</b> one would need to
have root privileges to create the constituent files of the archives with
the correct permissions and ownership, and then pack them up, or one would
have to construct the archives directly, without using the archiver.</p>
<p class="Pp"><b>fakeroot</b> works by replacing the file manipulation library
functions (chmod(2), stat(2) etc.) by ones that simulate the effect the real
library functions would have had, had the user really been root. These
wrapper functions are in a shared library <b>/usr/lib/*/libfakeroot-*.so</b>
or similar location on your platform. The shared object is loaded through
the <b>LD_PRELOAD</b> mechanism of the dynamic loader. (See
<b>ld.so</b>(8))</p>
<p class="Pp">If you intend to build packages with <b>fakeroot</b>, please try
building the fakeroot package first: the "debian/rules build"
stage has a few tests (testing mostly for bugs in old fakeroot versions). If
those tests fail (for example because you have certain libc5 programs on
your system), other packages you build with fakeroot will quite likely fail
too, but possibly in much more subtle ways.</p>
<p class="Pp">Also, note that it's best not to do the building of the binaries
themselves under fakeroot. Especially configure and friends don't like it
when the system suddenly behaves differently from what they expect. (or,
they randomly unset some environment variables, some of which fakeroot
needs).</p>
<p class="Pp"></p>
</section>
<section class="Sh">
<h1 class="Sh" id="OPTIONS"><a class="permalink" href="#OPTIONS">OPTIONS</a></h1>
<dl class="Bl-tag">
<dt id="l"><a class="permalink" href="#l"><b>-l</b> <i>library</i>,
<b>--lib</b> <i>library</i></a></dt>
<dd>Specify an alternative wrapper library.</dd>
<dt id="faked"><a class="permalink" href="#faked"><b>--faked</b><i> binary</i></a></dt>
<dd>Specify an alternative binary to use as faked.</dd>
<dt><b>[--]</b><i> command</i></dt>
<dd>Any command you want to be ran as fakeroot. Use ‘--’ if in
the command you have other options that may confuse fakeroot's option
parsing.</dd>
<dt id="s"><a class="permalink" href="#s"><b>-s</b><i> save-file</i></a></dt>
<dd>Save the fakeroot environment to save-file on exit. This file can be used
to restore the environment later using -i. However, this file will leak
and fakeroot will behave in odd ways unless you leave the files touched
inside the fakeroot alone when outside the environment. Still, this can be
useful. For example, it can be used with rsync(1) to back up and restore
whole directory trees complete with user, group and device information
without needing to be root. See
<i>/usr/share/doc/fakeroot/README.saving</i> for more details.</dd>
<dt id="i"><a class="permalink" href="#i"><b>-i</b><i> load-file</i></a></dt>
<dd>Load a fakeroot environment previously saved using -s from load-file. Note
that this does not implicitly save the file, use -s as well for that
behaviour. Using the same file for both -i and -s in a single
<b>fakeroot</b> invocation is safe.</dd>
<dt id="u"><a class="permalink" href="#u"><b>-u</b>,
<b>--unknown-is-real</b></a></dt>
<dd>Use the real ownership of files previously unknown to fakeroot instead of
pretending they are owned by root:root.</dd>
<dt id="b"><a class="permalink" href="#b"><b>-b</b><i> fd</i></a></dt>
<dd>Specify fd base (TCP mode only). fd is the minimum file descriptor number
to use for TCP connections; this may be important to avoid conflicts with
the file descriptors used by the programs being run under fakeroot.</dd>
<dt id="h"><a class="permalink" href="#h"><b>-h</b></a></dt>
<dd>Display help.</dd>
<dt id="v"><a class="permalink" href="#v"><b>-v</b></a></dt>
<dd>Display version.
<p class="Pp"></p>
</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
<p class="Pp">Here is an example session with <b>fakeroot</b>. Notice that
inside the fake root environment file manipulation that requires root
privileges succeeds, but is not really happening.</p>
<p class="Pp"></p>
<pre>
<span class="Li">$ whoami</span>
<span class="Li">joost</span>
<span class="Li">$ fakeroot /bin/bash</span>
<span class="Li"># whoami</span>
<span class="Li">root</span>
<span class="Li"># mknod hda3 b 3 1</span>
<span class="Li"># ls -ld hda3</span>
<span class="Li">brw-r--r-- 1 root root 3, 1 Jul 2 22:58 hda3</span>
<span class="Li"># chown joost:root hda3</span>
<span class="Li"># ls -ld hda3</span>
<span class="Li">brw-r--r-- 1 joost root 3, 1 Jul 2 22:58 hda3</span>
<span class="Li"># ls -ld /</span>
<span class="Li">drwxr-xr-x 20 root root 1024 Jun 17 21:50 /</span>
<span class="Li"># chown joost:users /</span>
<span class="Li"># chmod a+w /</span>
<span class="Li"># ls -ld /</span>
<span class="Li">drwxrwxrwx 20 joost users 1024 Jun 17 21:50 /</span>
<span class="Li"># exit</span>
<span class="Li">$ ls -ld /</span>
<span class="Li">drwxr-xr-x 20 root root 1024 Jun 17 21:50 //</span>
<span class="Li">$ ls -ld hda3</span>
<span class="Li">-rw-r--r-- 1 joost users 0 Jul 2 22:58 hda3</span>
</pre>
<p class="Pp">Only the effects that user <b>joost</b> could do anyway happen for
real.</p>
<p class="Pp"><b>fakeroot</b> was specifically written to enable users to create
Debian GNU/Linux packages (in the <b>deb(5)</b> format) without giving them
root privileges. This can be done by commands like <b>dpkg-buildpackage
-rfakeroot</b> or <b>debuild -rfakeroot</b> (actually, -rfakeroot is default
in debuild nowadays, so you don't need that argument).</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SECURITY_ASPECTS"><a class="permalink" href="#SECURITY_ASPECTS">SECURITY
ASPECTS</a></h1>
<p class="Pp"><b>fakeroot</b> is a regular, non-setuid program. It does not
enhance a user's privileges, or decrease the system's security.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
<p class="Pp"><i>/usr/lib/*/libfakeroot-*.so</i> The shared library containing
the wrapper functions.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="ENVIRONMENT"><a class="permalink" href="#ENVIRONMENT">ENVIRONMENT</a></h1>
<dl class="Bl-tag">
<dt id="FAKEROOTKEY"><a class="permalink" href="#FAKEROOTKEY">FAKEROOTKEY</a></dt>
<dd>The key used to communicate with the fakeroot daemon. Any program started
with the right <b>LD_PRELOAD</b> and a <b>FAKEROOTKEY</b> of a running
daemon will automatically connect to that daemon, and have the same
"fake" view of the file system's permissions/ownerships.
(assuming the daemon and connecting program were started by the same
user).</dd>
<dt id="LD_LIBRARY_PATH"><a class="permalink" href="#LD_LIBRARY_PATH">LD_LIBRARY_PATH</a></dt>
<dd></dd>
<dt id="LD_PRELOAD"><a class="permalink" href="#LD_PRELOAD">LD_PRELOAD</a></dt>
<dd>Fakeroot is implemented by wrapping system calls. This is accomplished by
setting LD_LIBRARY_PATH=/usr/lib/fakeroot and LD_PRELOAD=libfakeroot.so.0.
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
<b>LD_LIBRARY_PATH</b> or <b>LD_PRELOAD</b> from within a fakeroot
environment, it should be set relative to the given paths, as in
<b>LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/foo/bar/</b>
<p class="Pp"></p>
</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="LIMITATIONS"><a class="permalink" href="#LIMITATIONS">LIMITATIONS</a></h1>
<dl class="Bl-tag">
<dt id="Library"><a class="permalink" href="#Library">Library
versions</a></dt>
<dd>Every command executed within <b>fakeroot</b> needs to be linked to the
same version of the C library as <b>fakeroot</b> itself.</dd>
<dt id="open()/create()"><a class="permalink" href="#open()/create()">open()/create()</a></dt>
<dd>fakeroot doesn't wrap open(), create(), etc. So, if user <b>joost</b> does
either
<p class="Pp"></p>
<pre>
<span class="Li">touch foo</span>
<span class="Li">fakeroot </span>
<span class="Li">ls -al foo</span>
</pre>
<p class="Pp">or the other way around,</p>
<p class="Pp"></p>
<pre>
<span class="Li">fakeroot</span>
<span class="Li">touch foo</span>
<span class="Li">ls -al foo</span>
</pre>
<p class="Pp">fakeroot has no way of knowing that in the first case, the
owner of foo really should be <b>joost</b> while the second case it
should have been <b>root</b>. For the Debian packaging, defaulting to
giving all "unknown" files uid=gid=0, is always OK. The real
way around this is to wrap <b>open()</b> and <b>create()</b>, but that
creates other problems, as demonstrated by the libtricks package. This
package wrapped many more functions, and tried to do a lot more than
<b>fakeroot .</b> It turned out that a minor upgrade of libc (from one
where the <b>stat()</b> function didn't use <b>open()</b> to one with a
<b>stat()</b> function that did (in some cases) use <b>open()</b>),
would cause unexplainable segfaults (that is, the libc6 <b>stat()</b>
called the wrapped <b>open()</b>, which would then call the libc6
<b>stat()</b>, etc). Fixing them wasn't all that easy, but once fixed,
it was just a matter of time before another function started to use
open(), never mind trying to port it to a different operating system.
Thus I decided to keep the number of functions wrapped by fakeroot as
small as possible, to limit the likelihood of
‘collisions’.</p>
</dd>
<dt id="GNU"><a class="permalink" href="#GNU">GNU configure (and other such
programs)</a></dt>
<dd>fakeroot, in effect, is changing the way the system behaves. Programs that
probe the system like GNU configure may get confused by this (or if they
don't, they may stress fakeroot so much that fakeroot itself becomes
confused). So, it's advisable not to run "configure" from within
fakeroot. As configure should be called in the "debian/rules
build" target, running "dpkg-buildpackage -rfakeroot"
correctly takes care of this.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
<p class="Pp">It doesn't wrap open(). This isn't bad by itself, but if a program
does open("file", O_WRONLY, 000), writes to file "file",
closes it, and then again tries to open to read the file, then that open
fails, as the mode of the file will be 000. The bug is that if root does the
same, open() will succeed, as the file permissions aren't checked at all for
root. I choose not to wrap open(), as open() is used by many other functions
in libc (also those that are already wrapped), thus creating loops (or
possible future loops, when the implementation of various libc functions
slightly change).</p>
</section>
<section class="Sh">
<h1 class="Sh" id="COPYING"><a class="permalink" href="#COPYING">COPYING</a></h1>
<p class="Pp"><b>fakeroot</b> is distributed under the GNU General Public
License. (GPL 2.0 or greater).</p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<dl class="Bl-tag">
<dt id="joost"><a class="permalink" href="#joost">joost witteveen</a></dt>
<dd><<i>joostje@debian.org</i>></dd>
<dt id="Clint"><a class="permalink" href="#Clint">Clint Adams</a></dt>
<dd><<i>clint@debian.org</i>></dd>
<dt id="Timo"><a class="permalink" href="#Timo">Timo Savola</a></dt>
<dd></dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="MANUAL_PAGE"><a class="permalink" href="#MANUAL_PAGE">MANUAL
PAGE</a></h1>
<p class="Pp">mostly by J.H.M. Dassen <jdassen@debian.org> Rather a lot
mods/additions by joost and Clint.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><b>faked</b>(1)</p>
<p class="Pp"></p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">5 October 2014</td>
<td class="foot-os">Debian Project</td>
</tr>
</table>
</body>
</html>