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

   1
   2 # Copyright (C) 2014-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, write to the Free Software
  16 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  17
  18
  19 Listing XATTR/EA and getting the value
  20 ----------------------------------------------------------------------
  21 For the inode standard attributes (owner, group, timestamps, etc.), aufs
  22 shows the values from the topmost existing file. This behaviour is good
  23 for the non-dir entries since the bahaviour exactly matches the shown
  24 information. But for the directories, aufs considers all the same named
  25 entries on the lower branches. Which means, if one of the lower entry
  26 rejects readdir call, then aufs returns an error even if the topmost
  27 entry allows it. This behaviour is necessary to respect the branch fs's
  28 security, but can make users confused since the user-visible standard
  29 attributes don't match the behaviour.
  30 To address this issue, aufs has a mount option called dirperm1 which
  31 checks the permission for the topmost entry only, and ignores the lower
  32 entry's permission.
  33
  34 A similar issue can happen around XATTR.
  35 getxattr(2) and listxattr(2) families behave as if dirperm1 option is
  36 always set. Otherwise these very unpleasant situation would happen.
  37 - listxattr(2) may return the duplicated entries.
  38 - users may not be able to remove or reset the XATTR forever,
  39
  40
  41 XATTR/EA support in the internal (copy,move)-(up,down)
  42 ----------------------------------------------------------------------
  43 Generally the extended attributes of inode are categorized as these.
  44 - "security" for LSM and capability.
  45 - "system" for posix ACL, 'acl' mount option is required for the branch
  46   fs generally.
  47 - "trusted" for userspace, CAP_SYS_ADMIN is required.
  48 - "user" for userspace, 'user_xattr' mount option is required for the
  49   branch fs generally.
  50
  51 Moreover there are some other categories. Aufs handles these rather
  52 unpopular categories as the ordinary ones, ie. there is no special
  53 condition nor exception.
  54
  55 In copy-up, the support for XATTR on the dst branch may differ from the
  56 src branch. In this case, the copy-up operation will get an error and
  57 the original user operation which triggered the copy-up will fail. It
  58 can happen that even all copy-up will fail.
  59 When both of src and dst branches support XATTR and if an error occurs
  60 during copying XATTR, then the copy-up should fail obviously. That is a
  61 good reason and aufs should return an error to userspace. But when only
  62 the src branch support that XATTR, aufs should not return an error.
  63 For example, the src branch supports ACL but the dst branch doesn't
  64 because the dst branch may natively un-support it or temporary
  65 un-support it due to "noacl" mount option. Of course, the dst branch fs
  66 may NOT return an error even if the XATTR is not supported. It is
  67 totally up to the branch fs.
  68
  69 Anyway when the aufs internal copy-up gets an error from the dst branch
  70 fs, then aufs tries removing the just copied entry and returns the error
  71 to the userspace. The worst case of this situation will be all copy-up
  72 will fail.
  73
  74 For the copy-up operation, there two basic approaches.
  75 - copy the specified XATTR only (by category above), and return the
  76   error unconditionally if it happens.
  77 - copy all XATTR, and ignore the error on the specified category only.
  78
  79 In order to support XATTR and to implement the correct behaviour, aufs
  80 chooses the latter approach and introduces some new branch attributes,
  81 "icexsec", "icexsys", "icextr", "icexusr", and "icexoth".
  82 They correspond to the XATTR namespaces (see above). Additionally, to be
  83 convenient, "icex" is also provided which means all "icex*" attributes
  84 are set (here the word "icex" stands for "ignore copy-error on XATTR").
  85
  86 The meaning of these attributes is to ignore the error from setting
  87 XATTR on that branch.
  88 Note that aufs tries copying all XATTR unconditionally, and ignores the
  89 error from the dst branch according to the specified attributes.
  90
  91 Some XATTR may have its default value. The default value may come from
  92 the parent dir or the environment. If the default value is set at the
  93 file creating-time, it will be overwritten by copy-up.
  94 Some contradiction may happen I am afraid.
  95 Do we need another attribute to stop copying XATTR? I am unsure. For
  96 now, aufs implements the branch attributes to ignore the error.