fsfakeroot

ABSTRACT

fsfakeroot creates a "fake" root environment for non-root users with
respect to filesystem operations, such as chown, chmod, and mknod. The
results of these operations are store in the extended filesystem
attributes of the files modified.

This project is more narrow in scope than the original fakeroot
project; it fakes only system calls relating to filesystem operations
and it persists changes only through extended attributes.

IMPLEMENTATION

This project is implemented as a single library which is loaded using
the LD_PRELOAD environment variable. It intercepts and overrides key
system calls to give the running program the illusion of running under
root permissions. Changes in ownership, mode, and device information
are persisted as extended attributes [see attr(5)] attached to the the
modified file.

All extended attributes used fall under the namespace "user.fsfr.*" In
order to make this environment more transparent to the user, the
fsfakeroot library will filter extended attributes with that prefix out
when retrieving an attribute list.

As extended attributes are not allowed on symbolic links, changes
applied to symbolic links are persisted in "proxy" files. See the
SYMBOLIC LINKS section for more information.

USAGE

To use this library, add it to the LD_PRELOAD environment variable.
For example, to start a bash shell with faked root permission, you
could do the following:

    $ LD_PRELOAD=/path/to/fsfakeroot.so bash

To take advantage of the "proxy dir" feature for symbolic links, you
need to also set the FSFR_PROXY_DIR environment variable, as follows:

    $ mkdir /tmp/.proxy
    $ FSFR_PROXY_DIR=/tmp/.proxy LD_PRELOAD=/path/to/fsfakeroot.so bash

See the SYMBOLIC LINKS section for more information.

Any changes you make under your "fake root" environment will be evident
any time you or anyone views the files or directories with the
fsfakeroot library preloaded. 

Note that these changes are superficial only. See the LIMITATIONS
section for more information about how these changes affect your
operating environment.

IMPORTANT: 
YOU SHOULD ALWAYS USE ABSOLUTE PATHS with the LD_PRELOAD and
FSFR_PROXY_DIR variables. If you use a relative path, things will break
if the running progam changes its working directory.

ALTERNATE UIDS

If you would prefer to pretend to be a different user (other than root),
you can do so by setting the environment variables FSFR_UID, FSFR_EUID,
FSFR_GID, and FSFR_EGID accordingly. Calls to setresuid() and setresgid()
are also intercepted and modified to set the appropriate variables.

LIMITATIONS

Some care is taken to ensure that the faked environment is usable to a
reasonable extent, while still maintaining the illusion of running as
root. For example, changing the group and public permission on a file
within the environment will change the appropriate permission bits for
the file itself. However, removing read, write and for directories
execute, permissions from the owner is "faked", since as root, you
can't lock yourself out of your own files.

"Faked" changes made through the fsfakeroot environment are only
visible within the fsfakeroot environment. These chages do not ever
affect the system interaction with the files in question.  For example,
setting the setuid bit within this environment will only give the
appearance of this modification. The operating system will not honor
these modifications, even while running within the fsfakeroot
environment.

In other words, you cannot escalate your privileges in any way through
the use of this library.

The changes made within this environment are visible to anyone who
views the files using this library. However, you can only change the
"faked" atributes on files that you have permission to modify. 

As this library uses extended attributes to persist changes, the kernel
and filesystem in use MUST support user-defined extended attributes in
order for this environment to work. On Linux, these filesystems include
ext2, ext3, ext4, XFS, JFS, reiserfs, and btrfs. If the files are
copied without copying the extended attributes, or if the files are
copied to a filesystem that does not support extended attributes, then
the "faked" modifications will be lost.

SYMBOLIC LINKS

Security policy prohibits attaching user-defined extended attributes to 
symbolic links, so "faked" changes to symbolic links cannot be persisted
in the normal fashion. To compensate, you can optionally use the 
environment variable FSFR_PROXY_DIR to set a location where to store
"proxy" files that will host the attributes associated with symbolic
links. Proxy files are zero-length and are named using the inode number
of the associated symbolic link with the suffix ".fsfr".

The fsfakeroot environment will create the appropriate proxy files if
they do not exist, however, it will never delete these files, even if
you delete the associated symbolic link. YOU ARE RESPONSIBLE FOR
KEEPING THE PROXY DIRECTORY CLEANED OUT.

If you run fsfakeroot on an ongoing basis, you should periodically
prune your proxy directory by removing the files that do not correspond
to an existing symlink. See the prune_proxy.sh script included for an
example of how to do this.

LICENSE

Copyright (c) 2010, Tyler Larson <[email protected]>

This software is licensed under the terms of the MIT license. See
the included file "LICENSE" for more information.