]>
Commit | Line | Data |
---|---|---|
544a5910 AG |
1 | .\" Extended attributes manual page |
2 | .\" | |
3 | .\" Copyright (C) 2000, 2002, 2007 Andreas Gruenbacher <agruen@suse.de> | |
4 | .\" Copyright (C) 2001, 2002, 2004, 2007 Silicon Graphics, Inc. | |
5 | .\" All rights reserved. | |
6 | .\" | |
7 | .\" This is free documentation; you can redistribute it and/or | |
8 | .\" modify it under the terms of the GNU General Public License as | |
9 | .\" published by the Free Software Foundation; either version 2 of | |
10 | .\" the License, or (at your option) any later version. | |
11 | .\" | |
12 | .\" The GNU General Public License's references to "object code" | |
13 | .\" and "executables" are to be interpreted as the output of any | |
14 | .\" document formatting or typesetting system, including | |
15 | .\" intermediate and printed output. | |
16 | .\" | |
17 | .\" This manual is distributed in the hope that it will be useful, | |
18 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
19 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
20 | .\" GNU General Public License for more details. | |
21 | .\" | |
22 | .\" You should have received a copy of the GNU General Public | |
23 | .\" License along with this manual. If not, see | |
24 | .\" <http://www.gnu.org/licenses/>. | |
25 | .\" | |
367f5ee5 | 26 | .TH XATTR 7 |
544a5910 AG |
27 | .SH NAME |
28 | attr - Extended attributes | |
29 | .SH DESCRIPTION | |
30 | Extended attributes are name:value pairs associated permanently with | |
31 | files and directories, similar to the environment strings associated | |
32 | with a process. | |
33 | An attribute may be defined or undefined. | |
34 | If it is defined, its value may be empty or non-empty. | |
35 | .PP | |
36 | Extended attributes are extensions to the normal attributes which are | |
ebce8403 | 37 | associated with all inodes in the system (i.e., the |
544a5910 AG |
38 | .BR stat (2) |
39 | data). | |
40 | They are often used to provide additional functionality | |
ca7d9e34 | 41 | to a filesystem\(emfor example, additional security features such as |
544a5910 AG |
42 | Access Control Lists (ACLs) may be implemented using extended attributes. |
43 | .PP | |
d59b17a4 MK |
44 | Users with search access to a file or directory may use |
45 | .BR listxattr (2) | |
46 | to retrieve a list of attribute names defined for that file or directory. | |
544a5910 AG |
47 | .PP |
48 | Extended attributes are accessed as atomic objects. | |
d59b17a4 MK |
49 | Reading |
50 | .RB ( getxattr (2)) | |
51 | retrieves the whole value of an attribute and stores it in a buffer. | |
52 | Writing | |
53 | .RB ( setxattr (2)) | |
54 | replaces any previous value with the new value. | |
544a5910 | 55 | .PP |
54015724 | 56 | Space consumed for extended attributes may be counted towards the disk quotas |
544a5910 | 57 | of the file owner and file group. |
b63436d8 | 58 | .SS Extended attribute namespaces |
68d53b6d | 59 | Attribute names are null-terminated strings. |
544a5910 AG |
60 | The attribute name is always specified in the fully qualified |
61 | .IR namespace.attribute | |
ebce8403 | 62 | form, for example, |
544a5910 AG |
63 | .IR user.mime_type , |
64 | .IR trusted.md5sum , | |
65 | .IR system.posix_acl_access , | |
66 | or | |
67 | .IR security.selinux . | |
68 | .PP | |
69 | The namespace mechanism is used to define different classes of extended | |
70 | attributes. | |
ebce8403 MK |
71 | These different classes exist for several reasons; |
72 | for example, the permissions | |
544a5910 AG |
73 | and capabilities required for manipulating extended attributes of one |
74 | namespace may differ to another. | |
75 | .PP | |
ca7d9e34 | 76 | Currently, the |
544a5910 AG |
77 | .IR security , |
78 | .IR system , | |
79 | .IR trusted , | |
80 | and | |
81 | .IR user | |
933e4675 MK |
82 | extended attribute classes are defined as described below. |
83 | Additional classes may be added in the future. | |
544a5910 AG |
84 | .SS Extended security attributes |
85 | The security attribute namespace is used by kernel security modules, | |
d8ba7694 MK |
86 | such as Security Enhanced Linux, and also to implement file capabilities (see |
87 | .BR capabilities (7)). | |
544a5910 AG |
88 | Read and write access permissions to security attributes depend on the |
89 | policy implemented for each security attribute by the security module. | |
90 | When no security module is loaded, all processes have read access to | |
91 | extended security attributes, and write access is limited to processes | |
5ee7f61c MK |
92 | that have the |
93 | .B CAP_SYS_ADMIN | |
94 | capability. | |
544a5910 AG |
95 | .SS Extended system attributes |
96 | Extended system attributes are used by the kernel to store system | |
d8ba7694 | 97 | objects such as Access Control Lists. |
933e4675 | 98 | Read and write |
544a5910 AG |
99 | access permissions to system attributes depend on the policy implemented |
100 | for each system attribute implemented by filesystems in the kernel. | |
101 | .SS Trusted extended attributes | |
102 | Trusted extended attributes are visible and accessible only to processes that | |
5ee7f61c MK |
103 | have the |
104 | .B CAP_SYS_ADMIN | |
b4a61f89 | 105 | capability. |
544a5910 AG |
106 | Attributes in this class are used to implement mechanisms in user |
107 | space (i.e., outside the kernel) which keep information in extended attributes | |
108 | to which ordinary processes should not have access. | |
109 | .SS Extended user attributes | |
110 | Extended user attributes may be assigned to files and directories for | |
111 | storing arbitrary additional information such as the mime type, | |
933e4675 MK |
112 | character set or encoding of a file. |
113 | The access permissions for user | |
03a93c37 MK |
114 | attributes are defined by the file permission bits: |
115 | read permission is required to retrieve the attribute value, | |
116 | and writer permission is required to change it. | |
544a5910 AG |
117 | .PP |
118 | The file permission bits of regular files and directories are | |
119 | interpreted differently from the file permission bits of special files | |
933e4675 MK |
120 | and symbolic links. |
121 | For regular files and directories the file | |
544a5910 AG |
122 | permission bits define access to the file's contents, while for device special |
123 | files they define access to the device described by the special file. | |
933e4675 MK |
124 | The file permissions of symbolic links are not used in access checks. |
125 | These differences would allow users to consume filesystem resources in | |
126 | a way not controllable by disk quotas for group or world writable | |
127 | special files and directories. | |
544a5910 | 128 | .PP |
933e4675 | 129 | For this reason, |
355657c2 | 130 | extended user attributes are allowed only for regular files and directories, |
933e4675 | 131 | and access to extended user attributes is restricted to the |
544a5910 AG |
132 | owner and to users with appropriate capabilities for directories with the |
133 | sticky bit set (see the | |
134 | .BR chmod (1) | |
54015724 | 135 | manual page for an explanation of the sticky bit). |
b63436d8 | 136 | .SS Filesystem differences |
544a5910 AG |
137 | The kernel and the filesystem may place limits on the maximum number |
138 | and size of extended attributes that can be associated with a file. | |
6db035a3 | 139 | The VFS imposes limitations that an attribute names is limited to 255 bytes |
5c69f84a MK |
140 | and an attribute value is limited to 64 kB. |
141 | The list of attribute names that | |
54015724 | 142 | can be returned is also limited to 64 kB. |
6db035a3 | 143 | |
9a7d1c23 MK |
144 | Some filesystems, such as Reiserfs (and, historically, ext2 and ext3), |
145 | require the filesystem to be mounted with the | |
544a5910 AG |
146 | .B user_xattr |
147 | mount option in order for extended user attributes to be used. | |
148 | .PP | |
3d33987b | 149 | In the current ext2, ext3, and ext4 filesystem implementations, |
6ad46a9d MK |
150 | the total bytes used by the names and values of all of a files |
151 | extended attributes must fit in a single filesystem block (1024, 2048 | |
544a5910 AG |
152 | or 4096 bytes, depending on the block size specified when the |
153 | filesystem was created). | |
154 | .PP | |
b68d4dc3 | 155 | In the Btrfs, XFS, and Reiserfs filesystem implementations, there is no |
6db035a3 | 156 | practical limit on the number of extended attributes |
544a5910 AG |
157 | associated with a file, and the algorithms used to store extended |
158 | attribute information on disk are scalable. | |
edb159da MK |
159 | |
160 | In the JFS, XFS, and Reiserfs filesystem implementations, | |
161 | the limit on bytes used in an EA value is the ceiling imposed by the VFS. | |
7f4f24ea MK |
162 | |
163 | In the Btrfs filesystem implementation, | |
164 | the total bytes used for the name, value, and implementation overhead bytes | |
165 | is limited to the filesystem | |
166 | .I nodesize | |
54015724 | 167 | value (16 kB by default). |
b124a27b MK |
168 | .SH CONFORMING TO |
169 | Extended attributes are not specified in POSIX.1, but some other systems | |
170 | (e.g., the BSDs and Solaris) provide a similar feature. | |
7ee629ab | 171 | .SH NOTES |
544a5910 AG |
172 | Since the filesystems on which extended attributes are stored might also |
173 | be used on architectures with a different byte order and machine word | |
5871fb36 MK |
174 | size, care should be taken to store attribute values in an |
175 | architecture-independent format. | |
367f5ee5 MK |
176 | |
177 | This page was formerly named | |
178 | .BR attr (5). | |
31a369b8 MK |
179 | .\" .SH AUTHORS |
180 | .\" Andreas Gruenbacher, | |
181 | .\" .RI < a.gruenbacher@bestbits.at > | |
182 | .\" and the SGI XFS development team, | |
183 | .\" .RI < linux-xfs@oss.sgi.com >. | |
544a5910 | 184 | .SH SEE ALSO |
5ee7f61c | 185 | .BR getfattr (1), |
aad5c297 MK |
186 | .BR setfattr (1), |
187 | .BR getxattr (2), | |
188 | .BR listxattr (2), | |
189 | .BR removexattr (2), | |
190 | .BR setxattr (2), | |
191 | .BR acl (5), | |
192 | .BR capabilities (7) |