Re: [PATCH 2/2] landlock: Clarify IPC scoping documentation

Re: [PATCH 2/2] landlock: Clarify IPC scoping documentation

[Günther Noack]

Hi!

This is an attempt to clarify the kernel documentation for Landlock's IPC
scoping support before I send the same wording to the man page list in troff
format.

(Adding Alejandro and the man-page list to get an early review on wording and
clarity.)

On Fri, Jan 24, 2025 at 03:44:45PM +0000, Günther Noack wrote:
> * Clarify terminology
> * Stop mixing the unix(7) and signal(7) aspects in the explanation.
> 
> Terminology:
> 
> * The *IPC Scope* of a Landlock domain is that Landlock domain and its
>   nested domains.
> * An *operation* (e.g., signaling, connecting to abstract UDS) is said
>   *to be scoped within a domain* when the flag for that operation was
>   *set at ruleset creation time.  This means that for the purpose of
>   *this operation, only processes within the domain's IPC scope are
>   *reachable.
> 
> Cc: Mickaël Salaün <mic@digikod.net>
> Cc: Tahera Fahimi <fahimitahera@gmail.com>
> Cc: Tanya Agarwal <tanyaagarwal25699@gmail.com>
> Signed-off-by: Günther Noack <gnoack@google.com>
> ---
>  Documentation/userspace-api/landlock.rst | 53 ++++++++++++------------
>  1 file changed, 26 insertions(+), 27 deletions(-)
> 
> diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
> index ca8b325d53e5..6b80106d33de 100644
> --- a/Documentation/userspace-api/landlock.rst
> +++ b/Documentation/userspace-api/landlock.rst
> @@ -317,33 +317,32 @@ IPC scoping
>  -----------
>  
>  Similar to the implicit `Ptrace restrictions`_, we may want to further restrict
> -interactions between sandboxes. Each Landlock domain can be explicitly scoped
> -for a set of actions by specifying it on a ruleset.  For example, if a
> -sandboxed process should not be able to :manpage:`connect(2)` to a
> -non-sandboxed process through abstract :manpage:`unix(7)` sockets, we can
> -specify such a restriction with ``LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET``.
> -Moreover, if a sandboxed process should not be able to send a signal to a
> -non-sandboxed process, we can specify this restriction with
> -``LANDLOCK_SCOPE_SIGNAL``.
> -
> -A sandboxed process can connect to a non-sandboxed process when its domain is
> -not scoped. If a process's domain is scoped, it can only connect to sockets
> -created by processes in the same scope.
> -Moreover, if a process is scoped to send signal to a non-scoped process, it can
> -only send signals to processes in the same scope.
> -
> -A connected datagram socket behaves like a stream socket when its domain is
> -scoped, meaning if the domain is scoped after the socket is connected, it can
> -still :manpage:`send(2)` data just like a stream socket.  However, in the same
> -scenario, a non-connected datagram socket cannot send data (with
> -:manpage:`sendto(2)`) outside its scope.
> -
> -A process with a scoped domain can inherit a socket created by a non-scoped
> -process. The process cannot connect to this socket since it has a scoped
> -domain.

Tahera, Mickaël:

I suspect what was meant in this paragraph are Abstract Unix Domain Sockets of
the datagram type? -- the scenario where the process has an (unconnected) Unix
Datagram Socket and then can not call connect(2) or send(2) *on* it?

I removed this paragraph because I believe it's sufficiently covered in the
section that I wrote about Abstract Unix Domain Sockets below.  If I'm
misunderstanding this, please let me know. :)

> -
> -IPC scoping does not support exceptions, so if a domain is scoped, no rules can
> -be added to allow access to resources or processes outside of the scope.
> +interactions between sandboxes.  Therefore, at ruleset creation time, each
> +Landlock domain can restrict the scope for certain operations, so that these
> +operations can only reach out to processes within the same Landlock domain or in
> +a nested Landlock domain (the "scope").
> +
> +The operations which can be scoped are:
> +
> +``LANDLOCK_SCOPE_SIGNAL``
> +    When set, this limits the sending of signals to target processes which run
> +    within the same or a nested Landlock domain.
> +
> +``LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET``
> +    When set, this limits the set of abstract :manpage:`unix(7)` sockets we can
> +    :manpage:`connect(2)` to to socket addresses which were created by a process
> +    in the same or a nested Landlock domain.
> +
> +    A :manpage:`send(2)` on a non-connected datagram socket is treated like an
> +    implicit :manpage:`connect(2)` and will be blocked when the remote end does
> +    not stem from the same or a nested Landlock domain.
> +
> +    A :manpage:`send(2)` on a socket which was previously connected will work.
> +    This works for both datagram and stream sockets.
> +
> +IPC scoping does not support exceptions via :manpage:`landlock_add_rule(2)`.
> +If an operation is scoped within a domain, no rules can be added to allow access
> +to resources or processes outside of the scope.
>  
>  Truncating files
>  ----------------
> -- 
> 2.48.1.262.g85cc9f2d1e-goog
> 

—Günther

Re: [PATCH 2/2] landlock: Clarify IPC scoping documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2890 bytes --]

Hi Guenther!

On Fri, Jan 24, 2025 at 04:59:29PM +0100, G??nther Noack wrote:
> Hi!
> 
> This is an attempt to clarify the kernel documentation for Landlock's IPC
> scoping support before I send the same wording to the man page list in troff
> format.
> 
> (Adding Alejandro and the man-page list to get an early review on wording and
> clarity.)

Sorry for not replying before.  I had fever last week.  :)

> On Fri, Jan 24, 2025 at 03:44:45PM +0000, G??nther Noack wrote:
> > -IPC scoping does not support exceptions, so if a domain is scoped, no rules can
> > -be added to allow access to resources or processes outside of the scope.
> > +interactions between sandboxes.  Therefore, at ruleset creation time, each
> > +Landlock domain can restrict the scope for certain operations, so that these
> > +operations can only reach out to processes within the same Landlock domain or in
> > +a nested Landlock domain (the "scope").
> > +
> > +The operations which can be scoped are:
> > +
> > +``LANDLOCK_SCOPE_SIGNAL``
> > +    When set,

Do we need to say when set?  I'd say that's redundant (of course if you
don't set a flag, its effects don't apply).

> > this limits the sending of signals to target processes which run
> > +    within the same or a nested Landlock domain.
> > +
> > +``LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET``
> > +    When set, this limits the set of abstract :manpage:`unix(7)` sockets we can
> > +    :manpage:`connect(2)` to to socket addresses which were created by a process
> > +    in the same or a nested Landlock domain.
> > +
> > +    A :manpage:`send(2)` on a non-connected datagram socket is treated like an
> > +    implicit :manpage:`connect(2)` and will be blocked when the remote end does

I think *if* would be more appropriate than *when* here.

> > +    not stem from the same or a nested Landlock domain.

This could be read such that send(2) is replaced by connect(2) on a
non-connected datagram socket.  But you want to say that a connect(2)
is implicitly executed before the actual send(2) (which is still
executed, if connect(2) succeeds).

How about this wording?

	If send(2) is used on a non-connected datagram socket, an
	implicit connect(2) is executed first, and will be blocked when
	the remote end does not ....


Have a lovely day!
Alex

> > +    A :manpage:`send(2)` on a socket which was previously connected will work.
> > +    This works for both datagram and stream sockets.
> > +
> > +IPC scoping does not support exceptions via :manpage:`landlock_add_rule(2)`.
> > +If an operation is scoped within a domain, no rules can be added to allow access
> > +to resources or processes outside of the scope.
> >  
> >  Truncating files
> >  ----------------
> > -- 
> > 2.48.1.262.g85cc9f2d1e-goog
> > 
> 
> ???G??nther

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 2/2] landlock: Clarify IPC scoping documentation

[Günther Noack]

Hello Alejandro!

On Sun, Feb 02, 2025 at 01:51:54PM +0100, Alejandro Colomar wrote:
> On Fri, Jan 24, 2025 at 04:59:29PM +0100, G??nther Noack wrote:
> > On Fri, Jan 24, 2025 at 03:44:45PM +0000, G??nther Noack wrote:
> > > -IPC scoping does not support exceptions, so if a domain is scoped, no rules can
> > > -be added to allow access to resources or processes outside of the scope.
> > > +interactions between sandboxes.  Therefore, at ruleset creation time, each
> > > +Landlock domain can restrict the scope for certain operations, so that these
> > > +operations can only reach out to processes within the same Landlock domain or in
> > > +a nested Landlock domain (the "scope").
> > > +
> > > +The operations which can be scoped are:
> > > +
> > > +``LANDLOCK_SCOPE_SIGNAL``
> > > +    When set,
> 
> Do we need to say when set?  I'd say that's redundant (of course if you
> don't set a flag, its effects don't apply).

Removed, thanks!


> > > this limits the sending of signals to target processes which run
> > > +    within the same or a nested Landlock domain.
> > > +
> > > +``LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET``
> > > +    When set, this limits the set of abstract :manpage:`unix(7)` sockets we can
> > > +    :manpage:`connect(2)` to to socket addresses which were created by a process
> > > +    in the same or a nested Landlock domain.
> > > +
> > > +    A :manpage:`send(2)` on a non-connected datagram socket is treated like an
> > > +    implicit :manpage:`connect(2)` and will be blocked when the remote end does
> 
> I think *if* would be more appropriate than *when* here.
> 
> > > +    not stem from the same or a nested Landlock domain.
> 
> This could be read such that send(2) is replaced by connect(2) on a
> non-connected datagram socket.  But you want to say that a connect(2)
> is implicitly executed before the actual send(2) (which is still
> executed, if connect(2) succeeds).

Thanks, that can indeed be misunderstood.

> How about this wording?
> 
> 	If send(2) is used on a non-connected datagram socket, an
> 	implicit connect(2) is executed first, and will be blocked when
> 	the remote end does not ....

I think this would be misleading as well, because the send(2) on the
non-connected datagram socket does *not* actually perform an implicit
connect(2).  (If it were doing that, the socket would be connected afterwards,
but it isn't.)  But we *do* initiate a communication with a previously unknown
remote address, just like connect(2), so we enforce the same Landlock policy as
for connect(2).

(Remark, connected datagram sockets sound absurd, because there is no connection
at the network layer. On datagram sockets, connect(2) only fixes the destination
address so that it can be omitted in subsequent send(2) calls.).

Rewording it to:

  A sendto(2) on a non-connected datagram socket is treated as if
  it were doing an implicit connect(2) and will be blocked if the
  remote end does not stem from the same or a nested Landlock domain.

(P.S. I also replaced send(2) with sendto(2), which is a bit more appropriate in
the middle paragraph - you can not actually pass the destination address with
send(2), that only works with sendto(2).  I replaced it in the third paragraph
as well for consistency. It still makes sense IMHO considering that send(2) is a
special case of sendto(2).)

—Günther

Re: [PATCH 2/2] landlock: Clarify IPC scoping documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2053 bytes --]

Hello Günther!

On Wed, Feb 26, 2025 at 08:52:03PM +0000, Günther Noack wrote:
> > > > +    not stem from the same or a nested Landlock domain.
> > 
> > This could be read such that send(2) is replaced by connect(2) on a
> > non-connected datagram socket.  But you want to say that a connect(2)
> > is implicitly executed before the actual send(2) (which is still
> > executed, if connect(2) succeeds).
> 
> Thanks, that can indeed be misunderstood.
> 
> > How about this wording?
> > 
> > 	If send(2) is used on a non-connected datagram socket, an
> > 	implicit connect(2) is executed first, and will be blocked when
> > 	the remote end does not ....
> 
> I think this would be misleading as well, because the send(2) on the
> non-connected datagram socket does *not* actually perform an implicit
> connect(2).  (If it were doing that, the socket would be connected afterwards,
> but it isn't.)  But we *do* initiate a communication with a previously unknown
> remote address, just like connect(2), so we enforce the same Landlock policy as
> for connect(2).

Agreed.

> (Remark, connected datagram sockets sound absurd, because there is no connection
> at the network layer. On datagram sockets, connect(2) only fixes the destination
> address so that it can be omitted in subsequent send(2) calls.).
> 
> Rewording it to:
> 
>   A sendto(2) on a non-connected datagram socket is treated as if
>   it were doing an implicit connect(2) and will be blocked if the
>   remote end does not stem from the same or a nested Landlock domain.

Sounds good.

> (P.S. I also replaced send(2) with sendto(2), which is a bit more appropriate in
> the middle paragraph - you can not actually pass the destination address with
> send(2), that only works with sendto(2).  I replaced it in the third paragraph
> as well for consistency. It still makes sense IMHO considering that send(2) is a
> special case of sendto(2).)

Yep, that sounds great.  Thanks!


Cheers,
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 2/2] landlock: Clarify IPC scoping documentation

[Mickaël Salaün]

On Fri, Jan 24, 2025 at 04:59:29PM +0100, Günther Noack wrote:
> Hi!
> 
> This is an attempt to clarify the kernel documentation for Landlock's IPC
> scoping support before I send the same wording to the man page list in troff
> format.
> 
> (Adding Alejandro and the man-page list to get an early review on wording and
> clarity.)
> 
> On Fri, Jan 24, 2025 at 03:44:45PM +0000, Günther Noack wrote:
> > * Clarify terminology
> > * Stop mixing the unix(7) and signal(7) aspects in the explanation.
> > 
> > Terminology:
> > 
> > * The *IPC Scope* of a Landlock domain is that Landlock domain and its
> >   nested domains.
> > * An *operation* (e.g., signaling, connecting to abstract UDS) is said
> >   *to be scoped within a domain* when the flag for that operation was
> >   *set at ruleset creation time.  This means that for the purpose of
> >   *this operation, only processes within the domain's IPC scope are
> >   *reachable.

This makes sense, but there are a lot of stars in here. ;)

> > 
> > Cc: Mickaël Salaün <mic@digikod.net>
> > Cc: Tahera Fahimi <fahimitahera@gmail.com>
> > Cc: Tanya Agarwal <tanyaagarwal25699@gmail.com>
> > Signed-off-by: Günther Noack <gnoack@google.com>
> > ---
> >  Documentation/userspace-api/landlock.rst | 53 ++++++++++++------------
> >  1 file changed, 26 insertions(+), 27 deletions(-)
> > 
> > diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
> > index ca8b325d53e5..6b80106d33de 100644
> > --- a/Documentation/userspace-api/landlock.rst
> > +++ b/Documentation/userspace-api/landlock.rst
> > @@ -317,33 +317,32 @@ IPC scoping
> >  -----------
> >  
> >  Similar to the implicit `Ptrace restrictions`_, we may want to further restrict
> > -interactions between sandboxes. Each Landlock domain can be explicitly scoped
> > -for a set of actions by specifying it on a ruleset.  For example, if a
> > -sandboxed process should not be able to :manpage:`connect(2)` to a
> > -non-sandboxed process through abstract :manpage:`unix(7)` sockets, we can
> > -specify such a restriction with ``LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET``.
> > -Moreover, if a sandboxed process should not be able to send a signal to a
> > -non-sandboxed process, we can specify this restriction with
> > -``LANDLOCK_SCOPE_SIGNAL``.
> > -
> > -A sandboxed process can connect to a non-sandboxed process when its domain is
> > -not scoped. If a process's domain is scoped, it can only connect to sockets
> > -created by processes in the same scope.
> > -Moreover, if a process is scoped to send signal to a non-scoped process, it can
> > -only send signals to processes in the same scope.
> > -
> > -A connected datagram socket behaves like a stream socket when its domain is
> > -scoped, meaning if the domain is scoped after the socket is connected, it can
> > -still :manpage:`send(2)` data just like a stream socket.  However, in the same
> > -scenario, a non-connected datagram socket cannot send data (with
> > -:manpage:`sendto(2)`) outside its scope.
> > -
> > -A process with a scoped domain can inherit a socket created by a non-scoped
> > -process. The process cannot connect to this socket since it has a scoped
> > -domain.
> 
> Tahera, Mickaël:
> 
> I suspect what was meant in this paragraph are Abstract Unix Domain Sockets of
> the datagram type? -- the scenario where the process has an (unconnected) Unix
> Datagram Socket and then can not call connect(2) or send(2) *on* it?

Yes, that's correct.

> 
> I removed this paragraph because I believe it's sufficiently covered in the
> section that I wrote about Abstract Unix Domain Sockets below.  If I'm
> misunderstanding this, please let me know. :)
> 
> > -
> > -IPC scoping does not support exceptions, so if a domain is scoped, no rules can
> > -be added to allow access to resources or processes outside of the scope.

> > +interactions between sandboxes.  Therefore, at ruleset creation time, each
> > +Landlock domain can restrict the scope for certain operations, so that these
> > +operations can only reach out to processes within the same Landlock domain or in
> > +a nested Landlock domain (the "scope").
> > +
> > +The operations which can be scoped are:
> > +
> > +``LANDLOCK_SCOPE_SIGNAL``
> > +    When set, this limits the sending of signals to target processes which run
> > +    within the same or a nested Landlock domain.
> > +
> > +``LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET``
> > +    When set, this limits the set of abstract :manpage:`unix(7)` sockets we can
> > +    :manpage:`connect(2)` to to socket addresses which were created by a process
> > +    in the same or a nested Landlock domain.
> > +
> > +    A :manpage:`send(2)` on a non-connected datagram socket is treated like an
> > +    implicit :manpage:`connect(2)` and will be blocked when the remote end does
> > +    not stem from the same or a nested Landlock domain.
> > +
> > +    A :manpage:`send(2)` on a socket which was previously connected will work.
> > +    This works for both datagram and stream sockets.

Nice!  I also agree with Daniel and Alejandro.

> > +
> > +IPC scoping does not support exceptions via :manpage:`landlock_add_rule(2)`.
> > +If an operation is scoped within a domain, no rules can be added to allow access
> > +to resources or processes outside of the scope.

A bit of background on the rationale.  The particularity of scopes is
that they implicitly allow operations on the current or a nested domain.
With a handled field we would have needed to manually add exceptions for
processes in the current domain or a nested one, which would have been
possible with a new type of rule to identify relative domains (i.e. not
at ruleset creation time but at restriction time).  This new scope
semantic is easy to use, well specified (with this doc ;) ), and it
should fit to most sandbox use cases.  If we ever need a way to further
restrict the use of some IPC, we could still implement a new handled_*
field with the dedicated rule types, which could still compose with the
current scope.


> >  
> >  Truncating files
> >  ----------------
> > -- 
> > 2.48.1.262.g85cc9f2d1e-goog
> > 
> 
> —Günther
> 

[PATCH man 1/3] landlock.7: Update description of Landlock rules

[Günther Noack]

This brings it up to date with the wording in the kernel documentation.

Cc: Mickaël Salaün <mic@digikod.net>
Cc: Tahera Fahimi <fahimitahera@gmail.com>
Cc: Tanya Agarwal <tanyaagarwal25699@gmail.com>
Signed-off-by: Günther Noack <gnoack@google.com>
---
 man/man7/landlock.7 | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
index c6b7272ea..11f76b072 100644
--- a/man/man7/landlock.7
+++ b/man/man7/landlock.7
@@ -39,13 +39,25 @@ the running kernel must support Landlock and
 it must be enabled at boot time.
 .\"
 .SS Landlock rules
-A Landlock rule describes an action on an object.
-An object is currently a file hierarchy,
-and the related filesystem actions are defined with access rights (see
-.BR landlock_add_rule (2)).
+A Landlock rule describes an action on an object
+which the process intends to perform.
 A set of rules is aggregated in a ruleset,
 which can then restrict the thread enforcing it,
 and its future children.
+.P
+The two existing types of rules are:
+.P
+.TP
+.B Filesystem rules
+For these rules, the object is a file hierarchy,
+and the related filesystem actions are defined with
+.IR "filesystem access rights" .
+.TP
+.B Network rules (since ABI v4)
+For these rules, the object is a TCP port,
+and the related actions are defined with
+.IR "network access rights" .
+.BR landlock_add_rule (2)).
 .\"
 .SS Filesystem actions
 These flags enable to restrict a sandboxed process to a
-- 
2.48.1.262.g85cc9f2d1e-goog

[PATCH man 2/3] landlock.7: Move over documentation for ABI version 6

[Günther Noack]

With this ABI version, Landlock can restrict outgoing interactions with
higher-privileged Landlock domains through Abstract Unix Domain sockets and
signals.

Cc: Mickaël Salaün <mic@digikod.net>
Cc: Tahera Fahimi <fahimitahera@gmail.com>
Cc: Tanya Agarwal <tanyaagarwal25699@gmail.com>
Signed-off-by: Günther Noack <gnoack@google.com>
---
 man/man7/landlock.7 | 69 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 68 insertions(+), 1 deletion(-)

diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
index 11f76b072..30dbac73d 100644
--- a/man/man7/landlock.7
+++ b/man/man7/landlock.7
@@ -248,7 +248,8 @@ This access right is available since the fifth version of the Landlock ABI.
 .SS Network flags
 These flags enable to restrict a sandboxed process
 to a set of network actions.
-This is supported since the Landlock ABI version 4.
+.P
+This is supported since Landlock ABI version 4.
 .P
 The following access rights apply to TCP port numbers:
 .TP
@@ -258,6 +259,24 @@ Bind a TCP socket to a local port.
 .B LANDLOCK_ACCESS_NET_CONNECT_TCP
 Connect an active TCP socket to a remote port.
 .\"
+.SS Scope flags
+These flags enable to isolate a sandboxed process from a set of IPC actions.
+Setting a flag for a ruleset will isolate the Landlock domain
+to forbid connections to resources outside the domain.
+.P
+This is supported since Landlock ABI version 6.
+.P
+The following scopes exist:
+.TP
+.B LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET
+Restrict a sandboxed process from connecting to an abstract UNIX socket
+created by a process outside the related Landlock domain
+(e.g., a parent domain or a non-sandboxed process).
+.TP
+.B LANDLOCK_SCOPE_SIGNAL
+Restrict a sandboxed process from sending a signal
+to another process outside the domain.
+.\"
 .SS Layers of file path access rights
 Each time a thread enforces a ruleset on itself,
 it updates its Landlock domain with a new layer of policy.
@@ -334,6 +353,51 @@ and related syscalls on a target process,
 a sandboxed process should have a subset of the target process rules,
 which means the tracee must be in a sub-domain of the tracer.
 .\"
+.SS IPC scoping
+Similar to the implicit
+.BR "Ptrace restrictions" ,
+we may want to further restrict interactions between sandboxes.
+Each Landlock domain can be explicitly scoped for a set of actions
+by specifying it on a ruleset.
+For example, if a sandboxed process should not be able to
+.BR connect (2)
+to a non-sandboxed process through abstract
+.BR unix (7)
+sockets,
+we can specify such a restriction with
+.BR LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET .
+Moreover, if a sandboxed process should not be able
+to send a signal to a non-sandboxed process,
+we can specify this restriction with
+.BR LANDLOCK_SCOPE_SIGNAL .
+.P
+A sandboxed process can connect to a non-sandboxed process
+when its domain is not scoped.
+If a process's domain is scoped,
+it can only connect to sockets created by processes in the same scope.
+Moreover,
+If a process is scoped to send signal to a non-scoped process,
+it can only send signals to processes in the same scope.
+.P
+A connected datagram socket behaves like a stream socket
+when its domain is scoped,
+meaning if the domain is scoped after the socket is connected,
+it can still
+.BR send (2)
+data just like a stream socket.
+However, in the same scenario,
+a non-connected datagram socket cannot send data (with
+.BR sendto (2))
+outside its scope.
+.P
+A process with a scoped domain can inherit a socket
+created by a non-scoped process.
+The process cannot connect to this socket since it has a scoped domain.
+.P
+IPC scoping does not support exceptions, so if a domain is scoped,
+no rules can be added to allow access to resources or processes
+outside of the scope.
+.\"
 .SS Truncating files
 The operations covered by
 .B LANDLOCK_ACCESS_FS_WRITE_FILE
@@ -413,6 +477,9 @@ _	_	_
 \^	\^	LANDLOCK_ACCESS_NET_CONNECT_TCP
 _	_	_
 5	6.10	LANDLOCK_ACCESS_FS_IOCTL_DEV
+_	_	_
+6	6.12	LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET
+\^	\^	LANDLOCK_SCOPE_SIGNAL
 .TE
 .P
 Users should use the Landlock ABI version rather than the kernel version
-- 
2.48.1.262.g85cc9f2d1e-goog

[PATCH man 3/3] landlock.7: Update wording in line with kernel side proposal

[Günther Noack]

Cc: Mickaël Salaün <mic@digikod.net>
Cc: Tahera Fahimi <fahimitahera@gmail.com>
Cc: Tanya Agarwal <tanyaagarwal25699@gmail.com>
Link: https://lore.kernel.org/linux-security-module/20250124154445.162841-2-gnoack@google.com/
Signed-off-by: Günther Noack <gnoack@google.com>
---
 man/man7/landlock.7 | 75 ++++++++++++++++++++++-----------------------
 1 file changed, 37 insertions(+), 38 deletions(-)

diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
index 30dbac73d..749b4a3fa 100644
--- a/man/man7/landlock.7
+++ b/man/man7/landlock.7
@@ -357,46 +357,45 @@ which means the tracee must be in a sub-domain of the tracer.
 Similar to the implicit
 .BR "Ptrace restrictions" ,
 we may want to further restrict interactions between sandboxes.
-Each Landlock domain can be explicitly scoped for a set of actions
-by specifying it on a ruleset.
-For example, if a sandboxed process should not be able to
-.BR connect (2)
-to a non-sandboxed process through abstract
+Therefore, at ruleset creation time,
+each Landlock domain can restrict the scope for certain operations,
+so that these operations can only reach out to processes
+within the same Landlock domain or in a nested Landlock domain (the "scope").
+.P
+The operations which can be scoped are:
+.P
+.TP
+.B LANDLOCK_SCOPE_SIGNAL
+When set,
+this limits the sending of signals to target processes
+which run within the same or a nested Landlock domain.
+.TP
+.B LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET
+When set, this limits the set of abstract
 .BR unix (7)
-sockets,
-we can specify such a restriction with
-.BR LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET .
-Moreover, if a sandboxed process should not be able
-to send a signal to a non-sandboxed process,
-we can specify this restriction with
-.BR LANDLOCK_SCOPE_SIGNAL .
-.P
-A sandboxed process can connect to a non-sandboxed process
-when its domain is not scoped.
-If a process's domain is scoped,
-it can only connect to sockets created by processes in the same scope.
-Moreover,
-If a process is scoped to send signal to a non-scoped process,
-it can only send signals to processes in the same scope.
-.P
-A connected datagram socket behaves like a stream socket
-when its domain is scoped,
-meaning if the domain is scoped after the socket is connected,
-it can still
+sockets we can
+.BR connect (2)
+to
+to socket addresses which were created
+by a process in the same or a nested Landlock domain.
+.IP
+A
+.BR send (2)
+on a non-connected datagram socket is treated like an implicit
+.BR connect (2)
+and will be blocked when the remote end does not stem
+from the same or a nested Landlock domain.
+.IP
+A
 .BR send (2)
-data just like a stream socket.
-However, in the same scenario,
-a non-connected datagram socket cannot send data (with
-.BR sendto (2))
-outside its scope.
-.P
-A process with a scoped domain can inherit a socket
-created by a non-scoped process.
-The process cannot connect to this socket since it has a scoped domain.
-.P
-IPC scoping does not support exceptions, so if a domain is scoped,
-no rules can be added to allow access to resources or processes
-outside of the scope.
+on a socket which was previously connected will work.
+This works for both datagram and stream sockets.
+.P
+IPC scoping does not support exceptions via
+.BR landlock_add_rule (2).
+If an operation is scoped within a domain,
+no rules can be added to allow access
+to resources or processes outside of the scope.
 .\"
 .SS Truncating files
 The operations covered by
-- 
2.48.1.262.g85cc9f2d1e-goog

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Mickaël Salaün]

On Fri, Jan 24, 2025 at 03:44:44PM +0000, Günther Noack wrote:
> * Fix some whitespace, punctuation and minor grammar
> * Add a missing sentence about the minimum ABI version,
>   to stay in line with the section next to it
> 
> Cc: Mickaël Salaün <mic@digikod.net>
> Cc: Tahera Fahimi <fahimitahera@gmail.com>
> Cc: Tanya Agarwal <tanyaagarwal25699@gmail.com>
> Signed-off-by: Günther Noack <gnoack@google.com>

Looks good, thanks!

I'm going to take this patch in my tree with the changes explained
below. You can send a v2 with the second patch according to the reviews.

As a side note, applying the patch series from this thread with b4
doesn't work because they apply to different repositories.

Dealing with duplicated doc in two repositories is not practical and
adds work to everyone...  Could we move the non-libc syscall man pages
to the kernel repository?

> ---
>  Documentation/userspace-api/landlock.rst | 4 ++--
>  include/uapi/linux/landlock.h            | 6 ++++--
>  2 files changed, 6 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
> index d639c61cb472..ca8b325d53e5 100644
> --- a/Documentation/userspace-api/landlock.rst
> +++ b/Documentation/userspace-api/landlock.rst
> @@ -329,11 +329,11 @@ non-sandboxed process, we can specify this restriction with
>  A sandboxed process can connect to a non-sandboxed process when its domain is
>  not scoped. If a process's domain is scoped, it can only connect to sockets
>  created by processes in the same scope.
> -Moreover, If a process is scoped to send signal to a non-scoped process, it can
> +Moreover, if a process is scoped to send signal to a non-scoped process, it can
>  only send signals to processes in the same scope.
>  
>  A connected datagram socket behaves like a stream socket when its domain is
> -scoped, meaning if the domain is scoped after the socket is connected , it can
> +scoped, meaning if the domain is scoped after the socket is connected, it can
>  still :manpage:`send(2)` data just like a stream socket.  However, in the same
>  scenario, a non-connected datagram socket cannot send data (with
>  :manpage:`sendto(2)`) outside its scope.
> diff --git a/include/uapi/linux/landlock.h b/include/uapi/linux/landlock.h
> index 33745642f787..048a2c77c4eb 100644
> --- a/include/uapi/linux/landlock.h
> +++ b/include/uapi/linux/landlock.h
> @@ -268,7 +268,7 @@ struct landlock_net_port_attr {
>   * ~~~~~~~~~~~~~~~~
>   *
>   * These flags enable to restrict a sandboxed process to a set of network
> - * actions. This is supported since the Landlock ABI version 4.
> + * actions. This is supported since Landlock ABI version 4.

If that's OK with you, I'll move this sentence to a standalone paragraph
like the one you added below:

+ * actions.
+ *
+ * This is supported since Landlock ABI version 4.

>   *
>   * The following access rights apply to TCP port numbers:
>   *
> @@ -291,11 +291,13 @@ struct landlock_net_port_attr {
>   * Setting a flag for a ruleset will isolate the Landlock domain to forbid
>   * connections to resources outside the domain.
>   *
> + * This is supported since Landlock ABI version 6.
> + *
>   * Scopes:
>   *
>   * - %LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET: Restrict a sandboxed process from
>   *   connecting to an abstract UNIX socket created by a process outside the
> - *   related Landlock domain (e.g. a parent domain or a non-sandboxed process).
> + *   related Landlock domain (e.g., a parent domain or a non-sandboxed process).
>   * - %LANDLOCK_SCOPE_SIGNAL: Restrict a sandboxed process from sending a signal
>   *   to another process outside the domain.
>   */
> -- 
> 2.48.1.262.g85cc9f2d1e-goog
> 
> 

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1846 bytes --]

Hey Mickaël!

On Tue, Feb 11, 2025 at 04:17:30PM +0100, Mickaël Salaün wrote:
> On Fri, Jan 24, 2025 at 03:44:44PM +0000, Günther Noack wrote:
> > * Fix some whitespace, punctuation and minor grammar
> > * Add a missing sentence about the minimum ABI version,
> >   to stay in line with the section next to it
> > 
> > Cc: Mickaël Salaün <mic@digikod.net>
> > Cc: Tahera Fahimi <fahimitahera@gmail.com>
> > Cc: Tanya Agarwal <tanyaagarwal25699@gmail.com>
> > Signed-off-by: Günther Noack <gnoack@google.com>
> 
> Looks good, thanks!
> 
> I'm going to take this patch in my tree with the changes explained
> below. You can send a v2 with the second patch according to the reviews.
> 
> As a side note, applying the patch series from this thread with b4
> doesn't work because they apply to different repositories.
> 
> Dealing with duplicated doc in two repositories is not practical and
> adds work to everyone...  Could we move the non-libc syscall man pages
> to the kernel repository?

Let me suggest the opposite: Could we move the kernel docs to manual
pages in man9?  (As is the historic place for kernel docs.)
(You could keep man9 in the kernel tree if you want, or could handle it
 to the Linux man-pages project, if you want.)  That would help have a
more clear separation between the two sets of documentation, and prevent
duplication.

I personally don't like the idea of having man2 in the kernel tree.
Michael Kerrisk already mentioned several reasons for why it's a bad
idea in the past.  On top of them, I'd add that the build system of the
Linux man-pages project is quite more powerful than the kernel one, and
it would be an important regression to have to adapt to the kernel
Makefiles in the manual pages.


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Mickaël Salaün]

On Tue, Feb 11, 2025 at 04:27:04PM +0100, Alejandro Colomar wrote:
> Hey Mickaël!

Hey!

> 
> On Tue, Feb 11, 2025 at 04:17:30PM +0100, Mickaël Salaün wrote:
> > On Fri, Jan 24, 2025 at 03:44:44PM +0000, Günther Noack wrote:
> > > * Fix some whitespace, punctuation and minor grammar
> > > * Add a missing sentence about the minimum ABI version,
> > >   to stay in line with the section next to it
> > > 
> > > Cc: Mickaël Salaün <mic@digikod.net>
> > > Cc: Tahera Fahimi <fahimitahera@gmail.com>
> > > Cc: Tanya Agarwal <tanyaagarwal25699@gmail.com>
> > > Signed-off-by: Günther Noack <gnoack@google.com>
> > 
> > Looks good, thanks!
> > 
> > I'm going to take this patch in my tree with the changes explained
> > below. You can send a v2 with the second patch according to the reviews.
> > 
> > As a side note, applying the patch series from this thread with b4
> > doesn't work because they apply to different repositories.
> > 
> > Dealing with duplicated doc in two repositories is not practical and
> > adds work to everyone...  Could we move the non-libc syscall man pages
> > to the kernel repository?
> 
> Let me suggest the opposite: Could we move the kernel docs to manual
> pages in man9?  (As is the historic place for kernel docs.)
> (You could keep man9 in the kernel tree if you want, or could handle it
>  to the Linux man-pages project, if you want.)  That would help have a
> more clear separation between the two sets of documentation, and prevent
> duplication.

I didn't know about man9 but it's not clear to me what would be the
content.  Because I want new kernel features to come with proper tests
and documentation, it would be much easier to apply all these patches to
the same repository, at the same time.  Using the same repository should
also help to synchronize documentation with code changes.

One remaining issue would be that some generated documentation come from
the kernel source files, especially the UAPI headers, which also helps
maintaining the documentation in sync with the code.  What would you
suggest to improve the current workflow?

> 
> I personally don't like the idea of having man2 in the kernel tree.
> Michael Kerrisk already mentioned several reasons for why it's a bad
> idea in the past.  On top of them, I'd add that the build system of the
> Linux man-pages project is quite more powerful than the kernel one, and
> it would be an important regression to have to adapt to the kernel
> Makefiles in the manual pages.

For the Landlock syscalls case, could we move the syscall documentation
to man9?

> 
> 
> Have a lovely day!
> Alex
> 
> -- 
> <https://www.alejandro-colomar.es/>

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 3479 bytes --]

Hi!

On Tue, Feb 11, 2025 at 04:53:44PM +0100, Mickaël Salaün wrote:
> > Let me suggest the opposite: Could we move the kernel docs to manual
> > pages in man9?  (As is the historic place for kernel docs.)
> > (You could keep man9 in the kernel tree if you want, or could handle it
> >  to the Linux man-pages project, if you want.)  That would help have a
> > more clear separation between the two sets of documentation, and prevent
> > duplication.
> 
> I didn't know about man9 but it's not clear to me what would be the
> content.

The official name of man9 is "Kernel Developer's Manual".
In-scope in man9 are internal kernel APIs, and in general anything that
is of interest to kernel developers but not to user-space developers.

>  Because I want new kernel features to come with proper tests
> and documentation, it would be much easier to apply all these patches to
> the same repository, at the same time.  Using the same repository should
> also help to synchronize documentation with code changes.
> 
> One remaining issue would be that some generated documentation come from
> the kernel source files, especially the UAPI headers, which also helps
> maintaining the documentation in sync with the code.  What would you
> suggest to improve the current workflow?

For generated documentation, I'd really avoid that.  Currently, in the
man-pages we only have bpf-helpers(7), and I'd very much not follow that
for other pages.

For APIs that change often, that may make sense, but in general, APIs
shouldn't change significantly enough to prefer generated docs.

> > I personally don't like the idea of having man2 in the kernel tree.
> > Michael Kerrisk already mentioned several reasons for why it's a bad
> > idea in the past.  On top of them, I'd add that the build system of the
> > Linux man-pages project is quite more powerful than the kernel one, and
> > it would be an important regression to have to adapt to the kernel
> > Makefiles in the manual pages.
> 
> For the Landlock syscalls case, could we move the syscall documentation
> to man9?

man9 is for internal kernel APIs.  Here's intro(9) in different systems,
which documents what should go into man9, and what shouldn't:

<https://man.netbsd.org/intro.9>
<https://man.openbsd.org/intro.9>
<https://man.freebsd.org/cgi/man.cgi?query=intro&apropos=0&sektion=9&manpath=FreeBSD+14.2-RELEASE+and+Ports&arch=default&format=html>

Debian had a project which documented some Linux kernel internals in
man9, but it was eventually dropped.  I don't know who maintained that,
and what was the history about it.

If Landlock has internal documentation that only matters to kernel
developers, yes, that would be in-scope for man9.  The user-facing docs
are more relevant in man2 and man7, though.

I would be happy to take all the landlock docs in the form of man9 pages
if you handle them to the Linux man-pages project.  I can do the work of
transforming the .rst docs into man(7) pages; that's fine by me.

If there's consensus in the kernel of moving to man9 docs, I'd be happy
to help with that.  I fear that some maintainers may fear man(7) pages.
If you need me to give any talks to explain how to write man(7) source
code, and show that it's easier than it looks like, I could do that
(Günther already suggested me to do so :).  Maybe I should give a talk
at Plumbers.


Cheers,
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1009 bytes --]

At 2025-02-11T17:13:21+0100, Alejandro Colomar wrote:
> If there's consensus in the kernel of moving to man9 docs, I'd be
> happy to help with that.  I fear that some maintainers may fear man(7)
> pages.  If you need me to give any talks to explain how to write
> man(7) source code, and show that it's easier than it looks like, I
> could do that (Günther already suggested me to do so :).  Maybe I
> should give a talk at Plumbers.

Consider me a resource for this purpose as well.  I gave a talk on this
very subject at DebConf 5 (not a typo, that was 2005),[1] and have some
familiarity with the man(7) macro package, its history in various
Unices, its groff implementation, and the underlying language of the
formatter, troff/nroff, which were developed at the Bell Labs Computing
Science Research Center contemporaneously with, and by the same group
as, the Unix kernel.

Regards,
Branden

[1] https://web.archive.org/web/20071015000604/http://people.debian.org/~branden/talks/wtfm/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1594 bytes --]

Hi Branden,

On Tue, Feb 11, 2025 at 12:08:51PM -0600, G. Branden Robinson wrote:
> At 2025-02-11T17:13:21+0100, Alejandro Colomar wrote:
> > If there's consensus in the kernel of moving to man9 docs, I'd be
> > happy to help with that.  I fear that some maintainers may fear man(7)
> > pages.  If you need me to give any talks to explain how to write
> > man(7) source code, and show that it's easier than it looks like, I
> > could do that (Günther already suggested me to do so :).  Maybe I
> > should give a talk at Plumbers.
> 
> Consider me a resource for this purpose as well.  I gave a talk on this
> very subject at DebConf 5 (not a typo, that was 2005),[1] and have some
> familiarity with the man(7) macro package, its history in various
> Unices, its groff implementation, and the underlying language of the
> formatter, troff/nroff, which were developed at the Bell Labs Computing
> Science Research Center contemporaneously with, and by the same group
> as, the Unix kernel.

Yup!  Maybe we can prepare a talk together?  I mean two speakers.  You
certainly know things I don't, and I probably have other points of view
that are interesting.

I think we could meet IRL eventually to prepare something like this.
I'll probably be in the US a couple of times in 2025 (one C Committee
meeting, and OSS.us/LSS.us).  If you're interested, please send me an
email.

And if any kernel people reading this is interested in anything specific
from us man(7) people, please let us know!


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Mickaël Salaün]

On Tue, Feb 11, 2025 at 05:13:21PM +0100, Alejandro Colomar wrote:
> Hi!
> 
> On Tue, Feb 11, 2025 at 04:53:44PM +0100, Mickaël Salaün wrote:
> > > Let me suggest the opposite: Could we move the kernel docs to manual
> > > pages in man9?  (As is the historic place for kernel docs.)
> > > (You could keep man9 in the kernel tree if you want, or could handle it
> > >  to the Linux man-pages project, if you want.)  That would help have a
> > > more clear separation between the two sets of documentation, and prevent
> > > duplication.
> > 
> > I didn't know about man9 but it's not clear to me what would be the
> > content.
> 
> The official name of man9 is "Kernel Developer's Manual".
> In-scope in man9 are internal kernel APIs, and in general anything that
> is of interest to kernel developers but not to user-space developers.
> 
> >  Because I want new kernel features to come with proper tests
> > and documentation, it would be much easier to apply all these patches to
> > the same repository, at the same time.  Using the same repository should
> > also help to synchronize documentation with code changes.
> > 
> > One remaining issue would be that some generated documentation come from
> > the kernel source files, especially the UAPI headers, which also helps
> > maintaining the documentation in sync with the code.  What would you
> > suggest to improve the current workflow?
> 
> For generated documentation, I'd really avoid that.  Currently, in the
> man-pages we only have bpf-helpers(7), and I'd very much not follow that
> for other pages.

OK, kernel doc in man9 would not be a good fit then.

> 
> For APIs that change often, that may make sense, but in general, APIs
> shouldn't change significantly enough to prefer generated docs.
> 
> > > I personally don't like the idea of having man2 in the kernel tree.
> > > Michael Kerrisk already mentioned several reasons for why it's a bad
> > > idea in the past.  On top of them, I'd add that the build system of the
> > > Linux man-pages project is quite more powerful than the kernel one, and
> > > it would be an important regression to have to adapt to the kernel
> > > Makefiles in the manual pages.
> > 
> > For the Landlock syscalls case, could we move the syscall documentation
> > to man9?
> 
> man9 is for internal kernel APIs.  Here's intro(9) in different systems,
> which documents what should go into man9, and what shouldn't:
> 
> <https://man.netbsd.org/intro.9>
> <https://man.openbsd.org/intro.9>
> <https://man.freebsd.org/cgi/man.cgi?query=intro&apropos=0&sektion=9&manpath=FreeBSD+14.2-RELEASE+and+Ports&arch=default&format=html>
> 
> Debian had a project which documented some Linux kernel internals in
> man9, but it was eventually dropped.  I don't know who maintained that,
> and what was the history about it.
> 
> If Landlock has internal documentation that only matters to kernel
> developers, yes, that would be in-scope for man9.  The user-facing docs
> are more relevant in man2 and man7, though.
> 
> I would be happy to take all the landlock docs in the form of man9 pages
> if you handle them to the Linux man-pages project.  I can do the work of
> transforming the .rst docs into man(7) pages; that's fine by me.
> 
> If there's consensus in the kernel of moving to man9 docs, I'd be happy
> to help with that.  I fear that some maintainers may fear man(7) pages.
> If you need me to give any talks to explain how to write man(7) source
> code, and show that it's easier than it looks like, I could do that
> (Günther already suggested me to do so :).  Maybe I should give a talk
> at Plumbers.

It would be interesting to get the point of view of other kernel
maintainers but I guess a lot of them would have the same: to lower the
bar of contributions.

> 
> 
> Cheers,
> Alex
> 
> -- 
> <https://www.alejandro-colomar.es/>

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 6507 bytes --]

Hi Mickaël,

On Tue, Feb 11, 2025 at 08:24:21PM +0100, Mickaël Salaün wrote:
> > The official name of man9 is "Kernel Developer's Manual".
> > In-scope in man9 are internal kernel APIs, and in general anything that
> > is of interest to kernel developers but not to user-space developers.
> > 
> > >  Because I want new kernel features to come with proper tests
> > > and documentation, it would be much easier to apply all these patches to
> > > the same repository, at the same time.  Using the same repository should
> > > also help to synchronize documentation with code changes.
> > > 
> > > One remaining issue would be that some generated documentation come from
> > > the kernel source files, especially the UAPI headers, which also helps
> > > maintaining the documentation in sync with the code.  What would you
> > > suggest to improve the current workflow?
> > 
> > For generated documentation, I'd really avoid that.  Currently, in the
> > man-pages we only have bpf-helpers(7), and I'd very much not follow that
> > for other pages.
> 
> OK, kernel doc in man9 would not be a good fit then.

Well, I think I should develop what I said.  I think the quality of
generated documentation isn't good, compared to hand-written
documentation.  I wouldn't recommend in general generating man(7) pages,
just like I wouldn't recommend generating .rst documents.

However, given the assumption that you're going to generate the
documentation anyway from comments (which is what I recommend against),
generating man(7) source isn't worse than generating .rst docs.  I
personally don't like in-source comments either, so writing only man(7)
source is fine --I don't have the problem of keeping it up to date with
the comments; there's no duplication--.  If you're committed to
in-source comments, and your internal APIs change so often that it
wouldn't be reasonable to write documentation by hand (other than the
in-source comments), then it makes sense to generate man(7) pages in
the man9 section.

I'm going to release today the next version of the Linux man-pages
project, and have refreshed the bpf-helpers(7) manual page from Linux
source.  The process is pretty easy:

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=ebfa53a052e70a1252051ba3ad99c3b5a87da42d>
	commit ebfa53a052e70a1252051ba3ad99c3b5a87da42d
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   Wed Feb 12 15:46:18 2025 +0100

	    man/man7/bpf-helpers.7: Refresh page from Linux v6.13
	    
	    Scripted change:
	    
		    $ ~/src/linux/linux/v6.13/scripts/bpf_doc.py \
		    | rst2man \
		    >man7/bpf-helpers.7;
	    
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

	diff --git a/man/man7/bpf-helpers.7 b/man/man7/bpf-helpers.7
	[...]

So you could really use man9 for internal Landlock stuff.  Even if I
think generated documentation isn't ideal, it's better than nothing.
Being able to use man(1) for reading kernel documentation would still be
a nice feature.

And while I can't run all the linters that I run on hand-written docs on
generated pages (because generated source necessarily triggers many
false positives), I could still run some, which would trigger some
accidents in the docs, and would also detect bugs in the software
translating the docs from one language to another.

So, I'd still recommend you considering man9.

> > For APIs that change often, that may make sense, but in general, APIs
> > shouldn't change significantly enough to prefer generated docs.
> > 
> > > > I personally don't like the idea of having man2 in the kernel tree.
> > > > Michael Kerrisk already mentioned several reasons for why it's a bad
> > > > idea in the past.  On top of them, I'd add that the build system of the
> > > > Linux man-pages project is quite more powerful than the kernel one, and
> > > > it would be an important regression to have to adapt to the kernel
> > > > Makefiles in the manual pages.
> > > 
> > > For the Landlock syscalls case, could we move the syscall documentation
> > > to man9?
> > 
> > man9 is for internal kernel APIs.  Here's intro(9) in different systems,
> > which documents what should go into man9, and what shouldn't:
> > 
> > <https://man.netbsd.org/intro.9>
> > <https://man.openbsd.org/intro.9>
> > <https://man.freebsd.org/cgi/man.cgi?query=intro&apropos=0&sektion=9&manpath=FreeBSD+14.2-RELEASE+and+Ports&arch=default&format=html>
> > 
> > Debian had a project which documented some Linux kernel internals in
> > man9, but it was eventually dropped.  I don't know who maintained that,
> > and what was the history about it.
> > 
> > If Landlock has internal documentation that only matters to kernel
> > developers, yes, that would be in-scope for man9.  The user-facing docs
> > are more relevant in man2 and man7, though.
> > 
> > I would be happy to take all the landlock docs in the form of man9 pages
> > if you handle them to the Linux man-pages project.  I can do the work of
> > transforming the .rst docs into man(7) pages; that's fine by me.
> > 
> > If there's consensus in the kernel of moving to man9 docs, I'd be happy
> > to help with that.  I fear that some maintainers may fear man(7) pages.
> > If you need me to give any talks to explain how to write man(7) source
> > code, and show that it's easier than it looks like, I could do that
> > (Günther already suggested me to do so :).  Maybe I should give a talk
> > at Plumbers.
> 
> It would be interesting to get the point of view of other kernel
> maintainers but I guess a lot of them would have the same: to lower the
> bar of contributions.

I'm working hard on making it easier to contribute to the Linux
man-pages project.  Adding consistency to the existing pages makes it
easier to just look at the surrounding documentation and deduce how to
document some new feature.  The source is today much more
self-consistent than it was 5 years ago.

Also, me being paid to work on the project means significantly less time
to review something.  If I can do anything else to make it easier to
write man(7) and/or contribute via email, please let me know.

Yes, tools like b4(1) may not be ideal for working in two different
repos, but I expect that if you report that to Konstantin, he'll
probably have ideas for that.  I don't think that should be impossible
to fix.


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Günther Noack]

Hello!

On Wed, Feb 12, 2025 at 04:06:06PM +0100, Alejandro Colomar wrote:
> So you could really use man9 for internal Landlock stuff.  Even if I
> think generated documentation isn't ideal, it's better than nothing.
> Being able to use man(1) for reading kernel documentation would still be
> a nice feature.
> 
> And while I can't run all the linters that I run on hand-written docs on
> generated pages (because generated source necessarily triggers many
> false positives), I could still run some, which would trigger some
> accidents in the docs, and would also detect bugs in the software
> translating the docs from one language to another.
> 
> So, I'd still recommend you considering man9.

This is different to the BPF helpers; Landlock's existing man pages document
user space APIs, and the largest part of the kernel-side .rst documentation for
Landlock also covers only user space. Only a small part of the .rst
documentation is about kernel internals.

If I understood that correctly, section 9 is supposed to be document things that
are relevant to kernel developers, right?  So it doesn't sound like the right
place for the documentation that we have?

—Günther

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1723 bytes --]

On Wed, Feb 26, 2025 at 08:24:22PM +0000, Günther Noack wrote:
> Hello!

Hello!

> On Wed, Feb 12, 2025 at 04:06:06PM +0100, Alejandro Colomar wrote:
> > So you could really use man9 for internal Landlock stuff.  Even if I
> > think generated documentation isn't ideal, it's better than nothing.
> > Being able to use man(1) for reading kernel documentation would still be
> > a nice feature.
> > 
> > And while I can't run all the linters that I run on hand-written docs on
> > generated pages (because generated source necessarily triggers many
> > false positives), I could still run some, which would trigger some
> > accidents in the docs, and would also detect bugs in the software
> > translating the docs from one language to another.
> > 
> > So, I'd still recommend you considering man9.
> 
> This is different to the BPF helpers; Landlock's existing man pages document
> user space APIs, and the largest part of the kernel-side .rst documentation for
> Landlock also covers only user space.

Huh!  Why does the kernel duplicate what's already in the manual pages?
Or does it cover other stuff?

> Only a small part of the .rst
> documentation is about kernel internals.

Hmmmm.  I expected it would be mostly for kernel internals, but it seems
my guess was wrong.  :)

> If I understood that correctly, section 9 is supposed to be document things that
> are relevant to kernel developers, right?  So it doesn't sound like the right
> place for the documentation that we have?

Yep, that suggestion was due to my wrong idea that the .rst docs were
mostly kernel internals.


Have a lovely night!
Alex

> 
> —Günther
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Günther Noack]

Hello!

On Wed, Feb 26, 2025 at 09:57:58PM +0100, Alejandro Colomar wrote:
> On Wed, Feb 26, 2025 at 08:24:22PM +0000, Günther Noack wrote:
> > On Wed, Feb 12, 2025 at 04:06:06PM +0100, Alejandro Colomar wrote:
> > > So you could really use man9 for internal Landlock stuff.  Even if I
> > > think generated documentation isn't ideal, it's better than nothing.
> > > Being able to use man(1) for reading kernel documentation would still be
> > > a nice feature.
> > > 
> > > And while I can't run all the linters that I run on hand-written docs on
> > > generated pages (because generated source necessarily triggers many
> > > false positives), I could still run some, which would trigger some
> > > accidents in the docs, and would also detect bugs in the software
> > > translating the docs from one language to another.
> > > 
> > > So, I'd still recommend you considering man9.
> > 
> > This is different to the BPF helpers; Landlock's existing man pages document
> > user space APIs, and the largest part of the kernel-side .rst documentation for
> > Landlock also covers only user space.
> 
> Huh!  Why does the kernel duplicate what's already in the manual pages?

That duplication is *precisely* the problem we have in Landlock. :)

(If you look at the patch series I've been sending with both the patches sent to
linux-security-modules@ and linux-man@, you'll see the duplication,
e.g. https://lore.kernel.org/all/20250226211814.31420-2-gnoack@google.com/)

Documentation of user space APIs is not unusual in the kernel documentation,
there is the entire subdirectory Documentation/userspace-api for it.

—Günther

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1365 bytes --]

Hello!

On Wed, Feb 26, 2025 at 10:38:05PM +0100, Günther Noack wrote:
> That duplication is *precisely* the problem we have in Landlock. :)
> 
> (If you look at the patch series I've been sending with both the patches sent to
> linux-security-modules@ and linux-man@, you'll see the duplication,
> e.g. https://lore.kernel.org/all/20250226211814.31420-2-gnoack@google.com/)

Yeah, I've been looking at those that you've CCd me.  I just thought
that the user-space part of the documentation was minoritary, and that
it was part of a much larger documentation that would include many
internals.  But if most .rst docs are UAPI, then I think it should all
be burnt down to flames.  :-)

> Documentation of user space APIs is not unusual in the kernel documentation,
> there is the entire subdirectory Documentation/userspace-api for it.

Huh!  You're indeed right.  A great percentage of Documentation/ is the
UAPI.

	alx@debian:~/.../Documentation$ find * -type f \
					| xargs wc | tail -n1;
	 110625  453670 3990219 total
	alx@debian:~/.../Documentation$ find userspace-api/ -type f \
					| xargs wc | tail -n1;
	  96501  368382 3411766 total


If anyone wants to burn that and send the parts that are missing form
the manual pages, you're invited.  :-)


Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]