1fakeroot(1)                      Debian manual                     fakeroot(1)
2
3
4

NAME

6       fakeroot  -  run a command in an environment faking root privileges for
7       file manipulation
8

SYNOPSIS

10       fakeroot [-l|--lib library] [--faked faked-binary] [-i  load-file]  [-s
11       save-file]   [-u|--unknown-is-real   ]  [-b|--fd-base  ]  [-h|--help  ]
12       [-v|--version ] [--] [command]
13

DESCRIPTION

15       fakeroot runs a command in an environment wherein it  appears  to  have
16       root  privileges  for  file  manipulation.  This is useful for allowing
17       users to create archives (tar, ar, .deb etc.) with files in  them  with
18       root  permissions/ownership.   Without  fakeroot one would need to have
19       root privileges to create the constituent files of  the  archives  with
20       the  correct  permissions  and ownership, and then pack them up, or one
21       would have to  construct  the  archives  directly,  without  using  the
22       archiver.
23
24       fakeroot  works  by  replacing  the file manipulation library functions
25       (chmod(2), stat(2) etc.) by ones that  simulate  the  effect  the  real
26       library  functions would have had, had the user really been root. These
27       wrapper functions are  in  a  shared  library  /usr/lib/libfakeroot.so*
28       which is loaded through the LD_PRELOAD mechanism of the dynamic loader.
29       (See ld.so(8))
30
31       If you intend to build packages with fakeroot, please try building  the
32       fakeroot  package first: the "debian/rules build" stage has a few tests
33       (testing mostly for bugs in old fakeroot versions). If those tests fail
34       (for  example  because you have certain libc5 programs on your system),
35       other packages you build with fakeroot will quite likely fail too,  but
36       possibly in much more subtle ways.
37
38       Also,  note that it's best not to do the building of the binaries them‐
39       selves under fakeroot. Especially configure and friends don't  like  it
40       when  the  system  suddenly  behaves differently from what they expect.
41       (or, they randomly unset some  environment  variables,  some  of  which
42       fakeroot needs).
43
44

OPTIONS

46       -l library, --lib library
47              Specify an alternative wrapper library.
48
49       --faked binary
50              Specify an alternative binary to use as faked.
51
52       [--] command
53              Any  command  you want to be ran as fakeroot. Use ‘--’ if in the
54              command you have  other  options  that  may  confuse  fakeroot's
55              option parsing.
56
57       -s save-file
58              Save  the  fakeroot  environment to save-file on exit. This file
59              can be used to restore the environment later using -i.  However,
60              this  file will leak and fakeroot will behave in odd ways unless
61              you leave the files touched inside the fakeroot alone when  out‐
62              side the environment. Still, this can be useful. For example, it
63              can be used with rsync(1) to back up and restore whole directory
64              trees  complete  with user, group and device information without
65              needing to be  root.  See  /usr/share/doc/fakeroot/README.saving
66              for more details.
67
68       -i load-file
69              Load a fakeroot environment previously saved using -s from load-
70              file.  Note that this does not implicitly save the file, use  -s
71              as  well for that behaviour. Using the same file for both -i and
72              -s in a single fakeroot invocation is safe.
73
74       -u, --unknown-is-real
75              Use the real ownership of files previously unknown  to  fakeroot
76              instead of pretending they are owned by root:root.
77
78       -b fd  Specify fd base (TCP mode only). fd is the minimum file descrip‐
79              tor number to use for TCP connections; this may be important  to
80              avoid  conflicts  with the file descriptors used by the programs
81              being run under fakeroot.
82
83       -h     Display help.
84
85       -v     Display version.
86
87

EXAMPLES

89       Here is an example session with fakeroot.  Notice that inside the  fake
90       root  environment  file manipulation that requires root privileges suc‐
91       ceeds, but is not really happening.
92
93       $  whoami
94       joost
95       $ fakeroot /bin/bash
96       #  whoami
97       root
98       # mknod hda3 b 3 1
99       # ls -ld hda3
100       brw-r--r--   1 root     root       3,   1 Jul  2 22:58 hda3
101       # chown joost:root hda3
102       # ls -ld hda3
103       brw-r--r--   1 joost    root       3,   1 Jul  2 22:58 hda3
104       # ls -ld /
105       drwxr-xr-x  20 root     root         1024 Jun 17 21:50 /
106       # chown joost:users /
107       # chmod a+w /
108       # ls -ld /
109       drwxrwxrwx  20 joost    users        1024 Jun 17 21:50 /
110       # exit
111       $ ls -ld /
112       drwxr-xr-x  20 root     root         1024 Jun 17 21:50 //
113       $ ls -ld hda3
114       -rw-r--r--   1 joost    users           0 Jul  2 22:58 hda3
115
116       Only the effects that user joost could do anyway happen for real.
117
118       fakeroot was specifically written to  enable  users  to  create  Debian
119       GNU/Linux  packages  (in  the  deb(5)  format) without giving them root
120       privileges.  This  can  be  done  by  commands  like  dpkg-buildpackage
121       -rfakeroot  or  debuild  -rfakeroot (actually, -rfakeroot is default in
122       debuild nowadays, so you don't need that argument).
123

SECURITY ASPECTS

125       fakeroot is a regular, non-setuid program. It does not enhance a user's
126       privileges, or decrease the system's security.
127

FILES

129       /usr/lib/libfakeroot/libfakeroot.so*  The shared library containing the
130       wrapper functions.
131

ENVIRONMENT

133       FAKEROOTKEY
134              The key used to communicate with the fakeroot daemon.  Any  pro‐
135              gram  started  with  the right LD_PRELOAD and a FAKEROOTKEY of a
136              running daemon will automatically connect to  that  daemon,  and
137              have  the same "fake" view of the file system's permissions/own‐
138              erships.  (assuming  the  daemon  and  connecting  program  were
139              started by the same user).
140
141       LD_LIBRARY_PATH
142
143       LD_PRELOAD
144              Fakeroot  is  implemented  by  wrapping  system  calls.  This is
145              accomplished by  setting  LD_LIBRARY_PATH=/usr/lib/fakeroot  and
146              LD_PRELOAD=libfakeroot.so.0.   That library is loaded before the
147              system's C library, and so most of  the  library  functions  are
148              intercepted by it.  If you need to set either LD_LIBRARY_PATH or
149              LD_PRELOAD from within a fakeroot environment, it should be  set
150              relative      to      the      given      paths,      as      in
151              LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/foo/bar/
152
153

LIMITATIONS

155       Library versions
156              Every command executed within fakeroot needs to be linked to the
157              same version of the C library as fakeroot itself.
158
159       open()/create()
160              fakeroot  doesn't  wrap open(), create(), etc. So, if user joost
161              does either
162
163              touch foo
164              fakeroot
165              ls -al foo
166
167              or the other way around,
168
169              fakeroot
170              touch foo
171              ls -al foo
172
173              fakeroot has no way of knowing that in the first case, the owner
174              of  foo  really  should be joost while the second case it should
175              have been root.  For the Debian packaging, defaulting to  giving
176              all "unknown" files uid=gid=0, is always OK. The real way around
177              this is to wrap open() and  create(),  but  that  creates  other
178              problems, as demonstrated by the libtricks package. This package
179              wrapped many more functions, and tried to do  a  lot  more  than
180              fakeroot .  It turned out that a minor upgrade of libc (from one
181              where the stat() function didn't use open() to one with a stat()
182              function that did (in some cases) use open()), would cause unex‐
183              plainable segfaults  (that  is,  the  libc6  stat()  called  the
184              wrapped  open(),  which  would then call the libc6 stat(), etc).
185              Fixing them wasn't all that easy, but once fixed, it was just  a
186              matter  of  time  before another function started to use open(),
187              never mind trying to port it to a  different  operating  system.
188              Thus  I decided to keep the number of functions wrapped by fake‐
189              root as small as possible, to limit the  likelihood  of  ‘colli‐
190              sions’.
191
192       GNU configure (and other such programs)
193              fakeroot,  in  effect,  is  changing the way the system behaves.
194              Programs that probe the system like GNU configure may  get  con‐
195              fused  by  this  (or  if they don't, they may stress fakeroot so
196              much that fakeroot itself becomes confused). So, it's  advisable
197              not to run "configure" from within fakeroot. As configure should
198              be  called  in  the   "debian/rules   build"   target,   running
199              "dpkg-buildpackage -rfakeroot" correctly takes care of this.
200

BUGS

202       It doesn't wrap open(). This isn't bad by itself, but if a program does
203       open("file", O_WRONLY, 000), writes to file "file", closes it, and then
204       again tries to open to read the file, then that open fails, as the mode
205       of the file will be 000. The bug is that if root does the same,  open()
206       will succeed, as the file permissions aren't checked at all for root. I
207       choose not to wrap open(), as open() is used by many other functions in
208       libc  (also  those  that  are already wrapped), thus creating loops (or
209       possible future loops, when the implementation of  various  libc  func‐
210       tions slightly change).
211

COPYING

213       fakeroot is distributed under the GNU General Public License.  (GPL 2.0
214       or greater).
215

AUTHORS

217       joost witteveen
218              <joostje@debian.org>
219
220       Clint Adams
221              <schizo@debian.org>
222
223       Timo Savola
224

MANUAL PAGE

226       mostly by J.H.M. Dassen <jdassen@debian.org> Rather  a  lot  mods/addi‐
227       tions by joost and Clint.
228

SEE ALSO

230       faked(1) dpkg-buildpackage(1), debuild(1) /usr/share/doc/fakeroot/DEBUG
231
232
233
234
235Debian Project                   6 August 2004                     fakeroot(1)
Impressum