summaryrefslogtreecommitdiff
path: root/Documentation/filesystems/overlayfs.rst
diff options
context:
space:
mode:
authorMiklos Szeredi <mszeredi@redhat.com>2020-03-17 17:04:22 +0300
committerMiklos Szeredi <mszeredi@redhat.com>2020-03-17 17:04:22 +0300
commit4c494bd582fa23d2d70851e958da6cee1dc161cb (patch)
treecbc418bf35a356a49424a645c8f888110a687e72 /Documentation/filesystems/overlayfs.rst
parent62c832ed4e1b67cc65d909005aae5ce7031a2b38 (diff)
downloadlinux-4c494bd582fa23d2d70851e958da6cee1dc161cb.tar.xz
ovl: document permission model
Add missing piece of documentation regarding how permissions are checked in overlayfs. Signed-off-by: Miklos Szeredi <mszeredi@redhat.com>
Diffstat (limited to 'Documentation/filesystems/overlayfs.rst')
-rw-r--r--Documentation/filesystems/overlayfs.rst44
1 files changed, 44 insertions, 0 deletions
diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst
index e443be7928db..e398fdf7353e 100644
--- a/Documentation/filesystems/overlayfs.rst
+++ b/Documentation/filesystems/overlayfs.rst
@@ -248,6 +248,50 @@ overlay filesystem (though an operation on the name of the file such as
rename or unlink will of course be noticed and handled).
+Permission model
+----------------
+
+Permission checking in the overlay filesystem follows these principles:
+
+ 1) permission check SHOULD return the same result before and after copy up
+
+ 2) task creating the overlay mount MUST NOT gain additional privileges
+
+ 3) non-mounting task MAY gain additional privileges through the overlay,
+ compared to direct access on underlying lower or upper filesystems
+
+This is achieved by performing two permission checks on each access
+
+ a) check if current task is allowed access based on local DAC (owner,
+ group, mode and posix acl), as well as MAC checks
+
+ b) check if mounting task would be allowed real operation on lower or
+ upper layer based on underlying filesystem permissions, again including
+ MAC checks
+
+Check (a) ensures consistency (1) since owner, group, mode and posix acls
+are copied up. On the other hand it can result in server enforced
+permissions (used by NFS, for example) being ignored (3).
+
+Check (b) ensures that no task gains permissions to underlying layers that
+the mounting task does not have (2). This also means that it is possible
+to create setups where the consistency rule (1) does not hold; normally,
+however, the mounting task will have sufficient privileges to perform all
+operations.
+
+Another way to demonstrate this model is drawing parallels between
+
+ mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,... /merged
+
+and
+
+ cp -a /lower /upper
+ mount --bind /upper /merged
+
+The resulting access permissions should be the same. The difference is in
+the time of copy (on-demand vs. up-front).
+
+
Multiple lower layers
---------------------