
Aufs -- Another Unionfs
Junjiro Okajima

# $Id: README,v 1.15 2006/08/15 04:13:45 sfjro Exp $

0. Introduction
Aufs was entirely re-designed and re-implemented Unionfs, after
enhancing with many original ideas, approaches and implementations, it
becomes totally different one while keeping the basic features.
Unionfs is being developed by Professor Erez Zadok at Stony Brook
University and his team.
If you don't know Unionfs, I recommend you to try and know it before
using aufs. Some terminology in aufs follows Unionfs's.
Bug reports, suggestions, comments and donations are always welcome.

1. Features
- unite several directories into a single writable 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 and mod (flags)
- etc... see Unionfs in detail

Also there are some enhancements in aufs, such like,,,
- simplified, safer and faster
- keep inode number by external inode number table
- keep the timestamps of file/dir in internal copyup operation
- seekable directory
- do not copyup, nor create a whiteout when it is unnecessary
- support mmap(2) without page-copy
- revert a single systemcall when an error occurs in aufs
- remount interface instead of ioctl
- 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
- allow a direct access (by user's hand) to a file on branch,
  eg. bypassing aufs (incomplete)
- pseudo hardlink (hardlink over branches) (incomplete)
- and more... see util/aufs.in.5 in detail

Aufs is in still development stage, especially,,,
- hardlinked whiteout
  whiteout is hardlinked in order to reduce the consumption of inodes
  on branch
- remount option copy/move between two branches
- O_DIRECT (unnecessary?)
- export via nfs (unnecessary?)
- mini version, without branch manipulation.
- xattr
- and documentation

2. Download and Contact
CVS tree is in aufs project of SourceForge.

When you have any problems or strange behaviour of aufs, please let me
know with,,,
- /proc/mounts (instead of the output of mount(8))
- linux kernel version
- AUFS_VERSION (defined in include/linux/aufs_type.h)
- configuration (define/undefine CONFIG_AUFS_xxx, or plain local.mk is
  used or not)
- phenomenon
- actual operation, reproducible one is better
- mailto: aufs-users at lists.sourceforge.net

3. Install and Usage
Usually, ./local.mk will work for you.
	$ make -f local.mk
The local.mk searches your kernel source files by
	KDIR = /lib/modules/$(shell uname -r)/build
If you are cross-compiling the aufs module, try
	$ make KDIR=/your/kernel/source/path -f local.mk

You need to apply the ./ksize.patch to your linux kernel, in order to
export 'ksize' kernel internal function.
If you don't want to apply this patch, you can compile and use aufs
without the patch by defining CONFIG_AUFS_NO_KSIZE (cf. local.mk). But
some operations (add a branch, readdir to a large directory, and the
first access to files after add/del branches) will be inefficient.
Aufs is being developed and tested on linux-2.6.16 and later.

	(after 'make')
	$ man -l ./aufs.5
	# install -m 500 -p mount.aufs mount.unionfs /sbin (optional)
	# insmod ./aufs.ko
	$ mkdir /tmp/rw /tmp/aufs
	# mount -t unionfs -o dirs=/tmp/rw:${HOME}=ro none /tmp/aufs

If you undefine CONFIG_AUFS_COMPAT, the filesystem type name is 'aufs'
instead of 'unionfs'. Here is another example.

	# mount -t aufs -o br:/tmp/rw:${HOME} none /tmp/aufs
	or
	# mount -t aufs -o br:/tmp/rw none /tmp/aufs
	# mount -o remount,append:${HOME} /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, but the same named file will be newly created under
/tmp/rw. This is called Copy on Write (COW) method.
Aufs mount options are described in util/aufs.in.5, and ./aufs.5 would
be built by the first 'make'.
When you finish using aufs, you can unmount it by umount(8)
simply. Aufs has no special daemons nor special files.

If you are a 'sparse' user, which is commonly used for checking linux
kernel source files, you will meet
	'error: undefined identifier '__func__''
since aufs uses 'nested function' GCC extension.
While it is used in very limited and simple manner, the sparse says
it is an error. You can ignore this message if your compilation
succeeds.
If you want to shut your sparse up, then apply
'./nested__func__.patch' to it (of course, it is aboslutely no
warranty too).

If you are an experienced user, no explanation is needed. Aufs is
just a linux filesystem module. take a glance at ./local.mk,
aufs.in.5, and Unionfs.

Enjoy!

# Local variables: ;
# mode: text;
# End: ;
