| .\" Process this file with |
| .\" groff -man -Tascii foo.1 |
| .\" |
| .\" "verbatim" environment (from strace.1) |
| .de CW |
| .sp |
| .nf |
| .ft CW |
| .. |
| .de CE |
| .ft |
| .fi |
| .sp |
| .. |
| .\" |
| .TH fakeroot 1 "5 October 2014" "Debian Project" "Debian manual" |
| .\" Manpage by J.H.M. Dassen <jdassen@debian.org> |
| .\" and Clint Adams <clint@debian.org> |
| .SH NAME |
| fakeroot \- run a command in an environment faking root privileges for file |
| manipulation |
| .SH SYNOPSIS |
| .B fakeroot |
| .B [\-l|\-\-lib |
| .IB library] |
| .B [\-\-faked |
| .IB faked-binary ] |
| .B [\-i |
| .IB load-file ] |
| .B [\-s |
| .IB save-file ] |
| .B [\-u|\-\-unknown\-is\-real ] |
| .B [\-b|\-\-fd\-base ] |
| .B [\-h|\-\-help ] |
| .B [\-v|\-\-version ] |
| .BI [\-\-] |
| .BI [command] |
| .SH DESCRIPTION |
| .B fakeroot |
| 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 |
| 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. |
| |
| .B fakeroot |
| 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 |
| or similar location on your platform. |
| The shared object is loaded through the |
| .B LD_PRELOAD |
| mechanism of the dynamic loader. (See |
| .BR ld.so (8)) |
| |
| If you intend to build packages with |
| .BR fakeroot , |
| 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. |
| |
| 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). |
| |
| .SH OPTIONS |
| .TP |
| \fB\-l\fR \fIlibrary\fR, \fB\-\-lib\fR \fIlibrary\fR |
| Specify an alternative wrapper library. |
| .TP |
| .BI \-\-faked \ binary |
| Specify an alternative binary to use as faked. |
| .TP |
| .BI [\-\-] \ command |
| Any command you want to be ran as fakeroot. Use \(oq\-\-\(cq if in the command |
| you have other options that may confuse fakeroot's option parsing. |
| .TP |
| .BI \-s \ save-file |
| 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 |
| for more details. |
| .TP |
| .BI \-i \ load-file |
| 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 |
| .BR fakeroot |
| invocation is safe. |
| .TP |
| \fB\-u\fR, \fB\-\-unknown\-is\-real\fR |
| Use the real ownership of files previously unknown to fakeroot instead of |
| pretending they are owned by root:root. |
| .TP |
| .BI \-b \ fd |
| 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. |
| .TP |
| .BI \-h |
| Display help. |
| .TP |
| .BI \-v |
| Display version. |
| |
| .SH EXAMPLES |
| Here is an example session with |
| .BR fakeroot . |
| Notice that inside the fake root environment file manipulation that |
| requires root privileges succeeds, but is not really happening. |
| .CW |
| $ whoami |
| joost |
| $ fakeroot /bin/bash |
| # whoami |
| root |
| # mknod hda3 b 3 1 |
| # ls \-ld hda3 |
| brw\-r\-\-r\-\- 1 root root 3, 1 Jul 2 22:58 hda3 |
| # chown joost:root hda3 |
| # ls \-ld hda3 |
| brw\-r\-\-r\-\- 1 joost root 3, 1 Jul 2 22:58 hda3 |
| # ls \-ld / |
| drwxr\-xr\-x 20 root root 1024 Jun 17 21:50 / |
| # chown joost:users / |
| # chmod a+w / |
| # ls \-ld / |
| drwxrwxrwx 20 joost users 1024 Jun 17 21:50 / |
| # exit |
| $ ls \-ld / |
| drwxr\-xr\-x 20 root root 1024 Jun 17 21:50 // |
| $ ls \-ld hda3 |
| \-rw\-r\-\-r\-\- 1 joost users 0 Jul 2 22:58 hda3 |
| .CE |
| Only the effects that user |
| .B joost |
| could do anyway happen for real. |
| |
| .B fakeroot |
| was specifically written to enable users to create Debian GNU/Linux |
| packages (in the |
| .BR deb(5) |
| format) without giving them root privileges. |
| This can be done by commands like |
| .B dpkg-buildpackage \-rfakeroot |
| or |
| .B debuild \-rfakeroot |
| (actually, \-rfakeroot is default in debuild nowadays, so you don't |
| need that argument). |
| .SH SECURITY ASPECTS |
| .B fakeroot |
| is a regular, non-setuid program. It does not enhance a user's |
| privileges, or decrease the system's security. |
| .SH FILES |
| .I /usr/lib/*/libfakeroot-*.so |
| The shared library containing the wrapper functions. |
| .SH ENVIRONMENT |
| .B |
| .IP FAKEROOTKEY |
| The key used to communicate with the fakeroot daemon. Any program |
| started with the right |
| .B LD_PRELOAD |
| and a |
| .B FAKEROOTKEY |
| 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). |
| .B |
| .IP LD_LIBRARY_PATH |
| .B |
| .IP LD_PRELOAD |
| 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 |
| or |
| .B LD_PRELOAD |
| 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/ |
| |
| .SH LIMITATIONS |
| .B |
| .IP "Library versions" |
| Every command executed within |
| .B fakeroot |
| needs to be linked to the same version of the C library as |
| .B fakeroot |
| itself. |
| .B |
| .IP open()/create() |
| fakeroot doesn't wrap open(), create(), etc. So, if user |
| .B joost |
| does either |
| .CW |
| touch foo |
| fakeroot |
| ls \-al foo |
| .CE |
| or the other way around, |
| .CW |
| fakeroot |
| touch foo |
| ls \-al foo |
| .CE |
| fakeroot has no way of knowing that in the first case, the owner of |
| foo really should be |
| .B joost |
| while the second case it should have been |
| .BR root . |
| 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() |
| and |
| .BR create() , |
| 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 . |
| It turned out that a minor upgrade of libc (from one where the |
| .BR stat() |
| function didn't use |
| .BR open() |
| to one with a |
| .BR stat() |
| function that did (in some cases) use |
| .BR open() ), |
| would cause unexplainable segfaults (that is, the libc6 |
| .BR stat() |
| called the wrapped |
| .BR open() , |
| which would then call the libc6 |
| .BR stat() , |
| 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 \(oqcollisions\(cq. |
| .B |
| .IP "GNU configure (and other such programs)" |
| 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. |
| .SH BUGS |
| 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). |
| .SH COPYING |
| .B fakeroot |
| is distributed under the GNU General Public License. |
| (GPL 2.0 or greater). |
| .SH AUTHORS |
| .TP |
| joost witteveen |
| .RI < joostje@debian.org > |
| .TP |
| Clint Adams |
| .RI < clint@debian.org > |
| .TP |
| Timo Savola |
| .SH MANUAL PAGE |
| mostly by J.H.M. Dassen |
| .RI <jdassen@debian.org> |
| Rather a lot mods/additions by joost and Clint. |
| .SH "SEE ALSO" |
| .BR faked (1) |
| .BR dpkg\-buildpackage (1), |
| .BR debuild (1) |
| .BR /usr/share/doc/fakeroot/DEBUG |
| |