aboutsummaryrefslogtreecommitdiff
path: root/Documentation/filesystems
diff options
context:
space:
mode:
authorLinus Torvalds2020-12-17 11:42:48 -0800
committerLinus Torvalds2020-12-17 11:42:48 -0800
commit92dbc9dedccb9759c7f9f2f0ae6242396376988f (patch)
tree514f252b670bd1ad9b848ff4a8eefb0d1a0a6d12 /Documentation/filesystems
parent65de0b89d7d5e173d71cb50dfae786133c579308 (diff)
parent459c7c565ac36ba09ffbf24231147f408fde4203 (diff)
Merge tag 'ovl-update-5.11' of git://git.kernel.org/pub/scm/linux/kernel/git/mszeredi/vfs
Pull overlayfs updates from Miklos Szeredi: - Allow unprivileged mounting in a user namespace. For quite some time the security model of overlayfs has been that operations on underlying layers shall be performed with the privileges of the mounting task. This way an unprvileged user cannot gain privileges by the act of mounting an overlayfs instance. A full audit of all function calls made by the overlayfs code has been performed to see whether they conform to this model, and this branch contains some fixes in this regard. - Support running on copied filesystem images by optionally disabling UUID verification. - Bug fixes as well as documentation updates. * tag 'ovl-update-5.11' of git://git.kernel.org/pub/scm/linux/kernel/git/mszeredi/vfs: ovl: unprivieged mounts ovl: do not get metacopy for userxattr ovl: do not fail because of O_NOATIME ovl: do not fail when setting origin xattr ovl: user xattr ovl: simplify file splice ovl: make ioctl() safe ovl: check privs before decoding file handle vfs: verify source area in vfs_dedupe_file_range_one() vfs: move cap_convert_nscap() call into vfs_setxattr() ovl: fix incorrect extent info in metacopy case ovl: expand warning in ovl_d_real() ovl: document lower modification caveats ovl: warn about orphan metacopy ovl: doc clarification ovl: introduce new "uuid=off" option for inodes index feature ovl: propagate ovl_fs to ovl_decode_real_fh and ovl_encode_real_fh
Diffstat (limited to 'Documentation/filesystems')
-rw-r--r--Documentation/filesystems/overlayfs.rst36
1 files changed, 28 insertions, 8 deletions
diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst
index 580ab9a0fe31..587a93973929 100644
--- a/Documentation/filesystems/overlayfs.rst
+++ b/Documentation/filesystems/overlayfs.rst
@@ -97,11 +97,13 @@ directory trees to be in the same filesystem and there is no
requirement that the root of a filesystem be given for either upper or
lower.
-The lower filesystem can be any filesystem supported by Linux and does
-not need to be writable. The lower filesystem can even be another
-overlayfs. The upper filesystem will normally be writable and if it
-is it must support the creation of trusted.* extended attributes, and
-must provide valid d_type in readdir responses, so NFS is not suitable.
+A wide range of filesystems supported by Linux can be the lower filesystem,
+but not all filesystems that are mountable by Linux have the features
+needed for OverlayFS to work. The lower filesystem does not need to be
+writable. The lower filesystem can even be another overlayfs. The upper
+filesystem will normally be writable and if it is it must support the
+creation of trusted.* and/or user.* extended attributes, and must provide
+valid d_type in readdir responses, so NFS is not suitable.
A read-only overlay of two read-only filesystems may use any
filesystem type.
@@ -467,14 +469,18 @@ summarized in the `Inode properties`_ table above.
Changes to underlying filesystems
---------------------------------
-Offline changes, when the overlay is not mounted, are allowed to either
-the upper or the lower trees.
-
Changes to the underlying filesystems while part of a mounted overlay
filesystem are not allowed. If the underlying filesystem is changed,
the behavior of the overlay is undefined, though it will not result in
a crash or deadlock.
+Offline changes, when the overlay is not mounted, are allowed to the
+upper tree. Offline changes to the lower tree are only allowed if the
+"metadata only copy up", "inode index", and "redirect_dir" features
+have not been used. If the lower tree is modified and any of these
+features has been used, the behavior of the overlay is undefined,
+though it will not result in a crash or deadlock.
+
When the overlay NFS export feature is enabled, overlay filesystems
behavior on offline changes of the underlying lower layer is different
than the behavior when NFS export is disabled.
@@ -563,6 +569,11 @@ This verification may cause significant overhead in some cases.
Note: the mount options index=off,nfs_export=on are conflicting for a
read-write mount and will result in an error.
+Note: the mount option uuid=off can be used to replace UUID of the underlying
+filesystem in file handles with null, and effectively disable UUID checks. This
+can be useful in case the underlying disk is copied and the UUID of this copy
+is changed. This is only applicable if all lower/upper/work directories are on
+the same filesystem, otherwise it will fallback to normal behaviour.
Volatile mount
--------------
@@ -583,6 +594,15 @@ fresh one. In very limited cases where the user knows that the system has
not crashed and contents of upperdir are intact, The "volatile" directory
can be removed.
+
+User xattr
+----------
+
+The the "-o userxattr" mount option forces overlayfs to use the
+"user.overlay." xattr namespace instead of "trusted.overlay.". This is
+useful for unprivileged mounting of overlayfs.
+
+
Testsuite
---------