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 v2 35/35] ovl: fix documentation of non-standard behavior
Date: Mon, 7 May 2018 10:38:07 +0200 [thread overview]
Message-ID: <20180507083807.28792-36-mszeredi@redhat.com> (raw)
In-Reply-To: <20180507083807.28792-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 961b287ef323..97eae826adf9 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
prev parent reply other threads:[~2018-05-07 8:40 UTC|newest]
Thread overview: 53+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-05-07 8:37 [PATCH v2 00/35] overlayfs: stack file operations Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 01/35] vfs: add path_open() Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 02/35] vfs: optionally don't account file in nr_files Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 03/35] vfs: add f_op->pre_mmap() Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 04/35] vfs: export vfs_ioctl() to modules Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 05/35] vfs: export vfs_dedupe_file_range_one() " Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 06/35] ovl: copy up times Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 07/35] ovl: copy up inode flags Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 08/35] Revert "Revert "ovl: get_write_access() in truncate"" Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 09/35] ovl: copy up file size as well Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 10/35] ovl: deal with overlay files in ovl_d_real() Miklos Szeredi
2018-05-07 13:17 ` Vivek Goyal
2018-05-07 8:37 ` [PATCH v2 11/35] ovl: stack file ops Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 12/35] ovl: add helper to return real file Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 13/35] ovl: add ovl_read_iter() Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 14/35] ovl: add ovl_write_iter() Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 15/35] ovl: add ovl_fsync() Miklos Szeredi
2018-05-08 5:14 ` Amir Goldstein
2018-05-08 14:57 ` Miklos Szeredi
2018-05-08 15:02 ` Amir Goldstein
2018-05-07 8:37 ` [PATCH v2 16/35] ovl: add ovl_mmap() Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 17/35] ovl: add ovl_fallocate() Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 18/35] ovl: add lsattr/chattr support Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 19/35] ovl: add ovl_fiemap() Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 20/35] ovl: add O_DIRECT support Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 21/35] ovl: add reflink/copyfile/dedup support Miklos Szeredi
2018-05-07 20:43 ` Darrick J. Wong
2018-05-08 14:13 ` Miklos Szeredi
2018-05-08 14:38 ` Darrick J. Wong
2018-05-07 8:37 ` [PATCH v2 22/35] vfs: don't open real Miklos Szeredi
2018-05-07 10:27 ` Amir Goldstein
2018-05-07 10:29 ` Miklos Szeredi
2018-05-11 18:54 ` Vivek Goyal
2018-05-11 19:42 ` Vivek Goyal
2018-05-14 13:58 ` Vivek Goyal
2018-05-15 20:42 ` Vivek Goyal
2018-05-14 14:03 ` Daniel Walsh
2018-05-07 8:37 ` [PATCH v2 23/35] ovl: copy-up on MAP_SHARED Miklos Szeredi
2018-05-07 19:28 ` Randy Dunlap
2018-05-08 15:03 ` Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 24/35] vfs: simplify dentry_open() Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 25/35] Revert "ovl: fix may_write_real() for overlayfs directories" Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 26/35] Revert "ovl: don't allow writing ioctl on lower layer" Miklos Szeredi
2018-05-07 8:37 ` [PATCH v2 27/35] vfs: fix freeze protection in mnt_want_write_file() for overlayfs Miklos Szeredi
2018-05-07 8:38 ` [PATCH v2 28/35] Revert "ovl: fix relatime for directories" Miklos Szeredi
2018-05-07 8:38 ` [PATCH v2 29/35] Revert "vfs: update ovl inode before relatime check" Miklos Szeredi
2018-05-07 8:38 ` [PATCH v2 30/35] Revert "vfs: add flags to d_real()" Miklos Szeredi
2018-05-07 8:38 ` [PATCH v2 31/35] Revert "vfs: do get_write_access() on upper layer of overlayfs" Miklos Szeredi
2018-05-07 8:38 ` [PATCH v2 32/35] Partially revert "locks: fix file locking on overlayfs" Miklos Szeredi
2018-05-08 15:15 ` Jeff Layton
2018-05-07 8:38 ` [PATCH v2 33/35] Revert "fsnotify: support overlayfs" Miklos Szeredi
2018-05-07 8:38 ` [PATCH v2 34/35] vfs: remove open_flags from d_real() Miklos Szeredi
2018-05-07 8:38 ` Miklos Szeredi [this message]
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=20180507083807.28792-36-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).