From c4fb1a79a00ec0fb92886bad5138b1a5ec92bfbe Mon Sep 17 00:00:00 2001 From: Alexandr Savca Date: Thu, 9 Jan 2025 23:29:53 +0200 Subject: [PATCH] add acl(5) & xattr(7), update util-linux man pages --- acl.5.html | 511 +++++++++++++++++++++++++++++++++++++++++++++++++ blkid.8.html | 8 +- config.mk | 2 + fstab.5.html | 17 +- mkfs.8.html | 8 +- mkswap.8.html | 8 +- more.1.html | 8 +- rfkill.8.html | 8 +- setterm.1.html | 8 +- xattr.7.html | 174 +++++++++++++++++ 10 files changed, 721 insertions(+), 31 deletions(-) create mode 100644 acl.5.html create mode 100644 xattr.7.html diff --git a/acl.5.html b/acl.5.html new file mode 100644 index 0000000..27d9dee --- /dev/null +++ b/acl.5.html @@ -0,0 +1,511 @@ + + + + + + + + ACL(5) + + + + + + + + +
ACL(5)File Formats ManualACL(5)
+
+
+

+

acl — Access + Control Lists

+
+
+

+

This manual page describes POSIX Access Control Lists, which are + used to define more fine-grained discretionary access rights for files and + directories.

+
+
+

+

Every object can be thought of as having associated with it an ACL + that governs the discretionary access to that object; this ACL is referred + to as an access ACL. In addition, a directory may have an associated ACL + that governs the initial access ACL for objects created within that + directory; this ACL is referred to as a default ACL.

+
+
+

+

An ACL consists of a set of ACL entries. An ACL entry specifies + the access permissions on the associated object for an individual user or a + group of users as a combination of read, write and search/execute + permissions.

+

An ACL entry contains an entry tag type, an optional entry tag + qualifier, and a set of permissions. We use the term qualifier to denote the + entry tag qualifier of an ACL entry.

+

The qualifier denotes the identifier of a user or a group, for + entries with tag types of ACL_USER or ACL_GROUP, respectively. Entries with + tag types other than ACL_USER or ACL_GROUP have no defined qualifiers.

+

The following entry tag types are defined:

+
+
+
ACL_USER_OBJ
+
The ACL_USER_OBJ entry denotes access rights for the file owner.
+
ACL_USER
+
ACL_USER entries denote access rights for users identified by the entry's + qualifier.
+
ACL_GROUP_OBJ
+
The ACL_GROUP_OBJ entry denotes access rights for the file group.
+
ACL_GROUP
+
ACL_GROUP entries denote access rights for groups identified by the + entry's qualifier.
+
ACL_MASK
+
The ACL_MASK entry denotes the maximum access rights that can be granted + by entries of type ACL_USER, ACL_GROUP_OBJ, or ACL_GROUP.
+
ACL_OTHER
+
The ACL_OTHER entry denotes access rights for processes that do not match + any other entry in the ACL.
+
+
+

When an access check is performed, the ACL_USER_OBJ and ACL_USER + entries are tested against the effective user ID. The effective group ID, as + well as all supplementary group IDs are tested against the ACL_GROUP_OBJ and + ACL_GROUP entries.

+
+
+

+

A valid ACL contains exactly one entry with each of the + ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER tag types. Entries with ACL_USER + and ACL_GROUP tag types may appear zero or more times in an ACL. An ACL that + contains entries of ACL_USER or ACL_GROUP tag types must contain exactly one + entry of the ACL_MASK tag type. If an ACL contains no entries of ACL_USER or + ACL_GROUP tag types, the ACL_MASK entry is optional.

+

All user ID qualifiers must be unique among all entries of + ACL_USER tag type, and all group IDs must be unique among all entries of + ACL_GROUP tag type.

+

+
+ The + () + function returns an ACL with zero ACL entries as the default ACL of a + directory, if the directory is not associated with a default ACL. The + () + function also accepts an ACL with zero ACL entries as a valid default ACL + for directories, denoting that the directory shall not be associated with a + default ACL. This is equivalent to using the + () + function.

+
+
+

+

The permissions defined by ACLs are a superset of the permissions + specified by the file permission bits.

+

There is a correspondence between the file owner, group, and other + permissions and specific ACL entries: the owner permissions correspond to + the permissions of the ACL_USER_OBJ entry. If the ACL has an ACL_MASK entry, + the group permissions correspond to the permissions of the ACL_MASK entry. + Otherwise, if the ACL has no ACL_MASK entry, the group permissions + correspond to the permissions of the ACL_GROUP_OBJ entry. The other + permissions correspond to the permissions of the ACL_OTHER entry.

+

The file owner, group, and other permissions always match the + permissions of the corresponding ACL entry. Modification of the file + permission bits results in the modification of the associated ACL entries, + and modification of these ACL entries results in the modification of the + file permission bits.

+
+
+

+

The access ACL of a file object is initialized when the object is + created with any of the + (), + (), + (), + (), + or + () + functions. If a default ACL is associated with a directory, the + mode parameter to the functions creating file objects + and the default ACL of the directory are used to determine the ACL of the + new object:

+
    +
  1. The new object inherits the default ACL of the containing directory as its + access ACL.
    2. +
  2. The access ACL entries corresponding to the file permission bits are + modified so that they contain no permissions that are not contained in the + permissions specified by the mode parameter.
    3. +
+

If no default ACL is associated with a directory, the + mode parameter to the functions creating file objects + and the file creation mask (see + umask(2)) are used to determine the + ACL of the new object:

+
    +
  1. The new object is assigned an access ACL containing entries of tag types + ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER. The permissions of these + entries are set to the permissions specified by the file creation + mask.
    2. +
  2. The access ACL entries corresponding to the file permission bits are + modified so that they contain no permissions that are not contained in the + permissions specified by the mode parameter.
    3. +
+
+
+

+

A process may request read, write, or execute/search access to a + file object protected by an ACL. The access check algorithm determines + whether access to the object will be granted.

+
    +
  1. the + effective user ID of the process matches the user ID of the file object + owner, then +
    if the ACL_USER_OBJ entry + contains the requested permissions, access is granted, +

    else access is denied.

    +
    +
    2. +
  2. else if the effective user ID of the process matches the + qualifier of any entry of type ACL_USER, then +
    if the matching ACL_USER + entry and the ACL_MASK entry contain the requested permissions, access is + granted, +

    else access is denied.

    +
    +
    3. +
  3. else if the effective group ID or any of the + supplementary group IDs of the process match the file group or the + qualifier of any entry of type ACL_GROUP, then +
    if the ACL contains an + ACL_MASK entry, then +
    if the ACL_MASK entry and any + of the matching ACL_GROUP_OBJ or ACL_GROUP entries contain the requested + permissions, access is granted, +

    else access is denied.

    +

    +
    + else (note that there can be no ACL_GROUP entries without + an ACL_MASK entry) +
    if the ACL_GROUP_OBJ entry + contains the requested permissions, access is granted, +

    else access is denied.

    +
    +
    +
    4. +
  4. else if the ACL_OTHER entry contains the requested + permissions, access is granted.
    5. +
  5. + access is denied.
    6. +
+
+
+

+

A long and a short text form for representing ACLs is defined. In + both forms, ACL entries are represented as three colon separated fields: an + ACL entry tag type, an ACL entry qualifier, and the discretionary access + permissions. The first field contains one of the following entry tag type + keywords:

+
+
+
+
A user ACL entry specifies the access granted to + either the file owner (entry tag type ACL_USER_OBJ) or a specified user + (entry tag type ACL_USER).
+
+
A group ACL entry specifies the access granted to + either the file group (entry tag type ACL_GROUP_OBJ) or a specified group + (entry tag type ACL_GROUP).
+
+
A mask ACL entry specifies the maximum access + which can be granted by any ACL entry except the + user entry for the file owner and the + other entry (entry tag type ACL_MASK).
+
+
An other ACL entry specifies the access granted to + any process that does not match any user or + group ACL entries (entry tag type ACL_OTHER).
+
+
+

The second field contains the user or group identifier of the user + or group associated with the ACL entry for entries of entry tag type + ACL_USER or ACL_GROUP, and is empty for all other entries. A user identifier + can be a user name or a user ID number in decimal form. A group identifier + can be a group name or a group ID number in decimal form.

+

The third field contains the discretionary access permissions. The + read, write and search/execute permissions are represented by the + r, w, and + x characters, in this order. Each of these + characters is replaced by the - character to denote + that a permission is absent in the ACL entry. When converting from the text + form to the internal representation, permissions that are absent need not be + specified.

+

White space is permitted at the beginning and end of each ACL + entry, and immediately before and after a field separator (the colon + character).

+
+

+

The long text form contains one ACL entry per line. In addition, a + number sign (#) may start a comment that extends + until the end of the line. If an ACL_USER, ACL_GROUP_OBJ or ACL_GROUP ACL + entry contains permissions that are not also contained in the ACL_MASK + entry, the entry is followed by a number sign, the string + “effective:”, and the effective access permissions defined by + that entry. This is an example of the long text form:

+
+
user::rw-
+user:lisa:rw-         #effective:r--
+group::r--
+group:toolies:rw-     #effective:r--
+mask::r--
+other::r--
+
+
+
+

+

The short text form is a sequence of ACL entries separated by + commas, and is used for input. Comments are not supported. Entry tag type + keywords may either appear in their full unabbreviated form, or in their + single letter abbreviated form. The abbreviation for + user is u, the abbreviation + for group is g, the + abbreviation for mask is m, + and the abbreviation for other is + o. The permissions may contain at most one each of + the following characters in any order: r, + w, x. These are examples of + the short text form:

+
+
u::rw-,u:lisa:rw-,g::r--,g:toolies:rw-,m::r--,o::r--
+g:toolies:rw,u:lisa:rw,u::wr,g::r,o::r,m::r
+
+
+
+
+

+

IEEE 1003.1e draft 17 defines Access Control Lists that include + entries of tag type ACL_MASK, and defines a mapping between file permission + bits that is not constant. The standard working group defined this + relatively complex interface in order to ensure that applications that are + compliant with IEEE 1003.1 (“POSIX.1”) will still function as + expected on systems with ACLs. The IEEE 1003.1e draft 17 contains the + rationale for choosing this interface in section B.23.

+
+
+

+

On a system that supports ACLs, the file utilities + ls(1), + cp(1), and + mv(1) change their behavior in the + following way:

+
    +
  • For files that have a default ACL or an access ACL that contains more than + the three required ACL entries, the + ls(1) utility in the long form produced + by ls -l displays a plus sign + (+) after the permission string.
    • +
  • If the -p flag is specified, the + cp(1) utility also preserves ACLs. If + this is not possible, a warning is produced.
    • +
  • +
    + The mv(1) utility always preserves ACLs. + If this is not possible, a warning is produced.
    • +
+

The effect of the chmod(1) + utility, and of the chmod(2) system + call, on the access ACL is described in + CORRESPONDENCE + BETWEEN ACL ENTRIES AND FILE PERMISSION BITS.

+
+
+

+

The IEEE 1003.1e draft 17 (“POSIX.1e”) document + describes several security extensions to the IEEE 1003.1 standard. While the + work on 1003.1e has been abandoned, many UNIX style systems implement parts + of POSIX.1e draft 17, or of earlier drafts.

+

Linux Access Control Lists implement the full set of functions and + utilities defined for Access Control Lists in POSIX.1e, and several + extensions. The implementation is fully compliant with POSIX.1e draft 17; + extensions are marked as such. The Access Control List manipulation + functions are defined in the ACL library (libacl, -lacl). The POSIX + compliant interfaces are declared in the + <sys/acl.h> header. Linux-specific extensions + to these functions are declared in the + <acl/libacl.h> header.

+
+
+

+
+

+

While ACLs can be used to deny processes permissions based on the + groups they are in, this is considered bad practice. Privileged helpers such + as newuidmap(1) can give + unprivileged processes access to the + setgroups(2) system call, which + allows them to drop supplementary group membership and render restrictions + based on that membership ineffective. For further details, see + user_namespaces(7).

+
+
+
+

+

chmod(1), + creat(2), + getfacl(1), + ls(1), + mkdir(2), + mkfifo(2), + mknod(2), + mount(8), + open(2), + setfacl(1), + stat(2), + umask(1)

+
+

+

https://wt.tuxomania.net/publications/posix.1e/download.html

+
+
+

+
+
+
acl_dup(3), + acl_free(3), + acl_init(3)
+
+
acl_copy_entry(3), + acl_create_entry(3), + acl_delete_entry(3), + acl_get_entry(3), + acl_valid(3) +

acl_add_perm(3), + acl_calc_mask(3), + acl_clear_perms(3), + acl_delete_perm(3), + acl_get_permset(3), + acl_set_permset(3)

+

acl_get_qualifier(3), + acl_get_tag_type(3), + acl_set_qualifier(3), + acl_set_tag_type(3)

+
+
+
acl_delete_def_file(3), + acl_get_fd(3), + acl_get_file(3), + acl_set_fd(3), + acl_set_file(3)
+
+
acl_copy_entry(3), + acl_copy_ext(3), + acl_from_text(3), + acl_to_text(3), + acl_size(3)
+
+
+
+

+

The first group of functions is supported on most systems with + POSIX-like access control lists, while the second group is supported on + fewer systems. For applications that will be ported the second group is best + avoided.

+

acl_delete_def_file(3), + acl_dup(3), + acl_free(3), + acl_from_text(3), + acl_get_fd(3), + acl_get_file(3), + acl_init(3), + acl_set_fd(3), + acl_set_file(3), + acl_to_text(3), + acl_valid(3)

+

acl_add_perm(3), + acl_calc_mask(3), + acl_clear_perms(3), + acl_copy_entry(3), + acl_copy_ext(3), + acl_copy_int(3), + acl_create_entry(3), + acl_delete_entry(3), + acl_delete_perm(3), + acl_get_entry(3), + acl_get_permset(3), + acl_get_qualifier(3), + acl_get_tag_type(3), + acl_set_permset(3), + acl_set_qualifier(3), + acl_set_tag_type(3), + acl_size(3)

+
+
+

+

These non-portable extensions are available on Linux systems.

+

acl_check(3), + acl_cmp(3), + acl_entries(3), + acl_equiv_mode(3), + acl_error(3), + acl_extended_fd(3), + acl_extended_file(3), + acl_extended_file_nofollow(3), + acl_from_mode(3), + acl_get_perm(3), + acl_to_any_text(3)

+
+
+
+

+

Andreas Gruenbacher, <andreas.gruenbacher@gmail.com>

+
+
+ + + + + +
March 23, 2002Linux ACL
+ + diff --git a/blkid.8.html b/blkid.8.html index f20656d..8ff3539 100644 --- a/blkid.8.html +++ b/blkid.8.html @@ -5,9 +5,9 @@ Title: blkid Author: [see the "AUTHOR(S)" section] Generator: Asciidoctor 2.0.20 - Date: 2024-07-04 + Date: 2025-01-09 Manual: System Administration - Source: util-linux 2.40.2 + Source: util-linux 2.40.3 Language: English --> @@ -310,8 +310,8 @@

+

xattr - Extended attributes

+
+
+

+

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.

+

Extended attributes are extensions to the normal attributes which + are associated with all inodes in the system (i.e., the 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.

+

Users with search access to a file or directory may use + listxattr(2) to retrieve a list of attribute names defined for that + file or directory.

+

Extended attributes are accessed as atomic objects. Reading + (getxattr(2)) retrieves the whole value of an attribute and stores it + in a buffer. Writing (setxattr(2)) replaces any previous value with + the new value.

+

Space consumed for extended attributes may be counted towards the + disk quotas of the file owner and file group.

+
+

+

Attribute names are null-terminated strings. The attribute name is + always specified in the fully qualified namespace.attribute form, for + example, user.mime_type, trusted.md5sum, + system.posix_acl_access, or security.selinux.

+

The namespace mechanism is used to define different classes of + extended attributes. These different classes exist for several reasons; for + example, the permissions and capabilities required for manipulating extended + attributes of one namespace may differ to another.

+

Currently, the security, system, trusted, and + user extended attribute classes are defined as described below. + Additional classes may be added in the future.

+
+
+

+

The security attribute namespace is used by kernel security + modules, such as Security Enhanced Linux, and also to implement file + capabilities (see capabilities(7)). 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.

+
+
+

+

System extended attributes are used by the kernel to store system + objects such as Access Control Lists. Read and write access permissions to + system attributes depend on the policy implemented for each system attribute + implemented by filesystems in the kernel.

+
+
+

+

Trusted extended attributes are visible and accessible only to + processes that have the CAP_SYS_ADMIN 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.

+
+
+

+

User extended 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: read permission is + required to retrieve the attribute value, and writer permission is required + to change it.

+

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.

+

For this reason, user extended attributes are allowed only for + regular files and directories, and access to user extended attributes is + restricted to the owner and to users with appropriate capabilities for + directories with the sticky bit set (see the chmod(1) manual page for + an explanation of the sticky bit).

+
+
+

+

The kernel and the filesystem may place limits on the maximum + number and size of extended attributes that can be associated with a file. + The VFS-imposed limits on attribute names and values are 255 bytes and + 64 kB, respectively. The list of attribute names that can be returned + is also limited to 64 kB (see BUGS in listxattr(2)).

+

Some filesystems, such as Reiserfs (and, historically, ext2 and + ext3), require the filesystem to be mounted with the user_xattr mount + option in order for user extended attributes to be used.

+

In the current ext2, ext3, and ext4 filesystem implementations, + the total bytes used by the names and values of all of a file's extended + attributes must fit in a single filesystem block (1024, 2048 or 4096 bytes, + depending on the block size specified when the filesystem was created).

+

In the Btrfs, XFS, and Reiserfs filesystem implementations, there + is no practical limit on the number of extended attributes associated with a + file, and the algorithms used to store extended attribute information on + disk are scalable.

+

In the JFS, XFS, and Reiserfs filesystem implementations, the + limit on bytes used in an EA value is the ceiling imposed by the VFS.

+

In the Btrfs filesystem implementation, the total bytes used for + the name, value, and implementation overhead bytes is limited to the + filesystem nodesize value (16 kB by default).

+
+
+
+

+

Extended attributes are not specified in POSIX.1, but some other + systems (e.g., the BSDs and Solaris) provide a similar feature.

+
+
+

+

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.

+

This page was formerly named attr(5).

+
+
+

+

attr(1), getfattr(1), setfattr(1), + getxattr(2), FS_IOC_GETFLAGS(2const), + FS_IOC_SETFLAGS(2const), listxattr(2), removexattr(2), + setxattr(2), acl(5), capabilities(7), + selinux(8)

+
+
+ + + + + +
2024-06-13Linux man-pages 6.9.1
+ +