Documentation/filesystems/aufs/design/06dirren.txt

   1
   2 # Copyright (C) 2017-2020 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 Special handling for renaming a directory (DIRREN)
  18 ----------------------------------------------------------------------
  19 First, let's assume we have a simple usecase.
  20
  21 - /u = /rw + /ro
  22 - /rw/dirA exists
  23 - /ro/dirA and /ro/dirA/file exist too
  24 - there is no dirB on both branches
  25 - a user issues rename("dirA", "dirB")
  26
  27 Now, what should aufs behave against this rename(2)?
  28 There are a few possible cases.
  29
  30 A. returns EROFS.
  31    since dirA exists on a readonly branch which cannot be renamed.
  32 B. returns EXDEV.
  33    it is possible to copy-up dirA (only the dir itself), but the child
  34    entries ("file" in this case) should not be. it must be a bad
  35    approach to copy-up recursively.
  36 C. returns a success.
  37    even the branch /ro is readonly, aufs tries renaming it. Obviously it
  38    is a violation of aufs' policy.
  39 D. construct an extra information which indicates that /ro/dirA should
  40    be handled as the name of dirB.
  41    overlayfs has a similar feature called REDIRECT.
  42
  43 Until now, aufs implements the case B only which returns EXDEV, and
  44 expects the userspace application behaves like mv(1) which tries
  45 issueing rename(2) recursively.
  46
  47 A new aufs feature called DIRREN is introduced which implements the case
  48 D. There are several "extra information" added.
  49
  50 1. detailed info per renamed directory
  51    path: /rw/dirB/$AUFS_WH_DR_INFO_PFX.<lower branch-id>
  52 2. the inode-number list of directories on a branch
  53    path: /rw/dirB/$AUFS_WH_DR_BRHINO
  54
  55 The filename of "detailed info per directory" represents the lower
  56 branch, and its format is
  57 - a type of the branch id
  58   one of these.
  59   + uuid (not implemented yet)
  60   + fsid
  61   + dev
  62 - the inode-number of the branch root dir
  63
  64 And it contains these info in a single regular file.
  65 - magic number
  66 - branch's inode-number of the logically renamed dir
  67 - the name of the before-renamed dir
  68
  69 The "detailed info per directory" file is created in aufs rename(2), and
  70 loaded in any lookup.
  71 The info is considered in lookup for the matching case only. Here
  72 "matching" means that the root of branch (in the info filename) is same
  73 to the current looking-up branch. After looking-up the before-renamed
  74 name, the inode-number is compared. And the matched dentry is used.
  75
  76 The "inode-number list of directories" is a regular file which contains
  77 simply the inode-numbers on the branch. The file is created or updated
  78 in removing the branch, and loaded in adding the branch. Its lifetime is
  79 equal to the branch.
  80 The list is refered in lookup, and when the current target inode is
  81 found in the list, the aufs tries loading the "detailed info per
  82 directory" and get the changed and valid name of the dir.
  83
  84 Theoretically these "extra informaiton" may be able to be put into XATTR
  85 in the dir inode. But aufs doesn't choose this way because
  86 1. XATTR may not be supported by the branch (or its configuration)
  87 2. XATTR may have its size limit.
  88 3. XATTR may be less easy to convert than a regular file, when the
  89    format of the info is changed in the future.
  90 At the same time, I agree that the regular file approach is much slower
  91 than XATTR approach. So, in the future, aufs may take the XATTR or other
  92 better approach.
  93
  94 This DIRREN feature is enabled by aufs configuration, and is activated
  95 by a new mount option.
  96
  97 For the more complicated case, there is a work with UDBA option, which
  98 is to dected the direct access to the branches (by-passing aufs) and to
  99 maintain the cashes in aufs. Since a single cached aufs dentry may
 100 contains two names, before- and after-rename, the name comparision in
 101 UDBA handler may not work correctly. In this case, the behaviour will be
 102 equivalen to udba=reval case.