SourceForge.net Logo


linux kernel version aufs version
5.10 and later aufs6
Currently aufs6 supports these kernels.

version status on www.kernel.org support status
linux-6.x  mainline supported and fully tested
linux-6.0 mainline supported and fully tested

aufs5
Currently aufs5 supports these kernels.

version status on www.kernel.org support status
linux-5.x  mainline supported and fully tested
linux-5.19 stable supported and fully tested. SIGIO and nfs4 don't work expectedly
linux-5.18 stable supported and fully tested. SIGIO and nfs4 don't work expectedly
linux-5.17.3 EOL supported and fully tested, except SIGIO which doesn't work expectedly
linux-5.17 EOL supported and fully tested, except SIGIO which doesn't work expectedly
linux-5.16 EOL supported and fully tested, except SIGIO which doesn't work expectedly
linux-5.15.41 longterm supported but little tested. SIGIO and nfs4 don't work expectedly
linux-5.15.36 EOL supported but little tested. SIGIO and nfs4 don't work expectedly
linux-5.15.5 EOL supported but little tested. SIGIO doesn't work expectedly
linux-5.15 longterm supported and fully tested, except SIGIO which doesn't work expectedly
linux-5.14 EOL supported but little tested, except SIGIO which doesn't work expectedly
linux-5.13 EOL supported and fully tested, except SIGIO which doesn't work expectedly
linux-5.12 EOL supported and fully tested, except SIGIO which doesn't work expectedly
linux-5.11 EOL supported but little tested. SIGIO doesn't work expectedly
linux-5.10.140 longterm supported but little tested. SIGIO and nfs4 doesn't work expectedly
linux-5.10.117 EOL supported but little tested. SIGIO and nfs4 doesn't work expectedly
linux-5.10.82 EOL supported but little tested. SIGIO doesn't work expectedly
linux-5.10 longterm supported and fully tested, except SIGIO which doesn't work expectedly
5.4 ... 5.9 aufs5
Unsupported since Sep 2021
4.19 ... 5.3 aufs4 and aufs5
Unsupported since Jan 2021
4.14 ... 4.18 aufs4
Unsupported since Sep 2019
4.9 ... 4.13 aufs4
Unsupported since Aug 2018
4.4 ... 4.8 aufs4
Unsupported since Sep 2017
4.1 ... 4.3 aufs4
Unsupported since Mar 2017
4.0 aufs4
Unsupported since Aug 2016
3.18 ... 3.19 aufs3
Unsupported since Aug 2016
3.14 ... 3.17 aufs3
Unsupported since Oct 2015
3.9 ... 3.13 aufs3
Unsupported since Jan 2015
3.2, 3.2.x, 3.4 and 3.8 aufs3
Unsupported since Nov 2013
3.6 and 3.7 aufs3
Unsupported since Aug 2013
3.0, 3.1, 3.3 and 3.5 aufs3
Unsupported since Apr 2013
2.6.35 ... 2.6.39 aufs2.2
Unsupported since Oct 2012
2.6.31 ... 2.6.34 aufs2.1
Unsupported since Aug 2011
2.6.27 ... 2.6.30 aufs2
Unsupported since Sep 2010
Started in Feb 2009
2.6.25 ... 2.6.27 aufs1(fs/aufs25)
2.6.16 ... 2.6.24 aufs1(fs/aufs)
Started late in 2005
and made widely public in early summer in 2006
2.6.15 and earlier aufs1(fs/aufs)
Untested, but some of users tried and succeeded
Note1: aufs1 is NOT maintained since Jan 2009.
Note2: packages called aufs2-base were temporary trasition releases and are NOT maintained either.

Public aufs5 and later GIT trees GIT HTTP
aufs5 and later with mainline kernel source files git://github.com/sfjro/aufs-linux.git https://github.com/sfjro/aufs-linux.git
aufs5 and later standalone git://github.com/sfjro/aufs-standalone.git https://github.com/sfjro/aufs-standalone.git
aufs5 repositories are renamed to aufs-linux and aufs-standalone respectively, and they contain aufs6 and later.
Public aufs4 GIT trees GIT HTTP
aufs4 with mainline kernel source files git://github.com/sfjro/aufs4-linux.git https://github.com/sfjro/aufs4-linux.git
aufs4 standalone git://github.com/sfjro/aufs4-standalone.git https://github.com/sfjro/aufs4-standalone.git
aufs (v3 and later) utilities git://git.code.sf.net/p/aufs/aufs-util http://git.code.sf.net/p/aufs/aufs-util
Public aufs3 GIT trees GIT HTTP
aufs3 with full kernel source files git://git.code.sf.net/p/aufs/aufs3-linux

Currnetly (Mar 2013) the aufs3-linux.git repository on SourceForge is unstable, particulary the web interface doesn't show the all branches correctly. I created the same named repostitory on GitHub.
Try git://github.com/sfjro/aufs3-linux.git.

http://git.code.sf.net/p/aufs/aufs3-linux
aufs3 standalone git://git.code.sf.net/p/aufs/aufs3-standalone http://git.code.sf.net/p/aufs/aufs3-standalone
aufs (v3 and later) utilities git://git.code.sf.net/p/aufs/aufs-util http://git.code.sf.net/p/aufs/aufs-util
Public aufs2 GIT trees GIT HTTP
aufs2 (with full kernel source files) git://git.c3sl.ufpr.br/aufs/aufs2-2.6.git http://git.c3sl.ufpr.br/pub/scm/aufs/aufs2-2.6.git
aufs2 standalone
  1. git://git.c3sl.ufpr.br/aufs/aufs2-standalone.git
  2. git://aufs.git.sourceforge.net/gitroot/aufs/aufs2-standalone.git
http://git.c3sl.ufpr.br/pub/scm/aufs/aufs2-standalone.git
aufs2 utilities
  1. git://git.c3sl.ufpr.br/aufs/aufs2-util.git
  2. git://aufs.git.sourceforge.net/gitroot/aufs/aufs2-util.git
http://git.c3sl.ufpr.br/pub/scm/aufs/aufs2-util.git
Public aufs1 CVS tree CVS
aufs1 standalone and utilities See the project page on SourceForge

aufs manual for aufs5.x-rcN
(Running "man aufs" on your actual system is recommended since the contents may depend upon the aufs version)

Contributions



Aufs6 -- advanced multi layered unification filesystem version 6.x
http://aufs.sf.net
Junjiro R. Okajima


0. Introduction
----------------------------------------
In the early days, aufs was entirely re-designed and re-implemented
Unionfs Version 1.x series. Adding many original ideas, approaches,
improvements and implementations, it became totally different from
Unionfs while keeping the basic features.
Later, Unionfs Version 2.x series began taking some of the same
approaches to aufs1's.
Unionfs was being developed by Professor Erez Zadok at Stony Brook
University and his team.

Aufs6 supports linux-v6.0 and later, try aufs6.0 branch in
aufs-linux.git or aufs-standalone.git.
If you want older kernel version support,
- for linux-v5.x series, try aufs-linux.git or aufs-standalone.git
- for linux-v4.x series, try aufs4-linux.git or aufs4-standalone.git
- for linux-v3.x series, try aufs3-linux.git or aufs3-standalone.git
- for linux-v2.6.16 and later, try aufs2-2.6.git, aufs2-standalone.git
  or aufs1 from CVS on SourceForge.

Note: the name of aufs5-linux.git and aufs5-standalone.git on github
      were changed. Now they are aufs-linux.git and
      aufs-standalone.git and they contain aufs5 and later branches.

Note: it becomes clear that "Aufs was rejected. Let's give it up."
      According to Christoph Hellwig, linux rejects all union-type
      filesystems but UnionMount.
<http://marc.info/?l=linux-kernel&m=123938533724484&w=2>

PS. Al Viro seems have a plan to merge aufs as well as overlayfs and
    UnionMount, and he pointed out an issue around a directory mutex
    lock and aufs addressed it. But it is still unsure whether aufs will
    be merged (or any other union solution).
<http://marc.info/?l=linux-kernel&m=136312705029295&w=1>


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...

Also there are many enhancements in aufs, such as:
- test only the highest one for the directory permission (dirperm1)
- copyup on open (coo=)
- 'move' policy for copy-up between two writable branches, after
  checking free space.
- xattr, acl
- readdir(3) in userspace.
- keep inode number by external inode number table
- keep the timestamps of file/dir in internal copyup operation
- seekable directory, supporting NFS readdir.
- 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 command, /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 and <debugfs>/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.
- no glibc changes are required.
- 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.
- userspace wrapper for pathconf(3)/fpathconf(3) with _PC_LINK_MAX.
- and more...

Currently these features are dropped temporary from aufs6.
See design/08plan.txt in detail.
- nested mount, i.e. aufs as readonly no-whiteout branch of another aufs
  (robr)
- statistics of aufs thread (/sys/fs/aufs/stat)

Features or just an idea in the future (see also design/*.txt),
- reorder the branch index without del/re-add.
- permanent xino files for NFSD
- an option for refreshing the opened files after add/del branches
- light version, without branch manipulation. (unnecessary?)
- copyup in userspace
- inotify in userspace
- readv/writev


2. Download
----------------------------------------
There are three GIT trees for aufs6, aufs6-linux.git,
aufs6-standalone.git, and aufs-util.git. Note that there is no "6" in
"aufs-util.git."
While the aufs-util is always necessary, you need either of aufs6-linux
or aufs6-standalone.

The aufs6-linux tree includes the whole linux mainline GIT tree,
git://git.kernel.org/.../torvalds/linux.git.
And you cannot select CONFIG_AUFS_FS=m for this version, eg. you cannot
build aufs6 as an external kernel module.
Several extra patches are not included in this tree. Only
aufs6-standalone tree contains them. They are described in the later
section "Configuration and Compilation."

On the other hand, the aufs6-standalone tree has only aufs source files
and necessary patches, and you can select CONFIG_AUFS_FS=m.
But you need to apply all aufs patches manually.

You will find GIT branches whose name is in form of "aufs6.x" where "x"
represents the linux kernel version, "linux-6.x". For instance,
"aufs6.0" is for linux-6.0. For latest "linux-6.x-rcN", use
"aufs6.x-rcN" branch.

o aufs6-linux tree
$ git clone --reference /your/linux/git/tree \
	git://github.com/sfjro/aufs6-linux.git aufs6-linux.git
- if you don't have linux GIT tree, then remove "--reference ..."
$ cd aufs6-linux.git
$ git checkout origin/aufs6.0

Or You may want to directly git-pull aufs into your linux GIT tree, and
leave the patch-work to GIT.
$ cd /your/linux/git/tree
$ git remote add aufs6 git://github.com/sfjro/aufs6-linux.git
$ git fetch aufs6
$ git checkout -b my6.0 v6.0
$ (add your local change...)
$ git pull aufs6 aufs6.0
- now you have v6.0 + your_changes + aufs6.0 in you my6.0 branch.
- you may need to solve some conflicts between your_changes and
  aufs6.0. in this case, git-rerere is recommended so that you can
  solve the similar conflicts automatically when you upgrade to 6.1 or
  later in the future.

o aufs6-standalone tree
$ git clone git://github.com/sfjro/aufs6-standalone.git aufs6-standalone.git
$ cd aufs6-standalone.git
$ git checkout origin/aufs6.0

o aufs-util tree
$ git clone git://git.code.sf.net/p/aufs/aufs-util aufs-util.git
- note that the public aufs-util.git is on SourceForge instead of
  GitHUB.
$ cd aufs-util.git
$ git checkout origin/aufs6.0

Note: The 6.x-rcN branch is to be used with `rc' kernel versions ONLY.
The minor version number, 'x' in '6.x', of aufs may not always
follow the minor version number of the kernel.
Because changes in the kernel that cause the use of a new
minor version number do not always require changes to aufs-util.

Since aufs-util has its own minor version number, you may not be
able to find a GIT branch in aufs-util for your kernel's
exact minor version number.
In this case, you should git-checkout the branch for the
nearest lower number.

For (an unreleased) example:
If you are using "linux-6.10" and the "aufs6.10" branch
does not exist in aufs-util repository, then "aufs6.9", "aufs6.8"
or something numerically smaller is the branch for your kernel.

Also you can view all branches by
	$ git branch -a


3. Configuration and Compilation
----------------------------------------
Make sure you have git-checkout'ed the correct branch.

For aufs6-linux tree,
- enable CONFIG_AUFS_FS.
- set other aufs configurations if necessary.
- for aufs5.13 and later
  Because aufs is not only an ordinary filesystem (callee of VFS), but
  also a caller of VFS functions for branch filesystems, subclassing of
  the internal locks for LOCKDEP is necessary. LOCKDEP is a debugging
  feature of linux kernel. If you enable CONFIG_LOCKDEP, then you will
  need to customize some LOCKDEP numbers. Here are what I use on my
  test environment.
	CONFIG_LOCKDEP_BITS=21
	CONFIG_LOCKDEP_CHAINS_BITS=21
	CONFIG_LOCKDEP_STACK_TRACE_BITS=24

For aufs6-standalone tree,
There are several ways to build.

1.
- apply ./aufs6-kbuild.patch to your kernel source files.
- apply ./aufs6-base.patch too.
- apply ./aufs6-mmap.patch too.
- apply ./aufs6-standalone.patch too, if you have a plan to set
  CONFIG_AUFS_FS=m. otherwise you don't need ./aufs6-standalone.patch.
- copy ./{Documentation,fs,include/uapi/linux/aufs_type.h} files to your
  kernel source tree. Never copy $PWD/include/uapi/linux/Kbuild.
- enable CONFIG_AUFS_FS, you can select either
  =m or =y.
- and build your kernel as usual.
- install the built kernel.
- install the header files too by "make headers_install" to the
  directory where you specify. By default, it is $PWD/usr.
  "make help" shows a brief note for headers_install.
- and reboot your system.

2.
- module only (CONFIG_AUFS_FS=m).
- apply ./aufs6-base.patch to your kernel source files.
- apply ./aufs6-mmap.patch too.
- apply ./aufs6-standalone.patch too.
- build your kernel, don't forget "make headers_install", and reboot.
- edit ./config.mk and set other aufs configurations if necessary.
  Note: You should read $PWD/fs/aufs/Kconfig carefully which describes
  every aufs configurations.
- build the module by simple "make".
- you can specify ${KDIR} make variable which points to your kernel
  source tree.
- install the files
  + run "make install" to install the aufs module, or copy the built
    $PWD/aufs.ko to /lib/modules/... and run depmod -a (or reboot simply).
  + run "make install_headers" (instead of headers_install) to install
    the modified aufs header file (you can specify DESTDIR which is
    available in aufs standalone version's Makefile only), or copy
    $PWD/usr/include/linux/aufs_type.h to /usr/include/linux or wherever
    you like manually. By default, the target directory is $PWD/usr.
- no need to apply aufs6-kbuild.patch, nor copying source files to your
  kernel source tree.

Note: The header file aufs_type.h is necessary to build aufs-util
      as well as "make headers_install" in the kernel source tree.
      headers_install is subject to be forgotten, but it is essentially
      necessary, not only for building aufs-util.
      You may not meet problems without headers_install in some older
      version though.

And then,
- read README in aufs-util, build and install it
- note that your distribution may contain an obsoleted version of
  aufs_type.h in /usr/include/linux or something. When you build aufs
  utilities, make sure that your compiler refers the correct aufs header
  file which is built by "make headers_install."
- if you want to use readdir(3) in userspace or pathconf(3) wrapper,
  then run "make install_ulib" too. And refer to the aufs manual in
  detail.

There several other patches in aufs6-standalone.git. They are all
optional. When you meet some problems, they will help you.
- aufs6-loopback.patch
  Supports a nested loopback mount in a branch-fs. This patch is
  unnecessary until aufs produces a message like "you may want to try
  another patch for loopback file".
- vfs-ino.patch
  Modifies a system global kernel internal function get_next_ino() in
  order to stop assigning 0 for an inode-number. Not directly related to
  aufs, but recommended generally.
- tmpfs-idr.patch
  Keeps the tmpfs inode number as the lowest value. Effective to reduce
  the size of aufs XINO files for tmpfs branch. Also it prevents the
  duplication of inode number, which is important for backup tools and
  other utilities. When you find aufs XINO files for tmpfs branch
  growing too much, try this patch.


4. Usage
----------------------------------------
At first, make sure aufs-util are installed, and please read the aufs
manual, aufs.6 in aufs-util.git tree.
$ man -l aufs.6

And then,
$ mkdir /tmp/rw /tmp/aufs
# mount -t aufs -o br=/tmp/rw:${HOME} none /tmp/aufs

Here is another example. The result is equivalent.
# mount -t aufs -o br=/tmp/rw=rw:${HOME}=ro 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, instead the same named file will be newly created under
/tmp/rw. And all of your modification to a 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 aufs.6.
If you run chroot or something and make your aufs as a root directory,
then you need to customize the shutdown script. See the aufs manual in
detail.

Additionally, there are some sample usages of aufs which are a
diskless system with network booting, and LiveCD over NFS.
See sample dir in CVS tree on SourceForge.


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/module/aufs/*
- /sys/fs/aufs/* (if you have them)
- /debug/aufs/* (if you have them)
- 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)
- kernel configuration or /proc/config.gz (if you have it)
- LSM (linux security module, if you are using)
- 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, whoever
have reported a bug or any feedback.

Especially donators:
Tomas Matejicek(slax.org) made a donation (much more than once).
	Since Apr 2010, Tomas M (the author of Slax and Linux Live
	scripts) is making "doubling" donations.
	Unfortunately I cannot list all of the donators, but I really
	appreciate.
	It ends Aug 2010, but the ordinary donation URL is still available.
	<http://sourceforge.net/donate/index.php?group_id=167503>
Dai Itasaka made a donation (2007/8).
Chuck Smith made a donation (2008/4, 10 and 12).
Henk Schoneveld made a donation (2008/9).
Chih-Wei Huang, ASUS, CTC donated Eee PC 4G (2008/10).
Francois Dupoux made a donation (2008/11).
Bruno Cesar Ribas and Luis Carlos Erpen de Bona, C3SL serves public
	aufs2 GIT tree (2009/2).
William Grant made a donation (2009/3).
Patrick Lane made a donation (2009/4).
The Mail Archive (mail-archive.com) made donations (2009/5).
Nippy Networks (Ed Wildgoose) made a donation (2009/7).
New Dream Network, LLC (www.dreamhost.com) made a donation (2009/11).
Pavel Pronskiy made a donation (2011/2).
Iridium and Inmarsat satellite phone retailer (www.mailasail.com), Nippy
	Networks (Ed Wildgoose) made a donation for hardware (2011/3).
Max Lekomcev (DOM-TV project) made a donation (2011/7, 12, 2012/3, 6 and
11).
Sam Liddicott made a donation (2011/9).
Era Scarecrow made a donation (2013/4).
Bor Ratajc made a donation (2013/4).
Alessandro Gorreta made a donation (2013/4).
POIRETTE Marc made a donation (2013/4).
Alessandro Gorreta made a donation (2013/4).
lauri kasvandik made a donation (2013/5).
"pemasu from Finland" made a donation (2013/7).
The Parted Magic Project made a donation (2013/9 and 11).
Pavel Barta made a donation (2013/10).
Nikolay Pertsev made a donation (2014/5).
James B made a donation (2014/7, 2015/7, and 2021/12).
Stefano Di Biase made a donation (2014/8).
Daniel Epellei made a donation (2015/1).
OmegaPhil made a donation (2016/1, 2018/4).
Tomasz Szewczyk made a donation (2016/4).
James Burry made a donation (2016/12).
Carsten Rose made a donation (2018/9).
Porteus Kiosk made a donation (2018/10).
Enya Quetzalli Gomez Rodriguez made a donation (2022/5).

Thank you very much.
Donations are always, including future donations, very important and
helpful for me to keep on developing aufs.


7.
----------------------------------------
If you are an experienced user, no explanation is needed. Aufs is
just a linux filesystem.


Enjoy!

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

aufs-util.git tree

README in aufs-util

Contributions

Michael S. Zick wrote good examples, and made them public.

aufs2-util.git tree (obsolete)

README in aufs2-util

Reports around aufs2

PDF Filesystems in LiveCD

Samples in aufs2-util

cluster aufs for cluster
brsync rsync between aufs branches
shwh Show Whiteout mode
auroot chroot-ed/jail environment for internet
auware aufs for VMware Appliance
vserver aufs for Linux-VServer
logrow expand the size of the mounted loopback block device
uloop loopback block device in userspace

Aufs1 (obsoleted)

README for aufs1
aufs.5 for aufs1
tips from users
history of aufs1