From 544a5910f779d41c6f6edd69f5942c19ff1660ca Mon Sep 17 00:00:00 2001 From: Andreas Gruenbacher Date: Wed, 22 Apr 2015 08:28:34 +0200 Subject: [PATCH] attr.7: Import attr(5) man page from the 'attr' project After discussions with Andreas Gruenbacher, it makes sense to move this page into man-pages, since it mostly relates to kernel details. Signed-off-by: Michael Kerrisk --- man7/attr.7 | 153 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 man7/attr.7 diff --git a/man7/attr.7 b/man7/attr.7 new file mode 100644 index 000000000..a02757d3e --- /dev/null +++ b/man7/attr.7 @@ -0,0 +1,153 @@ +.\" Extended attributes manual page +.\" +.\" Copyright (C) 2000, 2002, 2007 Andreas Gruenbacher +.\" Copyright (C) 2001, 2002, 2004, 2007 Silicon Graphics, Inc. +.\" All rights reserved. +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual. If not, see +.\" . +.\" +.TH ATTR 5 +.SH NAME +attr - Extended attributes +.SH DESCRIPTION +Extended attributes are name:value pairs associated permanently with +files and directories, similar to the environment strings associated +with a process. +An attribute may be defined or undefined. +If it is defined, its value may be empty or non-empty. +.PP +Extended attributes are extensions to the normal attributes which are +associated with all inodes in the system (i.e. the +.BR stat (2) +data). +They are often used to provide additional functionality +to a filesystem \- for example, additional security features such as +Access Control Lists (ACLs) may be implemented using extended attributes. +.PP +Users with search access to a file or directory may retrieve a list of +attribute names defined for that file or directory. +.PP +Extended attributes are accessed as atomic objects. +Reading retrieves the whole value of an attribute and stores it in a buffer. +Writing replaces any previous value with the new value. +.PP +Space consumed for extended attributes is counted towards the disk quotas +of the file owner and file group. +.PP +Currently, support for extended attributes is implemented on Linux by the +ext2, ext3, ext4, XFS, JFS and reiserfs filesystems. +.SH EXTENDED ATTRIBUTE NAMESPACES +Attribute names are zero-terminated strings. +The attribute name is always specified in the fully qualified +.IR namespace.attribute +form, eg. +.IR user.mime_type , +.IR trusted.md5sum , +.IR system.posix_acl_access , +or +.IR security.selinux . +.PP +The namespace mechanism is used to define different classes of extended +attributes. +These different classes exist for several reasons, e.g. the permissions +and capabilities required for manipulating extended attributes of one +namespace may differ to another. +.PP +Currently the +.IR security , +.IR system , +.IR trusted , +and +.IR user +extended attribute classes are defined as described below. Additional +classes may be added in the future. +.SS Extended security attributes +The security attribute namespace is used by kernel security modules, +such as Security Enhanced Linux. +Read and write access permissions to security attributes depend on the +policy implemented for each security attribute by the security module. +When no security module is loaded, all processes have read access to +extended security attributes, and write access is limited to processes +that have the CAP_SYS_ADMIN capability. +.SS Extended system attributes +Extended system attributes are used by the kernel to store system +objects such as Access Control Lists and Capabilities. Read and write +access permissions to system attributes depend on the policy implemented +for each system attribute implemented by filesystems in the kernel. +.SS Trusted extended attributes +Trusted extended attributes are visible and accessible only to processes that +have the CAP_SYS_ADMIN capability (the super user usually has this +capability). +Attributes in this class are used to implement mechanisms in user +space (i.e., outside the kernel) which keep information in extended attributes +to which ordinary processes should not have access. +.SS Extended user attributes +Extended user attributes may be assigned to files and directories for +storing arbitrary additional information such as the mime type, +character set or encoding of a file. The access permissions for user +attributes are defined by the file permission bits. +.PP +The file permission bits of regular files and directories are +interpreted differently from the file permission bits of special files +and symbolic links. For regular files and directories the file +permission bits define access to the file's contents, while for device special +files they define access to the device described by the special file. +The file permissions of symbolic links are not used in access +checks. These differences would allow users to consume filesystem resources in +a way not controllable by disk quotas for group or world writable special files and directories. +.PP +For this reason, extended user attributes are only allowed for regular files and directories, and access to extended user attributes is restricted to the +owner and to users with appropriate capabilities for directories with the +sticky bit set (see the +.BR chmod (1) +manual page for an explanation of Sticky Directories). +.SH FILESYSTEM DIFFERENCES +The kernel and the filesystem may place limits on the maximum number +and size of extended attributes that can be associated with a file. +Some file systems, such as ext2/3 and reiserfs, require the filesystem +to be mounted with the +.B user_xattr +mount option in order for extended user attributes to be used. +.PP +In the current ext2, ext3 and ext4 filesystem implementations, each +extended attribute must fit on a single filesystem block (1024, 2048 +or 4096 bytes, depending on the block size specified when the +filesystem was created). +.PP +In the XFS and reiserfs filesystem implementations, there is no +practical limit on the number or size of extended attributes +associated with a file, and the algorithms used to store extended +attribute information on disk are scalable. +.PP +In the JFS filesystem implementation, names can be up to 255 bytes and +values up to 65,535 bytes. +.SH ADDITIONAL NOTES +Since the filesystems on which extended attributes are stored might also +be used on architectures with a different byte order and machine word +size, care should be taken to store attribute values in an architecture +independent format. +.SH AUTHORS +Andreas Gruenbacher, +.RI < a.gruenbacher@bestbits.at > +and the SGI XFS development team, +.RI < linux-xfs@oss.sgi.com >. +.SH SEE ALSO +getfattr(1), +setfattr(1).