UBUNTU: SAUCE: shiftfs: rework and extend

UBUNTU: SAUCE: shiftfs: rework and extend

BugLink: https://bugs.launchpad.net/bugs/1823186
/* Introduction */
The shiftfs filesystem is implemented as a stacking filesystem. Since it is
a stacking filesystem it shares concepts with overlayfs and ecryptfs.
Usually, shiftfs will be stacked upon another filesystem. The filesystem on
top - shiftfs - is referred to as "upper filesystem" or "overlay" and the
filesystem it is stacked upon is referred to as "lower filesystem" or
"underlay".

/* Marked and Unmarked shiftfs mounts */
To use shiftfs it is necessary that a given mount is marked as shiftable via
the "mark" mount option. Any mount of shiftfs without the "mark" mount option
not on top of a shiftfs mount with the "mark" mount option will be refused with
EPERM.
After a marked shiftfs mount has been performed other shiftfs mounts
referencing the marked shiftfs mount can be created. These secondary shiftfs
mounts are usually what are of interest.
The marked shiftfs mount will take a reference to the underlying mountpoint of
the directory it is marking as shiftable. Any unmarked shiftfts mounts
referencing this marked shifts mount will take a second reference to this
directory as well. This ensures that the underlying marked shiftfs mount can be
unmounted thereby dropping the reference to the underlying directory without
invalidating the mountpoint of said directory since the non-marked shiftfs
mount still holds another reference to it.

/* Stacking Depth */
Shiftfs tries to keep the stack as flat as possible to avoid hitting the
kernel enforced filesystem stacking limit.

/* Permission Model */
When the mark shiftfs mount is created shiftfs will record the credentials of
the creator of the super block and stash it in the super block. When other
non-mark shiftfs mounts are created that reference the mark shiftfs mount they
will stash another reference to the creators credentials. Before calling into
the underlying filesystem shiftfs will switch to the creators credentials and
revert to the original credentials after the underlying filesystem operation
returns.

/* Mount Options */
- mark
  When set the mark mount option indicates that the mount in question is
  allowed to be shifted. Since shiftfs it mountable in by user namespace root
  non-initial user namespace this mount options ensures that the system
  administrator has decided that the marked mount is safe to be shifted.
  To mark a mount as shiftable CAP_SYS_ADMIN in the user namespace is required.
- passthrough={0,1,2,3}
  This mount options functions as a bitmask. When set to a non-zero value
  shiftfs will try to act as an invisible shim sitting on top of the
  underlying filesystem.
  - 1: Shifts will report the filesystem type of the underlay for stat-like
       system calls.
  - 2: Shiftfs will passthrough whitelisted ioctl() to the underlay.
  - 3: Shiftfs will both use 1 and 2.
Note that mount options on a marked mount cannot be changed.

/* Extended Attributes */
Shiftfs will make sure to translate extended attributes.

/* Inodes Numbers */
Shiftfs inodes numbers are copied up from the underlying filesystem, i.e.
shiftfs inode numbers will be identical to the corresponding underlying
filesystem's inode numbers. This has the advantage that inotify and friends
should work out of the box.
(In essence, shiftfs is nothing but a 1:1 mirror of the underlying filesystem's
 dentries and inodes.)

/* Device Support */
Shiftfs only supports the creation of pipe and socket devices. Character and
block devices cannot be created through shiftfs.

Signed-off-by: Christian Brauner <christian.brauner@ubuntu.com>
Signed-off-by: Seth Forshee <seth.forshee@canonical.com>
Acked-by: Tyler Hicks <tyhicks@canonical.com>
Signed-off-by: Seth Forshee <seth.forshee@canonical.com>