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