attributes.rst 6.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191
  1. .. SPDX-License-Identifier: GPL-2.0
  2. Extended Attributes
  3. -------------------
  4. Extended attributes (xattrs) are typically stored in a separate data
  5. block on the disk and referenced from inodes via ``inode.i_file_acl*``.
  6. The first use of extended attributes seems to have been for storing file
  7. ACLs and other security data (selinux). With the ``user_xattr`` mount
  8. option it is possible for users to store extended attributes so long as
  9. all attribute names begin with “user”; this restriction seems to have
  10. disappeared as of Linux 3.0.
  11. There are two places where extended attributes can be found. The first
  12. place is between the end of each inode entry and the beginning of the
  13. next inode entry. For example, if inode.i\_extra\_isize = 28 and
  14. sb.inode\_size = 256, then there are 256 - (128 + 28) = 100 bytes
  15. available for in-inode extended attribute storage. The second place
  16. where extended attributes can be found is in the block pointed to by
  17. ``inode.i_file_acl``. As of Linux 3.11, it is not possible for this
  18. block to contain a pointer to a second extended attribute block (or even
  19. the remaining blocks of a cluster). In theory it is possible for each
  20. attribute's value to be stored in a separate data block, though as of
  21. Linux 3.11 the code does not permit this.
  22. Keys are generally assumed to be ASCIIZ strings, whereas values can be
  23. strings or binary data.
  24. Extended attributes, when stored after the inode, have a header
  25. ``ext4_xattr_ibody_header`` that is 4 bytes long:
  26. .. list-table::
  27. :widths: 8 8 24 40
  28. :header-rows: 1
  29. * - Offset
  30. - Type
  31. - Name
  32. - Description
  33. * - 0x0
  34. - \_\_le32
  35. - h\_magic
  36. - Magic number for identification, 0xEA020000. This value is set by the
  37. Linux driver, though e2fsprogs doesn't seem to check it(?)
  38. The beginning of an extended attribute block is in
  39. ``struct ext4_xattr_header``, which is 32 bytes long:
  40. .. list-table::
  41. :widths: 8 8 24 40
  42. :header-rows: 1
  43. * - Offset
  44. - Type
  45. - Name
  46. - Description
  47. * - 0x0
  48. - \_\_le32
  49. - h\_magic
  50. - Magic number for identification, 0xEA020000.
  51. * - 0x4
  52. - \_\_le32
  53. - h\_refcount
  54. - Reference count.
  55. * - 0x8
  56. - \_\_le32
  57. - h\_blocks
  58. - Number of disk blocks used.
  59. * - 0xC
  60. - \_\_le32
  61. - h\_hash
  62. - Hash value of all attributes.
  63. * - 0x10
  64. - \_\_le32
  65. - h\_checksum
  66. - Checksum of the extended attribute block.
  67. * - 0x14
  68. - \_\_u32
  69. - h\_reserved[3]
  70. - Zero.
  71. The checksum is calculated against the FS UUID, the 64-bit block number
  72. of the extended attribute block, and the entire block (header +
  73. entries).
  74. Following the ``struct ext4_xattr_header`` or
  75. ``struct ext4_xattr_ibody_header`` is an array of
  76. ``struct ext4_xattr_entry``; each of these entries is at least 16 bytes
  77. long. When stored in an external block, the ``struct ext4_xattr_entry``
  78. entries must be stored in sorted order. The sort order is
  79. ``e_name_index``, then ``e_name_len``, and finally ``e_name``.
  80. Attributes stored inside an inode do not need be stored in sorted order.
  81. .. list-table::
  82. :widths: 8 8 24 40
  83. :header-rows: 1
  84. * - Offset
  85. - Type
  86. - Name
  87. - Description
  88. * - 0x0
  89. - \_\_u8
  90. - e\_name\_len
  91. - Length of name.
  92. * - 0x1
  93. - \_\_u8
  94. - e\_name\_index
  95. - Attribute name index. There is a discussion of this below.
  96. * - 0x2
  97. - \_\_le16
  98. - e\_value\_offs
  99. - Location of this attribute's value on the disk block where it is stored.
  100. Multiple attributes can share the same value. For an inode attribute
  101. this value is relative to the start of the first entry; for a block this
  102. value is relative to the start of the block (i.e. the header).
  103. * - 0x4
  104. - \_\_le32
  105. - e\_value\_inum
  106. - The inode where the value is stored. Zero indicates the value is in the
  107. same block as this entry. This field is only used if the
  108. INCOMPAT\_EA\_INODE feature is enabled.
  109. * - 0x8
  110. - \_\_le32
  111. - e\_value\_size
  112. - Length of attribute value.
  113. * - 0xC
  114. - \_\_le32
  115. - e\_hash
  116. - Hash value of attribute name and attribute value. The kernel doesn't
  117. update the hash for in-inode attributes, so for that case this value
  118. must be zero, because e2fsck validates any non-zero hash regardless of
  119. where the xattr lives.
  120. * - 0x10
  121. - char
  122. - e\_name[e\_name\_len]
  123. - Attribute name. Does not include trailing NULL.
  124. Attribute values can follow the end of the entry table. There appears to
  125. be a requirement that they be aligned to 4-byte boundaries. The values
  126. are stored starting at the end of the block and grow towards the
  127. xattr\_header/xattr\_entry table. When the two collide, the overflow is
  128. put into a separate disk block. If the disk block fills up, the
  129. filesystem returns -ENOSPC.
  130. The first four fields of the ``ext4_xattr_entry`` are set to zero to
  131. mark the end of the key list.
  132. Attribute Name Indices
  133. ~~~~~~~~~~~~~~~~~~~~~~
  134. Logically speaking, extended attributes are a series of key=value pairs.
  135. The keys are assumed to be NULL-terminated strings. To reduce the amount
  136. of on-disk space that the keys consume, the beginning of the key string
  137. is matched against the attribute name index. If a match is found, the
  138. attribute name index field is set, and matching string is removed from
  139. the key name. Here is a map of name index values to key prefixes:
  140. .. list-table::
  141. :widths: 16 64
  142. :header-rows: 1
  143. * - Name Index
  144. - Key Prefix
  145. * - 0
  146. - (no prefix)
  147. * - 1
  148. - “user.”
  149. * - 2
  150. - “system.posix\_acl\_access”
  151. * - 3
  152. - “system.posix\_acl\_default”
  153. * - 4
  154. - “trusted.”
  155. * - 6
  156. - “security.”
  157. * - 7
  158. - “system.” (inline\_data only?)
  159. * - 8
  160. - “system.richacl” (SuSE kernels only?)
  161. For example, if the attribute key is “user.fubar”, the attribute name
  162. index is set to 1 and the “fubar” name is recorded on disk.
  163. POSIX ACLs
  164. ~~~~~~~~~~
  165. POSIX ACLs are stored in a reduced version of the Linux kernel (and
  166. libacl's) internal ACL format. The key difference is that the version
  167. number is different (1) and the ``e_id`` field is only stored for named
  168. user and group ACLs.