Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1328517 > unrolled thread

RichACLs man-pages review

Back to article view | Back to linux.kernel

Contents

  RichACLs man-pages review "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> - 2016-02-07 17:30 +0100
    getrichacl(1) man page review comments "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> - 2016-02-07 17:40 +0100
      Re: getrichacl(1) man page review comments Martin Steigerwald <martin@lichtvoll.de> - 2016-02-07 19:20 +0100
    Re: RichACLs man-pages review "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> - 2016-02-07 17:40 +0100
    richacl(7) man page review comments "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> - 2016-02-07 17:40 +0100
    setrichacl(1) man page review comments "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> - 2016-02-07 17:40 +0100

#1328517 — RichACLs man-pages review

Hello Andreas

I've taken a look at the current drafts of the setrichacl(1), 
getrichacl(1), and richacl(7) man pages, and will send comments
as separate following mails.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[toc] | [next] | [standalone]

#1328518 — getrichacl(1) man page review comments

Hello Andreas,

Here, some comments on the getrichacl(1) page.

> .\"
> .\" Richacl Manual Pages
> .\"
> .\" Copyright (C) 2015  Red Hat, Inc.
> .\" Written by Andreas Gruenbacher <agruenba@redhat.com>
> .\" 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/>.
> .\"
> .TH GETRICHACL 7 2015-09-01 "Linux" "Rich Access Control Lists"
> 
> .SH NAME
> getrichacl \- Get Rich Access Control Lists
> 
> .SH SYNOPSIS
> .B getrichacl
> .RI [ OPTION "]... [" FILE ]...

In man-pages, at least, the convention is to use lower case for these
pieces (and thus through the remainder of the page), so:

> .RI [ option "]... [" file ]...

> .SH DESCRIPTION
> For each file, getrichacl displays the file name and Rich Access Control List

For man-pages, at least, the convention is that the references to the
function/command name explained in the page are bold, do:

.BR getrichacl

> (richacl).

For what it's worth, I think it would be worthwhile to start with
a consistent abbreviation comment here (and use it throughout all of the
man pages): "RichACL" (or "richACL"), rather than "richacl"; that seems
more consistent with the traditional abbreviation "ACL".

> 
> By default, getrichacl displays the effective permissions remaining after

.BR getrichacl

> applying the file masks to the ACL.  The file masks and underlying NFSv4 ACL
> can be displayed with the \-\-raw option.

Use
.BR \-\-raw

> 
> The output format of getrichacl is as follows:

.BR getrichacl

> .fam C
> .RS
> .nf
>  1:  file:
>  2:      flags:a
>  3:      owner:rwp-------------::mask
>  4:      group:r-p-------------::mask
>  5:      other:r---------------::mask
>  6:     owner@:rwp-------------::allow
>  7:   user:foo:r-p-------------::allow
>  8:     group@:r-p-------------::allow
>  9:  group:bar:r-p-------------::allow
> 10:  everyone@:r---------------::allow
> 11:
> .fi
> .RE
> .fam T
> 
> Line 1 contains the file name, followed by a colon.
> 
> Line 2 contains the ACL flags. This line is omitted if no flags are set.
> 
> Lines 3--5 indicate the owner, group, and other file masks, which are only
> shown if the \-\-raw option is specified.
> 
> Lines 6--10 indicate different ACL entries for the file owner
> .RB ( owner@ ),
> user foo, the owning group
> .RB ( group@ ),
> group bar, and for everyone

.IR bar ,

> .RB ( everyone@ ).
> 
> A blank line follows at the end.
> 
> By default, getrichacl displays the the single-letter forms of flags and

.BR getrichacl

s/the the/the/

> permissions, the identifiers of ACL entryies are right justified, the

s/entryies/entries/

> permissions are vertically aligned, and permissions which are always
> granted
> .RB ( read_attributes ", " read_acl ", " synchronize )
> are omitted. See the richacl(7) manual page for the defined flags and

Use
.BR richachl (7)
for page cross references.

> permissions.
> 
> When getrichacl is used on a file that does not have a richacl or on a

.BR getrichacl

> filesystem that does not support richacls, getrichacl displays the access

.BR getrichacl

> permissions defined by the traditional file permission bits as a richacl. When
> getrichacl is used on a file that has a POSIX ACL, it prints an error message.

.BR getrichacl

And then:

[...] has a POSIX ACL (see
.BR acl (7)), it prints [...]
> 
> .SH OPTIONS
> .TP
> \fB\-\-long\fR, \fB\-l\fR
> Display access masks and flags in their long form.
> .TP
> \fB\-\-full\fR
> Also show permissions which are always implicitly allowed.
> .TP
> \fB\-\-raw\fR
> Show acls as stored on the file system including the file masks. Implies

s/axls/ACLs/

> \fB\-\-full\fR.
> .TP
> \fB\-\-unaligned\fR
> Do not align ACL entries or pad missing permissions with '-'.
> .TP
> \fB\-\-numeric-ids\fR
> Display numeric user and group IDs instead of names.
> .TP
> \fB\-\-access\fR [=\fIuser\fR[:\fIgroup\fR:...]}, \fB\-a\fR[\fIuser\fR[:\fIgroup\fR:...]}
> Instead of the ACL, show which permissions the caller or a specified user has

"caller"? "the user running the command, "

> for file(s).  When a list of groups is given, this overrides the groups the

s/file(s)/specified file(s)/

> user is in.

The preceding text is not very clear.

> .TP
> \fB\-\-version\fR, \fB\-v\fR
> Display the version of getrichacl and exit.

.BR getrichacl

> .TP
> \fB\-\-help\fR, \fB\-h\fR
> Display command-line usage help text.
> 
> .SH AUTHOR
> Written by Andreas Grünbacher <agruenba@redhat.com>.
> 
> Please send your bug reports, suggested features and comments to the above address.
> 
> .SH CONFORMING TO
> Rich Access Control Lists are Linux-specific.
> 
> .SH SEE ALSO
> .BR setrichacl (1),
> .BR richacl (7)

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[toc] | [prev] | [next] | [standalone]

#1328553 — Re: getrichacl(1) man page review comments

Am Sonntag, 7. Februar 2016, 17:30:49 CET schrieb Michael Kerrisk (man-pages):
> Hello Andreas,
> 
> Here, some comments on the getrichacl(1) page.

I know that the command names are based on setfacl and getfacl. But sometimes 
I still wonder about these names. They just don´t fit.

Its chsomething for changing things in Unix traditionally – chown, chmod, 
chattr, chage chsh, you name it –, but there is nothing for querying things. 
So I get where this is coming from, yet I always found setfacl and getfacl 
command names cumbersome.

Sorry, for posting here instead of a previous richacl implementation patchset. 
I fully appreciate that it may be too late to change anything regarding 
command names. Also considering usermod and groupmod the command naming in 
Unix / Linux appears to be a big mess anyway.

Thanks,
-- 
Martin

[toc] | [prev] | [next] | [standalone]

#1328519

Hello Andreas,

Here, some comments on the setrichacl(1) page.

> .\"
> .\" Richacl Manual Pages
> .\"
> .\" Copyright (C) 2015  Red Hat, Inc.
> .\" Written by Andreas Gruenbacher <agruenba@redhat.com>
> .\" 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/>.
> .\"
> .TH SETRICHACL 7 2015-09-01 "Linux" "Rich Access Control Lists"
> 
> .SH NAME
> setrichacl \- Set Rich Access Control Lists
> 
> .SH SYNOPSIS
> .B setrichacl
> .RI [ OPTION "]... [" FILE ]...

In man-pages, at least, the convention is to use lower case for these
pieces (and thus through the remainder of the page), so:

> .RI [ option "]... [" file ]...

> 
> .SH DESCRIPTION
> The setrichacl utility sets or modifies Rich Access Control Lists (richacls) of

.BR setrichacl

> files and directories.
> 
> The
> .B \-m
> and
> .B \-s
> options expect an ACL or parts of an ACL on the command line. The
> .B \-M
> and
> .B \-S
> options read an ACL or parts of an ACL from a file. In either case, the entry
> format is described in section
> .I TEXT FORM
> of the richacl(7) manual page. The single-letter or long forms of flags and

Use
.BR richachl (7)
for page cross references.

> permissions can be mixed arbitrarily. Multiple entries are separated by
> whitespace, newlines or commas.
> 
> Note that the order of ACL entries matters, and that changing the order may
> grant different permissions.
> 
> The use of
> .B deny
> entries is discouraged. If
> .B deny
> entries are used, they should be placed ahead of
> .B allow
> entries for improved interoperability with Windows where possible.
> 
> When the file masks are not specified, they are computed automatically.
> 
> When the ACL to be set is simple enough that the traditional file permission
> bits can express the same permissions, setrichacl instead only sets the file

.BR setrichacl

> permission bits. Minor differences that do not have an influence on the
> permissions granted by the acl are not preserved.  When setrichacl's

s/acl/ACL/

.BR setrichacl 's

> counterpart utility, getrichacl, is used on a file or directory that does not

.BR getrichacl ,

> have a richacl, it displays the access permissions defined by the file
> permission bits as a richacl.
> 
> .SS Permissions
> 
> Setting ACLs or changing the file permission bits is allowed to the file owner,
> to processes which have the write_acl permission, and to processes which have

.B write_acl

> the CAP_FOWNER capability.

.B CAP_FOWNER

> 
> .SH OPTIONS
> .TP
> \-\-\fBmodify\fR \fIacl\fR, \fB\-m\fR \fIacl\fR
> Modify the ACL of \fIFILE\fR by replacing existing entries with the entries in
> \fIacl\fR, and adding all new entries. When the permissions of an entry are
> empty, remove the entry.
> .TP
> \fB\-\-modify\-file\fR \fIacl_file\fR, \fB\-M\fR \fIacl_file\fR
> Identical to \-\-modify, but read the ACL from \fIacl_file\fR instead. If the

.B \-\-modify

> file is \(lq\-\(rq, read from standard input.
> .TP
> \fB\-\-set\fR \fIacl\fR, \fB\-s\fR \fIacl\fR
> Set the ACL of \fIFILE\fR to \fIacl\fR. Any previous ACL is replaced.
> ACL entries are separated by whitespace, newlines, or commas.
> .TP
> \fB\-\-set\-file\fR \fIacl_file\fR, \fB\-S\fR \fIacl_file\fR
> Identical to \-\-set, but read the ACL from \fIacl_file\fR instead. If the

.BR \-\-set ,

> file is \(lq\-\(rq, read from standard input.
> .TP
> \fB\-\-remove\fR, \fB\-b\fR
> Remove all extended permissions and revert to the file permission bits only.
> .TP
> \fB\-\-version\fR, \fB\-v\fR
> Display the version of setrichacl and exit.

.BR setrichacl

> .TP
> \fB\-\-help\fR, \fB\-h\fR
> Display command-line usage help text.
> 
> .\" .SH EXAMPLES

Yes please!

> .SH AUTHOR
> Written by Andreas Grünbacher <agruenba@redhat.com>.
> 
> Please send your bug reports, suggested features and comments to the above address.
> 
> .SH CONFORMING TO
> Rich Access Control Lists are Linux-specific.
> 
> .SH SEE ALSO
> .BR getrichacl (1),
> .BR richacl (7)

Cheers,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[toc] | [prev] | [next] | [standalone]

#1328520 — richacl(7) man page review comments

Hi Andreas,

I'll probably have quite a few more comments on this page as I get to
understand RichACLs better. Here's some comments from an initial
reading.

So, an initial comment. It seems to me to that this page (but
not setrichacl(1) and getrichacl(1)) should ultimately land in
man-pages (just like acl(7)), since we're talking about a kernel
feature. Make sense?

> .\"
> .\" Richacl Manual Pages
> .\"
> .\" Copyright (C) 2015  Red Hat, Inc.
> .\" Written by Andreas Gruenbacher <agruenba@redhat.com>
> .\" 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

For what it's worth, I think it would be worthwhile to start with
a consistent abbreviation comment here (and use it throughout all of the
man pages): "RichACL" (or "richACL"), rather than "richacl"; that seems
more consistent with the traditional abbreviation "ACL".

> permission model to support

Make this:

permission mode (see
.BR acl (7))
to support

> .URL https://tools.ietf.org/rfc/rfc5661.txt "NFSv4 Access Control Lists"
> on local and remote-mounted filesystems.
> 
> Richacls support file masks which allow to apply a file mode to an existing

s/which allow to apply/which can be used to apply/

> 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
> Control Lists; the two ACL models will not coexist on the same filesystem.

s/will not/can not/ ?

> 
> When used on a filesystem that does not support richacls, the getrichacl and

Use
.BR getrichacl (1)
for cross-references.

> setrichacl utilities will operate on the file permission bits instead:
> getrichacl will display the file permission bits as a richacl; when a richacl

Use
.BR getrichacl (1)
for cross-references.

> is set with setrichacl which can be represented exactly by the file permission

Use
.BR setrichacl (1)
for cross-references.

> bits, setrichacl will set the file permission bits instead.

Use
.BR setrichacl (1)
for cross-references.

Here, I think it would be helpful to add a sentence:

"An attempt to set a richacl that cannot be represented exactly by the
file permission bits results in an error."

(If that sentence is correct, of course.)

> 
> .SH STRUCTURE OF RICHACLS

For all of the "nonstandard" (see man-pages(7)) ".SH" sections here, I'd
be inclined to switch to using ".SS" subsections. There are downsides to
multiple nonstandard section headings (e.g., automated TOCs for
Section headings become clumsy and long), and I don't think your use of
.SH vs .SS really helps much to structure the information in this page.

> 
> Richacls consist of a number of ACL entries, three file masks, and some flags.

s/some flags./some flags specifying attributes of the ACL as whole (by
contrast with the per-ACL-entry flags described below)./

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

s/acl//

> .IP \(bu 4
> The user (with prefix

s/The user/A tag which specifies the user/

(Is "tag" the right word? In any case, what would helpful to have here
is the generic term for this component of the ACL.)

> .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.
> .PP
> The owner, group, and other file masks further control which permissions the
> ACL grants, subject to the
> .B masked
> .RB ( m )
> and
> .B write_through
> .RB ( 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.

s/acl/ACL/

> Richacls do not have separate \(lqaccess\(rq ACLs that define the access
> permissions and \(lqdefault\(rq ACLs that define the inheritable permissions as
> POSIX ACLs.

I'd restructure the preceding sentence as:

"Unlike POSIX ACLs, richacls do not.... that define the inheritable
permissions."

> Instead, whether an ACL entry is effective during access checks
> and/or inheritable is determined by the ACL entry flags.
> 
> .SS ACL Flags

I'd use lower case in the above for all words except the first.
(That's the convention in man-pages.)

> 
> The following flags on ACLs are defined:
> 
> .RS 4
> .HP 4

s/4/8/ in the preceding two lines. I think more indentation would make
this (and the similar lists below) more readable.

> .B masked
> .RB ( m ):

I'd write each of these list entries starting here, and below, in the
form:

.BR masked "\ (" m ):

This form is a little easier to read in the source, and
it forces just a single space before the "(", which looks
a little better, I find.

> When set, the file masks define upper limits on the permissions the ACL may
> grant.
> .HP
> .B write_through
> .RB ( w ):
> When this flag and the masked flag are both set, the owner and other file masks

.B masked

> define the actual permissions granted to the file owner and to others instead
> of an upper limit.
> .HP
> .B auto_inherit
> .RB ( a ):
> Automatic Inheritance is enabled for the file the ACL is
> attached to. See
> .IR "Automatic Inheritance" .
> .HP
> .B protected
> .RB ( p ):
> The ACL is protected from modification by Automatic
> Inheritance.
> .HP
> .B defaulted
> .RB ( d ):
> The ACL has been assigned by default. Automatic Inheritance should completely
> replace the ACL.
> .RE
> 
> .SS ACL Entry Flags
> 
> The following flags on ACL entries are defined:
> 
> .RS 4
> .HP 4

s/4/8/ in the preceding two lines.

> .B file_inherit
> .RB ( f ):
> The entry is inheritable for files.
> .HP
> .B dir_inherit
> .RB ( d ):
> The entry is inheritable for directories.
> .HP
> .B no_propagate
> .RB ( n ):
> Inheritance stops at the next subdirectory level.
> .HP
> .B inherit_only
> .RB ( i ):
> The entry defines inheritable permissions only and is ignored for access
> checking.
> .HP
> .B inherited
> .RB ( a ):
> The entry has been automatically inherited from the parent directory; the
> ACL's auto_inherit

Use
.B auto_inherit

> .RB ( a )
> flag should be on.
> .HP
> .B unmapped
> .RB ( u ):
> The user or group identifier is a textual string and has no mapping to a
> numeric user or group identifier.

So here, I think there should be a sentence that explains how a meaning
is attached to the strings? Is this for NFS, for Windows, for something
else?

> .RE
> 
> .SS Permissions
> 
> The following permissions are defined for richacl entries and for the three
> file masks:
> 
> .RS 4
> .HP 4

s/4/8/ in the preceding two lines.

> .B read_data
> /
> .B list_directory
> .RB ( r ):

Replace the preceding four lines by

.BR read_data / list_directory "\ (" r )

and do similar for the next two list entried below.
Note that "\ (" will force just a singlke space before the "(".

> Read the data of a file.
> List the contents of a directory.

In the above list entry, and the next two, I find the layout ("xxx/yyy (z)")
confusing. A closer reading indicates that in each case, the "xxx"
applies for files and he "yyy" is for directories. But I think the text
could make this point a little easier to grasp. In each of these three
list entries this could be done something lke the following:

"For a file: read the data of the file. For a directory: list the
contents of the directory."

By the way, can the terms "read_data" and "list_directory" be used
interchangeably? That is, can you employ (say) "read_data" when setting
an ACL entry for a directory? (I'm assuming the answer is "yes".)
If the terms are just interchangeable synonyms, perhas it's worth
making that point explicitly in the text.

> .HP
> .B write_data
> /
> .B add_file
> .RB ( w ):
> Modify the data of a file. Add a new file in a directory.

See above comment re file/directory.

> .HP
> .B append_data
> /
> .B add_subdirectory
> .RB ( p ):
> Open a file in append mode. Create a subdirectory in a directory.

So, in other words, if append mode is denied, then the file can be
opened for writing (contingent on write permission  being granted), but
can't be opened with O_APPEND? Is that correct? This point needs to be
made clearer.

> .HP
> .B execute
> .RB ( x ):
> Execute a file. Traverse / search a directory.

See above comment re file/directory.

> .HP
> .B delete_child
> .RB ( d ):
> Delete a file or directory within a directory.
> .HP
> .B delete
> .RB ( D ):
> Delete the file or directory.
> .HP
> .B read_attributes
> .RB ( a ):
> Read basic attributes of a file or directory.

What are "attributes" in this context? Does this mean stat(2)? Make this
explicit.

> This permission is always implicitly granted.
> .HP
> .B write_attributes
> .RB ( 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
> .B read_acl
> .RB ( c ):
> Read the ACL of a file or directory. This permission is always
> implicitly granted.
> .HP
> .B write_acl
> .RB ( C ):
> Change the ACL or file mode of a file or directory.
> .HP
> .B write_owner
> .RB ( 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
> .B read_named_attrs
> .RB ( R ),
> .B write_named_attrs
> .RB ( W ),
> .B synchronize
> .RB ( S ),
> .B write_retention
> .RB ( e ),
> .B write_retention_hold
> .RB ( E ):
> These permissions can be stored, but do not have a local meaning.

So, I thenk that a sentence here should explain why these permissions
exist. Is if for future extension, because they are meaningful in NFS,
or something else?

> .RE
> 
> .SH TEXT FORM
> 
> The common textual representation of richacl consists of the colon separated

s/richacl/richacls/ (or, "RichACLs"/"richACLs")

s/colon separated/colon-separated/

> fields of the the acl flags, file masks, and acl entries in the following

s/acl/ACL/ (*2)

> 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 who field has

s/who/\\fIwho\\fP/

> 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.
> .PP
> The entries are comma, whitespace or newline separated.

s/whitespace/whitespace,/

> 
> Flags and permissions have single-letter as well as long forms as listed under

s/forms/forms,/

> .IR "ACL Flags" ,
> .IR "ACL Entry Flags" ,
> and
> .IR Permissions .

If you follow my suggestion about capitalization in the ".SS" entries,
you'll need to change the capitalization in the above phrases.

> 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
> use for padding.

s/use/used/

> 
> .SH SETTING AND MODIFYING FILE PERMISSIONS
> The access permissions for a file can either be set by assigning an access
> control list (setrichacl) or by changing the file mode permission bits (chmod).

Use
.RB ( setrichacl (1))
for cross-reference.

Use
.RB ( chmod (1)).

> In addition, a file can inherit an ACL from its parent
> directory at create time; the inherited ACL is then further

s/create/creation/

> restricted by the creating system call's mode parameter (see the creat(2)
> manual page).

creat(2) is pretty much history. I suggest writing

(as given to
.BR open (2),
.BR mkdir (2),
and similar).

And here, I think we need a statement about whether the process umask
has an effect or not...

> 
> .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
> 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 access control
> list and the ACL is not stored.  (When the reverse happens and

s/and/and the/

> ACL of a file is requested which doesn't have an explicit
> ACL, the file mode permission bits are converted into an
> equivalent richacl.)
> 
> .SS Changing The File Mode Permission Bits

I'd use lower case in the above for all words except the first

> When changing the file mode permission bits with chmod(2), the owner, group,

.BR chmod (2)

> 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 Create Time

s/File Create/file-creation/

I'd use lower case in the above for all words except the first

> 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 entries with the

s/all entries with/all of the directories entries that/

> .B file_inherit
> flag set, and all inheritance-related flags in the inherited entries will be
> cleared.
> 
> A subdirectory will inherit all entries with 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
> section
> .IR "COMPUTING THE MAXIMUM FILE MASKS" .
> .IP 4.
> The three sets of permissions for the owner, the group, and for others in
> the mode parameter of the creating system call are converted into sets of
> richacl permissions as described in section

s/in/in the/

> .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 section

s/in/in the/

> .IR "Assigning An Access Control List" .
> .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 (mode\ &\
> ~umask).

will be set to

    (mode & umask)

where
.I mode
is the permission mode argument of the relevant system call and
.I umask
is the process umask (see
.BR umask (2)).

> 
> .SS Automatic Inheritance

I'd use lower case in the above for all words except the first

> Automatic Inheritance allows permission changes to propagate from a directory
> to files and subdirectories inside that directory, recursively.  Carrying out
> this propagation of permissions is the responsibility of the process changing
> the directory permissions (usually, setrichacl(1)).

I'm confused by the previous sentence. the feature is labeled "Automatic
Inheritance", implying that the user/process need do nothing. The next
sentence says "propagation ... is the responsibility of the process".
These two points seem contradictory. I think something more needs to be
said here.

> 
> 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 (creat(2), open(2),
> mkdir(2), mkfifo(2), mknod(2)) all have mandatory mode parameters which define

Format that system call list as
.RB ( creat (2),
.BR open (2),
.BR mkdir (2),
.BR mknod (2))

Note that I removed mkfifo(): it's a library functionlayered on
mkonod(2).

> 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
> 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 should

Why "should"?

> happen for each entry inside that directory (for each \(lqchild\(rq):

Make the preceding line:

happen 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 1. 4

s/1./a)/

(i.e., use a different labeling scheme for the sublist)

> If the
> .B defaulted
> flag is set, replace the ACL with an empty ACL
> with the
> .B auto_inherit
> flag set.
> .IP 2.

s/2./b)/

> Delete all entries which have the
> .B inherited
> flag set.
> .IP 3.

s/3./c)/

> Append all entries inherited from the parent directory according to step 1 of
> the algorithm described under
> .IR "Permissions At File Create Time".
> Set the
> .B inherited
> flag of each of these entries.
> .IP 4.

s/4./d)/

> Recompute the file masks.
> .RE
> .IP 4.
> If the child is a directory, recursively apply this algorithm.
> 
> .SH ACCESS CHECK ALGORITHM
> 
> When a process requests a particular kind of access to a file defined by a set

s/defined/protected/ (?)

> of richacl permissions, the following algorithm determines if the access is

s/if/whether/

> granted or denied:
> 
> .IP 1. 4
> If the
> .B masked
> ACL flag is set, then:
> .RS 4
> .IP 1. 4

s/1./a)/

Use a different numbering scheme for sublists.

> if the

s/if/If/

> .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

s/if/If/

> 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,

s/if/If/

> 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 2.

s/2./b)/

> if any of the following is true:

s/if/If/

> .RS 4
> .IP \(bu 4
> the requesting process is the file owner and the owner mask does no include all

s/no /not /

> 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 no 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 no 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 1. 4

s/1./a)/

Use a different numbering scheme for sublists.

> if the
> .B inherit_only
> or
> .B unmapped
> flags are set, continue with the next ACL entry.
> .IP 2.

s/2./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
> the entry matches the process; proceed. Otherwise, continue with the next ACL

s/proceed/proceed to the next step/  (?)

> entry.
> .RE
> .IP 3.

s/3./c)/

> If the entry denies any of the remaining permissions, access is denied.
> .IP 4.

s/4./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.
> 
> .SH 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.

This page is in *desperate* need of *multiple* examples, starting simple,
and building up in complexity, with walkthogh text explaining how the
permisssions are interpreted and how the masks are generated.
Having read the page multiple times (and having little knowledge
of NFS ACLs), I'm still struggling to put all the pieces together.
Probably some examples that relate to an NFS context would also be
helpful.

> .\" .SH BUGS
> .SH AUTHOR
> Written by Andreas Grünbacher <agruenba@redhat.com>.
> 
> Please send your bug reports, suggested features and comments to the above address.
> 
> .SH CONFORMING TO
> Rich Access Control Lists are Linux-specific.
> .SH SEE ALSO
> .BR chmod (1),
> .BR getrichacl (1),
> .BR ls (1),
> .BR setrichacl (1)
> .BR stat (2),
> .BR umask (2),
> .BR acl (7)
> .\" librichacl

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[toc] | [prev] | [next] | [standalone]

#1328521 — setrichacl(1) man page review comments

Hello Andreas,

Here, some comments on the setrichacl(1) page.

> .\"
> .\" Richacl Manual Pages
> .\"
> .\" Copyright (C) 2015  Red Hat, Inc.
> .\" Written by Andreas Gruenbacher <agruenba@redhat.com>
> .\" 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/>.
> .\"
> .TH SETRICHACL 7 2015-09-01 "Linux" "Rich Access Control Lists"
> 
> .SH NAME
> setrichacl \- Set Rich Access Control Lists
> 
> .SH SYNOPSIS
> .B setrichacl
> .RI [ OPTION "]... [" FILE ]...

In man-pages, at least, the convention is to use lower case for these
pieces (and thus through the remainder of the page), so:

> .RI [ option "]... [" file ]...

> 
> .SH DESCRIPTION
> The setrichacl utility sets or modifies Rich Access Control Lists (richacls) of

.BR setrichacl

> files and directories.
> 
> The
> .B \-m
> and
> .B \-s
> options expect an ACL or parts of an ACL on the command line. The
> .B \-M
> and
> .B \-S
> options read an ACL or parts of an ACL from a file. In either case, the entry
> format is described in section
> .I TEXT FORM
> of the richacl(7) manual page. The single-letter or long forms of flags and

Use
.BR richachl (7)
for page cross references.

> permissions can be mixed arbitrarily. Multiple entries are separated by
> whitespace, newlines or commas.
> 
> Note that the order of ACL entries matters, and that changing the order may
> grant different permissions.
> 
> The use of
> .B deny
> entries is discouraged. If
> .B deny
> entries are used, they should be placed ahead of
> .B allow
> entries for improved interoperability with Windows where possible.
> 
> When the file masks are not specified, they are computed automatically.
> 
> When the ACL to be set is simple enough that the traditional file permission
> bits can express the same permissions, setrichacl instead only sets the file

.BR setrichacl

> permission bits. Minor differences that do not have an influence on the
> permissions granted by the acl are not preserved.  When setrichacl's

s/acl/ACL/

.BR setrichacl 's

> counterpart utility, getrichacl, is used on a file or directory that does not

.BR getrichacl ,

> have a richacl, it displays the access permissions defined by the file
> permission bits as a richacl.
> 
> .SS Permissions
> 
> Setting ACLs or changing the file permission bits is allowed to the file owner,
> to processes which have the write_acl permission, and to processes which have

.B write_acl

> the CAP_FOWNER capability.

.B CAP_FOWNER

> 
> .SH OPTIONS
> .TP
> \-\-\fBmodify\fR \fIacl\fR, \fB\-m\fR \fIacl\fR
> Modify the ACL of \fIFILE\fR by replacing existing entries with the entries in
> \fIacl\fR, and adding all new entries. When the permissions of an entry are
> empty, remove the entry.
> .TP
> \fB\-\-modify\-file\fR \fIacl_file\fR, \fB\-M\fR \fIacl_file\fR
> Identical to \-\-modify, but read the ACL from \fIacl_file\fR instead. If the

.B \-\-modify

> file is \(lq\-\(rq, read from standard input.
> .TP
> \fB\-\-set\fR \fIacl\fR, \fB\-s\fR \fIacl\fR
> Set the ACL of \fIFILE\fR to \fIacl\fR. Any previous ACL is replaced.
> ACL entries are separated by whitespace, newlines, or commas.
> .TP
> \fB\-\-set\-file\fR \fIacl_file\fR, \fB\-S\fR \fIacl_file\fR
> Identical to \-\-set, but read the ACL from \fIacl_file\fR instead. If the

.BR \-\-set ,

> file is \(lq\-\(rq, read from standard input.
> .TP
> \fB\-\-remove\fR, \fB\-b\fR
> Remove all extended permissions and revert to the file permission bits only.
> .TP
> \fB\-\-version\fR, \fB\-v\fR
> Display the version of setrichacl and exit.

.BR setrichacl

> .TP
> \fB\-\-help\fR, \fB\-h\fR
> Display command-line usage help text.
> 
> .\" .SH EXAMPLES

Yes please!

> .SH AUTHOR
> Written by Andreas Grünbacher <agruenba@redhat.com>.
> 
> Please send your bug reports, suggested features and comments to the above address.
> 
> .SH CONFORMING TO
> Rich Access Control Lists are Linux-specific.
> 
> .SH SEE ALSO
> .BR getrichacl (1),
> .BR richacl (7)

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web