head	1.1;
access;
symbols
	LKML-branch:1.1.0.2;
locks; strict;
comment	@# @;


1.1
date	2006.10.24.06.14.17;	author jsipek;	state dead;
branches
	1.1.2.1;
next	;

1.1.2.1
date	2006.10.24.06.14.17;	author jsipek;	state Exp;
branches;
next	1.1.2.2;

1.1.2.2
date	2006.11.07.06.13.33;	author jsipek;	state Exp;
branches;
next	1.1.2.3;

1.1.2.3
date	2006.12.11.14.23.59;	author jsipek;	state Exp;
branches;
next	1.1.2.4;

1.1.2.4
date	2006.12.31.22.29.19;	author jsipek;	state Exp;
branches;
next	;


desc
@@


1.1
log
@file documentation was initially added on branch LKML-branch.
@
text
@@


1.1.2.1
log
@Move unionfs specific bits into a subdir
@
text
@a0 187
Unionfs: Documentation

From: Josef "Jeff" Sipek <jsipek@@cs.sunysb.edu>

This patch contains documentation for Unionfs. You will find several files
outlining basic unification concepts and rename semantics.

Signed-off-by: Josef "Jeff" Sipek <jsipek@@cs.sunysb.edu>
Signed-off-by: David Quigley <dquigley@@fsl.cs.sunysb.edu>
Signed-off-by: Erez Zadok <ezk@@cs.sunysb.edu>

diff -r 15ef042873c7 Documentation/filesystems/00-INDEX
--- a/Documentation/filesystems/00-INDEX	Sat Oct 07 10:12:11 2006 +0700
+++ b/Documentation/filesystems/00-INDEX	Sat Oct 07 19:08:19 2006 -0400
@@@@ -80,6 +80,8 @@@@ udf.txt
 	- 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 -r 15ef042873c7 Documentation/filesystems/unionfs/00-INDEX
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Documentation/filesystems/unionfs/00-INDEX	Sat Oct 07 19:08:19 2006 -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 -r 15ef042873c7 Documentation/filesystems/unionfs/concepts.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Documentation/filesystems/unionfs/concepts.txt	Sat Oct 07 19:08:19 2006 -0400
@@@@ -0,0 +1,68 @@@@
+This file describes the concepts needed by a namespace 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 namespace. 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 namespace. 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 namespace (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 -r 15ef042873c7 Documentation/filesystems/unionfs/rename.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Documentation/filesystems/unionfs/rename.txt	Sat Oct 07 19:08:19 2006 -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 -r 15ef042873c7 Documentation/filesystems/unionfs/usage.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Documentation/filesystems/unionfs/usage.txt	Mon Oct 09 16:28:44 2006 -0400
@@@@ -0,0 +1,41 @@@@
+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 MOUNTPOINT
+
+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.
+
+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
+RESULT IN DATA LOSS.
+
+Unionfs shouldn't use lookup_one_len on the underlying fs as it confuses
+NFS. Currently, unionfs_lookup passes lookup intents to the lower
+filesystem, this eliminates part of the problem. The remaining calls to
+lookup_one_len may need to be changed to pass an intent.
+
@


1.1.2.2
log
@Git generates slightly different diffs - same information, just little
different
@
text
@d12 4
a15 5
diff --git a/Documentation/filesystems/00-INDEX b/Documentation/filesystems/00-INDEX
index 4dc28cc..c737e3e 100644
--- a/Documentation/filesystems/00-INDEX
+++ b/Documentation/filesystems/00-INDEX
@@@@ -82,6 +82,8 @@@@ udf.txt
d24 3
a26 5
diff --git a/Documentation/filesystems/unionfs/00-INDEX b/Documentation/filesystems/unionfs/00-INDEX
new file mode 100644
index 0000000..fa87f83
--- /dev/null
+++ b/Documentation/filesystems/unionfs/00-INDEX
d36 3
a38 5
diff --git a/Documentation/filesystems/unionfs/concepts.txt b/Documentation/filesystems/unionfs/concepts.txt
new file mode 100644
index 0000000..0b9bcc9
--- /dev/null
+++ b/Documentation/filesystems/unionfs/concepts.txt
d108 3
a110 5
diff --git a/Documentation/filesystems/unionfs/rename.txt b/Documentation/filesystems/unionfs/rename.txt
new file mode 100644
index 0000000..e20bb82
--- /dev/null
+++ b/Documentation/filesystems/unionfs/rename.txt
d143 3
a145 5
diff --git a/Documentation/filesystems/unionfs/usage.txt b/Documentation/filesystems/unionfs/usage.txt
new file mode 100644
index 0000000..8db9158
--- /dev/null
+++ b/Documentation/filesystems/unionfs/usage.txt
@


1.1.2.3
log
@Folded unionfs-lkml-comments-jan
@
text
@d14 2
a15 4

diff -r 89981c5ef6af Documentation/filesystems/00-INDEX
--- a/Documentation/filesystems/00-INDEX	Mon Dec 04 03:26:04 2006 -0500
+++ b/Documentation/filesystems/00-INDEX	Mon Dec 04 03:26:04 2006 -0500
d25 5
a29 3
diff -r 89981c5ef6af Documentation/filesystems/unionfs/00-INDEX
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Documentation/filesystems/unionfs/00-INDEX	Mon Dec 11 08:58:44 2006 -0500
d38 8
a45 7
+	- Usage and known limitations
diff -r 89981c5ef6af Documentation/filesystems/unionfs/concepts.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Documentation/filesystems/unionfs/concepts.txt	Mon Dec 11 08:58:50 2006 -0500
@@@@ -0,0 +1,70 @@@@
+This file describes the concepts needed by a namespace unification file
+system.
d50 2
a51 2
+Each branch is assigned a unique priority - starting from 0 (highest
+priority).  No two branches can have the same priority.
d67 2
a68 2
+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:
d79 4
a82 5
+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 namespace. Again,
+since branch 1 is read-only, the whiteout cannot be created there. So, we
+try on a higher priority (lower numerically) branch and create the whiteout
+there.
d89 2
a90 2
+Later, when Unionfs traverses branches (due to lookup or readdir), it
+eliminate 'foo' from the namespace (as well as the whiteout itself.)
d96 5
a100 5
+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
+(numerically lowest value) and "hide" the others.
d110 1
a110 1
+that lookup and readdir return this newer "version" of the file rather than
d113 5
a117 3
diff -r 89981c5ef6af Documentation/filesystems/unionfs/rename.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Documentation/filesystems/unionfs/rename.txt	Mon Dec 04 03:26:04 2006 -0500
d150 14
a163 12
diff -r 89981c5ef6af Documentation/filesystems/unionfs/usage.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Documentation/filesystems/unionfs/usage.txt	Mon Dec 11 08:58:53 2006 -0500
@@@@ -0,0 +1,42 @@@@
+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.
d170 4
a173 5
+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.
d185 2
a186 2
+The NFS server returns -EACCES for read-only exports, instead of -EROFS.
+This means we can't reliably detect a read-only NFS export.
d188 3
a190 3
+Modifying a Unionfs branch directly, while the union is mounted, is
+currently unsupported.  Any such change can cause Unionfs to oops, or stay
+silent and even RESULT IN DATA LOSS.
d192 2
a193 2
+Unionfs should not use lookup_one_len() on the underlying fs as it confuses
+NFS. Currently, unionfs_lookup() passes lookup intents to the lower
@


1.1.2.4
log
@Small cleanup
@
text
@d12 3
@


