aufs: policies for multiple writable branches, from aufs2.2-3.0
[zen-stable.git] / Documentation / filesystems / aufs / design / 08shwh.txt
bloba0ac3d076bfbb9db078d2f17c8275ef450186d1b
2 # Copyright (C) 2005-2011 Junjiro R. Okajima
3
4 # This program is free software; you can redistribute it and/or modify
5 # it under the terms of the GNU General Public License as published by
6 # the Free Software Foundation; either version 2 of the License, or
7 # (at your option) any later version.
8
9 # This program is distributed in the hope that it will be useful,
10 # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 # GNU General Public License for more details.
13
14 # You should have received a copy of the GNU General Public License
15 # along with this program; if not, write to the Free Software
16 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
18 Show Whiteout Mode (shwh)
19 ----------------------------------------------------------------------
20 Generally aufs hides the name of whiteouts. But in some cases, to show
21 them is very useful for users. For instance, creating a new middle layer
22 (branch) by merging existing layers.
24 (borrowing aufs1 HOW-TO from a user, Michael Towers)
25 When you have three branches,
26 - Bottom: 'system', squashfs (underlying base system), read-only
27 - Middle: 'mods', squashfs, read-only
28 - Top: 'overlay', ram (tmpfs), read-write
30 The top layer is loaded at boot time and saved at shutdown, to preserve
31 the changes made to the system during the session.
32 When larger changes have been made, or smaller changes have accumulated,
33 the size of the saved top layer data grows. At this point, it would be
34 nice to be able to merge the two overlay branches ('mods' and 'overlay')
35 and rewrite the 'mods' squashfs, clearing the top layer and thus
36 restoring save and load speed.
38 This merging is simplified by the use of another aufs mount, of just the
39 two overlay branches using the 'shwh' option.
40 # mount -t aufs -o ro,shwh,br:/livesys/overlay=ro+wh:/livesys/mods=rr+wh \
41         aufs /livesys/merge_union
43 A merged view of these two branches is then available at
44 /livesys/merge_union, and the new feature is that the whiteouts are
45 visible!
46 Note that in 'shwh' mode the aufs mount must be 'ro', which will disable
47 writing to all branches. Also the default mode for all branches is 'ro'.
48 It is now possible to save the combined contents of the two overlay
49 branches to a new squashfs, e.g.:
50 # mksquashfs /livesys/merge_union /path/to/newmods.squash
52 This new squashfs archive can be stored on the boot device and the
53 initramfs will use it to replace the old one at the next boot.