Hi Michael,

thanks again for all the feedback. I've followed all your suggestions;
again, please see the github repo for the latest version:

  https://github.com/andreas-gruenbacher/richacl

On Sun, Feb 14, 2016 at 10:31 PM, Michael Kerrisk (man-pages)
[off-list ref] wrote:

Hi Andreas,

Here's a few more comments on the current richacl(7) page
that I fetched from the git repo.

quoted

.\"
.\" RichACL Manual Pages
.\"
.\" Copyright (C) 2015,2016  Red Hat, Inc.
.\" Written by Andreas Gruenbacher [off-list ref]
.\" 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
.\" <http://www.gnu.org/licenses/>.
.\"
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.TH RICHACL 7 2015-09-01 "Linux" "Rich Access Control Lists"
.SH NAME
richacl \- Rich Access Control Lists
.SH DESCRIPTION
Rich Access Control Lists (RichACLs) are an extension of the POSIX file
permission model (see
.BR acl (5))
to support
.URL https://tools.ietf.org/rfc/rfc5661.txt "NFSv4 Access Control Lists"
on local and remote-mounted filesystems.

Having read the following paragraph a number of times (and being
ignorant of NFS ACLs), I find that I'm none the wiser about what you are
trying to say. What does it mean to "apply a file mode to an... ACL"?
Likewise, how does "the file mode determine the values of the file
masks"? This isn't clear in the following paragraph, and doesn't seem to
be elborated in the rest of the page. Could you add some text somehwere
to explain these points?

I've removed this paragraph and I've tried to explain what the masks
do in the Structure of RichACLs section.

quoted

RichACLs support file masks which can be used to apply a file mode to an existing
NFSv4 ACL without destructive side effects: the file mode determines the values
of the file masks; the file masks restrict the permissions granted by the NFSv4
ACL.  When a less restrictive file mode is applied later, the file masks become
less restrictive, and more of the original permissions can become effective.

A RichACL can always be translated into an equivalent NFSv4 ACL which grants
the same permissions.

RichACLs can be enabled on supported filesystems. This disables POSIX Access

I think it might be helpful here to list which filesystems so far
support RichACLs.

quoted

Control Lists; the two ACL models cannot coexist on the same filesystem.

When used on a filesystem that does not support RichACLs, the
.BR getrichacl (1)
and
.BR setrichacl (1)
utilities will operate on the file permission bits instead:
.BR getrichacl (1)
will display the file permission bits as a RichACL; when a RichACL
is set with
.BR setrichacl (1)
which can be represented exactly by the file permission bits,
.BR setrichacl (1)
will set the file permission bits instead.  An attempt to set a RichACL that
cannot be represented exactly by the file permission bits results in an error.

.SS Structure of RichACLs

RichACLs consist of a number of ACL entries, three file masks, and some flags
specifying attributes of the ACL as whole (by contrast with the per-ACL-entry
flags described below).

Insert a blank line here, to start a new paragraph.

quoted

Each of the ACL entries allows or denies some permissions to a particular user,
group, or special entity. Each entry consists of:

In the previous line you write "entity". In the lines below you use
"identifier". The terminology switch is confusing. Use just one
term.

quoted

.IP \(bu 4
A tag which specifies the user (with prefix
.B user:
or
.BR u: ),
group (with prefix
.B group:
or
.BR g: ),
or special identifier the entry applies to. Special
identifiers can be the file owner
.RB ( owner@ ),
the owning group
.RB ( group@ ),
or everyone
.RB ( everyone@ ).
.IP \(bu
A set of permissions the entry allows or denies.
.IP \(bu
A set of flags that indicate whether the user or group identifier is mapped or
unmapped, and whether the entry has been and can be inherited.
.IP \(bu 4
A field indicating whether the entry allows or denies access.

Does this field have a name? It would make dicussing it easier
to give it a name. That is, an ACL entry consists of four fields:

* a tag
* permissions
* flags
* ??? ("type"?)

quoted

.PP
The owner, group, and other file masks further control which permissions the
ACL grants, subject to the
.BR masked "\ (" m )
and
.BR write_through "\ (" w )
ACL flags.

Note that entries with the identifier
.B everyone@
apply to all processes, whereas the \(lqother\(rq file permissions and
\(lqother\(rq entries in POSIX ACLs apply to all processes which are not the
owner, are not in the owning group, and do not match a user or group mentioned
in the ACL.

Unlike POSIX ACLs, RichACLs do not have separate \(lqaccess\(rq ACLs that
define the access permissions and \(lqdefault\(rq ACLs that define the
inheritable permissions.  Instead, flags on each ACL entry determine whether
the entry is effective during access checks and/or inheritable.


.SS ACL flags

The following flags on ACLs are defined:

.RS
.HP

I don't think the heavy indentation here is helpful, and it narrors the
text considerably. I suggest replacing the preceding .RS+.HP with .TP,
and changing ewach .HP below to .TP, and remove the colon at the end of
each line that follows the .TP lines.

That's what I thought too, and that's why I had ".RS 4" and ".HP 4"
here originally.

quoted

.BR masked "\ (" m ):
When set, the file masks define upper limits on the permissions the ACL may
grant.
.HP
.BR write_through "\ (" w ):
When this flag and the
.B masked
flag are both set, the owner and other file masks define the actual permissions
granted to the file owner and to others instead of an upper limit.

There needs to be a statement here about what 'write_through' does if
'masked' is not set.

quoted

.HP
.BR auto_inherit "\ (" a ):
Automatic Inheritance is enabled for the file the ACL is
attached to. See
.IR "Automatic Inheritance" .
.HP
.BR protected "\ (" p ):
The ACL is protected from modification by Automatic
Inheritance.
.HP
.BR defaulted "\ (" d ):
The ACL has been assigned by default. Automatic Inheritance should completely

What does "assigned by default" mean? That it was inherited because of
'dir_inherit' or 'file_inherit' in the pareent directory? This needs to
be clearer.

quoted

replace the ACL.
.RE

If you follow my suggestion above, delete the preceding .RE

quoted

.SS ACL entry flags

The following flags on ACL entries are defined:

.RS
.HP

See above. Possibly change .RS+.HP to .TP

quoted

.BR file_inherit "\ (" f ):
The entry is inheritable for files.

Maybe this would be better as:

"When this flag appears in the ACL entry of a directory, then that entry is
inherited by new files created in the directory."

Is that text that I propose correct?

quoted

.HP
.BR dir_inherit "\ (" d ):
The entry is inheritable for directories.

"When this flag appears in the ACL entry of a directory, then that entry is
inherited by new subdirectories created in the directory."

Is that text that I propose correct?

It's not entirely wrong, but only a small part of the truth. Entries
are inherited such that the permissions in file_inherit entries become
effective for access checking for new files, and the permissions in
dir_inherit entries become effective for access checking for new
directories, recursively.

Your feedback prompted me to look into the inheritance flag
computation more closely once again, and I found bugs. The steps of
the algorithm are explained in the section "Permissions at
file-creation time", by the way.

quoted

.HP
.BR no_propagate "\ (" n ):
Inheritance stops at the next subdirectory level.
.HP
.BR inherit_only "\ (" i ):
The entry defines inheritable permissions only and is ignored for access
checking.
.HP
.BR inherited "\ (" a ):
The entry has been automatically inherited from the parent directory; the
ACL's
.B auto_inherit
flag should be on.
.HP
.BR unmapped "\ (" u ):
The user or group identifier is a textual string and is not mapped to a numeric
user or group identifier.  ACLs with unmapped identifiers can occur on NFSv4
mounted filesystems when the client cannot determine numeric user or group
identifiers for some of the NFSv4 user@domain or group@domain who values.  They
cannot be assigned to local files or directories.
.RE

If you follow my suggestion above, delete the preceding .RE

quoted

.SS Permissions

The following permissions are defined for RichACL entries and for the three
file masks:

.RS
.HP

See above. Possibly change .RS+.HP yo .TP

quoted

.BR read_data " / " list_directory "\ (" r ):
For a file: read the data of the file.
For a directory: list the contents of the directory.
.HP
.BR write_data " / " add_file "\ (" w ):
For a file: modify the data of the file; does not include opening the file in
append mode.
For a directory: add a new file in the directory.
.HP
.BR append_data " / " add_subdirectory "\ (" p ):
For a file: open the file in append mode.
For a directory: create a subdirectory in the directory.
.HP
.BR execute "\ (" x ):
For a file: execute the file.
For a directory: traverse / search the directory.
.HP
.BR delete_child "\ (" d ):
Delete a file or directory within a directory.
.HP
.BR delete "\ (" D ):
Delete the file or directory.
.HP
.BR read_attributes "\ (" a ):
Read basic attributes of a file or directory (see
.BR stat (2)).
This permission is always implicitly granted.

So, can this permission ever be taken away? If yes, say so. If not, why
does this permission exist? (And maybe say something about that.)

quoted

.HP
.BR write_attributes "\ (" A ):
Change the times associated with a file or directory to an arbitrary value.
This permission is always implicitly granted to the file owner.
.HP
.BR read_acl "\ (" c ):
Read the ACL of a file or directory. This permission is always
implicitly granted.
.HP
.BR write_acl "\ (" C ):
Change the ACL or file mode of a file or directory.
.HP
.BR write_owner "\ (" o ):
Take ownership of a file or directory.  Change the owning group of a file or
directory to a group of which the calling process is a member.
.HP
.BR read_named_attrs "\ (" R ),
.BR write_named_attrs "\ (" W ),
.BR synchronize "\ (" S ),
.BR write_retention "\ (" e ),
.BR write_retention_hold "\ (" E ):

If you follow my .TP suggestion above, then the above lines would need
to be rewritten sometinh like:

.BR read_named_attrs "\ (" R "), " write_named_attrs "\ (" W "), " \
synchronize "\ (" S "), " write_retention "\ (" e "), " \
write_retention_hold "\ (" E )

quoted

These permissions are defined by NFSv4 / NFSv4.1.  They can be stored, but are
not used.
.RE

If you follow my suggestion above, delete the preceding .RE and
add .PP

quoted

For the
.BR r ", " w ", and " p
permissions which have different long forms for files and directories, the
.BR getrichacl (1)
utility will output the appropriate form(s) depending on the context.
The
.BR setrichacl (1)
utility will accept either form for any file type.

.SS Text form
The common textual representation of a RichACL consists of the colon-separated
fields of the the ACL flags, file masks, and ACL entries in the following

s/the the/the/

quoted

format:
.TP
\fBflags:\fR\fIacl_flags\fR
The ACL flags.
.TP
\fBowner:\fR\fIperm\fR\fB::mask\fR, \fBgroup:\fR\fIperm\fR\fB::mask\fR, \fBother:\fR\fIperm\fR\fB::mask\fR
The file masks and their permissions.
.TP
\fIwho\fR\fB:\fR\fIperm\fR\fB:\fR\fIflags\fR\fB:allow\fR, \fIwho\fR\fB:\fR\fIperm\fR\fB:\fR\fIflags\fR\fB:deny\fR
For each ACL entry, who the entry applies to, the permissions of the entry, the
entry flags, and whether the entry allows or denies permissions.  The \fIwho\fR
field has no prefix for special identifiers, a
.B user:
or
.B u:
prefix for regular users, and a
.B group:
or
.B g:
prefix for regular groups.

I think the preceding sentence could be clearer. How about something
like the following (if correct):

[[
The who field is one of the following:

* One of the special identifiers: owner@, group@, or everyone@
* A user: or u: prefix followed by a [user name, user ID?] that designates
  s specific user
* A group: or g: prefix followed by a [group name, group ID?] that designates
  s specific group
]]

quoted

.PP
The entries are comma, whitespace, or newline separated.

Flags and permissions have single-letter as well as long forms, as listed under
.IR "ACL flags" ,
.IR "ACL entry flags" ,
and
.IR Permissions .
When the single-letter forms are used, the flags or permissions are
concatenated. When the long forms are used, the flags or permissions are
separated by slashes.  To align permissions or flags vertically, dashes can be
used for padding.

.SS Setting and modifying file permissions
The access permissions for a file can either be set by assigning an access
control list
.RB ( setrichacl (1))
or by changing the file mode permission bits
.RB ( chmod (1)).
In addition, a file can inherit an ACL from its parent directory at creation
time as described under
.IR "Permissions at file-creation time" .

.SS Assigning an Access Control List
When assigning an ACL to a file, unless explicitly specified, the owner, group,
and other file masks will be computed from the ACL entries as described in
the section
.IR "Computing the maximum file masks" .
The owner, group, and other file mode permission bits are then each set from
the owner, group, and other file mask as follows:
.IP \(bu 4
If the file mask includes the
.B r
permission, the read
file mode permission bit will be set.
.IP \(bu
If the file mask includes the
.B w
or
.B p
permission, the write file mode permission bit will be set.
.IP \(bu
If the file mask includes the
.B x
permission, the execute file mode permission bit will be set.
.PP
If the ACL can be represented exactly by the file mode
permission bits, the file permission bits are set to match the ACL and the ACL
is not stored.  (When the ACL of a file is requested which doesn't have an ACL,
the file mode permission bits are converted into an equivalent ACL.)

.SS Changing the file mode permission bits
When changing the file mode permission bits with
.BR chmod (1),
the owner, group,
and other file permission bits are set to the permission bits in the new mode,
and the file masks each are set based on the new mode bits as follows:
.IP \(bu 4
If the read bit in a set of permissions is set, the
.B r
permission in the corresponding file mask will be set.
.IP \(bu
If the write bit in a set of permissions is set, the
.B w
and
.B p
permissions in the corresponding file mask will be set.
.IP \(bu
If the execute bit in a set of permissions is set, the
.B x
permission in the corresponding file mask will be set.
.PP
In addition, the
.B masked
and
.B write_through
ACL flags are set. This has the
effect of limiting the permissions granted by the ACL to the file mode
permission bits; in addition, the owner is granted the owner mode bits and
others are granted the other mode bits. If the
.B auto_inherit
flag is set, the
.B protected
flag is also set to prevent the Automatic Inheritance algorithm from modifying
the ACL.

.SS Permissions at file-creation time
When a directory has inheritable ACL entries, the following
happens when a file or directory is created inside that directory:
.RS 4
.IP 1. 4
A file created inside that directory will inherit all of the ACL entries that
have the
.B file_inherit
flag set, and all inheritance-related flags in the inherited entries will be
cleared.

A subdirectory created inside that directory will inherit all of the ACL
entries that have the
.B file_inherit
or
.B dir_inherit
flag set.  Entries whose
.B no_propagate
flag is set will have all inheritance-related flags cleared.  Entries whose
.B no_propagate
and
.B dir_inherit
flags are not set and whose
.B file_inherit
is set will have their
.B inherit_only
flag set.
.IP 2.
If the parent directory's ACL has the
.B auto_inherit
flag set, the inherited ACL will have its
.B auto_inherit
flag set, and all entries will have their
.B inherited
flag set.
.IP 3.
The three file masks are computed from the inherited ACL as described in
the section
.IR "Computing the maximum file masks" .
.IP 4.
The three sets of permissions for the owner, the group, and for others in
the \fImode\fR parameter as given to
.BR open (2),
.BR mkdir (2),
and similar are converted into sets of RichACL permissions as described in
the section
.IR "Changing the file mode permission bits" .
Any RichACL permissions not included in those sets are
removed from the owner, group, and other file masks. The file mode permission
bits are then computed from the file masks as described in the section
.IR "Assigning an Access Control List" .
The process umask (see
.BR umask (2))
is ignored.
.IP 5.
The
.B masked
ACL flag is set. The
.B write_through
ACL flag remains cleared. In addition, if the
.B auto_inherit
flag of the inherited ACL is set, the
.B protected
flag is also set to prevent the Automatic Inheritance algorithm from modifying
the ACL.
.RE
.PP
When a directory does not have inheritable ACL entries, files and directories
created inside that directory will not be assigned access control lists and the
file mode permission bits will be set to (\fImode\fR\ &\ ~\fIumask\fR) where
\fImode\fR is the mode argument of the relevant system call and \fIumask\fR is
the process umask (see
.BR umask (2)).

.SS Automatic Inheritance
Automatic Inheritance is a mechanism that allows permission changes to
propagate from a directory to files and subdirectories inside that directory,
recursively.  Propagation is carried out by the process changing the directory
permissions (usually,
.BR setrichacl (1));
it happens without user intervention albeit not entirely automatically.

A significant limitation is that this mechanism works only as long as files
are created without explicitly specifying the file permissions to use. The
standard system calls for creating files an directories (

s/an /and /
s/ ($//

quoted

.BR creat (2),

Make that last line:

.RM ( creat (2),

quoted

.BR open (2),
.BR mkdir (2),
.BR mknod (2))
all have mandatory mode parameters which define the maximum allowed permissions
of the new files. To take account of this restriction, the
.B protected
ACL flag must be set if the
.B inherited
flag is set. This effectively disables Automatic Inheritance for that
particular file.

Automatic Inheritance still remains useful for network protocols like NFSv4 and
SMB, which both support creating files and directories without defining which

s/which$/their/

quoted

permissions: they can implement those operations by using the standard system
calls and by then undoing the effect of applying the mode parameters.

When the ACL of a directory is changed, the following happens for each entry
(\(lqchild\(rq) inside that directory:
.IP 1. 4
If the entry is a symblic link, skip the child.
.IP 2.
If the
.B auto_inherit
flag of the entry's ACL is not set or the
.B protected
flag is set, skip the child.
.IP 3.
With the child's ACL:
.RS 4
.IP a) 4
If the
.B defaulted
flag is set, replace the ACL with an empty ACL
with the
.B auto_inherit
flag set.
.IP b)
Delete all entries which have the
.B inherited
flag set.
.IP c)
Append all entries inherited from the parent directory according to step 1 of
the algorithm described under
.IR "Permissions at file-creation time".
Set the
.B inherited
flag of each of these entries.
.IP d)
Recompute the file masks.
.RE
.IP 4.
If the child is a directory, recursively apply this algorithm.

.SS Access check algorithm

When a process requests a particular kind of access (expressed as a set of
RichACL permissions) to a file, the following algorithm determines whether the
access is granted or denied:

.IP 1. 4
If the
.B masked
ACL flag is set, then:
.RS 4
.IP a) 4
If the
.B write_through
ACL flag is set, then:
.RS 4
.IP \(bu 4
If the requesting process is the file owner, then access is granted if the
owner mask includes the requested permissions, and is otherwise denied.
.IP \(bu
If the requesting process is not the file owner, is not in the owning group,
and no ACL entries other than
.B everyone@
match the process, then access is granted if the other mask includes the
requested permissions, and is otherwise denied.
.RE
.IP b)
If any of the following is true:
.RS 4
.IP \(bu 4
the requesting process is the file owner and the owner mask does not include all
requested permissions,
.IP \(bu 4
the requesting process is not the file owner and it is in the owning group or
matches any ACL entries other than
.BR everyone@ ,
and the group mask does not include all requested permissions,
.IP \(bu 4
the requesting process is not the file owner, not in the owning group, it
matches no ACL entries other than
.BR everyone@ ,
and the other mask does not include all requested permissions,
.PP
then access is denied.
.RE
.RE
.IP 2.
Set the remaining permissions to the requested permissions.  Go through all ACL
entries. For each entry:
.RS 4
.IP a) 4
If the
.B inherit_only
or
.B unmapped
flags are set, continue with the next ACL entry.
.IP b)
If any of the following is true:
.RS 4
.IP \(bu 4
the entry's identifier is
.B owner@
and the requesting process is the file owner,
.IP \(bu
the entry's identifier is
.B group@
and the requesting process is in the owning group,
.IP \(bu
the entry's identifier is a user and the requesting process is owned by that
user,
.IP \(bu
the entry's identifier is a group and the requesting process is a member in
that group,
.IP \(bu
the entry's identifier is
.BR everyone@ ,
.PP
then the entry matches the process; proceed to the next step. Otherwise,
continue with the next ACL entry.
.RE
.IP c)
If the entry denies any of the remaining permissions, access is denied.
.IP d)
If the entry allows any of the remaining permissions, then:
.RS 4
.IP \(bu 4
If the
.B masked
ACL flag is set and the entry's identifier is not
.B owner@
or
.BR everyone@
or is a user entry matching the file owner, remove all permissions from the
remaining permissions which are both allowed by the entry and included in the
group mask,
.IP \(bu
Otherwise, remove all permissions from the remaining permissions wich are
allowed by the entry.
.RE
.RE
.IP 3.
If there are no more remaining permissions, access is allowed. Otherwise,
access is denied.

.SS Computing the maximum file masks
When setting an ACL and no file masks have been explicitly specified and when
inheriting an ACL from the parent directory, the following algorithm is used
for computing the file masks:

.IP 1. 4
Clear the owner, group, and other file masks. Remember which permissions have
already been processed (initially, the empty set).
.IP 2.
For each ACL entry:
.RS 4
.IP \(bu 4
If the
.B inherit_only
flag is set, skip the entry.
.IP \(bu 4
Otherwise, compute which permissions the entry allows or denies that have not
been processed yet (the remaining permissions).
.IP \(bu
If the entry is an
.B owner@
entry, add the remaining permissions to the owner mask for
.B allow
entries, and remove the remaining permissions from the owner mask for
.B deny
entries.
.IP \(bu
Otherwise, if the entry is an
.B everyone@
entry, proceed as with
.B owner@
entries but add or remove the remaining permissions from the owner, group, and
other file masks.
.IP \(bu
Otherwise, proceed as with
.B owner@
entries but add or remove the remaining permissions from the owner and group
file masks.
.IP \(bu
Add the entry's permissions to the processed permissions.
.RE
.PP
The resulting file masks represent the ACL as closely as possible. With these
file masks, if the
.B masked
ACL flag is set, the effective permissions still stay the same.

.\" .SH BUGS
.SH AUTHOR
Written by Andreas Grünbacher [off-list ref].

Please send your bug reports, suggested features and comments to the above address.

Could we start with just a few simple examples already, and build up
over future iterations of this page?

quoted

.SH CONFORMING TO
Rich Access Control Lists are Linux-specific.
.SH SEE ALSO
.BR acl (5),
.BR chmod (1),
.BR getrichacl (1),
.BR ls (1),
.BR setrichacl (1)
.BR stat (2),
.BR umask (2)
.\" librichacl

Thanks,
Andreas