Documentation/filesystems/aufs/design/08shwh.txt

   1
   2 # Copyright (C) 2005-2017 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, see <http://www.gnu.org/licenses/>.
  16
  17 Show Whiteout Mode (shwh)
  18 ----------------------------------------------------------------------
  19 Generally aufs hides the name of whiteouts. But in some cases, to show
  20 them is very useful for users. For instance, creating a new middle layer
  21 (branch) by merging existing layers.
  22
  23 (borrowing aufs1 HOW-TO from a user, Michael Towers)
  24 When you have three branches,
  25 - Bottom: 'system', squashfs (underlying base system), read-only
  26 - Middle: 'mods', squashfs, read-only
  27 - Top: 'overlay', ram (tmpfs), read-write
  28
  29 The top layer is loaded at boot time and saved at shutdown, to preserve
  30 the changes made to the system during the session.
  31 When larger changes have been made, or smaller changes have accumulated,
  32 the size of the saved top layer data grows. At this point, it would be
  33 nice to be able to merge the two overlay branches ('mods' and 'overlay')
  34 and rewrite the 'mods' squashfs, clearing the top layer and thus
  35 restoring save and load speed.
  36
  37 This merging is simplified by the use of another aufs mount, of just the
  38 two overlay branches using the 'shwh' option.
  39 # mount -t aufs -o ro,shwh,br:/livesys/overlay=ro+wh:/livesys/mods=rr+wh \
  40         aufs /livesys/merge_union
  41
  42 A merged view of these two branches is then available at
  43 /livesys/merge_union, and the new feature is that the whiteouts are
  44 visible!
  45 Note that in 'shwh' mode the aufs mount must be 'ro', which will disable
  46 writing to all branches. Also the default mode for all branches is 'ro'.
  47 It is now possible to save the combined contents of the two overlay
  48 branches to a new squashfs, e.g.:
  49 # mksquashfs /livesys/merge_union /path/to/newmods.squash
  50
  51 This new squashfs archive can be stored on the boot device and the
  52 initramfs will use it to replace the old one at the next boot.