]>
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 | .\" | |
26 | .TH ATTR 5 | |
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 | |
44 | Users with search access to a file or directory may retrieve a list of | |
45 | attribute names defined for that file or directory. | |
46 | .PP | |
47 | Extended attributes are accessed as atomic objects. | |
48 | Reading retrieves the whole value of an attribute and stores it in a buffer. | |
49 | Writing replaces any previous value with the new value. | |
50 | .PP | |
51 | Space consumed for extended attributes is counted towards the disk quotas | |
52 | of the file owner and file group. | |
53 | .PP | |
b68d4dc3 MK |
54 | Currently, the filesystems that support extended attributes include |
55 | Btrfs, ext2, ext3, ext4, XFS, JFS, and Reiserfs. | |
b63436d8 | 56 | .SS Extended attribute namespaces |
68d53b6d | 57 | Attribute names are null-terminated strings. |
544a5910 AG |
58 | The attribute name is always specified in the fully qualified |
59 | .IR namespace.attribute | |
ebce8403 | 60 | form, for example, |
544a5910 AG |
61 | .IR user.mime_type , |
62 | .IR trusted.md5sum , | |
63 | .IR system.posix_acl_access , | |
64 | or | |
65 | .IR security.selinux . | |
66 | .PP | |
67 | The namespace mechanism is used to define different classes of extended | |
68 | attributes. | |
ebce8403 MK |
69 | These different classes exist for several reasons; |
70 | for example, the permissions | |
544a5910 AG |
71 | and capabilities required for manipulating extended attributes of one |
72 | namespace may differ to another. | |
73 | .PP | |
ca7d9e34 | 74 | Currently, the |
544a5910 AG |
75 | .IR security , |
76 | .IR system , | |
77 | .IR trusted , | |
78 | and | |
79 | .IR user | |
933e4675 MK |
80 | extended attribute classes are defined as described below. |
81 | Additional classes may be added in the future. | |
544a5910 AG |
82 | .SS Extended security attributes |
83 | The security attribute namespace is used by kernel security modules, | |
d8ba7694 MK |
84 | such as Security Enhanced Linux, and also to implement file capabilities (see |
85 | .BR capabilities (7)). | |
544a5910 AG |
86 | Read and write access permissions to security attributes depend on the |
87 | policy implemented for each security attribute by the security module. | |
88 | When no security module is loaded, all processes have read access to | |
89 | extended security attributes, and write access is limited to processes | |
5ee7f61c MK |
90 | that have the |
91 | .B CAP_SYS_ADMIN | |
92 | capability. | |
544a5910 AG |
93 | .SS Extended system attributes |
94 | Extended system attributes are used by the kernel to store system | |
d8ba7694 | 95 | objects such as Access Control Lists. |
933e4675 | 96 | Read and write |
544a5910 AG |
97 | access permissions to system attributes depend on the policy implemented |
98 | for each system attribute implemented by filesystems in the kernel. | |
99 | .SS Trusted extended attributes | |
100 | Trusted extended attributes are visible and accessible only to processes that | |
5ee7f61c MK |
101 | have the |
102 | .B CAP_SYS_ADMIN | |
b4a61f89 | 103 | capability. |
544a5910 AG |
104 | Attributes in this class are used to implement mechanisms in user |
105 | space (i.e., outside the kernel) which keep information in extended attributes | |
106 | to which ordinary processes should not have access. | |
107 | .SS Extended user attributes | |
108 | Extended user attributes may be assigned to files and directories for | |
109 | storing arbitrary additional information such as the mime type, | |
933e4675 MK |
110 | character set or encoding of a file. |
111 | The access permissions for user | |
544a5910 AG |
112 | attributes are defined by the file permission bits. |
113 | .PP | |
114 | The file permission bits of regular files and directories are | |
115 | interpreted differently from the file permission bits of special files | |
933e4675 MK |
116 | and symbolic links. |
117 | For regular files and directories the file | |
544a5910 AG |
118 | permission bits define access to the file's contents, while for device special |
119 | files they define access to the device described by the special file. | |
933e4675 MK |
120 | The file permissions of symbolic links are not used in access checks. |
121 | These differences would allow users to consume filesystem resources in | |
122 | a way not controllable by disk quotas for group or world writable | |
123 | special files and directories. | |
544a5910 | 124 | .PP |
933e4675 | 125 | For this reason, |
355657c2 | 126 | extended user attributes are allowed only for regular files and directories, |
933e4675 | 127 | and access to extended user attributes is restricted to the |
544a5910 AG |
128 | owner and to users with appropriate capabilities for directories with the |
129 | sticky bit set (see the | |
130 | .BR chmod (1) | |
131 | manual page for an explanation of Sticky Directories). | |
b63436d8 | 132 | .SS Filesystem differences |
544a5910 AG |
133 | The kernel and the filesystem may place limits on the maximum number |
134 | and size of extended attributes that can be associated with a file. | |
8d75a7a8 | 135 | Some filesystems, such as ext2/3 and Reiserfs, require the filesystem |
544a5910 AG |
136 | to be mounted with the |
137 | .B user_xattr | |
138 | mount option in order for extended user attributes to be used. | |
139 | .PP | |
140 | In the current ext2, ext3 and ext4 filesystem implementations, each | |
141 | extended attribute must fit on a single filesystem block (1024, 2048 | |
142 | or 4096 bytes, depending on the block size specified when the | |
143 | filesystem was created). | |
144 | .PP | |
b68d4dc3 | 145 | In the Btrfs, XFS, and Reiserfs filesystem implementations, there is no |
544a5910 AG |
146 | practical limit on the number or size of extended attributes |
147 | associated with a file, and the algorithms used to store extended | |
148 | attribute information on disk are scalable. | |
149 | .PP | |
150 | In the JFS filesystem implementation, names can be up to 255 bytes and | |
151 | values up to 65,535 bytes. | |
b124a27b MK |
152 | .SH CONFORMING TO |
153 | Extended attributes are not specified in POSIX.1, but some other systems | |
154 | (e.g., the BSDs and Solaris) provide a similar feature. | |
7ee629ab | 155 | .SH NOTES |
544a5910 AG |
156 | Since the filesystems on which extended attributes are stored might also |
157 | be used on architectures with a different byte order and machine word | |
5871fb36 MK |
158 | size, care should be taken to store attribute values in an |
159 | architecture-independent format. | |
31a369b8 MK |
160 | .\" .SH AUTHORS |
161 | .\" Andreas Gruenbacher, | |
162 | .\" .RI < a.gruenbacher@bestbits.at > | |
163 | .\" and the SGI XFS development team, | |
164 | .\" .RI < linux-xfs@oss.sgi.com >. | |
544a5910 | 165 | .SH SEE ALSO |
5ee7f61c | 166 | .BR getfattr (1), |
aad5c297 MK |
167 | .BR setfattr (1), |
168 | .BR getxattr (2), | |
169 | .BR listxattr (2), | |
170 | .BR removexattr (2), | |
171 | .BR setxattr (2), | |
172 | .BR acl (5), | |
173 | .BR capabilities (7) |