[PATCH 1/67] aufs document

[hooanon05]

From: Junjiro Okajima <hooanon05@xxxxxxxxxxx>

	initial commit
	aufs document

Signed-off-by: Junjiro Okajima <hooanon05@xxxxxxxxxxx>
---
 Documentation/filesystems/aufs/README |  374 +++++++++++++++++++++++++++++++++
 1 files changed, 374 insertions(+), 0 deletions(-)

diff --git a/Documentation/filesystems/aufs/README b/Documentation/filesystems/aufs/README
new file mode 100644
index 0000000..ebe19db
--- /dev/null
+++ b/Documentation/filesystems/aufs/README
@@ -0,0 +1,374 @@
+
+Aufs -- Another Unionfs
+Junjiro Okajima
+
+# $Id: README,v 1.79 2008/05/04 23:55:14 sfjro Exp $
+
+
+0. Introduction
+----------------------------------------
+In the early days, aufs was entirely re-designed and re-implemented
+Unionfs Version 1.x series. After many original ideas, approaches,
+improvements and implementations, it becomes totally different from
+Unionfs while keeping the basic features.
+Recently, Unionfs Version 2.x series begin taking some of same
+approaches to aufs's.
+Unionfs is being developed by Professor Erez Zadok at Stony Brook
+University and his team.
+If you don't know Unionfs, I recommend you becoming familiar with it
+before using aufs. Some terminology in aufs follows Unionfs's.
+
+Bug reports (including my broken English), suggestions, comments
+and donations are always welcome. Your bug report may help other users,
+including future users. Especially the bug report which doesn't follow
+unix/linux filesystem's semantics is important.
+
+
+1. Features
+----------------------------------------
+- unite several directories into a single virtual filesystem. The member
+  directory is called as a branch.
+- you can specify the permission flags to the branch, which are 'readonly',
+  'readwrite' and 'whiteout-able.'
+- by upper writable branch, internal copyup and whiteout, files/dirs on
+  readonly branch are modifiable logically.
+- dynamic branch manipulation, add, del.
+- etc... see Unionfs in detail.
+
+Also there are many enhancements in aufs, such as:
+- safer and faster
+- keep inode number by external inode number table
+- keep the timestamps of file/dir in internal copyup operation
+- seekable directory, supporting NFS readdir.
+- support mmap(2) including /proc/PID/exe symlink, without page-copy
+- whiteout is hardlinked in order to reduce the consumption of inodes
+  on branch
+- do not copyup, nor create a whiteout when it is unnecessary
+- revert a single systemcall when an error occurs in aufs
+- remount interface instead of ioctl
+- maintain /etc/mtab by an external shell script, /sbin/mount.aufs.
+- loopback mounted filesystem as a branch
+- kernel thread for removing the dir who has a plenty of whiteouts
+- support copyup sparse file (a file which has a 'hole' in it)
+- default permission flags for branches
+- selectable permission flags for ro branch, whether whiteout can
+  exist or not
+- export via NFS.
+- support <sysfs>/fs/aufs.
+- support multiple writable branches, some policies to select one
+  among multiple writable branches.
+- a new semantics for link(2) and rename(2) to support multiple
+  writable branches.
+- a delegation of the internal branch access to support task I/O
+  accounting, which also supports Linux Security Modules (LSM) mainly
+  for Suse AppArmor.
+- nested mount, i.e. aufs as readonly no-whiteout branch of another aufs.
+- copyup-on-open or copyup-on-write
+- show-whiteout mode
+- show configuration even out of kernel tree
+- no glibc changes are required.
+- and more... see aufs manual in detail
+
+Aufs is in still development stage, especially:
+- pseudo hardlink (hardlink over branches)
+- allow a direct access manually to a file on branch, e.g. bypassing aufs.
+  including NFS or remote filesystem branch.
+- refine xino and revalidate
+- pseudo-link in NFS-exporting
+
+(current work)
+- reorder the branch index without del/re-add.
+- permanent xino files
+
+(next work)
+- an option for refreshing the opened files after add/del branches
+- 'move' policy for copy-up between two writable branches, after
+  checking free space.
+- ioctl to manipulate file between branches.
+- and documentation
+
+(just an idea)
+- remount option copy/move between two branches. (unnecessary?)
+- O_DIRECT (unnecessary?)
+- light version, without branch manipulation. (unnecessary?)
+- SMP, because I don't have such machine. But several users reported
+  aufs is working fine on SMP machines.
+- copyup in userspace
+- inotify in userspace
+- xattr, acl
+
+
+2. Download
+----------------------------------------
+CVS tree is in aufs project of SourceForge.
+Here is simple instructions to get aufs source files. It is recommended to
+refer to the document about CVS on SourceForge.
+	$ mkdir aufs.wcvs
+	$ cd aufs.wcvs
+	$ cvs -d:pserver:anonymous@xxxxxxxxxxxxxxxxxxxxxxxx:/cvsroot/aufs login
+	(CVS password is empty)
+	$ cvs -z3 -d:pserver:anonymous@xxxxxxxxxxxxxxxxxxxxxxxx:/cvsroot/aufs co aufs
+
+In order to update files after the first checkout,
+	$ cd aufs.wcvs/aufs
+	$ cvs update
+Do not forget -A option for 'cvs update' if you have ever 'cvs update' with
+specifying a file version.
+
+In order to see what the difference between two versions (two dates) is,
+	$ cd aufs.wcvs/aufs
+	$ cvs diff -D20061212 -D20061219
+
+Usually I am updating CVS tree on every Monday.
+I always try putting the stable version in CVS, so you can try CVS
+instead of SourceForge File Release. And every changes are summarized
+and reported to aufs-users at lists.sourceforge.net ML. I'd like to
+recommend you to join this ML.
+
+
+3. Configuration and Compilation
+----------------------------------------
+Aufs is being developed and tested on linux-2.6.16 and later.
+You need the correct environment to build a kernel module. Generally
+it is an environment which your kernel was built.
+The aufs source files are under ./fs/aufs or ./fs/aufs25, which are
+for linux-2.6.16 - 2.6.24, and linux-2.6.25 and later respectively.
+Aufs makefile refers the files which is generated by linux build
+system.
+If you are unsure that you got the correct environment, then I
+recommend you to built your kernel by yourself. If it succeeds, you've
+got the correct environment.
+
+Currently aufs configuration is written in ./Kconfig.in. You can
+generate the real ./fs/aufs/Kconfig file by make(1). And follow the
+instructions which will be produced by make(1). The built
+./fs/aufs/Kconfig depends upon the kernel version.
+Before you build ./fs/aufs/Kconfig, you need to configure your kernel,
+since this build refers to linux/include/version.h.
+	$ make -f local.mk kconfig
+
+The local.mk searches your kernel build path by
+	KDIR = /lib/modules/$(shell uname -r)/build
+If you are cross-compiling the aufs module, try
+	$ make KDIR=/your/kernel/build/path -f local.mk kconfig
+If you link aufs statically, the generated Kconfig will help you.
+
+Also you can use ./local.mk to compile aufs as a module by simply,
+	$ make -f local.mk
+or
+	$ make KDIR=/your/kernel/build/path -f local.mk
+
+The default configuration is written in ./local.mk too, they will work
+for you in most cases. You can edit this file and change the
+configuration for your aufs module.
+If you don't want to change the ./local.mk, then create a new file
+./priv_def.mk and write the definitions your aufs configuration. The
+./local.mk includes ./priv_def.mk if it exists.
+When you configure aufs by modifying ./local.mk (or ./priv_dev.mk),
+leave it blank/unset when you disable an aufs configuration, instead
+of setting 'n.'
+
+The aufs build system may refer some kernel source files for some
+macros or internal functions which are not declared in their header
+files. It depends upon the configuration whether these files will be
+referred or not.
+Even if you don't have these source files in your build environment,
+aufs can be built safely, but works less efficiently in some cases.
+
+There is a contributed Makefile for aufs users. You might want to try
+it. Check
+http://sourceforge.net/mailarchive/forum.php?thread_name=9c4865a10707241831r189f9646n5f2c4a9c303797d1%40mail.gmail.com&forum_name=aufs-users
+and see the attachment.
+
+Currently, CONFIG_DEBUG_PROVE_LOCKING (in linux kernel) is not
+supported since MAX_LOCKDEP_SUBCLASSES is too small for a stackable
+filesystem. I am trying reducing the depth of lock subclasses.
+Until then, you need to increase the value of MAX_LOCKDEP_SUBCLASSES
+macro in include/linux/lockdep.h, for example, 16UL, when you enable
+CONFIG_DEBUG_PROVE_LOCKING.
+
+When you test the performance, it is recommended to disable
+CONFIG_AUFS_DEBUG. It is enabled by default for the feature test.
+
+Since aufs supports several versions of linux kernel, it uses the
+condition like this,
+	#if LINUX_VERSION_CODE < KERNEL_VERSION(2, 6, 18)
+On the other hand, some distributions modify their kernel by their own
+patches. For example, just a piece of code is brought from v2.6.18 and
+merged into a distribution kernel which calls itself as v2.6.17.
+Finally, the conditions in aufs will not work correctly.
+You may or may not find them when you compile aufs.
+You need to modify aufs source code for 'custom-version' kernel
+(cf. patch/ubuntu-edgy.patch).
+
+
+o Patches
+There are several patches for linux kernel, in order to use aufs.
+All of them are not necessary essentially, but in some cases you need
+them. It is up to your environment and aufs usage.
+All these patches are just for exporting a kernel internal function to
+modules. If the function was already declared as extern and you link
+aufs statically to your kernel, then you don't need such patch. If the
+function was not extern and you want the feature, you need to apply
+the patch.
+When you apply a patch, you need to enable the corresponding aufs
+configuration.
+All these patches are under CVS_TREE/aufs/patch.
+
+- sec_perm-2.6.24.patch
+  For linux-2.6.24 and later.
+  When you compile aufs as a module and enable CONFIG_SECURITY, this
+  patch is required.
+- splice-2.6.23.patch
+  For linux-2.6.23 and later.
+  When you use splice(2) (sendfile(2) in linux-2.6.23 and later), or
+  loopback-mount an fs-image file in aufs, this patch is
+  required. Aufs doesn't support splice(2) in linux-2.6.22 and
+  earlier.
+- put_filp.patch
+  For linux-2.6.19 and later.
+  When you compile aufs as a module and use NFS as an aufs branch
+  filesystem, this patch is required.
+- lhash.patch
+  For linux-2.6.19 and later till linux-2.6.21.
+  When you use NFS as an aufs branch filesystem, this patch is
+  required.
+- lhash-2.6.22.patch
+  Same above, but this patch is for linux-2.6.22 only.
+- fsync_super-2.6.16.patch
+  For linux-2.6.16 and later.
+  When you compile aufs as a module, apply this patch and enable a
+  configuration, aufs tries flushing everything for branch filesystems
+  which are not marked as 'rr' or 'rr+wh' at umount or remount time.
+- fsync_super-2.6.19.patch
+  Same above, but this patch is for linux-2.6.19 and later.
+- deny_write_access.patch
+  For linux-2.6.17 and later.
+  When you compile aufs as a module, applied this patch and enabled a
+  configuration, a minor security enhancement will be available at
+  execve(2).
+  You can omit this if you don't care the writing to a running
+  executable on a lower branch filesystem which was invoked through
+  aufs.
+- ksize.patch
+  For linux-2.6.22 and earlier.
+  When you compile aufs as a module and applied this patch, an
+  optimization inside aufs will be available at adding or deleting a
+  branch filesystem. You can omit this if you don't care the aufs
+  performance.
+
+Additionally, there are patches for aufs which will be necessary when
+you use non-standard kernel modules or patches. Some of them have been
+tested by several people, but not all.
+See also the comments in the patches.
+- ubuntu-2.6.22-14.46.patch
+  For Ubuntu kernel
+  (http://archive.ubuntu.com/ubuntu/pool/main/l/linux-source-2.6.22/
+  linux-source-2.6.22_2.6.22-14.46_all.deb) which is modified a lot by
+  ubuntu people.
+- ubuntu-2.6.24-5.8.patch
+  For http://archive.ubuntu.com/ubuntu/pool/main/l/linux/
+  linux-source-2.6.24_2.6.24-5.8_all.deb.
+- ubuntu-edgy.patch
+  For Ubuntu Edgy kernel which calls itself as 2.6.17, while its
+  umount_begin() interface has arguments of 2.6.18.
+- rt-compat.patch
+  For realtime patch (http://people.redhat.com/mingo/realtime-preempt).
+- vserver.patch
+  For linux-vserver module (http://linux-vserver.org).
+- openvz_028stab039.1.patch
+  For openvz module (http://openvz.org).
+
+
+4. Usage
+----------------------------------------
+After 'make',
+	$ man -l ./aufs.5
+	# install -m 500 -p mount.aufs umount.aufs auplink aulchown /sbin (recommended)
+	# echo FLUSH=ALL > /etc/default/auplink (recommended)
+	# insmod ./aufs.ko
+	$ mkdir /tmp/rw /tmp/aufs
+	# mount -t aufs -o dirs=/tmp/rw:${HOME}=ro none /tmp/aufs
+
+If you are familiar with Unionfs Version 1.x series and want to use
+unionctl(8), you can try the sample unionctl script under sample/
+directory too.
+
+Here is another example.
+
+	# mount -t aufs -o br:/tmp/rw:${HOME}=ro none /tmp/aufs
+	or
+	# mount -t aufs -o br:/tmp/rw none /tmp/aufs
+	# mount -o remount,append:${HOME}=ro /tmp/aufs
+
+If you disable CONFIG_AUFS_COMPAT in your configuration, you can remove the
+default branch permission '=ro' since '=rw' is set to the first branch
+only by default.
+
+	# mount -t aufs -o br:/tmp/rw:${HOME} none /tmp/aufs
+
+Then, you can see whole tree of your home dir through /tmp/aufs. If
+you modify a file under /tmp/aufs, the one on your home directory is
+not affected, instead the same named file will be newly created under
+/tmp/rw. And all of your modification to the file will be applied to
+the one under /tmp/rw. This is called the file based Copy on Write
+(COW) method.
+Aufs mount options are described in the generated ./aufs.5.
+
+Additionally, there are some sample usages of aufs which are a
+diskless system with network booting, and LiveCD over NFS.
+See ./sample/diskless in detail.
+
+
+5. Contact
+----------------------------------------
+When you have any problems or strange behaviour in aufs, please let me
+know with:
+- /proc/mounts (instead of the output of mount(8))
+- /sys/fs/aufs/* (if you have them)
+- /sys/module/aufs/*
+- linux kernel version
+  if your kernel is not plain, for example modified by distributor,
+  the url where i can download its source is necessary too.
+- aufs version which was printed at loading the module or booting the
+  system, instead of the date you downloaded.
+- configuration (define/undefine CONFIG_AUFS_xxx, or plain local.mk is
+  used or not)
+- kernel configuration or /proc/config.gz (if you have it)
+- behaviour which you think to be incorrect
+- actual operation, reproducible one is better
+- mailto: aufs-users at lists.sourceforge.net
+
+Usually, I don't watch the Public Areas(Bugs, Support Requests, Patches,
+and Feature Requests) on SourceForge. Please join and write to
+aufs-users ML.
+
+
+6. Acknowledgements
+----------------------------------------
+Thanks to everyone who have tried and are using aufs, especially who
+have reported a bug or any feedback.
+
+Tomas Matejicek(slax.org) made a donation (much more than once).
+Dai Itasaka made a donation (2007/8).
+Chuck Smith made a donation (2008/4).
+
+Thank you very much.
+Donations are always, including future donations, very important and
+helpful for me to keep on developing aufs.
+If you have a plan to develop or customize linux, feel free to ask me
+a job with some donations or payments.
+
+
+7.
+----------------------------------------
+If you are an experienced user, no explanation is needed. Aufs is
+just a linux filesystem module. take a glance at ./local.mk,
+aufs.5, and Unionfs.
+
+
+Enjoy!
+
+# Local variables: ;
+# mode: text;
+# End: ;
-- 
1.4.4.4

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/