Skip to contentSkip to conversation

landlock: Minor typo and grammar fixes in IPC scoping documentation

PATCH In review Günther Noack 5 participants 23 messages Jan 24, 2025 – Feb 26, 2025

Subsystems (4)
lore
Share & tools
lore

Günther Noack

author reviewer
#0 lore raw

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

* 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 <[email protected]>
Cc Tahera Fahimi <[email protected]>
Cc Tanya Agarwal <[email protected]>
---
 Documentation/userspace-api/landlock.rst | 4 ++--
 include/uapi/linux/landlock.h            | 6 ++++--
 2 files changed, 6 insertions(+), 4 deletions(-)
Documentation/userspace-api/landlock.rst +2 -2
index d639c61cb472..ca8b325d53e5 100644
@@ -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.
include/uapi/linux/landlock.h +4 -2
index 33745642f787..048a2c77c4eb 100644
@@ -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.
  *
  * 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.
  */
Signature · 1 line
2.48.1.262.g85cc9f2d1e-goog
author reviewer
#1 lore raw

PATCH 2/2 landlock: Clarify IPC scoping documentation

* 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 <[email protected]>
Cc Tahera Fahimi <[email protected]>
Cc Tanya Agarwal <[email protected]>
---
 Documentation/userspace-api/landlock.rst | 53 ++++++++++++------------
 1 file changed, 26 insertions(+), 27 deletions(-)
Documentation/userspace-api/landlock.rst +26 -27
index ca8b325d53e5..6b80106d33de 100644
@@ -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.
-
-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
 ----------------
Signature · 1 line
2.48.1.262.g85cc9f2d1e-goog
#2 lore raw

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

Quoted 60 lines · Günther Noack

* 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 <[email protected]>
Cc Tahera Fahimi <[email protected]>
Cc Tanya Agarwal <[email protected]>
---
  Documentation/userspace-api/landlock.rst | 53 ++++++++++++------------
  1 file changed, 26 insertions(+), 27 deletions(-)
Documentation/userspace-api/landlock.rst +4 -27
index ca8b325d53e5..6b80106d33de 100644
@@ -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.
-
-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").

Documentation/userspace-api/landlock.rst IPC scoping · line 333

Quoted 10 lines
Documentation/userspace-api/landlock.rst +10 -0
+
+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

The "to to" takes a couple of reads to parse. Would "...this limits the set of abstract :manpage:unix(7) sockets to which we can :manpage:connect(2) to socket addresses which were..." perhaps be easier to read?

Documentation/userspace-api/landlock.rst IPC scoping · line 340

Quoted 7 lines
Documentation/userspace-api/landlock.rst +7 -0
+    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.

Maybe overly pedantic, but I wonder if something like "will not be restricted" instead of "will work" would be clearer? "Work" just has a lot of meanings. I don't think it's actually ambiguous as written, I just think that a more precise word could avoid the potential for confusion.

-Daniel

Quoted 8 lines
Documentation/userspace-api/landlock.rst +5 -0
+    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
  ----------------
author reviewer
#3 lore raw

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

In reply to 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.)

Quoted 43 lines · Günther Noack

* 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 <[email protected]>
Cc Tahera Fahimi <[email protected]>
Cc Tanya Agarwal <[email protected]>
---
 Documentation/userspace-api/landlock.rst | 53 ++++++++++++------------
 1 file changed, 26 insertions(+), 27 deletions(-)
Documentation/userspace-api/landlock.rst +0 -14
index ca8b325d53e5..6b80106d33de 100644
@@ -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.

Documentation/userspace-api/landlock.rst IPC scoping · line 343

Quoted 10 lines
Documentation/userspace-api/landlock.rst +0 -10
-
-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. :)

Quoted 35 lines
Documentation/userspace-api/landlock.rst +26 -3
-
-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
 ----------------
Signature · 1 line
2.48.1.262.g85cc9f2d1e-goog

—Günther

#4 lore raw

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

Hi Guenther!

Quoted 8 lines · 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.)

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

Quoted 12 lines · G??nther Noack

Documentation/userspace-api/landlock.rst IPC scoping

Quoted 11 lines
Documentation/userspace-api/landlock.rst +9 -2
-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).

Quoted 10 lines

Documentation/userspace-api/landlock.rst IPC scoping · line 337

Quoted 10 lines

this limits the sending of signals to target processes which run

Documentation/userspace-api/landlock.rst +9 -0
+    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.

Quoted 1 line
Quoted 1 line

+ 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

Quoted 14 lines
Quoted 12 lines
Documentation/userspace-api/landlock.rst +6 -0
+    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
 ----------------
Signature · 1 line
2.48.1.262.g85cc9f2d1e-goog

???G??nther

Signature · 1 line
<https://www.alejandro-colomar.es/>
author reviewer
#5 lore raw

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

Hello Alejandro!

Quoted 16 lines · Alejandro Colomar
Quoted 12 lines · G??nther Noack

Documentation/userspace-api/landlock.rst IPC scoping

Quoted 11 lines · G??nther Noack
Documentation/userspace-api/landlock.rst +9 -2
-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!

Quoted 13 lines
Quoted 10 lines

Documentation/userspace-api/landlock.rst IPC scoping · line 337

Quoted 10 lines

this limits the sending of signals to target processes which run

Documentation/userspace-api/landlock.rst +9 -0
+    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.

Quoted 6 lines
Quoted 1 line
Quoted 1 line

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

Quoted 5 lines

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

#6 lore raw

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

Hello Günther!

Quoted 15 lines · Günther Noack
Quoted 6 lines
Quoted 1 line
Quoted 1 line

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

Quoted 5 lines

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

Quoted 6 lines

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.

Quoted 9 lines

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

Quoted 5 lines

(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

Signature · 1 line
<https://www.alejandro-colomar.es/>
maintainer
#7 lore raw

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

In reply to Günther Noack
Quoted 22 lines · 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.)

Quoted 12 lines · Günther Noack

* 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. ;)

Quoted 44 lines
Quoted 31 lines
Cc Mickaël Salaün <[email protected]>
Cc Tahera Fahimi <[email protected]>
Cc Tanya Agarwal <[email protected]>
---
 Documentation/userspace-api/landlock.rst | 53 ++++++++++++------------
 1 file changed, 26 insertions(+), 27 deletions(-)
Documentation/userspace-api/landlock.rst +0 -14
index ca8b325d53e5..6b80106d33de 100644
@@ -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.

Documentation/userspace-api/landlock.rst IPC scoping · line 343

Quoted 10 lines
Documentation/userspace-api/landlock.rst +0 -10
-
-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:

Quoted 3 lines

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.

Quoted 23 lines

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

Quoted 18 lines
Documentation/userspace-api/landlock.rst +14 -3
-
-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
Quoted 8 lines

Documentation/userspace-api/landlock.rst IPC scoping · line 341

Quoted 8 lines
Documentation/userspace-api/landlock.rst +8 -0
+    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.

Quoted 4 lines

Documentation/userspace-api/landlock.rst IPC scoping · line 345

Quoted 4 lines
Documentation/userspace-api/landlock.rst +4 -0
+
+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.

Quoted 9 lines
Quoted 6 lines
Documentation/userspace-api/landlock.rst +0 -0
 Truncating files
 ----------------
Signature · 1 line
2.48.1.262.g85cc9f2d1e-goog

—Günther

author reviewer
#8 lore raw

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

In reply to Günther Noack

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

Cc Mickaël Salaün <[email protected]>
Cc Tahera Fahimi <[email protected]>
Cc Tanya Agarwal <[email protected]>
---
 man/man7/landlock.7 | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)
man/man7/landlock.7 +16 -4
index c6b7272ea..11f76b072 100644
@@ -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
Signature · 1 line
2.48.1.262.g85cc9f2d1e-goog
author reviewer
#9 lore raw

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

In reply to 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 <[email protected]>
Cc Tahera Fahimi <[email protected]>
Cc Tanya Agarwal <[email protected]>
---
 man/man7/landlock.7 | 69 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 68 insertions(+), 1 deletion(-)
man/man7/landlock.7 +68 -1
index 11f76b072..30dbac73d 100644
@@ -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
Signature · 1 line
2.48.1.262.g85cc9f2d1e-goog
author reviewer
#10 lore raw

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

In reply to Günther Noack
---
 man/man7/landlock.7 | 75 ++++++++++++++++++++++-----------------------
 1 file changed, 37 insertions(+), 38 deletions(-)
man/man7/landlock.7 +37 -38
index 30dbac73d..749b4a3fa 100644
@@ -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
Signature · 1 line
2.48.1.262.g85cc9f2d1e-goog
maintainer
#11 lore raw
In reply to Günther Noack
Quoted 8 lines · Günther Noack

* 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 <[email protected]>
Cc Tahera Fahimi <[email protected]>
Cc Tanya Agarwal <[email protected]>

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?

Quoted 28 lines
---
 Documentation/userspace-api/landlock.rst | 4 ++--
 include/uapi/linux/landlock.h            | 6 ++++--
 2 files changed, 6 insertions(+), 4 deletions(-)
Documentation/userspace-api/landlock.rst +2 -2
index d639c61cb472..ca8b325d53e5 100644
@@ -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.
include/uapi/linux/landlock.h +0 -0
index 33745642f787..048a2c77c4eb 100644

include/uapi/linux/landlock.h struct landlock_net_port_attr { · line 271

Quoted 5 lines
include/uapi/linux/landlock.h +1 -1
@@ -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.

Quoted 22 lines
include/uapi/linux/landlock.h +3 -1
  *
  * 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.
  */
Signature · 1 line
2.48.1.262.g85cc9f2d1e-goog
#12 lore raw

Hey Mickaël!

Quoted 15 lines · Mickaël Salaün
Quoted 8 lines · Günther Noack

* 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 <[email protected]>
Cc Tahera Fahimi <[email protected]>
Cc Tanya Agarwal <[email protected]>

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.

Quoted 6 lines

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

Signature · 1 line
<https://www.alejandro-colomar.es/>
maintainer
#13 lore raw
Quoted 1 line · Alejandro Colomar

Hey Mickaël!

Hey!

Quoted 24 lines · Mickaël Salaün
Quoted 15 lines · Günther Noack
Quoted 8 lines

* 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 <[email protected]>
Cc Tahera Fahimi <[email protected]>
Cc Tanya Agarwal <[email protected]>

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.

Quoted 6 lines

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?

Quoted 6 lines

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?

Quoted 7 lines

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?

Quoted 7 lines

Have a lovely day!
Alex

Signature · 1 line
<https://www.alejandro-colomar.es/>
#14 lore raw

Hi!

Quoted 9 lines · Mickaël Salaün
Quoted 6 lines

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.

Quoted 9 lines

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.

Quoted 9 lines
Quoted 6 lines

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

Signature · 1 line
<https://www.alejandro-colomar.es/>
#15 lore raw
Quoted 6 lines · Alejandro Colomar

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/

#16 lore raw

Hi Branden,

Quoted 8 lines · G. Branden Robinson
Quoted 6 lines · Alejandro Colomar

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.

Quoted 7 lines

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

Signature · 1 line
<https://www.alejandro-colomar.es/>
maintainer
#17 lore raw
In reply to Alejandro Colomar
Quoted 22 lines · Alejandro Colomar

Hi!

Quoted 9 lines · Mickaël Salaün
Quoted 6 lines

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.

Quoted 5 lines

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.

Quoted 8 lines
Quoted 4 lines

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.

Quoted 33 lines

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

Quoted 9 lines
Quoted 6 lines

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.

Quoted 6 lines

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.

Quoted 7 lines

Cheers,
Alex

Signature · 1 line
<https://www.alejandro-colomar.es/>
#18 lore raw

Hi Mickaël,

Quoted 14 lines · Mickaël Salaün
Quoted 14 lines

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.

Quoted 9 lines

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?

Quoted 5 lines
Quoted 3 lines

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 <[email protected]>
	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 <[email protected]>

	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.

Quoted 39 lines
Quoted 32 lines

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

Quoted 9 lines
Quoted 6 lines

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.

Quoted 6 lines

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.

Quoted 3 lines

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

Signature · 1 line
<https://www.alejandro-colomar.es/>
author reviewer
#19 lore raw

Hello!

Quoted 5 lines · Alejandro Colomar

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.

Quoted 7 lines

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

#20 lore raw
Quoted 1 line · Günther Noack

Hello!

Hello!

Quoted 12 lines · Alejandro Colomar
Quoted 11 lines

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.

Quoted 5 lines
Quoted 1 line

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?

Quoted 2 lines

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

Quoted 3 lines

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

Quoted 3 lines

—Günther

Signature · 1 line
<https://www.alejandro-colomar.es/>
author reviewer
#21 lore raw

Hello!

Quoted 13 lines · Alejandro Colomar
Quoted 12 lines · Günther Noack
Quoted 11 lines · Alejandro Colomar

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.

Quoted 7 lines
Quoted 5 lines
Quoted 1 line

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/[email protected]/)

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

—Günther

#22 lore raw

Hello!

Quoted 5 lines · Günther Noack

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/[email protected]/)

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

Quoted 2 lines

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

Signature · 1 line
<https://www.alejandro-colomar.es/>