Skip to contentSkip to conversation

landlock*: Bring documentation up to date

PATCH Superseded Günther Noack 3 participants 16 messages Jul 15, 2024 – Jul 19, 2024 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

cover landlock*: Bring documentation up to date

This cleans up a variety of wording issues and small mistakes, and brings the man page documentation up to date with Landlock ABI v4 (networking support) and v5 (IOCTL support).

Günther Noack (5):
landlock.7, landlock_*.2: Wording improvements landlock_create_ruleset.2: Update docs for landlock_ruleset_attr landlock_add_rule.2: Document missing reason for EINVAL landlock.7, landlock_*.2: Document Landlock ABI version 4 landlock.7: Document Landlock ABI version 5 (IOCTL)

 man/man2/landlock_add_rule.2       | 93 ++++++++++++++++++++++++++----
 man/man2/landlock_create_ruleset.2 | 52 ++++++++++++++---
 man/man2/landlock_restrict_self.2  | 11 ++--
 man/man7/landlock.7                | 80 ++++++++++++++++++++++---
 4 files changed, 205 insertions(+), 31 deletions(-)
Signature · 1 line
2.45.2.993.g49e7a77208-goog
#1 lore raw

PATCH 1/5 landlock.7, landlock_*.2: Wording improvements

* Various wording fixes
* List the same error code multiple times,
if it can happen for multiple reasons.

Cc Mickaël Salaün <[email protected]>
---
 man/man2/landlock_add_rule.2       |  9 +++++++--
 man/man2/landlock_create_ruleset.2 |  6 +++---
 man/man2/landlock_restrict_self.2  | 11 ++++++-----
 man/man7/landlock.7                |  6 ++++--
 4 files changed, 20 insertions(+), 12 deletions(-)
man/man2/landlock_add_rule.2 +7 -2
index d4ae8f2f6..fa0b1f109 100644
@@ -60,7 +60,9 @@ struct landlock_path_beneath_attr {
 .in
 .IP
 .I allowed_access
-contains a bitmask of allowed filesystem actions for this file hierarchy
+contains a bitmask of allowed filesystem actions,
+which can be applied on the given
+.I parent_fd
 (see
 .B Filesystem actions
 in
@@ -92,7 +94,10 @@ Landlock is supported by the kernel but disabled at boot time.
 .TP
 .B EINVAL
 .I flags
-is not 0, or the rule accesses are inconsistent (i.e.,
+is not 0.
+.TP
+.B EINVAL
+The rule accesses are inconsistent (i.e.,
 .I rule_attr\->allowed_access
 is not a subset of the ruleset handled accesses).
 .TP
man/man2/landlock_create_ruleset.2 +3 -3
index 618d54f37..871b91dcb 100644
@@ -23,7 +23,8 @@ Standard C library
 A Landlock ruleset identifies a set of rules (i.e., actions on objects).
 This
 .BR landlock_create_ruleset ()
-system call enables creating a new file descriptor identifying a ruleset.
+system call creates a new file descriptor
+which identifies a ruleset.
 This file descriptor can then be used by
 .BR landlock_add_rule (2)
 and
@@ -45,8 +46,7 @@ struct landlock_ruleset_attr {
 .in
 .IP
 .I handled_access_fs
-is a bitmask of actions that is handled by this ruleset and
-should then be forbidden if no rule explicitly allows them
+is a bitmask of handled filesystem actions
 (see
 .B Filesystem actions
 in
man/man2/landlock_restrict_self.2 +6 -5
index d4e5e753c..f044c6b31 100644
@@ -20,7 +20,7 @@ Standard C library
 .SH DESCRIPTION
 Once a Landlock ruleset is populated with the desired rules, the
 .BR landlock_restrict_self ()
-system call enables enforcing this ruleset on the calling thread.
+system call enforces this ruleset on the calling thread.
 See
 .BR landlock (7)
 for a global overview.
@@ -38,10 +38,11 @@ with multiple independent rulesets coming from different sources
 built-in application policy).
 However, most applications should only need one call to
 .BR landlock_restrict_self ()
-and they should avoid arbitrary numbers of such calls because of the
-composed rulesets limit.
-Instead, developers are encouraged to build a tailored ruleset thanks to
-multiple calls to
+and they should avoid arbitrary numbers of such calls
+because of the composed rulesets limit.
+Instead,
+developers are encouraged to build a single tailored ruleset
+with multiple calls to
 .BR landlock_add_rule (2).
 .P
 In order to enforce a ruleset, either the caller must have the
man/man7/landlock.7 +4 -2
index 4a98f6549..f7bb37cba 100644
@@ -58,7 +58,7 @@ and
 .BR landlock_create_ruleset (2)
 for more context.
 .P
-A file can only receive these access rights:
+The following access rights apply only to files:
 .TP
 .B LANDLOCK_ACCESS_FS_EXECUTE
 Execute a file.
@@ -87,6 +87,9 @@ or
 .BR open (2)
 with
 .BR O_TRUNC .
+.IP
+This access right is available since the third version of the Landlock ABI.
+.P
 Whether an opened file can be truncated with
 .BR ftruncate (2)
 is determined during
@@ -97,7 +100,6 @@ using
 .B LANDLOCK_ACCESS_FS_READ_FILE
 and
 .BR LANDLOCK_ACCESS_FS_WRITE_FILE .
-This access right is available since the third version of the Landlock ABI.
 .P
 A directory can receive access rights related to files or directories.
 The following access right is applied to the directory itself,
Signature · 1 line
2.45.2.993.g49e7a77208-goog
#2 lore raw

Re: [PATCH 1/5] landlock.7, landlock_*.2: Wording improvements

Hi Günther,

Quoted 1 line

Subject: Re: [PATCH 1/5] landlock.7, landlock_*.2: Wording improvements

s/Wording improvements/wfix/

Quoted 107 lines · Günther Noack

* Various wording fixes
* List the same error code multiple times,
if it can happen for multiple reasons.

Cc Mickaël Salaün <[email protected]>
---
 man/man2/landlock_add_rule.2       |  9 +++++++--
 man/man2/landlock_create_ruleset.2 |  6 +++---
 man/man2/landlock_restrict_self.2  | 11 ++++++-----
 man/man7/landlock.7                |  6 ++++--
 4 files changed, 20 insertions(+), 12 deletions(-)
man/man2/landlock_add_rule.2 +7 -2
index d4ae8f2f6..fa0b1f109 100644
@@ -60,7 +60,9 @@ struct landlock_path_beneath_attr {
 .in
 .IP
 .I allowed_access
-contains a bitmask of allowed filesystem actions for this file hierarchy
+contains a bitmask of allowed filesystem actions,
+which can be applied on the given
+.I parent_fd
 (see
 .B Filesystem actions
 in
@@ -92,7 +94,10 @@ Landlock is supported by the kernel but disabled at boot time.
 .TP
 .B EINVAL
 .I flags
-is not 0, or the rule accesses are inconsistent (i.e.,
+is not 0.
+.TP
+.B EINVAL
+The rule accesses are inconsistent (i.e.,
 .I rule_attr\->allowed_access
 is not a subset of the ruleset handled accesses).
 .TP
man/man2/landlock_create_ruleset.2 +3 -3
index 618d54f37..871b91dcb 100644
@@ -23,7 +23,8 @@ Standard C library
 A Landlock ruleset identifies a set of rules (i.e., actions on objects).
 This
 .BR landlock_create_ruleset ()
-system call enables creating a new file descriptor identifying a ruleset.
+system call creates a new file descriptor
+which identifies a ruleset.
 This file descriptor can then be used by
 .BR landlock_add_rule (2)
 and
@@ -45,8 +46,7 @@ struct landlock_ruleset_attr {
 .in
 .IP
 .I handled_access_fs
-is a bitmask of actions that is handled by this ruleset and
-should then be forbidden if no rule explicitly allows them
+is a bitmask of handled filesystem actions
 (see
 .B Filesystem actions
 in
man/man2/landlock_restrict_self.2 +6 -5
index d4e5e753c..f044c6b31 100644
@@ -20,7 +20,7 @@ Standard C library
 .SH DESCRIPTION
 Once a Landlock ruleset is populated with the desired rules, the
 .BR landlock_restrict_self ()
-system call enables enforcing this ruleset on the calling thread.
+system call enforces this ruleset on the calling thread.
 See
 .BR landlock (7)
 for a global overview.
@@ -38,10 +38,11 @@ with multiple independent rulesets coming from different sources
 built-in application policy).
 However, most applications should only need one call to
 .BR landlock_restrict_self ()
-and they should avoid arbitrary numbers of such calls because of the
-composed rulesets limit.
-Instead, developers are encouraged to build a tailored ruleset thanks to
-multiple calls to
+and they should avoid arbitrary numbers of such calls
+because of the composed rulesets limit.
+Instead,
+developers are encouraged to build a single tailored ruleset
+with multiple calls to
 .BR landlock_add_rule (2).
 .P
 In order to enforce a ruleset, either the caller must have the
man/man7/landlock.7 +1 -1
index 4a98f6549..f7bb37cba 100644
@@ -58,7 +58,7 @@ and
 .BR landlock_create_ruleset (2)
 for more context.
 .P
-A file can only receive these access rights:
+The following access rights apply only to files:
 .TP
 .B LANDLOCK_ACCESS_FS_EXECUTE
 Execute a file.

man/man7/landlock.7 or · line 92

Quoted 6 lines
man/man7/landlock.7 +3 -0
@@ -87,6 +87,9 @@ or
 .BR open (2)
 with
 .BR O_TRUNC .
+.IP
+This access right is available since the third version of the Landlock ABI.
+.P

Did you really want a P here? Or maybe an IP?

Quoted 13 lines
man/man7/landlock.7 +0 -1
 Whether an opened file can be truncated with
 .BR ftruncate (2)
 is determined during
@@ -97,7 +100,6 @@ using
 .B LANDLOCK_ACCESS_FS_READ_FILE
 and
 .BR LANDLOCK_ACCESS_FS_WRITE_FILE .
-This access right is available since the third version of the Landlock ABI.
 .P
 A directory can receive access rights related to files or directories.
 The following access right is applied to the directory itself,
Signature · 1 line
2.45.2.993.g49e7a77208-goog

Other than that, LGTM.

Cheers,
Alex

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

Re: [PATCH 1/5] landlock.7, landlock_*.2: Wording improvements

Quoted 5 lines · Alejandro Colomar

Hi Günther,

Quoted 1 line

Subject: Re: [PATCH 1/5] landlock.7, landlock_*.2: Wording improvements

s/Wording improvements/wfix/

Done.

Quoted 6 lines · Günther Noack
Quoted 3 lines

+.IP
+This access right is available since the third version of the Landlock ABI. +.P

Did you really want a P here? Or maybe an IP?

Well spotted, thanks! Done.

The de-dentation is only needed once the paragraph talks about both truncate and ioctl operations (patch 5/5). Must have happened when I reshuffled the patch set. In patch 5/5 it becomes .P again.

Quoted 4 lines

Review using

Quoted 4 lines

Whether an opened file can be truncated with
.BR ftruncate (2)
is determined during

(quoted diff) +0 -0
@@ -97,7 +100,6 @@ using

Thanks,
—Günther

#4 lore raw

Re: [PATCH 1/5] landlock.7, landlock_*.2: Wording improvements

Hi Günther,

Quoted 9 lines · Günther Noack
Quoted 5 lines · Alejandro Colomar

Hi Günther,

Quoted 1 line

Subject: Re: [PATCH 1/5] landlock.7, landlock_*.2: Wording improvements

s/Wording improvements/wfix/

Done.

Quoted 8 lines
Quoted 6 lines · Günther Noack
Quoted 3 lines

+.IP
+This access right is available since the third version of the Landlock ABI. +.P

Did you really want a P here? Or maybe an IP?

Well spotted, thanks! Done.

:)

Quoted 4 lines

The de-dentation is only needed once the paragraph talks about both truncate and ioctl operations (patch 5/5). Must have happened when I reshuffled the patch set. In patch 5/5 it becomes .P again.

Would you mind resending, with the minor fixes and the RB tags? Thanks!

Have a lovely day!
Alex

Quoted 9 lines
Quoted 5 lines

Review using

Quoted 5 lines

Whether an opened file can be truncated with
.BR ftruncate (2)
is determined during

(quoted diff) +0 -0
@@ -97,7 +100,6 @@ using

Thanks,
—Günther

Signature · 1 line
<https://www.alejandro-colomar.es/>
Reviewed-by on v1 1/5
#5 lore raw

Re: [PATCH 1/5] landlock.7, landlock_*.2: Wording improvements

In reply to Günther Noack
Quoted 6 lines · Günther Noack

* Various wording fixes
* List the same error code multiple times,
if it can happen for multiple reasons.

Cc Mickaël Salaün <[email protected]>
Quoted 121 lines
---
 man/man2/landlock_add_rule.2       |  9 +++++++--
 man/man2/landlock_create_ruleset.2 |  6 +++---
 man/man2/landlock_restrict_self.2  | 11 ++++++-----
 man/man7/landlock.7                |  6 ++++--
 4 files changed, 20 insertions(+), 12 deletions(-)
man/man2/landlock_add_rule.2 +7 -2
index d4ae8f2f6..fa0b1f109 100644
@@ -60,7 +60,9 @@ struct landlock_path_beneath_attr {
 .in
 .IP
 .I allowed_access
-contains a bitmask of allowed filesystem actions for this file hierarchy
+contains a bitmask of allowed filesystem actions,
+which can be applied on the given
+.I parent_fd
 (see
 .B Filesystem actions
 in
@@ -92,7 +94,10 @@ Landlock is supported by the kernel but disabled at boot time.
 .TP
 .B EINVAL
 .I flags
-is not 0, or the rule accesses are inconsistent (i.e.,
+is not 0.
+.TP
+.B EINVAL
+The rule accesses are inconsistent (i.e.,
 .I rule_attr\->allowed_access
 is not a subset of the ruleset handled accesses).
 .TP
man/man2/landlock_create_ruleset.2 +3 -3
index 618d54f37..871b91dcb 100644
@@ -23,7 +23,8 @@ Standard C library
 A Landlock ruleset identifies a set of rules (i.e., actions on objects).
 This
 .BR landlock_create_ruleset ()
-system call enables creating a new file descriptor identifying a ruleset.
+system call creates a new file descriptor
+which identifies a ruleset.
 This file descriptor can then be used by
 .BR landlock_add_rule (2)
 and
@@ -45,8 +46,7 @@ struct landlock_ruleset_attr {
 .in
 .IP
 .I handled_access_fs
-is a bitmask of actions that is handled by this ruleset and
-should then be forbidden if no rule explicitly allows them
+is a bitmask of handled filesystem actions
 (see
 .B Filesystem actions
 in
man/man2/landlock_restrict_self.2 +6 -5
index d4e5e753c..f044c6b31 100644
@@ -20,7 +20,7 @@ Standard C library
 .SH DESCRIPTION
 Once a Landlock ruleset is populated with the desired rules, the
 .BR landlock_restrict_self ()
-system call enables enforcing this ruleset on the calling thread.
+system call enforces this ruleset on the calling thread.
 See
 .BR landlock (7)
 for a global overview.
@@ -38,10 +38,11 @@ with multiple independent rulesets coming from different sources
 built-in application policy).
 However, most applications should only need one call to
 .BR landlock_restrict_self ()
-and they should avoid arbitrary numbers of such calls because of the
-composed rulesets limit.
-Instead, developers are encouraged to build a tailored ruleset thanks to
-multiple calls to
+and they should avoid arbitrary numbers of such calls
+because of the composed rulesets limit.
+Instead,
+developers are encouraged to build a single tailored ruleset
+with multiple calls to
 .BR landlock_add_rule (2).
 .P
 In order to enforce a ruleset, either the caller must have the
man/man7/landlock.7 +4 -2
index 4a98f6549..f7bb37cba 100644
@@ -58,7 +58,7 @@ and
 .BR landlock_create_ruleset (2)
 for more context.
 .P
-A file can only receive these access rights:
+The following access rights apply only to files:
 .TP
 .B LANDLOCK_ACCESS_FS_EXECUTE
 Execute a file.
@@ -87,6 +87,9 @@ or
 .BR open (2)
 with
 .BR O_TRUNC .
+.IP
+This access right is available since the third version of the Landlock ABI.
+.P
 Whether an opened file can be truncated with
 .BR ftruncate (2)
 is determined during
@@ -97,7 +100,6 @@ using
 .B LANDLOCK_ACCESS_FS_READ_FILE
 and
 .BR LANDLOCK_ACCESS_FS_WRITE_FILE .
-This access right is available since the third version of the Landlock ABI.
 .P
 A directory can receive access rights related to files or directories.
 The following access right is applied to the directory itself,
Signature · 1 line
2.45.2.993.g49e7a77208-goog
#6 lore raw

PATCH 2/5 landlock_create_ruleset.2: Update docs for landlock_ruleset_attr

In reply to Günther Noack

This updates the documentation for struct landlock_ruleset_attr in line with the changed kernel documentation (see link below).

---
 man/man2/landlock_create_ruleset.2 | 34 ++++++++++++++++++++++++++++--
 1 file changed, 32 insertions(+), 2 deletions(-)
man/man2/landlock_create_ruleset.2 +32 -2
index 871b91dcb..105e9b062 100644
@@ -51,8 +51,38 @@ is a bitmask of handled filesystem actions
 .B Filesystem actions
 in
 .BR landlock (7)).
-This enables simply restricting ambient rights
-(e.g., global filesystem access) and is needed for compatibility reasons.
+.IP
+This structure defines a set of
+.IR "handled access rights" ,
+a set of actions on different object types,
+which should be denied by default
+when the ruleset is enacted.
+Vice versa,
+access rights that are not specifically listed here
+are not going to be denied by this ruleset when it is enacted.
+.IP
+For historical reasons, the
+.B LANDLOCK_ACCESS_FS_REFER
+right is always denied by default,
+even when its bit is not set in
+.IR handled_access_fs .
+In order to add new rules with this access right,
+the bit must still be set explicitly
+(see
+.B Filesystem actions
+in
+.BR landlock (7)).
+.IP
+The explicit listing of
+.I handled access rights
+is required for backwards compatibility reasons.
+In most use cases,
+processes that use Landlock will
+.I handle
+a wide range or all access rights that they know about at build time
+(and that they have tested with a kernel that supported them all).
+.IP
+This structure can grow in future Landlock versions.
 .P
 .I size
 must be specified as
Signature · 1 line
2.45.2.993.g49e7a77208-goog
Reviewed-by on v1 2/5
#7 lore raw

Re: [PATCH 2/5] landlock_create_ruleset.2: Update docs for landlock_ruleset_attr

Quoted 7 lines · Günther Noack

This updates the documentation for struct landlock_ruleset_attr in line with the changed kernel documentation (see link below).

Quoted 52 lines
---
 man/man2/landlock_create_ruleset.2 | 34 ++++++++++++++++++++++++++++--
 1 file changed, 32 insertions(+), 2 deletions(-)
man/man2/landlock_create_ruleset.2 +32 -2
index 871b91dcb..105e9b062 100644
@@ -51,8 +51,38 @@ is a bitmask of handled filesystem actions
 .B Filesystem actions
 in
 .BR landlock (7)).
-This enables simply restricting ambient rights
-(e.g., global filesystem access) and is needed for compatibility reasons.
+.IP
+This structure defines a set of
+.IR "handled access rights" ,
+a set of actions on different object types,
+which should be denied by default
+when the ruleset is enacted.
+Vice versa,
+access rights that are not specifically listed here
+are not going to be denied by this ruleset when it is enacted.
+.IP
+For historical reasons, the
+.B LANDLOCK_ACCESS_FS_REFER
+right is always denied by default,
+even when its bit is not set in
+.IR handled_access_fs .
+In order to add new rules with this access right,
+the bit must still be set explicitly
+(see
+.B Filesystem actions
+in
+.BR landlock (7)).
+.IP
+The explicit listing of
+.I handled access rights
+is required for backwards compatibility reasons.
+In most use cases,
+processes that use Landlock will
+.I handle
+a wide range or all access rights that they know about at build time
+(and that they have tested with a kernel that supported them all).
+.IP
+This structure can grow in future Landlock versions.
 .P
 .I size
 must be specified as
Signature · 1 line
2.45.2.993.g49e7a77208-goog
#8 lore raw

PATCH 3/5 landlock_add_rule.2: Document missing reason for EINVAL

In reply to Günther Noack

This documents a missing reason for why EINVAL might be returned. The documented behavior exists since the first version of Landlock.

Cc Mickaël Salaün <[email protected]>
---
 man/man2/landlock_add_rule.2 | 10 ++++++++++
 1 file changed, 10 insertions(+)
man/man2/landlock_add_rule.2 +10 -0
index fa0b1f109..530b45947 100644
@@ -101,6 +101,16 @@ The rule accesses are inconsistent (i.e.,
 .I rule_attr\->allowed_access
 is not a subset of the ruleset handled accesses).
 .TP
+.B EINVAL
+In
+.IR "struct landlock_path_beneath_attr" ,
+the rule accesses are not applicable to the file
+(i.e., some access rights in
+.I rule_attr\->allowed_access
+are only applicable to directories, but
+.I rule_attr\->parent_fd
+does not refer to a directory).
+.TP
 .B ENOMSG
 Empty accesses (i.e.,
 .I rule_attr\->allowed_access
Signature · 1 line
2.45.2.993.g49e7a77208-goog
Reviewed-by on v1 3/5
#9 lore raw

Re: [PATCH 3/5] landlock_add_rule.2: Document missing reason for EINVAL

Quoted 5 lines · Günther Noack

This documents a missing reason for why EINVAL might be returned. The documented behavior exists since the first version of Landlock.

Cc Mickaël Salaün <[email protected]>
Quoted 28 lines
---
 man/man2/landlock_add_rule.2 | 10 ++++++++++
 1 file changed, 10 insertions(+)
man/man2/landlock_add_rule.2 +10 -0
index fa0b1f109..530b45947 100644
@@ -101,6 +101,16 @@ The rule accesses are inconsistent (i.e.,
 .I rule_attr\->allowed_access
 is not a subset of the ruleset handled accesses).
 .TP
+.B EINVAL
+In
+.IR "struct landlock_path_beneath_attr" ,
+the rule accesses are not applicable to the file
+(i.e., some access rights in
+.I rule_attr\->allowed_access
+are only applicable to directories, but
+.I rule_attr\->parent_fd
+does not refer to a directory).
+.TP
 .B ENOMSG
 Empty accesses (i.e.,
 .I rule_attr\->allowed_access
Signature · 1 line
2.45.2.993.g49e7a77208-goog
#10 lore raw

PATCH 4/5 landlock.7, landlock_*.2: Document Landlock ABI version 4

In reply to Günther Noack

Landlock ABI 4 restricts bind(2) and connect(2) on TCP port numbers.

The intent is to bring the man pages mostly in line with the kernel documentation again. I intentionally did not add networking support to the usage example in landlock.7 - I feel that in the long run, we would be better advised to maintain longer example code in the kernel samples.

---
 man/man2/landlock_add_rule.2       | 74 ++++++++++++++++++++++++++----
 man/man2/landlock_create_ruleset.2 | 12 ++++-
 man/man7/landlock.7                | 23 ++++++++--
 3 files changed, 94 insertions(+), 15 deletions(-)
man/man2/landlock_add_rule.2 +64 -10
index 530b45947..a0ab13419 100644
@@ -20,15 +20,14 @@ Standard C library
 .BI "            const void *" rule_attr ", uint32_t " flags );
 .fi
 .SH DESCRIPTION
-A Landlock rule describes an action on an object.
-An object is currently a file hierarchy,
-and the related filesystem actions
-are defined with a set of access rights.
-This
+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
 .BR landlock_add_rule ()
-system call enables adding a new Landlock rule to an existing ruleset
-created with
-.BR landlock_create_ruleset (2).
+system call adds a new Landlock rule to an existing ruleset.
 See
 .BR landlock (7)
 for a global overview.
@@ -42,10 +41,15 @@ identifies the structure type pointed to by
 .IR rule_attr .
 Currently, Linux supports the following
 .I rule_type
-value:
+values:
 .TP
 .B LANDLOCK_RULE_PATH_BENEATH
-This defines the object type as a file hierarchy.
+For these rules,
+the object is a file hierarchy,
+and the related filesystem actions
+are defined with
+.IR "filesystem access rights" .
+.IP
 In this case,
 .I rule_attr
 points to the following structure:
@@ -74,6 +78,45 @@ is an opened file descriptor, preferably with the
 flag,
 which identifies the parent directory of the file hierarchy or
 just a file.
+.TP
+.B LANDLOCK_RULE_NET_PORT
+For these rules,
+the object is a TCP port,
+and the related actions are defined with
+.IR "network access rights" .
+.IP
+In this case,
+.I rule_attr
+points to the following structure:
+.IP
+.in +4n
+.EX
+struct landlock_net_port_attr {
+    __u64 allowed_access;
+    __u64 port;
+};
+.EE
+.in
+.IP
+.i allowed_access
+contains a bitmask of allowed network actions,
+which can be applied on the given port.
+.IP
+.i port
+is the network port in host endianness.
+.IP
+It should be noted that port 0 passed to
+.BR bind (2)
+will bind to an available port from the ephemeral port range.
+This can be configured in the
+.I /proc/sys/net/ipv4/ip_local_port_range
+sysctl (also used for IPv6).
+.IP
+A Landlock rule with port 0
+and the
+.B LANDLOCK_ACCESS_NET_BIND_TCP
+right means that requesting to bind on port 0 is allowed
+and it will automatically translate to binding on the related port range.
 .P
 .I flags
 must be 0.
@@ -89,6 +132,12 @@ is set to indicate the error.
 .BR landlock_add_rule ()
 can fail for the following reasons:
 .TP
+.B EAFNOSUPPORT
+.I rule_type
+is
+.BR LANDLOCK_RULE_NET_PORT ,
+but TCP is not supported by the running kernel.
+.TP
 .B EOPNOTSUPP
 Landlock is supported by the kernel but disabled at boot time.
 .TP
@@ -111,6 +160,11 @@ are only applicable to directories, but
 .I rule_attr\->parent_fd
 does not refer to a directory).
 .TP
+.B EINVAL
+In
+.IR "struct landlock_net_port_attr" ,
+the port number is greater than 65535.
+.TP
 .B ENOMSG
 Empty accesses (i.e.,
 .I rule_attr\->allowed_access
man/man2/landlock_create_ruleset.2 +10 -2
index 105e9b062..ca635ddbc 100644
@@ -41,6 +41,7 @@ It points to the following structure:
 .EX
 struct landlock_ruleset_attr {
     __u64 handled_access_fs;
+    __u64 handled_access_net;
 };
 .EE
 .in
@@ -52,6 +53,13 @@ is a bitmask of handled filesystem actions
 in
 .BR landlock (7)).
 .IP
+.I handled_access_net
+is a bitmask of handled network actions
+(see
+.B Network actions
+in
+.BR landlock (7)).
+.IP
 This structure defines a set of
 .IR "handled access rights" ,
 a set of actions on different object types,
@@ -143,8 +151,8 @@ was not a valid address.
 .TP
 .B ENOMSG
 Empty accesses (i.e.,
-.I attr\->handled_access_fs
-is 0).
+.I attr
+did not specify any access rights to restrict).
 .SH STANDARDS
 Linux.
 .SH HISTORY
man/man7/landlock.7 +20 -3
index f7bb37cba..d452b93b2 100644
@@ -189,6 +189,19 @@ If multiple requirements are not met, the
 error code takes precedence over
 .BR EXDEV .
 .\"
+.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
+The following access rights apply to TCP port numbers:
+.TP
+.B LANDLOCK_ACCESS_NET_BIND_TCP
+Bind a TCP socket to a local port.
+.TP
+.B LANDLOCK_ACCESS_NET_CONNECT_TCP
+Connect an active TCP socket to a remote port.
+.\"
 .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.
@@ -339,6 +352,9 @@ _	_	_
 2	5.19	LANDLOCK_ACCESS_FS_REFER
 _	_	_
 3	6.2	LANDLOCK_ACCESS_FS_TRUNCATE
+_	_	_
+4	6.7	LANDLOCK_ACCESS_NET_BIND_TCP
+\^	\^	LANDLOCK_ACCESS_NET_CONNECT_TCP
 .TE
 .P
 Users should use the Landlock ABI version rather than the kernel version
@@ -439,9 +455,10 @@ and only use the available subset of access rights:
  * numbers hardcoded to keep the example short.
  */
 __u64 landlock_fs_access_rights[] = {
-    (LANDLOCK_ACCESS_FS_MAKE_SYM << 1) \- 1,  /* v1                 */
-    (LANDLOCK_ACCESS_FS_REFER    << 1) \- 1,  /* v2: add "refer"    */
-    (LANDLOCK_ACCESS_FS_TRUNCATE << 1) \- 1,  /* v3: add "truncate" */
+    (LANDLOCK_ACCESS_FS_MAKE_SYM  << 1) \- 1,  /* v1                  */
+    (LANDLOCK_ACCESS_FS_REFER     << 1) \- 1,  /* v2: add "refer"     */
+    (LANDLOCK_ACCESS_FS_TRUNCATE  << 1) \- 1,  /* v3: add "truncate"  */
+    (LANDLOCK_ACCESS_FS_TRUNCATE  << 1) \- 1,  /* v4: TCP support     */
 };
 \&
 int abi = landlock_create_ruleset(NULL, 0,
Signature · 1 line
2.45.2.993.g49e7a77208-goog
Reviewed-by on v1 4/5
#11 lore raw

Re: [PATCH 4/5] landlock.7, landlock_*.2: Document Landlock ABI version 4

Quoted 8 lines · Günther Noack

Landlock ABI 4 restricts bind(2) and connect(2) on TCP port numbers.

The intent is to bring the man pages mostly in line with the kernel documentation again. I intentionally did not add networking support to the usage example in landlock.7 - I feel that in the long run, we would be better advised to maintain longer example code in the kernel samples.

In this case, we should use "Closes" instead of "Link".

Quoted 2 lines
Cc Konstantin Meskhidze <[email protected]>

Thanks!

Quoted 210 lines
---
 man/man2/landlock_add_rule.2       | 74 ++++++++++++++++++++++++++----
 man/man2/landlock_create_ruleset.2 | 12 ++++-
 man/man7/landlock.7                | 23 ++++++++--
 3 files changed, 94 insertions(+), 15 deletions(-)
man/man2/landlock_add_rule.2 +64 -10
index 530b45947..a0ab13419 100644
@@ -20,15 +20,14 @@ Standard C library
 .BI "            const void *" rule_attr ", uint32_t " flags );
 .fi
 .SH DESCRIPTION
-A Landlock rule describes an action on an object.
-An object is currently a file hierarchy,
-and the related filesystem actions
-are defined with a set of access rights.
-This
+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
 .BR landlock_add_rule ()
-system call enables adding a new Landlock rule to an existing ruleset
-created with
-.BR landlock_create_ruleset (2).
+system call adds a new Landlock rule to an existing ruleset.
 See
 .BR landlock (7)
 for a global overview.
@@ -42,10 +41,15 @@ identifies the structure type pointed to by
 .IR rule_attr .
 Currently, Linux supports the following
 .I rule_type
-value:
+values:
 .TP
 .B LANDLOCK_RULE_PATH_BENEATH
-This defines the object type as a file hierarchy.
+For these rules,
+the object is a file hierarchy,
+and the related filesystem actions
+are defined with
+.IR "filesystem access rights" .
+.IP
 In this case,
 .I rule_attr
 points to the following structure:
@@ -74,6 +78,45 @@ is an opened file descriptor, preferably with the
 flag,
 which identifies the parent directory of the file hierarchy or
 just a file.
+.TP
+.B LANDLOCK_RULE_NET_PORT
+For these rules,
+the object is a TCP port,
+and the related actions are defined with
+.IR "network access rights" .
+.IP
+In this case,
+.I rule_attr
+points to the following structure:
+.IP
+.in +4n
+.EX
+struct landlock_net_port_attr {
+    __u64 allowed_access;
+    __u64 port;
+};
+.EE
+.in
+.IP
+.i allowed_access
+contains a bitmask of allowed network actions,
+which can be applied on the given port.
+.IP
+.i port
+is the network port in host endianness.
+.IP
+It should be noted that port 0 passed to
+.BR bind (2)
+will bind to an available port from the ephemeral port range.
+This can be configured in the
+.I /proc/sys/net/ipv4/ip_local_port_range
+sysctl (also used for IPv6).
+.IP
+A Landlock rule with port 0
+and the
+.B LANDLOCK_ACCESS_NET_BIND_TCP
+right means that requesting to bind on port 0 is allowed
+and it will automatically translate to binding on the related port range.
 .P
 .I flags
 must be 0.
@@ -89,6 +132,12 @@ is set to indicate the error.
 .BR landlock_add_rule ()
 can fail for the following reasons:
 .TP
+.B EAFNOSUPPORT
+.I rule_type
+is
+.BR LANDLOCK_RULE_NET_PORT ,
+but TCP is not supported by the running kernel.
+.TP
 .B EOPNOTSUPP
 Landlock is supported by the kernel but disabled at boot time.
 .TP
@@ -111,6 +160,11 @@ are only applicable to directories, but
 .I rule_attr\->parent_fd
 does not refer to a directory).
 .TP
+.B EINVAL
+In
+.IR "struct landlock_net_port_attr" ,
+the port number is greater than 65535.
+.TP
 .B ENOMSG
 Empty accesses (i.e.,
 .I rule_attr\->allowed_access
man/man2/landlock_create_ruleset.2 +10 -2
index 105e9b062..ca635ddbc 100644
@@ -41,6 +41,7 @@ It points to the following structure:
 .EX
 struct landlock_ruleset_attr {
     __u64 handled_access_fs;
+    __u64 handled_access_net;
 };
 .EE
 .in
@@ -52,6 +53,13 @@ is a bitmask of handled filesystem actions
 in
 .BR landlock (7)).
 .IP
+.I handled_access_net
+is a bitmask of handled network actions
+(see
+.B Network actions
+in
+.BR landlock (7)).
+.IP
 This structure defines a set of
 .IR "handled access rights" ,
 a set of actions on different object types,
@@ -143,8 +151,8 @@ was not a valid address.
 .TP
 .B ENOMSG
 Empty accesses (i.e.,
-.I attr\->handled_access_fs
-is 0).
+.I attr
+did not specify any access rights to restrict).
 .SH STANDARDS
 Linux.
 .SH HISTORY
man/man7/landlock.7 +20 -3
index f7bb37cba..d452b93b2 100644
@@ -189,6 +189,19 @@ If multiple requirements are not met, the
 error code takes precedence over
 .BR EXDEV .
 .\"
+.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
+The following access rights apply to TCP port numbers:
+.TP
+.B LANDLOCK_ACCESS_NET_BIND_TCP
+Bind a TCP socket to a local port.
+.TP
+.B LANDLOCK_ACCESS_NET_CONNECT_TCP
+Connect an active TCP socket to a remote port.
+.\"
 .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.
@@ -339,6 +352,9 @@ _	_	_
 2	5.19	LANDLOCK_ACCESS_FS_REFER
 _	_	_
 3	6.2	LANDLOCK_ACCESS_FS_TRUNCATE
+_	_	_
+4	6.7	LANDLOCK_ACCESS_NET_BIND_TCP
+\^	\^	LANDLOCK_ACCESS_NET_CONNECT_TCP
 .TE
 .P
 Users should use the Landlock ABI version rather than the kernel version
@@ -439,9 +455,10 @@ and only use the available subset of access rights:
  * numbers hardcoded to keep the example short.
  */
 __u64 landlock_fs_access_rights[] = {
-    (LANDLOCK_ACCESS_FS_MAKE_SYM << 1) \- 1,  /* v1                 */
-    (LANDLOCK_ACCESS_FS_REFER    << 1) \- 1,  /* v2: add "refer"    */
-    (LANDLOCK_ACCESS_FS_TRUNCATE << 1) \- 1,  /* v3: add "truncate" */
+    (LANDLOCK_ACCESS_FS_MAKE_SYM  << 1) \- 1,  /* v1                  */
+    (LANDLOCK_ACCESS_FS_REFER     << 1) \- 1,  /* v2: add "refer"     */
+    (LANDLOCK_ACCESS_FS_TRUNCATE  << 1) \- 1,  /* v3: add "truncate"  */
+    (LANDLOCK_ACCESS_FS_TRUNCATE  << 1) \- 1,  /* v4: TCP support     */
 };
 \&
 int abi = landlock_create_ruleset(NULL, 0,
Signature · 1 line
2.45.2.993.g49e7a77208-goog
#12 lore raw

PATCH 5/5 landlock.7: Document Landlock ABI version 5 (IOCTL)

In reply to Günther Noack

Landlock ABI 5 restricts ioctl(2) on device files.

---
 man/man7/landlock.7 | 51 +++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 49 insertions(+), 2 deletions(-)
man/man7/landlock.7 +49 -2
index d452b93b2..044f57208 100644
@@ -92,6 +92,8 @@ This access right is available since the third version of the Landlock ABI.
 .P
 Whether an opened file can be truncated with
 .BR ftruncate (2)
+or used with
+.BR ioctl (2)
 is determined during
 .BR open (2),
 in the same way as read and write permissions are checked during
@@ -188,6 +190,48 @@ If multiple requirements are not met, the
 .B EACCES
 error code takes precedence over
 .BR EXDEV .
+.P
+The following access right
+applies to both files and directories:
+.TP
+.B LANDLOCK_ACCESS_FS_IOCTL_DEV
+Invoke
+.BR ioctl (2)
+commands on an opened character or block device.
+.IP
+This access right applies to all
+.BR ioctl (2)
+commands implemented by device drivers.
+However, the following common IOCTL commands continue to be invokable
+independent of the
+.B LANDLOCK_ACCESS_FS_IOCTL_DEV
+right:
+.RS
+.IP \[bu] 3
+IOCTL commands targeting file descriptors
+.RB ( FIOCLEX ,
+.BR FIONCLEX ),
+.IP \[bu]
+IOCTL commands targeting file descriptions
+.RB ( FIONBIO ,
+.BR FIOASYNC ),
+.IP \[bu]
+IOCTL commands targeting file systems
+.RB ( FIFREEZE ,
+.BR FITHAW ,
+.BR FIGETBSZ ,
+.BR FS_IOC_GETFSUUID ,
+.BR FS_IOC_GETFSSYSFSPATH )
+.IP \[bu]
+Some IOCTL commands which do not make sense when used with devices, but
+whose implementations are safe and return the right error codes
+.RB ( FS_IOC_FIEMAP ,
+.BR FICLONE ,
+.BR FICLONERANGE ,
+.BR FIDEDUPERANGE )
+.RE
+.IP
+This access right is available since the fifth version of the Landlock ABI.
 .\"
 .SS Network flags
 These flags enable to restrict a sandboxed process
@@ -355,6 +399,8 @@ _	_	_
 _	_	_
 4	6.7	LANDLOCK_ACCESS_NET_BIND_TCP
 \^	\^	LANDLOCK_ACCESS_NET_CONNECT_TCP
+_	_	_
+5	6.10	LANDLOCK_ACCESS_FS_IOCTL_DEV
 .TE
 .P
 Users should use the Landlock ABI version rather than the kernel version
@@ -405,7 +451,6 @@ accessible through these system call families:
 .BR chown (2),
 .BR setxattr (2),
 .BR utime (2),
-.BR ioctl (2),
 .BR fcntl (2),
 .BR access (2).
 Future Landlock evolutions will enable to restrict them.
@@ -440,7 +485,8 @@ attr.handled_access_fs =
         LANDLOCK_ACCESS_FS_MAKE_BLOCK |
         LANDLOCK_ACCESS_FS_MAKE_SYM |
         LANDLOCK_ACCESS_FS_REFER |
-        LANDLOCK_ACCESS_FS_TRUNCATE;
+        LANDLOCK_ACCESS_FS_TRUNCATE |;
+        LANDLOCK_ACCESS_FS_IOCTL_DEV;
 .EE
 .in
 .P
@@ -459,6 +505,7 @@ __u64 landlock_fs_access_rights[] = {
     (LANDLOCK_ACCESS_FS_REFER     << 1) \- 1,  /* v2: add "refer"     */
     (LANDLOCK_ACCESS_FS_TRUNCATE  << 1) \- 1,  /* v3: add "truncate"  */
     (LANDLOCK_ACCESS_FS_TRUNCATE  << 1) \- 1,  /* v4: TCP support     */
+    (LANDLOCK_ACCESS_FS_IOCTL_DEV << 1) \- 1,  /* v5: add "ioctl_dev" */
 };
 \&
 int abi = landlock_create_ruleset(NULL, 0,
Signature · 1 line
2.45.2.993.g49e7a77208-goog
#13 lore raw

Re: [PATCH 5/5] landlock.7: Document Landlock ABI version 5 (IOCTL)

Hi Günther,

Quoted 29 lines · Günther Noack

Landlock ABI 5 restricts ioctl(2) on device files.

---
 man/man7/landlock.7 | 51 +++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 49 insertions(+), 2 deletions(-)
man/man7/landlock.7 +5 -0
index d452b93b2..044f57208 100644
@@ -92,6 +92,8 @@ This access right is available since the third version of the Landlock ABI.
 .P
 Whether an opened file can be truncated with
 .BR ftruncate (2)
+or used with
+.BR ioctl (2)
 is determined during
 .BR open (2),
 in the same way as read and write permissions are checked during
@@ -188,6 +190,48 @@ If multiple requirements are not met, the
 .B EACCES
 error code takes precedence over
 .BR EXDEV .
+.P
+The following access right
+applies to both files and directories:

man/man7/landlock.7 If multiple requirements are not met, the · line 205

Quoted 10 lines
man/man7/landlock.7 +10 -0
+.TP
+.B LANDLOCK_ACCESS_FS_IOCTL_DEV
+Invoke
+.BR ioctl (2)
+commands on an opened character or block device.
+.IP
+This access right applies to all
+.BR ioctl (2)
+commands implemented by device drivers.
+However, the following common IOCTL commands continue to be invokable

Maybe s/IOCTL/ioctl(2)/ ?

Quoted 50 lines
man/man7/landlock.7 +31 -1
+independent of the
+.B LANDLOCK_ACCESS_FS_IOCTL_DEV
+right:
+.RS
+.IP \[bu] 3
+IOCTL commands targeting file descriptors
+.RB ( FIOCLEX ,
+.BR FIONCLEX ),
+.IP \[bu]
+IOCTL commands targeting file descriptions
+.RB ( FIONBIO ,
+.BR FIOASYNC ),
+.IP \[bu]
+IOCTL commands targeting file systems
+.RB ( FIFREEZE ,
+.BR FITHAW ,
+.BR FIGETBSZ ,
+.BR FS_IOC_GETFSUUID ,
+.BR FS_IOC_GETFSSYSFSPATH )
+.IP \[bu]
+Some IOCTL commands which do not make sense when used with devices, but
+whose implementations are safe and return the right error codes
+.RB ( FS_IOC_FIEMAP ,
+.BR FICLONE ,
+.BR FICLONERANGE ,
+.BR FIDEDUPERANGE )
+.RE
+.IP
+This access right is available since the fifth version of the Landlock ABI.
 .\"
 .SS Network flags
 These flags enable to restrict a sandboxed process
@@ -355,6 +399,8 @@ _	_	_
 _	_	_
 4	6.7	LANDLOCK_ACCESS_NET_BIND_TCP
 \^	\^	LANDLOCK_ACCESS_NET_CONNECT_TCP
+_	_	_
+5	6.10	LANDLOCK_ACCESS_FS_IOCTL_DEV
 .TE
 .P
 Users should use the Landlock ABI version rather than the kernel version
@@ -405,7 +451,6 @@ accessible through these system call families:
 .BR chown (2),
 .BR setxattr (2),
 .BR utime (2),
-.BR ioctl (2),
 .BR fcntl (2),
 .BR access (2).
 Future Landlock evolutions will enable to restrict them.

man/man7/landlock.7 attr.handled_access_fs = · line 488

Quoted 5 lines
man/man7/landlock.7 +1 -1
@@ -440,7 +485,8 @@ attr.handled_access_fs =
         LANDLOCK_ACCESS_FS_MAKE_BLOCK |
         LANDLOCK_ACCESS_FS_MAKE_SYM |
         LANDLOCK_ACCESS_FS_REFER |
-        LANDLOCK_ACCESS_FS_TRUNCATE;
+        LANDLOCK_ACCESS_FS_TRUNCATE |;

s/;//

right?

Quoted 16 lines
man/man7/landlock.7 +2 -0
+        LANDLOCK_ACCESS_FS_IOCTL_DEV;
 .EE
 .in
 .P
@@ -459,6 +505,7 @@ __u64 landlock_fs_access_rights[] = {
     (LANDLOCK_ACCESS_FS_REFER     << 1) \- 1,  /* v2: add "refer"     */
     (LANDLOCK_ACCESS_FS_TRUNCATE  << 1) \- 1,  /* v3: add "truncate"  */
     (LANDLOCK_ACCESS_FS_TRUNCATE  << 1) \- 1,  /* v4: TCP support     */
+    (LANDLOCK_ACCESS_FS_IOCTL_DEV << 1) \- 1,  /* v5: add "ioctl_dev" */
 };
 \&
 int abi = landlock_create_ruleset(NULL, 0,
Signature · 1 line
2.45.2.993.g49e7a77208-goog

Have a lovely day!
Alex

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

Re: [PATCH 5/5] landlock.7: Document Landlock ABI version 5 (IOCTL)

Quoted 6 lines · Alejandro Colomar

Hi Günther,

Quoted 3 lines · Günther Noack

Landlock ABI 5 restricts ioctl(2) on device files.

s/Link:/Closes:/

Quoted 2 lines
Quoted 2 lines
Cc Mickaël Salaün <[email protected]>
Quoted 28 lines
Quoted 28 lines
---
 man/man7/landlock.7 | 51 +++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 49 insertions(+), 2 deletions(-)
man/man7/landlock.7 +9 -0
index d452b93b2..044f57208 100644
@@ -92,6 +92,8 @@ This access right is available since the third version of the Landlock ABI.
 .P
 Whether an opened file can be truncated with
 .BR ftruncate (2)
+or used with
+.BR ioctl (2)
 is determined during
 .BR open (2),
 in the same way as read and write permissions are checked during
@@ -188,6 +190,48 @@ If multiple requirements are not met, the
 .B EACCES
 error code takes precedence over
 .BR EXDEV .
+.P
+The following access right
+applies to both files and directories:
+.TP
+.B LANDLOCK_ACCESS_FS_IOCTL_DEV
+Invoke
+.BR ioctl (2)
Quoted 8 lines

man/man7/landlock.7 If multiple requirements are not met, the · line 205

Quoted 6 lines
man/man7/landlock.7 +6 -0
+commands on an opened character or block device.
+.IP
+This access right applies to all
+.BR ioctl (2)
+commands implemented by device drivers.
+However, the following common IOCTL commands continue to be invokable

Maybe s/IOCTL/ioctl(2)/ ?

ioctl(2) is already used in the previous sentence, so it might be too much?

Quoted 59 lines
Quoted 51 lines
man/man7/landlock.7 +31 -1
+independent of the
+.B LANDLOCK_ACCESS_FS_IOCTL_DEV
+right:
+.RS
+.IP \[bu] 3
+IOCTL commands targeting file descriptors
+.RB ( FIOCLEX ,
+.BR FIONCLEX ),
+.IP \[bu]
+IOCTL commands targeting file descriptions
+.RB ( FIONBIO ,
+.BR FIOASYNC ),
+.IP \[bu]
+IOCTL commands targeting file systems
+.RB ( FIFREEZE ,
+.BR FITHAW ,
+.BR FIGETBSZ ,
+.BR FS_IOC_GETFSUUID ,
+.BR FS_IOC_GETFSSYSFSPATH )
+.IP \[bu]
+Some IOCTL commands which do not make sense when used with devices, but
+whose implementations are safe and return the right error codes
+.RB ( FS_IOC_FIEMAP ,
+.BR FICLONE ,
+.BR FICLONERANGE ,
+.BR FIDEDUPERANGE )
+.RE
+.IP
+This access right is available since the fifth version of the Landlock ABI.
 .\"
 .SS Network flags
 These flags enable to restrict a sandboxed process
@@ -355,6 +399,8 @@ _	_	_
 _	_	_
 4	6.7	LANDLOCK_ACCESS_NET_BIND_TCP
 \^	\^	LANDLOCK_ACCESS_NET_CONNECT_TCP
+_	_	_
+5	6.10	LANDLOCK_ACCESS_FS_IOCTL_DEV
 .TE
 .P
 Users should use the Landlock ABI version rather than the kernel version
@@ -405,7 +451,6 @@ accessible through these system call families:
 .BR chown (2),
 .BR setxattr (2),
 .BR utime (2),
-.BR ioctl (2),
 .BR fcntl (2),
 .BR access (2).
 Future Landlock evolutions will enable to restrict them.

man/man7/landlock.7 attr.handled_access_fs = · line 488

Quoted 5 lines
man/man7/landlock.7 +1 -1
@@ -440,7 +485,8 @@ attr.handled_access_fs =
         LANDLOCK_ACCESS_FS_MAKE_BLOCK |
         LANDLOCK_ACCESS_FS_MAKE_SYM |
         LANDLOCK_ACCESS_FS_REFER |
-        LANDLOCK_ACCESS_FS_TRUNCATE;
+        LANDLOCK_ACCESS_FS_TRUNCATE |;

s/;//

Quoted 1 line

right?

Correct

Quoted 23 lines
Quoted 17 lines
man/man7/landlock.7 +2 -0
+        LANDLOCK_ACCESS_FS_IOCTL_DEV;
 .EE
 .in
 .P
@@ -459,6 +505,7 @@ __u64 landlock_fs_access_rights[] = {
     (LANDLOCK_ACCESS_FS_REFER     << 1) \- 1,  /* v2: add "refer"     */
     (LANDLOCK_ACCESS_FS_TRUNCATE  << 1) \- 1,  /* v3: add "truncate"  */
     (LANDLOCK_ACCESS_FS_TRUNCATE  << 1) \- 1,  /* v4: TCP support     */
+    (LANDLOCK_ACCESS_FS_IOCTL_DEV << 1) \- 1,  /* v5: add "ioctl_dev" */
 };
 \&
 int abi = landlock_create_ruleset(NULL, 0,
Signature · 1 line
2.45.2.993.g49e7a77208-goog

Have a lovely day!
Alex

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

Re: [PATCH 5/5] landlock.7: Document Landlock ABI version 5 (IOCTL)

Thank you both for the reviews!
I sent out a second version.

Konstantin: Please also do have a look if you are around, since this also covers the documentation for your networking connect/bind feature. Thank you!

Quoted 39 lines · Mickaël Salaün
Quoted 29 lines · Alejandro Colomar
Quoted 28 lines · Günther Noack
---
 man/man7/landlock.7 | 51 +++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 49 insertions(+), 2 deletions(-)
man/man7/landlock.7 +9 -0
index d452b93b2..044f57208 100644
@@ -92,6 +92,8 @@ This access right is available since the third version of the Landlock ABI.
 .P
 Whether an opened file can be truncated with
 .BR ftruncate (2)
+or used with
+.BR ioctl (2)
 is determined during
 .BR open (2),
 in the same way as read and write permissions are checked during
@@ -188,6 +190,48 @@ If multiple requirements are not met, the
 .B EACCES
 error code takes precedence over
 .BR EXDEV .
+.P
+The following access right
+applies to both files and directories:
+.TP
+.B LANDLOCK_ACCESS_FS_IOCTL_DEV
+Invoke
+.BR ioctl (2)
Quoted 8 lines

man/man7/landlock.7 If multiple requirements are not met, the · line 205

Quoted 6 lines
man/man7/landlock.7 +6 -0
+commands on an opened character or block device.
+.IP
+This access right applies to all
+.BR ioctl (2)
+commands implemented by device drivers.
+However, the following common IOCTL commands continue to be invokable

Maybe s/IOCTL/ioctl(2)/ ?

Quoted 2 lines

ioctl(2) is already used in the previous sentence, so it might be too much?

I agree with Mickaël here, I feel that IOCTL might be more appropriate.

We've been using the uppercase spelling throughout the kernel docs to refer to IOCTL (the concept and the overall feature), as opposed to ioctl(2) (the specific system call).

This is the only remark which I left unaddressed in v2 of this patch set. We can change it though if you feel strongly about it, Alejandro. Otherwise I'd prefer to keep it in sync with the kernel documentation, to keep the delta between the kernel doc and man pages smaller.

Quoted 9 lines
Quoted 9 lines

man/man7/landlock.7 attr.handled_access_fs = · line 488

Quoted 6 lines
man/man7/landlock.7 +1 -1
@@ -440,7 +485,8 @@ attr.handled_access_fs =
         LANDLOCK_ACCESS_FS_MAKE_BLOCK |
         LANDLOCK_ACCESS_FS_MAKE_SYM |
         LANDLOCK_ACCESS_FS_REFER |
-        LANDLOCK_ACCESS_FS_TRUNCATE;
+        LANDLOCK_ACCESS_FS_TRUNCATE |;

s/;//

Quoted 3 lines
Quoted 1 line

right?

Correct

Well spotted, thanks for the attention to detail! Done.

—Günther