From: Erez Zadok <[email protected]>
Describe dynamic branch-management introduced by subsequent patches.
Signed-off-by: Erez Zadok <[email protected]>
Signed-off-by: Josef 'Jeff' Sipek <[email protected]>
---
Documentation/filesystems/unionfs/concepts.txt | 5 ++
Documentation/filesystems/unionfs/issues.txt | 22 +++++++-
Documentation/filesystems/unionfs/usage.txt | 61 +++++++++++++++++++++++-
3 files changed, 84 insertions(+), 4 deletions(-)
diff --git a/Documentation/filesystems/unionfs/concepts.txt b/Documentation/filesystems/unionfs/concepts.txt
index d417576..83d45b9 100644
--- a/Documentation/filesystems/unionfs/concepts.txt
+++ b/Documentation/filesystems/unionfs/concepts.txt
@@ -1,3 +1,6 @@
+Unionfs 2.0 CONCEPTS:
+=====================
+
This file describes the concepts needed by a namespace unification file
system.
@@ -68,3 +71,5 @@ though to this copy. The copy must be made on a higher priority branch so
that lookup and readdir return this newer "version" of the file rather than
the original (see duplicate elimination).
+
+For more information, see <http://unionfs.filesystems.org/>.
diff --git a/Documentation/filesystems/unionfs/issues.txt b/Documentation/filesystems/unionfs/issues.txt
index b070175..a434fee 100644
--- a/Documentation/filesystems/unionfs/issues.txt
+++ b/Documentation/filesystems/unionfs/issues.txt
@@ -1,5 +1,5 @@
-KNOWN Unionfs ISSUES:
-=====================
+KNOWN Unionfs 2.0 ISSUES:
+=========================
1. The NFS server returns -EACCES for read-only exports, instead of -EROFS.
This means we can't reliably detect a read-only NFS export.
@@ -14,10 +14,26 @@ KNOWN Unionfs ISSUES:
introducing small VFS/MM changes that would allow a file system to handle
cache coherency correctly.
+ Unionfs 2.0 has a temporary workaround for this. You can force Unionfs
+ to increase the superblock generation number, and hence purge all cached
+ Unionfs objects, which would then be re-gotten from the lower branches.
+ This should ensure cache consistency. To increase the generation number,
+ executed the command:
+
+ mount -t unionfs -o remount,incgen none MOUNTPOINT
+
+ Note that the older way of incrementing the generation number using an
+ ioctl, is no longer supported in Unionfs 2.0. Ioctls in general are not
+ encouraged. Plus, an ioctl is per-file concept, whereas the generation
+ number is a per-file-system concept. Worse, such an ioctl requires an
+ open file, which then has to be invalidated by the very nature of the
+ generation number increase (read: the old generation increase ioctl was
+ pretty racy).
+
3. Unionfs should not use lookup_one_len() on the underlying f/s as it
confuses NFS. Currently, unionfs_lookup() passes lookup intents to the
lower file-system, this eliminates part of the problem. The remaining
calls to lookup_one_len may need to be changed to pass an intent.
-For more information, see <unionfs.filesystems.org>.
+For more information, see <http://unionfs.filesystems.org/>.
diff --git a/Documentation/filesystems/unionfs/usage.txt b/Documentation/filesystems/unionfs/usage.txt
index 14e0856..13fbcea 100644
--- a/Documentation/filesystems/unionfs/usage.txt
+++ b/Documentation/filesystems/unionfs/usage.txt
@@ -28,4 +28,63 @@ Example:
dirs=/writable_branch=rw:/read-only_branch=ro
-For more information, see unionfs.filesystems.org.
+DYNAMIC BRANCH MANAGEMENT AND REMOUNTS
+======================================
+
+You can remount a union and change its overall mode, or reconfigure the
+branches, as follows.
+
+To downgrade a union from read-write to read-only:
+
+# mount -t unionfs -o remount,ro none MOUNTPOINT
+
+To upgrade a union from read-only to read-write:
+
+# mount -t unionfs -o remount,rw none MOUNTPOINT
+
+To delete a branch /foo, regardless where it is in the current union:
+
+# mount -t unionfs -o del=/foo none MOUNTPOINT
+
+To insert (add) a branch /foo before /bar:
+
+# mount -t unionfs -o remount,add=/bar:/foo none MOUNTPOINT
+
+To insert (add) a branch /foo (with the "rw" mode flag) before /bar:
+
+# mount -t unionfs -o remount,add=/bar:/foo=rw none MOUNTPOINT
+
+To insert (add) a branch /foo (in "rw" mode) at the very beginning (i.e., a
+new highest-priority branch), you can use the above syntax, or use a short
+hand version as follows:
+
+# mount -t unionfs -o remount,add=/foo none MOUNTPOINT
+
+To append a branch to the very end (new lowest-priority branch):
+
+# mount -t unionfs -o remount,add=:/foo none MOUNTPOINT
+
+To append a branch to the very end (new lowest-priority branch), in
+read-only mode:
+
+# mount -t unionfs -o remount,add=:/foo:ro none MOUNTPOINT
+
+Finally, to change the mode of one existing branch, say /foo, from read-only
+to read-write, and change /bar from read-write to read-only:
+
+# mount -t unionfs -o remount,mode=/foo=rw,mode=/bar=ro none MOUNTPOINT
+
+
+CACHE CONSISTENCY
+=================
+
+If you modify any file on any of the lower branches directly, while there is
+a Unionfs 2.0 mounted above any of those branches, you should tell Unionfs
+to purge its caches and re-get the objects. To do that, you have to
+incremenet the generation number of the superblock using the following
+command:
+
+# mount -t unionfs -o remount,remount,incgen none MOUNTPOINT
+
+
+For more information, see <http://unionfs.filesystems.org/>.
--
1.5.0.3.268.g3dda
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
[Index of Archives]
[Kernel Newbies]
[Netfilter]
[Bugtraq]
[Photo]
[Stuff]
[Gimp]
[Yosemite News]
[MIPS Linux]
[ARM Linux]
[Linux Security]
[Linux RAID]
[Video 4 Linux]
[Linux for the blind]
[Linux Resources]
