Documentation/filesystems/aufs/README

   1
   2 Aufs3 -- advanced multi layered unification filesystem version 3.x
   3 http://aufs.sf.net
   4 Junjiro R. Okajima
   5
   6
   7 0. Introduction
   8 ----------------------------------------
   9 In the early days, aufs was entirely re-designed and re-implemented
  10 Unionfs Version 1.x series. After many original ideas, approaches,
  11 improvements and implementations, it becomes totally different from
  12 Unionfs while keeping the basic features.
  13 Recently, Unionfs Version 2.x series begin taking some of the same
  14 approaches to aufs1's.
  15 Unionfs is being developed by Professor Erez Zadok at Stony Brook
  16 University and his team.
  17
  18 Aufs3 supports linux-3.0 and later.
  19 If you want older kernel version support, try aufs2-2.6.git or
  20 aufs2-standalone.git repository, aufs1 from CVS on SourceForge.
  21
  22 Note: it becomes clear that "Aufs was rejected. Let's give it up."
  23 According to Christoph Hellwig, linux rejects all union-type filesystems
  24 but UnionMount.
  25 <http://marc.info/?l=linux-kernel&m=123938533724484&w=2>
  26
  27
  28 1. Features
  29 ----------------------------------------
  30 - unite several directories into a single virtual filesystem. The member
  31   directory is called as a branch.
  32 - you can specify the permission flags to the branch, which are 'readonly',
  33   'readwrite' and 'whiteout-able.'
  34 - by upper writable branch, internal copyup and whiteout, files/dirs on
  35   readonly branch are modifiable logically.
  36 - dynamic branch manipulation, add, del.
  37 - etc...
  38
  39 Also there are many enhancements in aufs1, such as:
  40 - readdir(3) in userspace.
  41 - keep inode number by external inode number table
  42 - keep the timestamps of file/dir in internal copyup operation
  43 - seekable directory, supporting NFS readdir.
  44 - whiteout is hardlinked in order to reduce the consumption of inodes
  45   on branch
  46 - do not copyup, nor create a whiteout when it is unnecessary
  47 - revert a single systemcall when an error occurs in aufs
  48 - remount interface instead of ioctl
  49 - maintain /etc/mtab by an external command, /sbin/mount.aufs.
  50 - loopback mounted filesystem as a branch
  51 - kernel thread for removing the dir who has a plenty of whiteouts
  52 - support copyup sparse file (a file which has a 'hole' in it)
  53 - default permission flags for branches
  54 - selectable permission flags for ro branch, whether whiteout can
  55   exist or not
  56 - export via NFS.
  57 - support <sysfs>/fs/aufs and <debugfs>/aufs.
  58 - support multiple writable branches, some policies to select one
  59   among multiple writable branches.
  60 - a new semantics for link(2) and rename(2) to support multiple
  61   writable branches.
  62 - no glibc changes are required.
  63 - pseudo hardlink (hardlink over branches)
  64 - allow a direct access manually to a file on branch, e.g. bypassing aufs.
  65   including NFS or remote filesystem branch.
  66 - userspace wrapper for pathconf(3)/fpathconf(3) with _PC_LINK_MAX.
  67 - and more...
  68
  69 Currently these features are dropped temporary from aufs3.
  70 See design/08plan.txt in detail.
  71 - test only the highest one for the directory permission (dirperm1)
  72 - copyup on open (coo=)
  73 - nested mount, i.e. aufs as readonly no-whiteout branch of another aufs
  74   (robr)
  75 - statistics of aufs thread (/sys/fs/aufs/stat)
  76 - delegation mode (dlgt)
  77   a delegation of the internal branch access to support task I/O
  78   accounting, which also supports Linux Security Modules (LSM) mainly
  79   for Suse AppArmor.
  80 - intent.open/create (file open in a single lookup)
  81
  82 Features or just an idea in the future (see also design/*.txt),
  83 - reorder the branch index without del/re-add.
  84 - permanent xino files for NFSD
  85 - an option for refreshing the opened files after add/del branches
  86 - 'move' policy for copy-up between two writable branches, after
  87   checking free space.
  88 - light version, without branch manipulation. (unnecessary?)
  89 - copyup in userspace
  90 - inotify in userspace
  91 - readv/writev
  92 - xattr, acl
  93
  94
  95 2. Download
  96 ----------------------------------------
  97 There were three GIT trees for aufs3, aufs3-linux.git,
  98 aufs3-standalone.git, and aufs-util.git. Note that there is no "3" in
  99 "aufs-util.git."
 100 While the aufs-util is always necessary, you need either of aufs3-linux
 101 or aufs3-standalone.
 102
 103 The aufs3-linux tree includes the whole linux mainline GIT tree,
 104 git://git.kernel.org/.../torvalds/linux.git.
 105 And you cannot select CONFIG_AUFS_FS=m for this version, eg. you cannot
 106 build aufs3 as an external kernel module.
 107
 108 On the other hand, the aufs3-standalone tree has only aufs source files
 109 and necessary patches, and you can select CONFIG_AUFS_FS=m.
 110
 111 You will find GIT branches whose name is in form of "aufs3.x" where "x"
 112 represents the linux kernel version, "linux-3.x". For instance,
 113 "aufs3.0" is for linux-3.0. For latest "linux-3.x-rcN", use
 114 "aufs3.x-rcN" branch.
 115
 116 o aufs3-linux tree
 117 $ git clone --reference /your/linux/git/tree \
 118         git://git.code.sf.net/p/aufs/aufs3-linux aufs-aufs3-linux \
 119         aufs3-linux.git
 120 - if you don't have linux GIT tree, then remove "--reference ..."
 121 $ cd aufs3-linux.git
 122 $ git checkout origin/aufs3.0
 123
 124 o aufs3-standalone tree
 125 $ git clone git://git.code.sf.net/p/aufs/aufs3-standalone \
 126         aufs3-standalone.git
 127 $ cd aufs3-standalone.git
 128 $ git checkout origin/aufs3.0
 129
 130 o aufs-util tree
 131 $ git clone git://git.code.sf.net/p/aufs/aufs-util \
 132         aufs-util.git
 133 $ cd aufs-util.git
 134 $ git checkout origin/aufs3.0
 135
 136 Note: The 3.x-rcN branch is to be used with `rc' kernel versions ONLY.
 137 The minor version number, 'x' in '3.x', of aufs may not always
 138 follow the minor version number of the kernel.
 139 Because changes in the kernel that cause the use of a new
 140 minor version number do not always require changes to aufs-util.
 141
 142 Since aufs-util has its own minor version number, you may not be
 143 able to find a GIT branch in aufs-util for your kernel's
 144 exact minor version number.
 145 In this case, you should git-checkout the branch for the
 146 nearest lower number.
 147
 148 For (an unreleased) example:
 149 If you are using "linux-3.10" and the "aufs3.10" branch
 150 does not exist in aufs-util repository, then "aufs3.9", "aufs3.8"
 151 or something numerically smaller is the branch for your kernel.
 152
 153 Also you can view all branches by
 154         $ git branch -a
 155
 156
 157 3. Configuration and Compilation
 158 ----------------------------------------
 159 Make sure you have git-checkout'ed the correct branch.
 160
 161 For aufs3-linux tree,
 162 - enable CONFIG_EXPERIMENTAL and CONFIG_AUFS_FS.
 163 - set other aufs configurations if necessary.
 164
 165 For aufs3-standalone tree,
 166 There are several ways to build.
 167
 168 1.
 169 - apply ./aufs3-kbuild.patch to your kernel source files.
 170 - apply ./aufs3-base.patch too.
 171 - apply ./aufs3-mmap.patch too.
 172 - apply ./aufs3-standalone.patch too, if you have a plan to set
 173   CONFIG_AUFS_FS=m. otherwise you don't need ./aufs3-standalone.patch.
 174 - copy ./{Documentation,fs,include/linux/aufs_type.h} files to your
 175   kernel source tree. Never copy $PWD/include/linux/Kbuild.
 176 - enable CONFIG_EXPERIMENTAL and CONFIG_AUFS_FS, you can select either
 177   =m or =y.
 178 - and build your kernel as usual.
 179 - install the built kernel.
 180 - install the header files too by "make headers_install" to the
 181   directory where you specify. By default, it is $PWD/usr.
 182   "make help" shows a brief note for headers_install.
 183 - and reboot your system.
 184
 185 2.
 186 - module only (CONFIG_AUFS_FS=m).
 187 - apply ./aufs3-base.patch to your kernel source files.
 188 - apply ./aufs3-mmap.patch too.
 189 - apply ./aufs3-standalone.patch too.
 190 - build your kernel, don't forget "make headers_install", and reboot.
 191 - edit ./config.mk and set other aufs configurations if necessary.
 192   Note: You should read $PWD/fs/aufs/Kconfig carefully which describes
 193   every aufs configurations.
 194 - build the module by simple "make".
 195 - you can specify ${KDIR} make variable which points to your kernel
 196   source tree.
 197 - install the files
 198   + run "make install" to install the aufs module, or copy the built
 199     $PWD/aufs.ko to /lib/modules/... and run depmod -a (or reboot simply).
 200   + run "make install_headers" (instead of headers_install) to install
 201     the modified aufs header file (you can specify DESTDIR which is
 202     available in aufs standalone version's Makefile only), or copy
 203     $PWD/usr/include/linux/aufs_type.h to /usr/include/linux or wherever
 204     you like manually. By default, the target directory is $PWD/usr.
 205 - no need to apply aufs3-kbuild.patch, nor copying source files to your
 206   kernel source tree.
 207
 208 Note: The header file aufs_type.h is necessary to build aufs-util
 209       as well as "make headers_install" in the kernel source tree.
 210       headers_install is subject to be forgotten, but it is essentially
 211       necessary, not only for building aufs-util.
 212       You may not meet problems without headers_install in some older
 213       version though.
 214
 215 And then,
 216 - read README in aufs-util, build and install it
 217 - note that your distribution may contain an obsoleted version of
 218   aufs_type.h in /usr/include/linux or something. When you build aufs
 219   utilities, make sure that your compiler refers the correct aufs header
 220   file which is built by "make headers_install."
 221 - if you want to use readdir(3) in userspace or pathconf(3) wrapper,
 222   then run "make install_ulib" too. And refer to the aufs manual in
 223   detail.
 224
 225
 226 4. Usage
 227 ----------------------------------------
 228 At first, make sure aufs-util are installed, and please read the aufs
 229 manual, aufs.5 in aufs-util.git tree.
 230 $ man -l aufs.5
 231
 232 And then,
 233 $ mkdir /tmp/rw /tmp/aufs
 234 # mount -t aufs -o br=/tmp/rw:${HOME} none /tmp/aufs
 235
 236 Here is another example. The result is equivalent.
 237 # mount -t aufs -o br=/tmp/rw=rw:${HOME}=ro none /tmp/aufs
 238   Or
 239 # mount -t aufs -o br:/tmp/rw none /tmp/aufs
 240 # mount -o remount,append:${HOME} /tmp/aufs
 241
 242 Then, you can see whole tree of your home dir through /tmp/aufs. If
 243 you modify a file under /tmp/aufs, the one on your home directory is
 244 not affected, instead the same named file will be newly created under
 245 /tmp/rw. And all of your modification to a file will be applied to
 246 the one under /tmp/rw. This is called the file based Copy on Write
 247 (COW) method.
 248 Aufs mount options are described in aufs.5.
 249 If you run chroot or something and make your aufs as a root directory,
 250 then you need to customize the shutdown script. See the aufs manual in
 251 detail.
 252
 253 Additionally, there are some sample usages of aufs which are a
 254 diskless system with network booting, and LiveCD over NFS.
 255 See sample dir in CVS tree on SourceForge.
 256
 257
 258 5. Contact
 259 ----------------------------------------
 260 When you have any problems or strange behaviour in aufs, please let me
 261 know with:
 262 - /proc/mounts (instead of the output of mount(8))
 263 - /sys/module/aufs/*
 264 - /sys/fs/aufs/* (if you have them)
 265 - /debug/aufs/* (if you have them)
 266 - linux kernel version
 267   if your kernel is not plain, for example modified by distributor,
 268   the url where i can download its source is necessary too.
 269 - aufs version which was printed at loading the module or booting the
 270   system, instead of the date you downloaded.
 271 - configuration (define/undefine CONFIG_AUFS_xxx)
 272 - kernel configuration or /proc/config.gz (if you have it)
 273 - behaviour which you think to be incorrect
 274 - actual operation, reproducible one is better
 275 - mailto: aufs-users at lists.sourceforge.net
 276
 277 Usually, I don't watch the Public Areas(Bugs, Support Requests, Patches,
 278 and Feature Requests) on SourceForge. Please join and write to
 279 aufs-users ML.
 280
 281
 282 6. Acknowledgements
 283 ----------------------------------------
 284 Thanks to everyone who have tried and are using aufs, whoever
 285 have reported a bug or any feedback.
 286
 287 Especially donators:
 288 Tomas Matejicek(slax.org) made a donation (much more than once).
 289         Since Apr 2010, Tomas M (the author of Slax and Linux Live
 290         scripts) is making "doubling" donations.
 291         Unfortunately I cannot list all of the donators, but I really
 292         appreciate.
 293         It ends Aug 2010, but the ordinary donation URL is still available.
 294         <http://sourceforge.net/donate/index.php?group_id=167503>
 295 Dai Itasaka made a donation (2007/8).
 296 Chuck Smith made a donation (2008/4, 10 and 12).
 297 Henk Schoneveld made a donation (2008/9).
 298 Chih-Wei Huang, ASUS, CTC donated Eee PC 4G (2008/10).
 299 Francois Dupoux made a donation (2008/11).
 300 Bruno Cesar Ribas and Luis Carlos Erpen de Bona, C3SL serves public
 301         aufs2 GIT tree (2009/2).
 302 William Grant made a donation (2009/3).
 303 Patrick Lane made a donation (2009/4).
 304 The Mail Archive (mail-archive.com) made donations (2009/5).
 305 Nippy Networks (Ed Wildgoose) made a donation (2009/7).
 306 New Dream Network, LLC (www.dreamhost.com) made a donation (2009/11).
 307 Pavel Pronskiy made a donation (2011/2).
 308 Iridium and Inmarsat satellite phone retailer (www.mailasail.com), Nippy
 309         Networks (Ed Wildgoose) made a donation for hardware (2011/3).
 310 Max Lekomcev (DOM-TV project) made a donation (2011/7, 12, 2012/3, 6 and
 311 11).
 312 Sam Liddicott made a donation (2011/9).
 313 Era Scarecrow made a donation (2013/4).
 314 Bor Ratajc made a donation (2013/4).
 315 Alessandro Gorreta made a donation (2013/4).
 316 POIRETTE Marc made a donation (2013/4).
 317 Alessandro Gorreta made a donation (2013/4).
 318 lauri kasvandik made a donation (2013/5).
 319 "pemasu from Finland" made a donation (2013/7).
 320 The Parted Magic Project made a donation (2013/9).
 321 Pavel Barta made a donation (2013/10).
 322
 323 Thank you very much.
 324 Donations are always, including future donations, very important and
 325 helpful for me to keep on developing aufs.
 326
 327
 328 7.
 329 ----------------------------------------
 330 If you are an experienced user, no explanation is needed. Aufs is
 331 just a linux filesystem.
 332
 333
 334 Enjoy!
 335
 336 # Local variables: ;
 337 # mode: text;
 338 # End: ;