Re: [PATCH man-pages v2 2/2] openat2.2: document new openat2(2) syscall

Hi Aleksa,

Ping!

Cheers,

Michael

On Wed, 1 Apr 2020 at 08:38, Michael Kerrisk (man-pages)
[off-list ref] wrote:

Hello Aleksa,

On 3/31/20 4:39 PM, Aleksa Sarai wrote:

quoted

On 2020-03-30, Michael Kerrisk (man-pages) [off-list ref] wrote:

quoted

Hello Aleksa,

On 2/2/20 4:19 PM, Aleksa Sarai wrote:

quoted

Rather than trying to merge the new syscall documentation into open.2
(which would probably result in the man-page being incomprehensible),
instead the new syscall gets its own dedicated page with links between
open(2) and openat2(2) to avoid duplicating information such as the list
of O_* flags or common errors.

In addition to describing all of the key flags, information about the
extensibility design is provided so that users can better understand why
they need to pass sizeof(struct open_how) and how their programs will
work across kernels. After some discussions with David Laight, I also
included explicit instructions to zero the structure to avoid issues
when recompiling with new headers.

Signed-off-by: Aleksa Sarai <redacted>

Thanks. I've applied this patch, but also done quite a lot of
editing of the page. The current draft is below (and also pushed
to Git). Could I ask you to review the page, to see if I injected
any error during my edits.

Looks good to me.

quoted

In addition, I've added a number of FIXMEs in comments
in the page source. Can you please check these, and let me
know your thoughts.

Will do, see below.

quoted

.\" FIXME I find the "previously-functional systems" in the previous
.\" sentence a little odd (since openat2() ia new sysycall), so I would
.\" like to clarify a little...
.\" Are you referring to the scenario where someone might take an
.\" existing application that uses openat() and replaces the uses
.\" of openat() with openat2()? In which case, is it correct to
.\" understand that you mean that one should not just indiscriminately
.\" add the RESOLVE_NO_XDEV flag to all of the openat2() calls?
.\" If I'm not on the right track, could you point me in the right
.\" direction please.

This is mostly meant as a warning to hopefully avoid applications
because the developer didn't realise that system paths may contain
symlinks or bind-mounts. For an application which has switched to
openat2() and then uses RESOLVE_NO_SYMLINKS for a non-security reason,
it's possible that on some distributions (or future versions of a
distribution) that their application will stop working because a system
path suddenly contains a symlink or is a bind-mount.

This was a concern which was brought up on LWN some time ago. If you can
think of a phrasing that makes this more clear, I'd appreciate it.

Thanks. I've made the text:

                     Applications  that  employ  the RESOLVE_NO_XDEV flag
                     are encouraged to make its use configurable  (unless
                     it is used for a specific security purpose), as bind
                     mounts are widely used by end-users.   Setting  this
                     flag indiscriminately—i.e., for purposes not specif‐
                     ically related to security—for all uses of openat2()
                     may  result  in  spurious errors on previously-func‐
                     tional systems.  This may occur if, for  example,  a
                     system  pathname  that  is used by an application is
                     modified (e.g., in a new  distribution  release)  so
                     that  a  pathname  component  (now)  contains a bind
                     mount.

Okay?

quoted

quoted

.\" FIXME: what specific details in symlink(7) are being referred
.\" by the following sentence? It's not clear.

The section on magic-links, but you're right that the sentence ordering
is a bit odd. It should probably go after the first sentence.

I must admit that I'm still confused. There's only the briefest of
mentions of magic links in symlink(7). Perhaps that needs to be fixed?

And, while I think of it, the text just preceding that FIXME says:

    Due to the potential danger of unknowingly opening
    these magic links, it may be preferable for users to
    disable their resolution entirely.

This sentence reads a little strangely. Could you please give me some
concrete examples, and I will try rewording that sentence a bit.

quoted

quoted

.\" FIXME I found the following hard to understand (in particular, the
.\" meaning of "scoped" is unclear) , and reworded as below. Is it okay?
.\"     Absolute symbolic links and ".." path components will be scoped to
.\"     .IR dirfd .

Scoped does broadly mean "interpreted relative to", though the
difference is mainly that when I said scoped it's meant to be more of an
assertive claim ("the kernel promises to always treat this path inside
dirfd"). But "interpreted relative to" is a clearer way of phrasing the
semantics, so I'm okay with this change.

Okay.

quoted

quoted

.\" FIXME The next piece is unclear (to me). What kind of ".." escape
.\" attempts does chroot() not detect that RESOLVE_IN_ROOT does?

If the root is moved, you can escape from a chroot(2). But this sentence
might not really belong in a man-page since it's describing (important)
aspects of the implementation and not the semantics.

So, should I just remove the sentence?

Thanks,

Michael


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

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