From: Miklos Szeredi <mszeredi@redhat.com>
To: linux-unionfs@vger.kernel.org
Cc: linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: [PATCH 28/39] ovl: fix documentation of non-standard behavior
Date: Tue, 29 May 2018 16:43:28 +0200 [thread overview]
Message-ID: <20180529144339.16538-29-mszeredi@redhat.com> (raw)
In-Reply-To: <20180529144339.16538-1-mszeredi@redhat.com>
We can now drop description of the ro/rw inconsistency from the
documentation.
Also clarify, that now fully standard compliant behavior can be enabled
with kernel/module/mount options.
Signed-off-by: Miklos Szeredi <mszeredi@redhat.com>
---
Documentation/filesystems/overlayfs.txt | 60 +++++++++++++++++++++------------
1 file changed, 39 insertions(+), 21 deletions(-)
diff --git a/Documentation/filesystems/overlayfs.txt b/Documentation/filesystems/overlayfs.txt
index 72615a2c0752..f087bc40c6a5 100644
--- a/Documentation/filesystems/overlayfs.txt
+++ b/Documentation/filesystems/overlayfs.txt
@@ -10,10 +10,6 @@ union-filesystems). An overlay-filesystem tries to present a
filesystem which is the result over overlaying one filesystem on top
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
---------------
@@ -306,27 +302,49 @@ the copied layers will fail the verification of the lower root file handle.
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.
+
+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.
+
+3) "xino"
+
+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.
-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 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.
-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.
+4) "copy_up_shared"
-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 or module option "copy_up_shared=on" or with
+the kernel config option CONFIG_OVERLAY_FS_COPY_UP_SHARED=y.
-Unless "redirect_dir" feature is enabled, rename(2) on a lower or merged
-directory will fail with EXDEV.
+If this feature is disabled, then a memory mapping created with MAP_SHARED
+might contain stale data if the file has been copied up and modified in the
+meantime.
Changes to underlying filesystems
--
2.14.3
next prev parent reply other threads:[~2018-05-29 14:44 UTC|newest]
Thread overview: 83+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-05-29 14:43 [PATCH 00/39] overlayfs: stack file operations Miklos Szeredi
2018-05-29 14:43 ` [PATCH 01/39] vfs: dedpue: return loff_t Miklos Szeredi
2018-06-04 8:43 ` Christoph Hellwig
2018-06-05 8:33 ` Miklos Szeredi
2018-06-06 15:09 ` Darrick J. Wong
2018-06-18 20:08 ` Miklos Szeredi
2018-05-29 14:43 ` [PATCH 02/39] vfs: dedupe: rationalize args Miklos Szeredi
2018-06-06 15:02 ` Darrick J. Wong
2018-05-29 14:43 ` [PATCH 03/39] vfs: dedupe: extract helper for a single dedup Miklos Szeredi
2018-05-29 15:41 ` Amir Goldstein
2018-05-29 16:04 ` Amir Goldstein
2018-06-04 8:44 ` Christoph Hellwig
2018-05-29 14:43 ` [PATCH 04/39] vfs: add path_open() Miklos Szeredi
2018-06-04 8:46 ` Christoph Hellwig
2018-06-10 4:36 ` Al Viro
2018-05-29 14:43 ` [PATCH 05/39] vfs: optionally don't account file in nr_files Miklos Szeredi
2018-06-04 8:47 ` Christoph Hellwig
2018-06-04 8:57 ` Miklos Szeredi
2018-06-10 4:41 ` Al Viro
2018-05-29 14:43 ` [PATCH 06/39] vfs: add f_op->pre_mmap() Miklos Szeredi
2018-06-04 8:48 ` Christoph Hellwig
2018-06-05 11:36 ` Miklos Szeredi
2018-05-29 14:43 ` [PATCH 07/39] vfs: export vfs_ioctl() to modules Miklos Szeredi
2018-06-04 8:49 ` Christoph Hellwig
2018-06-10 4:57 ` Al Viro
2018-06-11 7:19 ` Miklos Szeredi
2018-06-11 16:24 ` Christoph Hellwig
2018-06-19 14:04 ` Miklos Szeredi
2018-06-19 14:24 ` Christoph Hellwig
2018-06-19 14:34 ` Miklos Szeredi
2018-06-19 14:54 ` Al Viro
2018-05-29 14:43 ` [PATCH 08/39] vfs: export vfs_dedupe_file_range_one() " Miklos Szeredi
2018-05-29 14:43 ` [PATCH 09/39] ovl: copy up times Miklos Szeredi
2018-05-29 14:43 ` [PATCH 10/39] ovl: copy up inode flags Miklos Szeredi
2018-05-29 14:43 ` [PATCH 11/39] Revert "Revert "ovl: get_write_access() in truncate"" Miklos Szeredi
2018-05-29 14:43 ` [PATCH 12/39] ovl: copy up file size as well Miklos Szeredi
2018-05-29 14:43 ` [PATCH 13/39] ovl: deal with overlay files in ovl_d_real() Miklos Szeredi
2018-05-29 14:43 ` [PATCH 14/39] ovl: stack file ops Miklos Szeredi
2018-06-10 4:13 ` Al Viro
2018-06-11 7:09 ` Miklos Szeredi
2018-06-12 2:29 ` Al Viro
2018-06-12 2:40 ` Al Viro
2018-06-12 9:24 ` Miklos Szeredi
2018-06-12 18:24 ` Al Viro
2018-06-12 18:31 ` Al Viro
2018-06-13 9:21 ` Miklos Szeredi
2018-06-15 5:47 ` Al Viro
2018-06-18 11:50 ` Miklos Szeredi
2018-06-13 11:56 ` J. R. Okajima
2018-05-29 14:43 ` [PATCH 15/39] ovl: add helper to return real file Miklos Szeredi
2018-06-10 5:42 ` Al Viro
2018-06-11 8:11 ` Miklos Szeredi
2018-05-29 14:43 ` [PATCH 16/39] ovl: add ovl_read_iter() Miklos Szeredi
2018-05-29 14:43 ` [PATCH 17/39] ovl: add ovl_write_iter() Miklos Szeredi
2018-05-29 14:43 ` [PATCH 18/39] ovl: add ovl_fsync() Miklos Szeredi
2018-05-29 14:43 ` [PATCH 19/39] ovl: add ovl_mmap() Miklos Szeredi
2018-06-10 5:24 ` Al Viro
2018-06-11 7:58 ` Miklos Szeredi
2018-05-29 14:43 ` [PATCH 20/39] ovl: add ovl_fallocate() Miklos Szeredi
2018-05-29 14:43 ` [PATCH 21/39] ovl: add lsattr/chattr support Miklos Szeredi
2018-05-29 14:43 ` [PATCH 22/39] ovl: add ovl_fiemap() Miklos Szeredi
2018-05-29 14:43 ` [PATCH 23/39] ovl: add O_DIRECT support Miklos Szeredi
2018-06-10 5:31 ` Al Viro
2018-06-11 8:08 ` Miklos Szeredi
2018-05-29 14:43 ` [PATCH 24/39] ovl: add reflink/copyfile/dedup support Miklos Szeredi
2018-05-29 14:43 ` [PATCH 25/39] vfs: don't open real Miklos Szeredi
2018-05-29 14:43 ` [PATCH 26/39] ovl: copy-up on MAP_SHARED Miklos Szeredi
2018-05-29 14:43 ` [PATCH 27/39] ovl: obsolete "check_copy_up" module option Miklos Szeredi
2018-05-29 15:13 ` Amir Goldstein
2018-05-30 8:26 ` Miklos Szeredi
2018-05-29 14:43 ` Miklos Szeredi [this message]
2018-05-29 14:43 ` [PATCH 29/39] vfs: simplify dentry_open() Miklos Szeredi
2018-05-29 14:43 ` [PATCH 30/39] Revert "ovl: fix may_write_real() for overlayfs directories" Miklos Szeredi
2018-05-29 14:43 ` [PATCH 31/39] Revert "ovl: don't allow writing ioctl on lower layer" Miklos Szeredi
2018-05-29 14:43 ` [PATCH 32/39] vfs: fix freeze protection in mnt_want_write_file() for overlayfs Miklos Szeredi
2018-06-04 8:50 ` Christoph Hellwig
2018-05-29 14:43 ` [PATCH 33/39] Revert "ovl: fix relatime for directories" Miklos Szeredi
2018-05-29 14:43 ` [PATCH 34/39] Revert "vfs: update ovl inode before relatime check" Miklos Szeredi
2018-05-29 14:43 ` [PATCH 35/39] Revert "vfs: add flags to d_real()" Miklos Szeredi
2018-05-29 14:43 ` [PATCH 36/39] Revert "vfs: do get_write_access() on upper layer of overlayfs" Miklos Szeredi
2018-05-29 14:43 ` [PATCH 37/39] Partially revert "locks: fix file locking on overlayfs" Miklos Szeredi
2018-05-29 14:43 ` [PATCH 38/39] Revert "fsnotify: support overlayfs" Miklos Szeredi
2018-05-29 14:43 ` [PATCH 39/39] vfs: remove open_flags from d_real() Miklos Szeredi
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20180529144339.16538-29-mszeredi@redhat.com \
--to=mszeredi@redhat.com \
--cc=linux-fsdevel@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-unionfs@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).