linux-fsdevel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
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

  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 \
    --subject='Re: [PATCH 28/39] ovl: fix documentation of non-standard behavior' \
    /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

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).