|
@@ -10,10 +10,6 @@ union-filesystems). An overlay-filesystem tries to present a
|
|
filesystem which is the result over overlaying one filesystem on top
|
|
filesystem which is the result over overlaying one filesystem on top
|
|
of the other.
|
|
of the other.
|
|
|
|
|
|
-The result will inevitably fail to look exactly like a normal
|
|
|
|
-filesystem for various technical reasons. The expectation is that
|
|
|
|
-many use cases will be able to ignore these differences.
|
|
|
|
-
|
|
|
|
|
|
|
|
Overlay objects
|
|
Overlay objects
|
|
---------------
|
|
---------------
|
|
@@ -266,6 +262,30 @@ rightmost one and going left. In the above example lower1 will be the
|
|
top, lower2 the middle and lower3 the bottom layer.
|
|
top, lower2 the middle and lower3 the bottom layer.
|
|
|
|
|
|
|
|
|
|
|
|
+Metadata only copy up
|
|
|
|
+--------------------
|
|
|
|
+
|
|
|
|
+When metadata only copy up feature is enabled, overlayfs will only copy
|
|
|
|
+up metadata (as opposed to whole file), when a metadata specific operation
|
|
|
|
+like chown/chmod is performed. Full file will be copied up later when
|
|
|
|
+file is opened for WRITE operation.
|
|
|
|
+
|
|
|
|
+In other words, this is delayed data copy up operation and data is copied
|
|
|
|
+up when there is a need to actually modify data.
|
|
|
|
+
|
|
|
|
+There are multiple ways to enable/disable this feature. A config option
|
|
|
|
+CONFIG_OVERLAY_FS_METACOPY can be set/unset to enable/disable this feature
|
|
|
|
+by default. Or one can enable/disable it at module load time with module
|
|
|
|
+parameter metacopy=on/off. Lastly, there is also a per mount option
|
|
|
|
+metacopy=on/off to enable/disable this feature per mount.
|
|
|
|
+
|
|
|
|
+Do not use metacopy=on with untrusted upper/lower directories. Otherwise
|
|
|
|
+it is possible that an attacker can create a handcrafted file with
|
|
|
|
+appropriate REDIRECT and METACOPY xattrs, and gain access to file on lower
|
|
|
|
+pointed by REDIRECT. This should not be possible on local system as setting
|
|
|
|
+"trusted." xattrs will require CAP_SYS_ADMIN. But it should be possible
|
|
|
|
+for untrusted layers like from a pen drive.
|
|
|
|
+
|
|
Sharing and copying layers
|
|
Sharing and copying layers
|
|
--------------------------
|
|
--------------------------
|
|
|
|
|
|
@@ -284,7 +304,7 @@ though it will not result in a crash or deadlock.
|
|
Mounting an overlay using an upper layer path, where the upper layer path
|
|
Mounting an overlay using an upper layer path, where the upper layer path
|
|
was previously used by another mounted overlay in combination with a
|
|
was previously used by another mounted overlay in combination with a
|
|
different lower layer path, is allowed, unless the "inodes index" feature
|
|
different lower layer path, is allowed, unless the "inodes index" feature
|
|
-is enabled.
|
|
|
|
|
|
+or "metadata only copy up" feature is enabled.
|
|
|
|
|
|
With the "inodes index" feature, on the first time mount, an NFS file
|
|
With the "inodes index" feature, on the first time mount, an NFS file
|
|
handle of the lower layer root directory, along with the UUID of the lower
|
|
handle of the lower layer root directory, along with the UUID of the lower
|
|
@@ -297,6 +317,10 @@ lower root origin, mount will fail with ESTALE. An overlayfs mount with
|
|
does not support NFS export, lower filesystem does not have a valid UUID or
|
|
does not support NFS export, lower filesystem does not have a valid UUID or
|
|
if the upper filesystem does not support extended attributes.
|
|
if the upper filesystem does not support extended attributes.
|
|
|
|
|
|
|
|
+For "metadata only copy up" feature there is no verification mechanism at
|
|
|
|
+mount time. So if same upper is mounted with different set of lower, mount
|
|
|
|
+probably will succeed but expect the unexpected later on. So don't do it.
|
|
|
|
+
|
|
It is quite a common practice to copy overlay layers to a different
|
|
It is quite a common practice to copy overlay layers to a different
|
|
directory tree on the same or different underlying filesystem, and even
|
|
directory tree on the same or different underlying filesystem, and even
|
|
to a different machine. With the "inodes index" feature, trying to mount
|
|
to a different machine. With the "inodes index" feature, trying to mount
|
|
@@ -306,27 +330,40 @@ the copied layers will fail the verification of the lower root file handle.
|
|
Non-standard behavior
|
|
Non-standard behavior
|
|
---------------------
|
|
---------------------
|
|
|
|
|
|
-The copy_up operation essentially creates a new, identical file and
|
|
|
|
-moves it over to the old name. Any open files referring to this inode
|
|
|
|
-will access the old data.
|
|
|
|
|
|
+Overlayfs can now act as a POSIX compliant filesystem with the following
|
|
|
|
+features turned on:
|
|
|
|
+
|
|
|
|
+1) "redirect_dir"
|
|
|
|
+
|
|
|
|
+Enabled with the mount option or module option: "redirect_dir=on" or with
|
|
|
|
+the kernel config option CONFIG_OVERLAY_FS_REDIRECT_DIR=y.
|
|
|
|
+
|
|
|
|
+If this feature is disabled, then rename(2) on a lower or merged directory
|
|
|
|
+will fail with EXDEV ("Invalid cross-device link").
|
|
|
|
+
|
|
|
|
+2) "inode index"
|
|
|
|
+
|
|
|
|
+Enabled with the mount option or module option "index=on" or with the
|
|
|
|
+kernel config option CONFIG_OVERLAY_FS_INDEX=y.
|
|
|
|
|
|
-The new file may be on a different filesystem, so both st_dev and st_ino
|
|
|
|
-of the real file may change. The values of st_dev and st_ino returned by
|
|
|
|
-stat(2) on an overlay object are often not the same as the real file
|
|
|
|
-stat(2) values to prevent the values from changing on copy_up.
|
|
|
|
|
|
+If this feature is disabled and a file with multiple hard links is copied
|
|
|
|
+up, then this will "break" the link. Changes will not be propagated to
|
|
|
|
+other names referring to the same inode.
|
|
|
|
|
|
-Unless "xino" feature is enabled, when overlay layers are not all on the
|
|
|
|
-same underlying filesystem, the value of st_dev may be different for two
|
|
|
|
-non-directory objects in the same overlay filesystem and the value of
|
|
|
|
-st_ino for directory objects may be non persistent and could change even
|
|
|
|
-while the overlay filesystem is still mounted.
|
|
|
|
|
|
+3) "xino"
|
|
|
|
|
|
-Unless "inode index" feature is enabled, if a file with multiple hard
|
|
|
|
-links is copied up, then this will "break" the link. Changes will not be
|
|
|
|
-propagated to other names referring to the same inode.
|
|
|
|
|
|
+Enabled with the mount option "xino=auto" or "xino=on", with the module
|
|
|
|
+option "xino_auto=on" or with the kernel config option
|
|
|
|
+CONFIG_OVERLAY_FS_XINO_AUTO=y. Also implicitly enabled by using the same
|
|
|
|
+underlying filesystem for all layers making up the overlay.
|
|
|
|
|
|
-Unless "redirect_dir" feature is enabled, rename(2) on a lower or merged
|
|
|
|
-directory will fail with EXDEV.
|
|
|
|
|
|
+If this feature is disabled or the underlying filesystem doesn't have
|
|
|
|
+enough free bits in the inode number, then overlayfs will not be able to
|
|
|
|
+guarantee that the values of st_ino and st_dev returned by stat(2) and the
|
|
|
|
+value of d_ino returned by readdir(3) will act like on a normal filesystem.
|
|
|
|
+E.g. the value of st_dev may be different for two objects in the same
|
|
|
|
+overlay filesystem and the value of st_ino for directory objects may not be
|
|
|
|
+persistent and could change even while the overlay filesystem is mounted.
|
|
|
|
|
|
|
|
|
|
Changes to underlying filesystems
|
|
Changes to underlying filesystems
|