Documentation/filesystems/aufs/design/05wbr_policy.txt

   1
   2 # Copyright (C) 2005-2013 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
  17
  18 Policies to Select One among Multiple Writable Branches
  19 ----------------------------------------------------------------------
  20 When the number of writable branch is more than one, aufs has to decide
  21 the target branch for file creation or copy-up. By default, the highest
  22 writable branch which has the parent (or ancestor) dir of the target
  23 file is chosen (top-down-parent policy).
  24 By user's request, aufs implements some other policies to select the
  25 writable branch, for file creation two policies, round-robin and
  26 most-free-space policies. For copy-up three policies, top-down-parent,
  27 bottom-up-parent and bottom-up policies.
  28
  29 As expected, the round-robin policy selects the branch in circular. When
  30 you have two writable branches and creates 10 new files, 5 files will be
  31 created for each branch. mkdir(2) systemcall is an exception. When you
  32 create 10 new directories, all will be created on the same branch.
  33 And the most-free-space policy selects the one which has most free
  34 space among the writable branches. The amount of free space will be
  35 checked by aufs internally, and users can specify its time interval.
  36
  37 The policies for copy-up is more simple,
  38 top-down-parent is equivalent to the same named on in create policy,
  39 bottom-up-parent selects the writable branch where the parent dir
  40 exists and the nearest upper one from the copyup-source,
  41 bottom-up selects the nearest upper writable branch from the
  42 copyup-source, regardless the existence of the parent dir.
  43
  44 There are some rules or exceptions to apply these policies.
  45 - If there is a readonly branch above the policy-selected branch and
  46   the parent dir is marked as opaque (a variation of whiteout), or the
  47   target (creating) file is whiteout-ed on the upper readonly branch,
  48   then the result of the policy is ignored and the target file will be
  49   created on the nearest upper writable branch than the readonly branch.
  50 - If there is a writable branch above the policy-selected branch and
  51   the parent dir is marked as opaque or the target file is whiteouted
  52   on the branch, then the result of the policy is ignored and the target
  53   file will be created on the highest one among the upper writable
  54   branches who has diropq or whiteout. In case of whiteout, aufs removes
  55   it as usual.
  56 - link(2) and rename(2) systemcalls are exceptions in every policy.
  57   They try selecting the branch where the source exists as possible
  58   since copyup a large file will take long time. If it can't be,
  59   ie. the branch where the source exists is readonly, then they will
  60   follow the copyup policy.
  61 - There is an exception for rename(2) when the target exists.
  62   If the rename target exists, aufs compares the index of the branches
  63   where the source and the target exists and selects the higher
  64   one. If the selected branch is readonly, then aufs follows the
  65   copyup policy.