From: David Quigley <[email protected]>
This patch contains documentation for Unionfs. You will find several files
outlining basic unification concepts and rename semantics.
Signed-off-by: David Quigley <[email protected]>
Signed-off-by: Josef "Jeff" Sipek <[email protected]>
Signed-off-by: Erez Zadok <[email protected]>
---
Documentation/filesystems/00-INDEX | 2
Documentation/filesystems/unionfs/00-INDEX | 8 ++
Documentation/filesystems/unionfs/concepts.txt | 68 +++++++++++++++++++++++++
Documentation/filesystems/unionfs/rename.txt | 31 +++++++++++
Documentation/filesystems/unionfs/usage.txt | 44 ++++++++++++++++
5 files changed, 153 insertions(+)
diff -Nur -x linux-2.6-git/Documentation/dontdiff linux-2.6-git/Documentation/filesystems/00-INDEX linux-2.6-git-unionfs/Documentation/filesystems/00-INDEX
--- linux-2.6-git/Documentation/filesystems/00-INDEX 2006-08-31 18:43:38.000000000 -0400
+++ linux-2.6-git-unionfs/Documentation/filesystems/00-INDEX 2006-08-31 19:03:48.000000000 -0400
@@ -82,6 +82,8 @@
- info and mount options for the UDF filesystem.
ufs.txt
- info on the ufs filesystem.
+unionfs/
+ - info on the unionfs filesystem
v9fs.txt
- v9fs is a Unix implementation of the Plan 9 9p remote fs protocol.
vfat.txt
diff -Nur -x linux-2.6-git/Documentation/dontdiff linux-2.6-git/Documentation/filesystems/unionfs/00-INDEX linux-2.6-git-unionfs/Documentation/filesystems/unionfs/00-INDEX
--- linux-2.6-git/Documentation/filesystems/unionfs/00-INDEX 1969-12-31 19:00:00.000000000 -0500
+++ linux-2.6-git-unionfs/Documentation/filesystems/unionfs/00-INDEX 2006-08-31 19:26:15.000000000 -0400
@@ -0,0 +1,8 @@
+00-INDEX
+ - this file.
+concepts.txt
+ - A brief introduction of concepts
+rename.txt
+ - Information regarding rename operations
+usage.txt
+ - Usage & known limitations
diff -Nur -x linux-2.6-git/Documentation/dontdiff linux-2.6-git/Documentation/filesystems/unionfs/concepts.txt linux-2.6-git-unionfs/Documentation/filesystems/unionfs/concepts.txt
--- linux-2.6-git/Documentation/filesystems/unionfs/concepts.txt 1969-12-31 19:00:00.000000000 -0500
+++ linux-2.6-git-unionfs/Documentation/filesystems/unionfs/concepts.txt 2006-08-31 19:03:48.000000000 -0400
@@ -0,0 +1,68 @@
+This file describes the concepts needed by a name-space unification file system.
+
+Branch Priority:
+================
+
+Each branch is assigned a unique priority - starting from 0 (highest priority).
+No two branches can have the same priority.
+
+
+Branch Mode:
+============
+
+Each branch is assigned a mode - read-write or read-only. This allows
+directories on media mounted read-write to be used in a read-only manner.
+
+
+Whiteouts:
+==========
+
+A whiteout removes a file name from the name-space. Whiteouts are needed when
+one attempts to remove a file on a read-only branch.
+
+Suppose we have a two branch union, where branch 0 is read-write and branch 1
+is read-only. And a file 'foo' on branch 1:
+
+./b0/
+./b1/
+./b1/foo
+
+The unified view would simply be:
+
+./union/
+./union/foo
+
+Since 'foo' is stored on a read-only branch, it cannot be removed. A whiteout
+is used to remove the name 'foo' from the unified name-space. Again, since
+branch 1 is read-only, the whiteout cannot be created there. So, we try on a
+higher priority (lower numerically) branch. And there we create the whiteout.
+
+./b0/
+./b0/.wh.foo
+./b1/
+./b1/foo
+
+Later, when Unionfs traverses branches (due to lookup or readdir), it eliminate
+'foo' from the name-space (as well as the whiteout itself.)
+
+
+Duplicate Elimination:
+======================
+
+It is possible for files on different branches to have the same name. Unionfs
+then has to select which instance of the file to show to the user. Given the
+fact that each branch has a priority associated with it, the simplest
+solution is to take the instance from the highest priority (lowest numerical
+value) and "hide" the others.
+
+
+Copyup:
+=======
+
+When a change is made to the contents of a file's data or meta-data, they
+have to be stored somewhere. The best way is to create a copy of the
+original file on a branch that is writable, and then redirect the write
+though to this copy. The copy must be made on a higher priority branch so
+that lookup & readdir return this newer "version" of the file rather than
+the original (see duplicate elimination).
+
diff -Nur -x linux-2.6-git/Documentation/dontdiff linux-2.6-git/Documentation/filesystems/unionfs/rename.txt linux-2.6-git-unionfs/Documentation/filesystems/unionfs/rename.txt
--- linux-2.6-git/Documentation/filesystems/unionfs/rename.txt 1969-12-31 19:00:00.000000000 -0500
+++ linux-2.6-git-unionfs/Documentation/filesystems/unionfs/rename.txt 2006-08-31 19:03:48.000000000 -0400
@@ -0,0 +1,31 @@
+Rename is a complex beast. The following table shows which rename(2) operations
+should succeed and which should fail.
+
+o: success
+E: error (either unionfs or vfs)
+X: EXDEV
+
+none = file does not exist
+file = file is a file
+dir = file is a empty directory
+child= file is a non-empty directory
+wh = file is a directory containing only whiteouts; this makes it logically
+ empty
+
+ none file dir child wh
+file o o E E E
+dir o E o E o
+child X E X E X
+wh o E o E o
+
+
+Renaming directories:
+=====================
+
+Whenever a empty (either physically or logically) directory is being renamed,
+the following sequence of events should take place:
+
+1) Remove whiteouts from both source and destination directory
+2) Rename source to destination
+3) Make destination opaque to prevent anything under it from showing up
+
diff -Nur -x linux-2.6-git/Documentation/dontdiff linux-2.6-git/Documentation/filesystems/unionfs/usage.txt linux-2.6-git-unionfs/Documentation/filesystems/unionfs/usage.txt
--- linux-2.6-git/Documentation/filesystems/unionfs/usage.txt 1969-12-31 19:00:00.000000000 -0500
+++ linux-2.6-git-unionfs/Documentation/filesystems/unionfs/usage.txt 2006-08-31 19:25:19.000000000 -0400
@@ -0,0 +1,44 @@
+Unionfs is a stackable unification file system, which can appear to merge the
+contents of several directories (branches), while keeping their physical
+content separate. Unionfs is useful for unified source tree management, merged
+contents of split CD-ROM, merged separate software package directories, data
+grids, and more. Unionfs allows any mix of read-only and read-write branches,
+as well as insertion and deletion of branches anywhere in the fan-out. To
+maintain unix semantics, Unionfs handles elimination of duplicates,
+partial-error conditions, and more.
+
+mount -t unionfs -o branch-option[,union-options[,...]] none unionfs
+
+The available branch-option for the mount command is:
+
+dirs=branch[=ro|=rw][:...]
+specifies a separated list of which directories compose the union. Directories
+that come earlier in the list have a higher precedence than those which come
+later. Additionally, read-only or read-write permissions of the branch can be
+specified by appending =ro or =rw (default) to each directory.
+
+Syntax:
+dirs=/branch1[=ro|=rw]:/branch2[=ro|=rw]:...:/branchN[=ro|=rw]
+
+Example:
+dirs=/writable_branch=rw:/read-only_branch=ro
+
+
+KNOWN ISSUES:
+=============
+
+The NFS server returns -EACCES for read-only exports, instead of -EROFS. This
+means we can't reliably detect a read-only NFS export. If you want to use
+copy-on-write with NFS, set the per-branch option `nfsro'. If this flag is
+set, then Unionfs will apply standard Unix permissions to files on this
+nfs-mouted branch.
+
+Modifying a Unionfs branch directly, while the union is mounted is currently
+unsupported. Any such change can cause Unionfs to oops, however it could even
+BRESULT IN DATA LOSS.
+
+The PPC module loading algorithm has an O(N^2) loop, so it takes a while to
+load the Unionfs module, because we have lots of symbols.
+
+Unionfs shouldn't use lookup_one_len on the underlying fs as it confuses NFS.
+
-
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]
