landlock: Minor typo and grammar fixes in IPC scoping documentation
Subsystems (4)
Günther Noack
reviewerPATCH 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
--- 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
@@ -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
@@ -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
Günther Noack
reviewerPATCH 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.
--- Documentation/userspace-api/landlock.rst | 53 ++++++++++++------------ 1 file changed, 26 insertions(+), 27 deletions(-)
Documentation/userspace-api/landlock.rst +26 -27
@@ -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
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]>Signed-off-by Günther Noack <[email protected]>--- Documentation/userspace-api/landlock.rst | 53 ++++++++++++------------ 1 file changed, 26 insertions(+), 27 deletions(-)Documentation/userspace-api/landlock.rst +4
-27@@ -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 ----------------
Günther Noack
reviewerRe: [PATCH 2/2] landlock: Clarify IPC scoping documentation
In reply to Günther NoackHi!
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]>Signed-off-by Günther Noack <[email protected]>--- Documentation/userspace-api/landlock.rst | 53 ++++++++++++------------ 1 file changed, 26 insertions(+), 27 deletions(-)Documentation/userspace-api/landlock.rst +0
-14@@ -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
Alejandro Colomar
maintainerRe: [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/>
Günther Noack
reviewerRe: [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 doesI 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
Alejandro Colomar
maintainerRe: [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/>
Mickaël Salaün
maintainerRe: [PATCH 2/2] landlock: Clarify IPC scoping documentation
In reply to Günther NoackQuoted 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]>Signed-off-by Günther Noack <[email protected]>--- Documentation/userspace-api/landlock.rst | 53 ++++++++++++------------ 1 file changed, 26 insertions(+), 27 deletions(-)Documentation/userspace-api/landlock.rst +0
-14@@ -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
-0Truncating files ----------------Signature · 1 line
2.48.1.262.g85cc9f2d1e-goog—Günther
Günther Noack
reviewerPATCH 1/3 landlock.7: Update description of Landlock rules
In reply to Günther NoackThis brings it up to date with the wording in the kernel documentation.
--- man/man7/landlock.7 | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-)
man/man7/landlock.7 +16 -4
@@ -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
Günther Noack
reviewerPATCH 2/3 landlock.7: Move over documentation for ABI version 6
In reply to Günther NoackWith this ABI version, Landlock can restrict outgoing interactions with higher-privileged Landlock domains through Abstract Unix Domain sockets and signals.
--- man/man7/landlock.7 | 69 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 68 insertions(+), 1 deletion(-)
man/man7/landlock.7 +68 -1
@@ -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
Günther Noack
reviewerPATCH 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
@@ -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
Mickaël Salaün
maintainerQuoted 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 itCc Mickaël Salaün <[email protected]>Cc Tahera Fahimi <[email protected]>Cc Tanya Agarwal <[email protected]>Signed-off-by Günther Noack <[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@@ -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
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
Alejandro Colomar
maintainerHey 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 itCc Mickaël Salaün <[email protected]>Cc Tahera Fahimi <[email protected]>Cc Tanya Agarwal <[email protected]>Signed-off-by Günther Noack <[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/>
Mickaël Salaün
maintainerQuoted 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 itCc Mickaël Salaün <[email protected]>Cc Tahera Fahimi <[email protected]>Cc Tanya Agarwal <[email protected]>Signed-off-by Günther Noack <[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!
AlexSignature · 1 line
<https://www.alejandro-colomar.es/>
Alejandro Colomar
maintainerHi!
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/>
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/
Alejandro Colomar
maintainerHi 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/>
Mickaël Salaün
maintainerQuoted 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,
AlexSignature · 1 line
<https://www.alejandro-colomar.es/>
Alejandro Colomar
maintainerHi 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:
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/>
Günther Noack
reviewerHello!
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
Alejandro Colomar
maintainerQuoted 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/>
Günther Noack
reviewerHello!
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
Alejandro Colomar
maintainerHello!
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-apifor 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/>