0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 Extended Attributes
0004 -------------------
0005
0006 Extended attributes (xattrs) are typically stored in a separate data
0007 block on the disk and referenced from inodes via ``inode.i_file_acl*``.
0008 The first use of extended attributes seems to have been for storing file
0009 ACLs and other security data (selinux). With the ``user_xattr`` mount
0010 option it is possible for users to store extended attributes so long as
0011 all attribute names begin with “user”; this restriction seems to have
0012 disappeared as of Linux 3.0.
0013
0014 There are two places where extended attributes can be found. The first
0015 place is between the end of each inode entry and the beginning of the
0016 next inode entry. For example, if inode.i_extra_isize = 28 and
0017 sb.inode_size = 256, then there are 256 - (128 + 28) = 100 bytes
0018 available for in-inode extended attribute storage. The second place
0019 where extended attributes can be found is in the block pointed to by
0020 ``inode.i_file_acl``. As of Linux 3.11, it is not possible for this
0021 block to contain a pointer to a second extended attribute block (or even
0022 the remaining blocks of a cluster). In theory it is possible for each
0023 attribute's value to be stored in a separate data block, though as of
0024 Linux 3.11 the code does not permit this.
0025
0026 Keys are generally assumed to be ASCIIZ strings, whereas values can be
0027 strings or binary data.
0028
0029 Extended attributes, when stored after the inode, have a header
0030 ``ext4_xattr_ibody_header`` that is 4 bytes long:
0031
0032 .. list-table::
0033 :widths: 8 8 24 40
0034 :header-rows: 1
0035
0036 * - Offset
0037 - Type
0038 - Name
0039 - Description
0040 * - 0x0
0041 - __le32
0042 - h_magic
0043 - Magic number for identification, 0xEA020000. This value is set by the
0044 Linux driver, though e2fsprogs doesn't seem to check it(?)
0045
0046 The beginning of an extended attribute block is in
0047 ``struct ext4_xattr_header``, which is 32 bytes long:
0048
0049 .. list-table::
0050 :widths: 8 8 24 40
0051 :header-rows: 1
0052
0053 * - Offset
0054 - Type
0055 - Name
0056 - Description
0057 * - 0x0
0058 - __le32
0059 - h_magic
0060 - Magic number for identification, 0xEA020000.
0061 * - 0x4
0062 - __le32
0063 - h_refcount
0064 - Reference count.
0065 * - 0x8
0066 - __le32
0067 - h_blocks
0068 - Number of disk blocks used.
0069 * - 0xC
0070 - __le32
0071 - h_hash
0072 - Hash value of all attributes.
0073 * - 0x10
0074 - __le32
0075 - h_checksum
0076 - Checksum of the extended attribute block.
0077 * - 0x14
0078 - __u32
0079 - h_reserved[3]
0080 - Zero.
0081
0082 The checksum is calculated against the FS UUID, the 64-bit block number
0083 of the extended attribute block, and the entire block (header +
0084 entries).
0085
0086 Following the ``struct ext4_xattr_header`` or
0087 ``struct ext4_xattr_ibody_header`` is an array of
0088 ``struct ext4_xattr_entry``; each of these entries is at least 16 bytes
0089 long. When stored in an external block, the ``struct ext4_xattr_entry``
0090 entries must be stored in sorted order. The sort order is
0091 ``e_name_index``, then ``e_name_len``, and finally ``e_name``.
0092 Attributes stored inside an inode do not need be stored in sorted order.
0093
0094 .. list-table::
0095 :widths: 8 8 24 40
0096 :header-rows: 1
0097
0098 * - Offset
0099 - Type
0100 - Name
0101 - Description
0102 * - 0x0
0103 - __u8
0104 - e_name_len
0105 - Length of name.
0106 * - 0x1
0107 - __u8
0108 - e_name_index
0109 - Attribute name index. There is a discussion of this below.
0110 * - 0x2
0111 - __le16
0112 - e_value_offs
0113 - Location of this attribute's value on the disk block where it is stored.
0114 Multiple attributes can share the same value. For an inode attribute
0115 this value is relative to the start of the first entry; for a block this
0116 value is relative to the start of the block (i.e. the header).
0117 * - 0x4
0118 - __le32
0119 - e_value_inum
0120 - The inode where the value is stored. Zero indicates the value is in the
0121 same block as this entry. This field is only used if the
0122 INCOMPAT_EA_INODE feature is enabled.
0123 * - 0x8
0124 - __le32
0125 - e_value_size
0126 - Length of attribute value.
0127 * - 0xC
0128 - __le32
0129 - e_hash
0130 - Hash value of attribute name and attribute value. The kernel doesn't
0131 update the hash for in-inode attributes, so for that case this value
0132 must be zero, because e2fsck validates any non-zero hash regardless of
0133 where the xattr lives.
0134 * - 0x10
0135 - char
0136 - e_name[e_name_len]
0137 - Attribute name. Does not include trailing NULL.
0138
0139 Attribute values can follow the end of the entry table. There appears to
0140 be a requirement that they be aligned to 4-byte boundaries. The values
0141 are stored starting at the end of the block and grow towards the
0142 xattr_header/xattr_entry table. When the two collide, the overflow is
0143 put into a separate disk block. If the disk block fills up, the
0144 filesystem returns -ENOSPC.
0145
0146 The first four fields of the ``ext4_xattr_entry`` are set to zero to
0147 mark the end of the key list.
0148
0149 Attribute Name Indices
0150 ~~~~~~~~~~~~~~~~~~~~~~
0151
0152 Logically speaking, extended attributes are a series of key=value pairs.
0153 The keys are assumed to be NULL-terminated strings. To reduce the amount
0154 of on-disk space that the keys consume, the beginning of the key string
0155 is matched against the attribute name index. If a match is found, the
0156 attribute name index field is set, and matching string is removed from
0157 the key name. Here is a map of name index values to key prefixes:
0158
0159 .. list-table::
0160 :widths: 16 64
0161 :header-rows: 1
0162
0163 * - Name Index
0164 - Key Prefix
0165 * - 0
0166 - (no prefix)
0167 * - 1
0168 - “user.”
0169 * - 2
0170 - “system.posix_acl_access”
0171 * - 3
0172 - “system.posix_acl_default”
0173 * - 4
0174 - “trusted.”
0175 * - 6
0176 - “security.”
0177 * - 7
0178 - “system.” (inline_data only?)
0179 * - 8
0180 - “system.richacl” (SuSE kernels only?)
0181
0182 For example, if the attribute key is “user.fubar”, the attribute name
0183 index is set to 1 and the “fubar” name is recorded on disk.
0184
0185 POSIX ACLs
0186 ~~~~~~~~~~
0187
0188 POSIX ACLs are stored in a reduced version of the Linux kernel (and
0189 libacl's) internal ACL format. The key difference is that the version
0190 number is different (1) and the ``e_id`` field is only stored for named
0191 user and group ACLs.
