commit 8d94aa6d048ed6823e48f5e705f6f70b96935a13
Author: Erez_Zadok <[EMAIL PROTECTED]>
Date: Fri Apr 13 16:49:56 2007 -0400
Update ODF design and usage documents
diff --git a/Documentation/filesystems/unionfs/00-INDEX
b/Documentation/filesystems/unionfs/00-INDEX
index 96fdf67..11e8c2c 100644
--- a/Documentation/filesystems/unionfs/00-INDEX
+++ b/Documentation/filesystems/unionfs/00-INDEX
@@ -4,6 +4,8 @@ concepts.txt
- A brief introduction of concepts.
issues.txt
- A summary of known issues with unionfs.
+odf.txt
+ - On-Disk Format (ODF) design and implementation.
rename.txt
- Information regarding rename operations.
usage.txt
diff --git a/Documentation/filesystems/unionfs/odf.txt
b/Documentation/filesystems/unionfs/odf.txt
index bb3b751..4f36035 100644
--- a/Documentation/filesystems/unionfs/odf.txt
+++ b/Documentation/filesystems/unionfs/odf.txt
@@ -1,6 +1,6 @@
- ODF: On Disk Format for Unionfs 2.x
+ ODF: On Disk Format for Unionfs 2.x
- March 24, 2007
+ (Updated April 13, 2007)
http://unionfs.filesystems.org/
@@ -27,10 +27,10 @@ can be retrieved easily.
Both of the above problems can be solved if Unionfs could store certain
amount of data persistently. This is accomplished using the On Disk Format
(ODF) support in Unionfs. Briefly stated, Unionfs uses another small file
-system partition or loop device, and another file system (e.g., Ext2), to
-store persistent data such as whiteout information, cached directories, and
-more. This, as you will see, solves *many* of the problems that stackable
-file systems such as Unionfs have to deal with.
+system partition or loop device, and another file system (e.g., ext2, XFS,
+etc.), to store persistent data such as whiteout information, cached
+directories, and more. This, as you will see, solves *many* of the problems
+that stackable file systems such as Unionfs have to deal with.
* ODF SOLVES IMPORTANT ISSUES
@@ -47,10 +47,12 @@ they prevent anyone from actually creating a file which may
start with
".wh". Also, writing those special files over various file systems,
especially network file systems, introduces various races.
-Instead, the new ODF code stores whiteouts as hardlinks to a special file in
-odf (odf/sb/whiteout) and opaqueness information for directories in the inode
-gid bits in an Ext2 file system on the local machine. This avoid the
name-space
-pollution and avoids races with network file systems.
+Instead, the new ODF code stores whiteouts as hardlinks to a special
+(regular) zero-length file in odf (/odf/whiteout), and it stores opaqueness
+information for directories in the inode GID bits in an ODF file system
+(e.g., ext2, XFS, etc.) on the local machine. This avoids the name-space
+pollution and avoids races with network file systems, while minimizing inode
+consummation in /odf.
2. Inode numbers must be persistent indefinitely.
@@ -170,9 +172,8 @@ normal user's view.
An /odf is a hierarchy of directories and files with specific purposes, as
follows:
-1. /odf/sb contains the whiteoute file and a file containing our superblock,
- which records branch configuration, UUIDs, etc. Each branch has a unique
- UUID so it can be identified consistently.
+1. /odf/sb is a plain file which records branch configuration, UUIDs, etc.
+ Each branch has a unique UUID so it can be identified consistently.
2. /odf/ns/<PATH> is used for storing information about whiteouts, opaque
directories, and persistent inode numbers. We use the actual inum of the
@@ -201,8 +202,8 @@ follows:
records the name of the hardlink, but with the inum of the *parent*
directory (e.g., <name,dirinum>). We need to store the parent inum so
that the hard-linked file's name can be found by searching the parent
- dir. A modification in path_lookup is needed that will allow us to lookup
- the file using only its name and its directory's inum.
+ dir. (Note: a modification to path_lookup is needed to allow us to
+ lookup the file using only its name and its directory's inum.)
We do not store the number of links here, because that can change (a user
can delete one link while we're still trying to discover the rest of the
@@ -224,6 +225,10 @@ follows:
and go cleanup some space in /odf, until it drops below a (configurable)
threshold.
+6. /odf/whiteout is a zero length plain file which we hard link to, from
+ /odf/ns/<PATH>, whenever we need to indicate that <PATH> is a whiteout
+ file.
+
** The ODF superblock
@@ -246,22 +251,31 @@ The ODF superblock (/odf/sb) stores the following:
Actions:
-1. To prepare a new ODF, just run "mkfs" on the /odf partition, and set the
- "new" bit.
+1. To prepare a new ODF, simply run "mkfs" on the /odf partition. Or, if
+ you already have a formatted /odf, you can mount it and them "rm -rf"
+ everything inside directly.
+
+2. on mount, check if /odf/sb exists; get the number and list of branches,
+ and their UUIDs, and store them in this file.
-2. on mount, check if config file in /odf/sb exists; get the number and list
- of branches, and their UUIDs, and store them in the config file.
+ If /osf/sb does not exist, then we know that we're mounting a new /odf
+ for the first time; in that case, create the /odf hierarchy: /sb,
+ /whiteout, /ic, /ns, and /reclaim. If we find that /odf/sb did not
+ exist, but some of the others do exist, then we assume that the /odf is
+ corrupt, and we fail the mount with an error message.
3. on remount, if we reconfigure the branches, then
-(a) /odf/sb/config must exist (else BUG_ON)
+(a) /odf/sb must exist (else BUG_ON)
-(b) update /odf/sb/co file
+(b) update /odf/sb file
-(c) if "odfforce" flag was not specified clean the dir cache in /odf/ic
+(c) if the "odfforce" flag was not specified, then clean the dir cache in
+ /odf/ic
-(d) otherwise, if you really wants to use an existing /odf cache (with
- possibly some stale info), then use options "remount,odfforce".
+(d) otherwise, if you really want to use an existing /odf cache (with
+ possibly some stale info), then use the mount options
+ "remount,odfforce".
** Whiteouts and Opaque Dir actions
@@ -474,7 +488,7 @@ Let dcache/icache algorithms figure out when to purge stuff.
This means we'll need lots of inodes in /odf, so mkfs it appropriately. Our
current estimate is to create around 3000 to 3500 inodes per MB in the odf
-using "mke2fs -i NNN"
+using "mkfs -t FOOFS -i NNN"
* Hardlinks
diff --git a/Documentation/filesystems/unionfs/usage.txt
b/Documentation/filesystems/unionfs/usage.txt
index 1a2420f..1caf182 100644
--- a/Documentation/filesystems/unionfs/usage.txt
+++ b/Documentation/filesystems/unionfs/usage.txt
@@ -112,34 +112,38 @@ possibly stale ODF:
# mount -t unionfs -o odfforce,odf=/odf none MOUNTPOINT
# mount -t unionfs -o remount,odfforce,add=...
-We use configfs to define three global variables for all mounted unions, to
-control cache cleaning. The following assumes that you mount configfs in
-/config. We have 5 variables
+We use configfs to define several global variables for all mounted unions,
+to control cache cleaning, and more. The following assumes that you mount
+configfs in /config.
-1. timeout: defaults to 30 seconds. Controls the interval when the ODF
- cleanup thread will wake up. You can use configfs to view the value:
+1. timeout: defaults to 30 seconds. Controls the interval when the ODF
+ cleanup thread will wake up. You can use configfs to view the value:
# cat /config/unionfs/timeout
- and you can change value, say reduce it to 15 seconds, as follows:
+ and you can change its value, say reduce it to 15 seconds, as follows:
# echo 15 > /config/unionfs/timeout
-2. block_high_thresh: defaults to 80%. The threshold of consumed disk blocks
in
- /odf, above which we begin cleaning, to bring the system below this
- threshold.
+2. block_high_thresh: defaults to 80%. The threshold of used disk blocks in
+ /odf, above which we begin cleaning, to bring the system below the
+ block_low_thresh threshold value.
-3. block_low_thresh: defaults to 70%. The threshold of consumed disk blocks in
- /odf we try to bring the system to after we begin cleaning.
+3. block_low_thresh: defaults to 70%. The threshold of used disk blocks in
+ /odf that we try to bring the system down to after we begin cleaning.
-4. inode_high_thresh: defaults to 80%. The threshold of consumed inodes in
/odf,
- above which we begin cleaning, to bring the system below this threshold.
+4. inode_high_thresh: defaults to 80%. The threshold of used inodes in
+ /odf, above which we begin cleaning, to bring the system below the
+ inode_low_thresh threshold value.
-5. inode_low_thresh: defaults to 70%. The threshold of consumed inodes in
/odf,
- we try to bring the system to after we begin cleaning.
+5. inode_low_thresh: defaults to 70%. The threshold of used inodes in /odf
+ that we try to bring the system down to after we begin cleaning.
-You can view or modify the latter two variables similarly to the 'timeout'
-variable.
+6. help: a read-only variable, whose contents is the usage help for
+ Unionfs's configfs parameters.
+
+You can view or modify any read-write Unionfs configfs variables similarly
+to the 'timeout' variable above.
For more information, see <http://unionfs.filesystems.org/>.
_______________________________________________
unionfs-cvs mailing list: http://unionfs.filesystems.org/
[email protected]
http://www.fsl.cs.sunysb.edu/mailman/listinfo/unionfs-cvs
