Skip to contentSkip to conversation

landlock.7: Move the warning about missing features into the CAVEATS section

PATCH In review Günther Noack 4 participants 21 messages Feb 21, 2023 – Feb 28, 2023 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

PATCH 1/3 landlock.7: Move the warning about missing features into the CAVEATS section

Putting the warning there makes it more prominent. CAVEATS is a standard section that exists in many man pages and is also described in man-pages(7).

---
 man7/landlock.7 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man7/landlock.7 +1 -1
index 0818b4bf9..099f68067 100644
@@ -201,7 +201,7 @@ command line parameter and further to the value of
 We can check that Landlock is enabled by looking for
 .I landlock: Up and running.
 in kernel logs.
-.PP
+.SH CAVEATS
 It is currently not possible to restrict some file-related actions
 accessible through these system call families:
 .BR chdir (2),

base-commit: 887b913eb2687f34bc056597c0501a4325bebf28

Signature · 1 line
2.39.2
#1 lore raw

PATCH 2/3 landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)

* Add the description for LANDLOCK_ACCESS_FS_REFER,
in line with recent update to the uapi headers:
https://lore.kernel.org/linux-security-module/[email protected]/T/
* VERSIONS: Add a table of Landlock versions and their changes. Briefly talk about how to probe ABI levels and warn users about the special semantics of the LANDLOCK_ACCESS_FS_REFER right.
* Add LANDLOCK_ACCESS_FS_REFER to the code example.

Code review threads for the "refer" feature:
* https://lore.kernel.org/all/[email protected]/ (initial commit)
* https://lore.kernel.org/all/[email protected]/ (bugfix)
* https://lore.kernel.org/all/[email protected]/ (documentation update)

---
 man7/landlock.7 | 90 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 88 insertions(+), 2 deletions(-)
man7/landlock.7 +88 -2
index 099f68067..6321b56ab 100644
@@ -105,6 +105,53 @@ Create (or rename or link) a block device.
 .TP
 .B LANDLOCK_ACCESS_FS_MAKE_SYM
 Create (or rename or link) a symbolic link.
+.TP
+.B LANDLOCK_ACCESS_FS_REFER
+Link or rename a file from or to a different directory (i.e. reparent
+a file hierarchy).
+.IP
+This access right is available since the second version of the
+Landlock ABI.
+.IP
+This is the only access right which is denied by default by any
+ruleset, even if the right is not specified as handled at ruleset
+creation time.  The only way to make a ruleset grant this right is to
+explicitly allow it for a specific directory by adding a matching rule
+to the ruleset.
+.IP
+In particular, when using the first Landlock ABI version, Landlock will
+always deny attempts to reparent files between different directories.
+.IP
+In addition to the source and destination directories having the
+.B LANDLOCK_ACCESS_FS_REFER
+access right, the attempted link or rename operation must meet the
+following constraints:
+.RS
+.IP \(bu 3
+The reparented file may not gain more access rights in the destination
+directory than it previously had in the source directory.  If this is
+attempted, the operation results in an
+.B EXDEV
+error.
+.IP \(bu 3
+When linking or renaming, the
+.B LANDLOCK_ACCESS_FS_MAKE_*
+right for the respective file type must be granted for the destination
+directory. Otherwise, the operation results in an
+.BR EACCES
+error.
+.IP \(bu 3
+When renaming, the
+.B LANDLOCK_ACCESS_FS_REMOVE_*
+right for the respective file type must be granted for the source directory. Otherwise, the operation results in an
+.B EACCES
+error.
+.RE
+.IP
+If multiple requirements are not met, the
+.B EACCES
+error code takes precedence over
+.BR EXDEV .
 .\"
 .SS Layers of file path access rights
 Each time a thread enforces a ruleset on itself,
@@ -182,7 +229,45 @@ 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.
 .SH VERSIONS
-Landlock was added in Linux 5.13.
+Landlock was introduced in Linux 5.13.
+.PP
+The availability of individual Landlock features is versioned through
+ABI levels:
+.TS
+box;
+ntb| ntb| lbx
+nt| nt| lbx.
+ABI	Kernel	Newly introduced access rights
+_	_	_
+1	5.13	LANDLOCK_ACCESS_FS_EXECUTE
+\^	\^	LANDLOCK_ACCESS_FS_WRITE_FILE
+\^	\^	LANDLOCK_ACCESS_FS_READ_FILE
+\^	\^	LANDLOCK_ACCESS_FS_READ_DIR
+\^	\^	LANDLOCK_ACCESS_FS_REMOVE_DIR
+\^	\^	LANDLOCK_ACCESS_FS_REMOVE_FILE
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_CHAR
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_DIR
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_REG
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_SOCK
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_FIFO
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_BLOCK
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_SYM
+_	_	_
+2	5.19	LANDLOCK_ACCESS_FS_REFER
+.TE
+.PP
+To query the running kernel's Landlock ABI level, programs may pass
+the
+.B LANDLOCK_CREATE_RULESET_VERSION
+flag to
+.BR landlock_create_ruleset (2).
+.PP
+When building fallback mechanisms for compatibility with older kernels,
+users are advised to consider the special semantics of the
+.B LANDLOCK_ACCESS_FS_REFER
+access right: In ABI v1, linking and moving of files between different
+directories is always forbidden, so programs relying on such
+operations are only compatible with Landlock ABI v2 and higher.
 .SH NOTES
 Landlock is enabled by
 .BR CONFIG_SECURITY_LANDLOCK .
@@ -242,7 +327,8 @@ attr.handled_access_fs =
         LANDLOCK_ACCESS_FS_MAKE_SOCK |
         LANDLOCK_ACCESS_FS_MAKE_FIFO |
         LANDLOCK_ACCESS_FS_MAKE_BLOCK |
-        LANDLOCK_ACCESS_FS_MAKE_SYM;
+        LANDLOCK_ACCESS_FS_MAKE_SYM |
+        LANDLOCK_ACCESS_FS_REFER;
 
 ruleset_fd = landlock_create_ruleset(&attr, sizeof(attr), 0);
 if (ruleset_fd == -1) {
Signature · 1 line
2.39.2
#2 lore raw

Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)

Thanks for this update Günther.

Quoted 75 lines · Günther Noack

* Add the description for LANDLOCK_ACCESS_FS_REFER,
in line with recent update to the uapi headers:
https://lore.kernel.org/linux-security-module/[email protected]/T/
* VERSIONS: Add a table of Landlock versions and their changes. Briefly talk about how to probe ABI levels and warn users about the special semantics of the LANDLOCK_ACCESS_FS_REFER right.
* Add LANDLOCK_ACCESS_FS_REFER to the code example.

Code review threads for the "refer" feature:
* https://lore.kernel.org/all/[email protected]/ (initial commit)
* https://lore.kernel.org/all/[email protected]/ (bugfix)
* https://lore.kernel.org/all/[email protected]/ (documentation update)

---
 man7/landlock.7 | 90 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 88 insertions(+), 2 deletions(-)
man7/landlock.7 +47 -0
index 099f68067..6321b56ab 100644
@@ -105,6 +105,53 @@ Create (or rename or link) a block device.
 .TP
 .B LANDLOCK_ACCESS_FS_MAKE_SYM
 Create (or rename or link) a symbolic link.
+.TP
+.B LANDLOCK_ACCESS_FS_REFER
+Link or rename a file from or to a different directory (i.e. reparent
+a file hierarchy).
+.IP
+This access right is available since the second version of the
+Landlock ABI.
+.IP
+This is the only access right which is denied by default by any
+ruleset, even if the right is not specified as handled at ruleset
+creation time.  The only way to make a ruleset grant this right is to
+explicitly allow it for a specific directory by adding a matching rule
+to the ruleset.
+.IP
+In particular, when using the first Landlock ABI version, Landlock will
+always deny attempts to reparent files between different directories.
+.IP
+In addition to the source and destination directories having the
+.B LANDLOCK_ACCESS_FS_REFER
+access right, the attempted link or rename operation must meet the
+following constraints:
+.RS
+.IP \(bu 3
+The reparented file may not gain more access rights in the destination
+directory than it previously had in the source directory.  If this is
+attempted, the operation results in an
+.B EXDEV
+error.
+.IP \(bu 3
+When linking or renaming, the
+.B LANDLOCK_ACCESS_FS_MAKE_*
+right for the respective file type must be granted for the destination
+directory. Otherwise, the operation results in an
+.BR EACCES
+error.
+.IP \(bu 3
+When renaming, the
+.B LANDLOCK_ACCESS_FS_REMOVE_*
+right for the respective file type must be granted for the source directory. Otherwise, the operation results in an
+.B EACCES
+error.
+.RE
+.IP
+If multiple requirements are not met, the
+.B EACCES
+error code takes precedence over
+.BR EXDEV .
 .\"
 .SS Layers of file path access rights
 Each time a thread enforces a ruleset on itself,

man7/landlock.7 and related syscalls on a target process, · line 235

Quoted 8 lines
man7/landlock.7 +4 -1
@@ -182,7 +229,45 @@ 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.
 .SH VERSIONS
-Landlock was added in Linux 5.13.
+Landlock was introduced in Linux 5.13.
+.PP
+The availability of individual Landlock features is versioned through
+ABI levels:

I think this table is useful, but it should contain a warning to make sure developers don't rely on kernel versions to check Landlock features, but use the dedicated Landlock syscall instead. It should be explained that this table is true for the mainline/vanilla kernel, but that can be incorrect for any other kernel (e.g. patched distro kernel, like chromeOS that may backport upstream features).

Quoted 40 lines
man7/landlock.7 +35 -0
+.TS
+box;
+ntb| ntb| lbx
+nt| nt| lbx.
+ABI	Kernel	Newly introduced access rights
+_	_	_
+1	5.13	LANDLOCK_ACCESS_FS_EXECUTE
+\^	\^	LANDLOCK_ACCESS_FS_WRITE_FILE
+\^	\^	LANDLOCK_ACCESS_FS_READ_FILE
+\^	\^	LANDLOCK_ACCESS_FS_READ_DIR
+\^	\^	LANDLOCK_ACCESS_FS_REMOVE_DIR
+\^	\^	LANDLOCK_ACCESS_FS_REMOVE_FILE
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_CHAR
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_DIR
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_REG
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_SOCK
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_FIFO
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_BLOCK
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_SYM
+_	_	_
+2	5.19	LANDLOCK_ACCESS_FS_REFER
+.TE
+.PP
+To query the running kernel's Landlock ABI level, programs may pass
+the
+.B LANDLOCK_CREATE_RULESET_VERSION
+flag to
+.BR landlock_create_ruleset (2).
+.PP
+When building fallback mechanisms for compatibility with older kernels,
+users are advised to consider the special semantics of the
+.B LANDLOCK_ACCESS_FS_REFER
+access right: In ABI v1, linking and moving of files between different
+directories is always forbidden, so programs relying on such
+operations are only compatible with Landlock ABI v2 and higher.
 .SH NOTES
 Landlock is enabled by
 .BR CONFIG_SECURITY_LANDLOCK .

man7/landlock.7 attr.handled_access_fs = · line 334

Quoted 9 lines
man7/landlock.7 +2 -1
@@ -242,7 +327,8 @@ attr.handled_access_fs =
         LANDLOCK_ACCESS_FS_MAKE_SOCK |
         LANDLOCK_ACCESS_FS_MAKE_FIFO |
         LANDLOCK_ACCESS_FS_MAKE_BLOCK |
-        LANDLOCK_ACCESS_FS_MAKE_SYM;
+        LANDLOCK_ACCESS_FS_MAKE_SYM |
+        LANDLOCK_ACCESS_FS_REFER;
 
 ruleset_fd = landlock_create_ruleset(&attr, sizeof(attr), 0);
 if (ruleset_fd == -1) {

2.39.2

#3 lore raw

Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)

Quoted 2 lines · Mickaël Salaün

I think this table is useful, but it should contain a warning to make sure developers don't rely on kernel versions to check Landlock features, but use the dedicated Landlock syscall instead. It should be explained that this table is true for the mainline/vanilla kernel, but that can be incorrect for any other kernel (e.g. patched distro kernel, like chromeOS that may backport upstream features).

Thanks, that's a good point. I'll add that.

#4 lore raw

Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)

In reply to Günther Noack

On 2023-02-21T21:50:22.000+01:00, Günther Noack wrote:

[...]

Quoted 19 lines

.SH VERSIONS

man7/landlock.7 +17 -1
-Landlock was added in Linux 5.13.
+Landlock was introduced in Linux 5.13.
+.PP
+The availability of individual Landlock features is versioned through
+ABI levels:
+.TS
+box;
+ntb| ntb| lbx
+nt| nt| lbx.
+ABI	Kernel	Newly introduced access rights
+_	_	_
+1	5.13	LANDLOCK_ACCESS_FS_EXECUTE
+\^	\^	LANDLOCK_ACCESS_FS_WRITE_FILE
+\^	\^	LANDLOCK_ACCESS_FS_READ_FILE
+\^	\^	LANDLOCK_ACCESS_FS_READ_DIR
+\^	\^	LANDLOCK_ACCESS_FS_REMOVE_DIR
+\^	\^	LANDLOCK_ACCESS_FS_REMOVE_FILE
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_CHAR

man7/landlock.7 and related syscalls on a target process, · line 258

Quoted 10 lines
man7/landlock.7 +10 -0
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_DIR
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_REG
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_SOCK
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_FIFO
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_BLOCK
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_SYM
+_	_	_
+2	5.19	LANDLOCK_ACCESS_FS_REFER
+.TE
+.PP

A line break would be nice here.

Quoted 1 line

+To query the running kernel's Landlock ABI level, programs may pass

s/level/version/

Quoted 4 lines
man7/landlock.7 +4 -0
+the
+.B LANDLOCK_CREATE_RULESET_VERSION
+flag to
+.BR landlock_create_ruleset (2).
#5 lore raw

Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)

Quoted 20 lines · Mickaël Salaün
Quoted 19 lines · Günther Noack
man7/landlock.7 +19 -0
+The availability of individual Landlock features is versioned through
+ABI levels:
+.TS
+box;
+ntb| ntb| lbx
+nt| nt| lbx.
+ABI	Kernel	Newly introduced access rights
+_	_	_
+1	5.13	LANDLOCK_ACCESS_FS_EXECUTE
+\^	\^	LANDLOCK_ACCESS_FS_WRITE_FILE
+\^	\^	LANDLOCK_ACCESS_FS_READ_FILE
+\^	\^	LANDLOCK_ACCESS_FS_READ_DIR
+\^	\^	LANDLOCK_ACCESS_FS_REMOVE_DIR
+\^	\^	LANDLOCK_ACCESS_FS_REMOVE_FILE
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_CHAR
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_DIR
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_REG
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_SOCK
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_FIFO
Quoted 8 lines
Quoted 6 lines

+\^ \^ LANDLOCK_ACCESS_FS_MAKE_BLOCK
+\^ \^ LANDLOCK_ACCESS_FS_MAKE_SYM
+_ _ _
+2 5.19 LANDLOCK_ACCESS_FS_REFER
+.TE
+.PP

A line break would be nice here.

Added. (Used .sp 1 for that, as it is already used in the mount_namespaces.7, ip.7 and other man pages.)

Quoted 3 lines
Quoted 1 line

+To query the running kernel's Landlock ABI level, programs may pass

s/level/version/

Thanks, I'm removing the word "level" here.

#6 lore raw

Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)

Hi Branden,

Quoted 30 lines · Günther Noack
Quoted 20 lines · Mickaël Salaün
Quoted 19 lines · Günther Noack
man7/landlock.7 +19 -0
+The availability of individual Landlock features is versioned through
+ABI levels:
+.TS
+box;
+ntb| ntb| lbx
+nt| nt| lbx.
+ABI	Kernel	Newly introduced access rights
+_	_	_
+1	5.13	LANDLOCK_ACCESS_FS_EXECUTE
+\^	\^	LANDLOCK_ACCESS_FS_WRITE_FILE
+\^	\^	LANDLOCK_ACCESS_FS_READ_FILE
+\^	\^	LANDLOCK_ACCESS_FS_READ_DIR
+\^	\^	LANDLOCK_ACCESS_FS_REMOVE_DIR
+\^	\^	LANDLOCK_ACCESS_FS_REMOVE_FILE
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_CHAR
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_DIR
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_REG
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_SOCK
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_FIFO
Quoted 8 lines
Quoted 6 lines

+\^ \^ LANDLOCK_ACCESS_FS_MAKE_BLOCK
+\^ \^ LANDLOCK_ACCESS_FS_MAKE_SYM
+_ _ _
+2 5.19 LANDLOCK_ACCESS_FS_REFER
+.TE
+.PP

A line break would be nice here.

Quoted 2 lines

Added. (Used .sp 1 for that, as it is already used in the mount_namespaces.7, ip.7 and other man pages.)

This sounds weird, but they are right that there seems to be a missing blank line. Could you explain why it's happening? I'd expect the .PP to separate paragraphs with a blank, right? I see:

The availability of individual Landlock features is versioned through ABI levels:

┌────┬────────┬────────────────────────────────────────────────┐
│ABI │ Kernel │ Newly introduced access rights │
├────┼────────┼────────────────────────────────────────────────┤
│ 1 │ 5.13 │ LANDLOCK_ACCESS_FS_EXECUTE │
│ │ │ LANDLOCK_ACCESS_FS_WRITE_FILE │
│ │ │ LANDLOCK_ACCESS_FS_READ_FILE │
│ │ │ LANDLOCK_ACCESS_FS_READ_DIR │
│ │ │ LANDLOCK_ACCESS_FS_REMOVE_DIR │
│ │ │ LANDLOCK_ACCESS_FS_REMOVE_FILE │
│ │ │ LANDLOCK_ACCESS_FS_MAKE_CHAR │
│ │ │ LANDLOCK_ACCESS_FS_MAKE_DIR │
│ │ │ LANDLOCK_ACCESS_FS_MAKE_REG │
│ │ │ LANDLOCK_ACCESS_FS_MAKE_SOCK │
│ │ │ LANDLOCK_ACCESS_FS_MAKE_FIFO │
│ │ │ LANDLOCK_ACCESS_FS_MAKE_BLOCK │
│ │ │ LANDLOCK_ACCESS_FS_MAKE_SYM │
├────┼────────┼────────────────────────────────────────────────┤
│ 2 │ 5.19 │ LANDLOCK_ACCESS_FS_REFER │
└────┴────────┴────────────────────────────────────────────────┘ To query the running kernel's Landlock ABI level, programs may pass the LANDLOCK_CREATE_RULESET_VERSION flag to landlock_cre‐ ate_ruleset(2).

Cheers,

Alex

Quoted 6 lines
Quoted 4 lines
Quoted 2 lines

+To query the running kernel's Landlock ABI level, programs may pass

s/level/version/

Thanks, I'm removing the word "level" here.

Signature · 2 lines
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
#7 lore raw

Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)

Hi Alex,

Quoted 31 lines · Alex Colomar
Quoted 30 lines · Günther Noack
Quoted 28 lines · Mickaël Salaün
Quoted 15 lines · Günther Noack
man7/landlock.7 +15 -0
+The availability of individual Landlock features is versioned through
+ABI levels:
+.TS
+box;
+ntb| ntb| lbx
+nt| nt| lbx.
+ABI	Kernel	Newly introduced access rights
+_	_	_
+1	5.13	LANDLOCK_ACCESS_FS_EXECUTE
+\^	\^	LANDLOCK_ACCESS_FS_WRITE_FILE
+\^	\^	LANDLOCK_ACCESS_FS_READ_FILE
+\^	\^	LANDLOCK_ACCESS_FS_READ_DIR
+\^	\^	LANDLOCK_ACCESS_FS_REMOVE_DIR
+\^	\^	LANDLOCK_ACCESS_FS_REMOVE_FILE
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_CHAR

man7/landlock.7 and related syscalls on a target process, · line 258

Quoted 10 lines
man7/landlock.7 +10 -0
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_DIR
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_REG
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_SOCK
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_FIFO
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_BLOCK
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_SYM
+_	_	_
+2	5.19	LANDLOCK_ACCESS_FS_REFER
+.TE
+.PP

A line break would be nice here.

Quoted 3 lines
Quoted 2 lines

Added. (Used .sp 1 for that, as it is already used in the mount_namespaces.7, ip.7 and other man pages.)

[reorganized]

Quoted 19 lines

I see:

The availability of individual Landlock features is versioned through ABI levels:

┌────┬────────┬────────────────────────────────────────────────┐
│ABI │ Kernel │ Newly introduced access rights │
├────┼────────┼────────────────────────────────────────────────┤
│ 1 │ 5.13 │ LANDLOCK_ACCESS_FS_EXECUTE │
│ │ │ LANDLOCK_ACCESS_FS_WRITE_FILE │
│ │ │ LANDLOCK_ACCESS_FS_READ_FILE │
│ │ │ LANDLOCK_ACCESS_FS_READ_DIR │
│ │ │ LANDLOCK_ACCESS_FS_REMOVE_DIR │
│ │ │ LANDLOCK_ACCESS_FS_REMOVE_FILE │
│ │ │ LANDLOCK_ACCESS_FS_MAKE_CHAR │
│ │ │ LANDLOCK_ACCESS_FS_MAKE_DIR │
│ │ │ LANDLOCK_ACCESS_FS_MAKE_REG │
│ │ │ LANDLOCK_ACCESS_FS_MAKE_SOCK │
│ │ │ LANDLOCK_ACCESS_FS_MAKE_FIFO │

Quoted 8 lines

│ │ │ LANDLOCK_ACCESS_FS_MAKE_BLOCK │
│ │ │ LANDLOCK_ACCESS_FS_MAKE_SYM │
├────┼────────┼────────────────────────────────────────────────┤
│ 2 │ 5.19 │ LANDLOCK_ACCESS_FS_REFER │
└────┴────────┴────────────────────────────────────────────────┘ To query the running kernel's Landlock ABI level, programs may pass the LANDLOCK_CREATE_RULESET_VERSION flag to landlock_cre‐ ate_ruleset(2).

[reorganized]

Quoted 2 lines

This sounds weird, but they are right that there seems to be a missing blank line.

Yes, they are.

Quoted 1 line

Could you explain why it's happening?

This is Savannah #49390.

https://savannah.gnu.org/bugs/?49390

It is fixed in groff 1.23.0. Which, by the way, is at release candidate 3 now. Final release may be this weekend, depending on Bertrand's opinion of the changes I've made this week.[1]

Quoted 1 line

I'd expect the .PP to separate paragraphs with a blank, right?

It does, and it is, but you can't see it because groff 1.22.4 and earlier table did not move the drawing position below the bottom box border on nroff devices.

The '.sp 1' workaround (which is synonymous with plain '.sp') can be removed when you feel groff 1.23.0 has spread sufficiently.

Regards,
Branden

[1] https://git.savannah.gnu.org/cgit/groff.git/log/

#8 lore raw

Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)

Hi Branden,

Quoted 71 lines · G. Branden Robinson

Hi Alex,

Quoted 31 lines · Alex Colomar
Quoted 30 lines · Günther Noack
Quoted 28 lines · Mickaël Salaün
Quoted 15 lines · Günther Noack
man7/landlock.7 +15 -0
+The availability of individual Landlock features is versioned through
+ABI levels:
+.TS
+box;
+ntb| ntb| lbx
+nt| nt| lbx.
+ABI	Kernel	Newly introduced access rights
+_	_	_
+1	5.13	LANDLOCK_ACCESS_FS_EXECUTE
+\^	\^	LANDLOCK_ACCESS_FS_WRITE_FILE
+\^	\^	LANDLOCK_ACCESS_FS_READ_FILE
+\^	\^	LANDLOCK_ACCESS_FS_READ_DIR
+\^	\^	LANDLOCK_ACCESS_FS_REMOVE_DIR
+\^	\^	LANDLOCK_ACCESS_FS_REMOVE_FILE
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_CHAR

man7/landlock.7 and related syscalls on a target process, · line 258

Quoted 10 lines
man7/landlock.7 +10 -0
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_DIR
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_REG
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_SOCK
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_FIFO
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_BLOCK
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_SYM
+_	_	_
+2	5.19	LANDLOCK_ACCESS_FS_REFER
+.TE
+.PP

A line break would be nice here.

Quoted 3 lines
Quoted 2 lines

Added. (Used .sp 1 for that, as it is already used in the mount_namespaces.7, ip.7 and other man pages.)

[reorganized]

Quoted 19 lines

I see:

The availability of individual Landlock features is versioned through ABI levels:

┌────┬────────┬────────────────────────────────────────────────┐
│ABI │ Kernel │ Newly introduced access rights │
├────┼────────┼────────────────────────────────────────────────┤
│ 1 │ 5.13 │ LANDLOCK_ACCESS_FS_EXECUTE │
│ │ │ LANDLOCK_ACCESS_FS_WRITE_FILE │
│ │ │ LANDLOCK_ACCESS_FS_READ_FILE │
│ │ │ LANDLOCK_ACCESS_FS_READ_DIR │
│ │ │ LANDLOCK_ACCESS_FS_REMOVE_DIR │
│ │ │ LANDLOCK_ACCESS_FS_REMOVE_FILE │
│ │ │ LANDLOCK_ACCESS_FS_MAKE_CHAR │
│ │ │ LANDLOCK_ACCESS_FS_MAKE_DIR │
│ │ │ LANDLOCK_ACCESS_FS_MAKE_REG │
│ │ │ LANDLOCK_ACCESS_FS_MAKE_SOCK │
│ │ │ LANDLOCK_ACCESS_FS_MAKE_FIFO │

Quoted 8 lines

│ │ │ LANDLOCK_ACCESS_FS_MAKE_BLOCK │
│ │ │ LANDLOCK_ACCESS_FS_MAKE_SYM │
├────┼────────┼────────────────────────────────────────────────┤
│ 2 │ 5.19 │ LANDLOCK_ACCESS_FS_REFER │
└────┴────────┴────────────────────────────────────────────────┘ To query the running kernel's Landlock ABI level, programs may pass the LANDLOCK_CREATE_RULESET_VERSION flag to landlock_cre‐ ate_ruleset(2).

[reorganized]

Quoted 2 lines

This sounds weird, but they are right that there seems to be a missing blank line.

Yes, they are.

Quoted 8 lines
Quoted 1 line

Could you explain why it's happening?

This is Savannah #49390.

https://savannah.gnu.org/bugs/?49390

It is fixed in groff 1.23.0. Which, by the way, is at release candidate 3 now.

Ahh, I forgot that in my laptop I still have 1.22.4 :) Good to know that it's already fixed. Thanks!

Quoted 2 lines

Final release may be this weekend, depending on Bertrand's
opinion of the changes I've made this week.[1]

Nice, we'll hopefully have it before I turn 30 (which BTW coincides with the deadline for having it in Bookworm, AFAIK :p)

Quoted 9 lines
Quoted 2 lines

I'd expect the .PP to separate paragraphs with a blank, right?

It does, and it is, but you can't see it because groff 1.22.4 and earlier table did not move the drawing position below the bottom box border on nroff devices.

The '.sp 1' workaround (which is synonymous with plain '.sp') can be removed when you feel groff 1.23.0 has spread sufficiently.

Since the bug is so minor, I'm in favor of removing it as soon as you release. A little bit of lack-of-blank-line inconvenience is not so bad.

Cheers,

Alex

Quoted 5 lines

Regards,
Branden

[1] https://git.savannah.gnu.org/cgit/groff.git/log/

Signature · 2 lines
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
#9 lore raw

Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)

Quoted 6 lines · Alex Colomar
Quoted 2 lines · G. Branden Robinson

The '.sp 1' workaround (which is synonymous with plain '.sp') can be removed when you feel groff 1.23.0 has spread sufficiently.

Since the bug is so minor, I'm in favor of removing it as soon as you release. A little bit of lack-of-blank-line inconvenience is not so bad.

OK, thanks for investigating this!

I'll keep it in the man page for now then.

–-Günther

#10 lore raw

Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)

In reply to Mickaël Salaün

Hi Mickaël,

Quoted 27 lines · Mickaël Salaün

On 2023-02-21T21:50:22.000+01:00, Günther Noack wrote:

[...]

Quoted 23 lines

.SH VERSIONS

man7/landlock.7 +21 -1
-Landlock was added in Linux 5.13.
+Landlock was introduced in Linux 5.13.
+.PP
+The availability of individual Landlock features is versioned through
+ABI levels:
+.TS
+box;
+ntb| ntb| lbx
+nt| nt| lbx.
+ABI	Kernel	Newly introduced access rights
+_	_	_
+1	5.13	LANDLOCK_ACCESS_FS_EXECUTE
+\^	\^	LANDLOCK_ACCESS_FS_WRITE_FILE
+\^	\^	LANDLOCK_ACCESS_FS_READ_FILE
+\^	\^	LANDLOCK_ACCESS_FS_READ_DIR
+\^	\^	LANDLOCK_ACCESS_FS_REMOVE_DIR
+\^	\^	LANDLOCK_ACCESS_FS_REMOVE_FILE
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_CHAR
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_DIR
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_REG
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_SOCK
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_FIFO
Quoted 8 lines
Quoted 6 lines

+\^ \^ LANDLOCK_ACCESS_FS_MAKE_BLOCK
+\^ \^ LANDLOCK_ACCESS_FS_MAKE_SYM
+_ _ _
+2 5.19 LANDLOCK_ACCESS_FS_REFER
+.TE
+.PP

A line break would be nice here.

.PP should be performing a line break. I didn't yet read the formatted version, so maybe there's something wrong with the table, but from inspection of the source it seems reasonable to me.

Cheers,

Alex

Quoted 9 lines
Quoted 2 lines

+To query the running kernel's Landlock ABI level, programs may pass

s/level/version/

Quoted 4 lines
man7/landlock.7 +4 -0
+the
+.B LANDLOCK_CREATE_RULESET_VERSION
+flag to
+.BR landlock_create_ruleset (2).
Signature · 2 lines
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
#11 lore raw

Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)

In reply to Günther Noack

On 2023-02-21T21:50:22.000+01:00, Günther Noack wrote:

[...]

Quoted 45 lines

.SH VERSIONS

man7/landlock.7 +39 -1
-Landlock was added in Linux 5.13.
+Landlock was introduced in Linux 5.13.
+.PP
+The availability of individual Landlock features is versioned through
+ABI levels:
+.TS
+box;
+ntb| ntb| lbx
+nt| nt| lbx.
+ABI	Kernel	Newly introduced access rights
+_	_	_
+1	5.13	LANDLOCK_ACCESS_FS_EXECUTE
+\^	\^	LANDLOCK_ACCESS_FS_WRITE_FILE
+\^	\^	LANDLOCK_ACCESS_FS_READ_FILE
+\^	\^	LANDLOCK_ACCESS_FS_READ_DIR
+\^	\^	LANDLOCK_ACCESS_FS_REMOVE_DIR
+\^	\^	LANDLOCK_ACCESS_FS_REMOVE_FILE
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_CHAR
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_DIR
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_REG
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_SOCK
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_FIFO
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_BLOCK
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_SYM
+_	_	_
+2	5.19	LANDLOCK_ACCESS_FS_REFER
+.TE
+.PP
+To query the running kernel's Landlock ABI level, programs may pass
+the
+.B LANDLOCK_CREATE_RULESET_VERSION
+flag to
+.BR landlock_create_ruleset (2).
+.PP
+When building fallback mechanisms for compatibility with older kernels,
+users are advised to consider the special semantics of the
+.B LANDLOCK_ACCESS_FS_REFER
+access right: In ABI v1, linking and moving of files between different
+directories is always forbidden, so programs relying on such
+operations are only compatible with Landlock ABI v2 and higher.
 .SH NOTES
 Landlock is enabled by
 .BR CONFIG_SECURITY_LANDLOCK .

man7/landlock.7 attr.handled_access_fs = · line 331

Quoted 6 lines
man7/landlock.7 +2 -1
@@ -242,7 +327,8 @@ attr.handled_access_fs =
         LANDLOCK_ACCESS_FS_MAKE_SOCK |
         LANDLOCK_ACCESS_FS_MAKE_FIFO |
         LANDLOCK_ACCESS_FS_MAKE_BLOCK |
-        LANDLOCK_ACCESS_FS_MAKE_SYM;
+        LANDLOCK_ACCESS_FS_MAKE_SYM |
+        LANDLOCK_ACCESS_FS_REFER;

This code example should now query the Landlock ABI version and mask new access right to make it works with old kernels.

man7/landlock.7 attr.handled_access_fs = · line 334

Quoted 4 lines
man7/landlock.7 +0 -0
 ruleset_fd = landlock_create_ruleset(&attr, sizeof(attr), 0);
 if (ruleset_fd == -1) {

2.39.2

#12 lore raw

Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)

Quoted 10 lines · Mickaël Salaün

man7/landlock.7 attr.handled_access_fs = · line 331

Quoted 7 lines · Günther Noack
man7/landlock.7 +2 -1
@@ -242,7 +327,8 @@ attr.handled_access_fs =
         LANDLOCK_ACCESS_FS_MAKE_SOCK |
         LANDLOCK_ACCESS_FS_MAKE_FIFO |
         LANDLOCK_ACCESS_FS_MAKE_BLOCK |
-        LANDLOCK_ACCESS_FS_MAKE_SYM;
+        LANDLOCK_ACCESS_FS_MAKE_SYM |
+        LANDLOCK_ACCESS_FS_REFER;

This code example should now query the Landlock ABI version and mask new access right to make it works with old kernels.

The changes I would have to do are:

- I would *remove* LANDLOCK_ACCESS_FS_REFER from attr.handled_access_fs, because it is not used in the LANDLOCK_RULE_PATH_PENEATH and that right is implicit anyway.

- Patch 3/3: I would *keep* LANDLOCK_ACCESS_FS_TRUNCATE in attr.handled_access_fs.

- Patch 3/3: I would query the ABI version, and mask away the LANDLOCK_ACCESS_FS_TRUNCATE right in handled_access_fs if the ABI version is < 3.

Things I don't like yet about this approach are:

* I believe if I were to read that example for the first time, I would be puzzled when seeing the "truncate" right set in handled_access_fs, but the "refer" right omitted. This requires additional explanation.

* It does not really describe what to do if you actually need to reparent files with the "refer" right in your program. The fallback logic is simpler in the man page example because "refer" is not needed in the LANDLOCK_RULE_PATH_BENEATH rule.

At the same time, I feel that the more complicated "refer" fallback logic might be beyond what would reasonably fit into a man page. Especially given that many users probably don't need the "refer" right for their programs.

So my proposal would be to change the example as described in the three bullet points above, but to point out that users who need "refer" should refer (ha ha) to the kernel documentation for more details.

Does that sound reasonable to you?

–-Günther

#13 lore raw

Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)

In reply to Günther Noack

Hi Günther,

Quoted 8 lines · Günther Noack

* Add the description for LANDLOCK_ACCESS_FS_REFER, in line with recent update to the uapi headers:

   https://lore.kernel.org/linux-security-module/[email protected]/T/

* VERSIONS: Add a table of Landlock versions and their changes. Briefly talk about how to probe ABI levels and warn users about the special semantics of the LANDLOCK_ACCESS_FS_REFER right.
* Add LANDLOCK_ACCESS_FS_REFER to the code example.

Quoted 4 lines

Code review threads for the "refer" feature:
* https://lore.kernel.org/all/[email protected]/ (initial commit)
* https://lore.kernel.org/all/[email protected]/ (bugfix)
* https://lore.kernel.org/all/[email protected]/ (documentation update)

I finally found some time to review your work. Thanks for the patience!

Please see some comments below.

Thanks!

Alex

Quoted 9 lines
---
  man7/landlock.7 | 90 +++++++++++++++++++++++++++++++++++++++++++++++--
  1 file changed, 88 insertions(+), 2 deletions(-)
man7/landlock.7 +0 -0
index 099f68067..6321b56ab 100644

man7/landlock.7 Create (or rename or link) a block device. · line 111

Quoted 7 lines
man7/landlock.7 +4 -0
@@ -105,6 +105,53 @@ Create (or rename or link) a block device.
  .TP
  .B LANDLOCK_ACCESS_FS_MAKE_SYM
  Create (or rename or link) a symbolic link.
+.TP
+.B LANDLOCK_ACCESS_FS_REFER
+Link or rename a file from or to a different directory (i.e. reparent
+a file hierarchy).

Please have a look at man-pages(7):
Use semantic newlines
In the source of a manual page, new sentences should be started on new lines, long sentences should be split into lines at clause breaks (commas, semicolons, colons, and so on), and long clauses should be split at phrase boundaries. This convention, sometimes known as "semantic newlines", makes it easier to see the effect of patches, which often operate at the level of in‐ dividual sentences, clauses, or phrases.

Here,
that would mean
breaking the line right before the opening parenthesis; please also apply it to the rest of the patch where appropriate.

Quoted 9 lines
man7/landlock.7 +9 -0
+.IP
+This access right is available since the second version of the
+Landlock ABI.
+.IP
+This is the only access right which is denied by default by any
+ruleset, even if the right is not specified as handled at ruleset
+creation time.  The only way to make a ruleset grant this right is to
+explicitly allow it for a specific directory by adding a matching rule
+to the ruleset.

man7/landlock.7 Create (or rename or link) a block device. · line 130

Quoted 10 lines
man7/landlock.7 +10 -0
+.IP
+In particular, when using the first Landlock ABI version, Landlock will
+always deny attempts to reparent files between different directories.
+.IP
+In addition to the source and destination directories having the
+.B LANDLOCK_ACCESS_FS_REFER
+access right, the attempted link or rename operation must meet the
+following constraints:
+.RS
+.IP \(bu 3

We now use \[bu] instead of \(bu (they are equivalent).

commit 36f73ba37945c7ff4aa2d8383f831519a38e3f27

Author: Alejandro Colomar <[email protected]>
Date:   Sun Feb 5 22:59:22 2023 +0100

man-pages.7: Recommend using \[..] instead of \(.. escapes

They are more readable.

man7/man-pages.7 +1 -1
index 4132ddabe..e5b111283 100644
@@ -666,7 +666,7 @@ These represent a set of (normally) exclusive alternatives.
 .TP
 Bullet lists
 Elements are preceded by bullet symbols
-.RB ( \e(bu ).
+.RB ( \e[bu] ).
 Anything that doesn't fit elsewhere is
 usually covered by this type of list.
 .TP
@@

[...]

commit cdede5cdd1b0ba75135d3b32d96354026e96f866

Author: Alejandro Colomar <[email protected]>
Date:   Sun Feb 5 23:14:38 2023 +0100

Many pages: Use \[bu] instead of \(bu

Quoted 6 lines
man7/landlock.7 +6 -0
+The reparented file may not gain more access rights in the destination
+directory than it previously had in the source directory.  If this is
+attempted, the operation results in an
+.B EXDEV
+error.
+.IP \(bu 3

man7/landlock.7 Create (or rename or link) a block device. · line 146

Quoted 10 lines
man7/landlock.7 +10 -0
+When linking or renaming, the
+.B LANDLOCK_ACCESS_FS_MAKE_*
+right for the respective file type must be granted for the destination
+directory. Otherwise, the operation results in an
+.BR EACCES
+error.
+.IP \(bu 3
+When renaming, the
+.B LANDLOCK_ACCESS_FS_REMOVE_*
+right for the respective file type must be granted for the source directory. Otherwise, the operation results in an

80 columns is a strong limit.
Using semantic newlines as suggested above should fix this.

Quoted 18 lines
man7/landlock.7 +10 -1
+.B EACCES
+error.
+.RE
+.IP
+If multiple requirements are not met, the
+.B EACCES
+error code takes precedence over
+.BR EXDEV .
  .\"
  .SS Layers of file path access rights
  Each time a thread enforces a ruleset on itself,
@@ -182,7 +229,45 @@ 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.
  .SH VERSIONS
-Landlock was added in Linux 5.13.
+Landlock was introduced in Linux 5.13.
+.PP

man7/landlock.7 and related syscalls on a target process, · line 243

Quoted 10 lines
man7/landlock.7 +10 -0
+The availability of individual Landlock features is versioned through
+ABI levels:
+.TS
+box;
+ntb| ntb| lbx
+nt| nt| lbx.
+ABI	Kernel	Newly introduced access rights
+_	_	_
+1	5.13	LANDLOCK_ACCESS_FS_EXECUTE
+\^	\^	LANDLOCK_ACCESS_FS_WRITE_FILE

What character do you want here?
If you want ASCII 0x5E,
then you want to use \[ha].

Quoted 40 lines
man7/landlock.7 +29 -1
+\^	\^	LANDLOCK_ACCESS_FS_READ_FILE
+\^	\^	LANDLOCK_ACCESS_FS_READ_DIR
+\^	\^	LANDLOCK_ACCESS_FS_REMOVE_DIR
+\^	\^	LANDLOCK_ACCESS_FS_REMOVE_FILE
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_CHAR
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_DIR
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_REG
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_SOCK
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_FIFO
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_BLOCK
+\^	\^	LANDLOCK_ACCESS_FS_MAKE_SYM
+_	_	_
+2	5.19	LANDLOCK_ACCESS_FS_REFER
+.TE
+.PP
+To query the running kernel's Landlock ABI level, programs may pass
+the
+.B LANDLOCK_CREATE_RULESET_VERSION
+flag to
+.BR landlock_create_ruleset (2).
+.PP
+When building fallback mechanisms for compatibility with older kernels,
+users are advised to consider the special semantics of the
+.B LANDLOCK_ACCESS_FS_REFER
+access right: In ABI v1, linking and moving of files between different
+directories is always forbidden, so programs relying on such
+operations are only compatible with Landlock ABI v2 and higher.
  .SH NOTES
  Landlock is enabled by
  .BR CONFIG_SECURITY_LANDLOCK .
@@ -242,7 +327,8 @@ attr.handled_access_fs =
          LANDLOCK_ACCESS_FS_MAKE_SOCK |
          LANDLOCK_ACCESS_FS_MAKE_FIFO |
          LANDLOCK_ACCESS_FS_MAKE_BLOCK |
-        LANDLOCK_ACCESS_FS_MAKE_SYM;
+        LANDLOCK_ACCESS_FS_MAKE_SYM |
+        LANDLOCK_ACCESS_FS_REFER;
 
  ruleset_fd = landlock_create_ruleset(&attr, sizeof(attr), 0);
  if (ruleset_fd == -1) {
Signature · 2 lines
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
author Applied
#14 lore raw

Re: [PATCH 2/3] landlock.7: Document Landlock ABI v2 (file reparenting; kernel 5.19)

Hello Alex!

Thank you for the review! Please see answers inline:

Quoted 9 lines · Alex Colomar

On 2/21/23 21:50, Günther Noack wrote:
Please have a look at man-pages(7):
Use semantic newlines

       [...]

Here,
that would mean
breaking the line right before the opening parenthesis; please also apply it to the rest of the patch where appropriate.

Thanks,
I applied this
so that the text is properly formatted now,
according to man-pages(7).

Quoted 3 lines
Quoted 1 line

+.IP \(bu 3

We now use \[bu] instead of \(bu (they are equivalent).

Thanks, applied.

Quoted 2 lines

80 columns is a strong limit.
Using semantic newlines as suggested above should fix this.

Done.

Quoted 4 lines
Quoted 4 lines

+.TS

(quoted diff) +3 -0
+box;
+ntb| ntb| lbx
+nt| nt| lbx.
Quoted 8 lines

Review

Quoted 4 lines
(quoted diff) +4 -0
+ABI	Kernel	Newly introduced access rights
+_	_	_
+1	5.13	LANDLOCK_ACCESS_FS_EXECUTE
+\^	\^	LANDLOCK_ACCESS_FS_WRITE_FILE

What character do you want here?
If you want ASCII 0x5E,
then you want to use \[ha].

I don't want it to show a character there. The intent is to make the table cells for ABI version and kernel version span across multiple rows, for the case where a single kernel version introduced multiple access rights at once. \^ is a data item in the tbl(1) syntax which has that special meaning.

https://manpages.debian.org/testing/groff-base/tbl.1.en.html

A data item consisting only of ‘\^’ indicates that the field immediately above spans downward over this row.

Quoted 5 lines
Quoted 5 lines

+\^ \^ LANDLOCK_ACCESS_FS_READ_FILE
+\^ \^ LANDLOCK_ACCESS_FS_READ_DIR
+\^ \^ LANDLOCK_ACCESS_FS_REMOVE_DIR
+\^ \^ LANDLOCK_ACCESS_FS_REMOVE_FILE
+\^ \^ LANDLOCK_ACCESS_FS_MAKE_CHAR

Quoted 8 lines
Quoted 8 lines

+\^ \^ LANDLOCK_ACCESS_FS_MAKE_DIR
+\^ \^ LANDLOCK_ACCESS_FS_MAKE_REG
+\^ \^ LANDLOCK_ACCESS_FS_MAKE_SOCK
+\^ \^ LANDLOCK_ACCESS_FS_MAKE_FIFO
+\^ \^ LANDLOCK_ACCESS_FS_MAKE_BLOCK
+\^ \^ LANDLOCK_ACCESS_FS_MAKE_SYM
+_ _ _
+2 5.19 LANDLOCK_ACCESS_FS_REFER

Thanks for the review!
–Günther

#15 lore raw

PATCH 3/3 landlock.7: Document Landlock ABI v3 (file truncation; kernel 6.2)

In reply to Günther Noack

https://lore.kernel.org/all/[email protected]/

---
 man7/landlock.7 | 80 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 77 insertions(+), 3 deletions(-)
man7/landlock.7 +77 -3
index 6321b56ab..b5b356642 100644
@@ -63,10 +63,38 @@ A file can only receive these access rights:
 Execute a file.
 .TP
 .B LANDLOCK_ACCESS_FS_WRITE_FILE
-Open a file with write access.
+Open a file with write access. Note that you might additionally need the
+.B LANDLOCK_ACCESS_FS_TRUNCATE
+right in order to overwrite files with
+.BR open (2)
+using
+.B O_TRUNC
+or
+.BR creat (2).
 .TP
 .B LANDLOCK_ACCESS_FS_READ_FILE
 Open a file with read access.
+.TP
+.B LANDLOCK_ACCESS_FS_TRUNCATE
+Truncate a file with
+.BR truncate (2),
+.BR ftruncate (2),
+.BR creat (2),
+or
+.BR open (2)
+with
+.BR O_TRUNC .
+Whether an opened file can be truncated with
+.BR ftruncate (2)
+is determined during
+.BR open (2),
+in the same way as read and write permissions are checked during
+.BR open (2)
+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.
 .PP
 A directory can receive access rights related to files or directories.
 The following access right is applied to the directory itself,
@@ -228,6 +256,50 @@ To be allowed to use
 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 Truncating files
+The operations covered by
+.B LANDLOCK_ACCESS_FS_WRITE_FILE
+and
+.B LANDLOCK_ACCESS_FS_TRUNCATE
+both change the contents of a file and sometimes overlap in
+non-intuitive ways. It is recommended to always specify both of these
+together.
+.PP
+A particularly surprising example is
+.BR creat (2).
+The name suggests that this system call requires the rights to create
+and write files. However, it also requires the truncate right if an
+existing file under the same name is already present.
+.PP
+It should also be noted that truncating files does not require the
+.B LANDLOCK_ACCESS_FS_WRITE_FILE
+right.  Apart from the
+.BR truncate (2)
+system call, this can also be done through
+.BR open (2)
+with the flags
+.BR "O_RDONLY | O_TRUNC" .
+.PP
+When opening a file, the availability of the
+.B LANDLOCK_ACCESS_FS_TRUNCATE
+right is associated with the newly created file descriptor and will be used for
+subsequent truncation attempts using
+.BR ftruncate (2).
+The behavior is similar to opening a file for reading or writing,
+where permissions are checked during
+.BR open (2),
+but not during the subsequent
+.BR read (2)
+and
+.BR write (2)
+calls.
+.PP
+As a consequence, it is possible to have multiple open file descriptors for the
+same file, where one grants the right to truncate the file and the other does
+not.  It is also possible to pass such file descriptors between processes,
+keeping their Landlock properties, even when these processes do not have an
+enforced Landlock ruleset.
 .SH VERSIONS
 Landlock was introduced in Linux 5.13.
 .PP
@@ -254,6 +326,8 @@ _	_	_
 \^	\^	LANDLOCK_ACCESS_FS_MAKE_SYM
 _	_	_
 2	5.19	LANDLOCK_ACCESS_FS_REFER
+_	_	_
+3	6.2	LANDLOCK_ACCESS_FS_TRUNCATE
 .TE
 .PP
 To query the running kernel's Landlock ABI level, programs may pass
@@ -290,7 +364,6 @@ in kernel logs.
 It is currently not possible to restrict some file-related actions
 accessible through these system call families:
 .BR chdir (2),
-.BR truncate (2),
 .BR stat (2),
 .BR flock (2),
 .BR chmod (2),
@@ -328,7 +401,8 @@ attr.handled_access_fs =
         LANDLOCK_ACCESS_FS_MAKE_FIFO |
         LANDLOCK_ACCESS_FS_MAKE_BLOCK |
         LANDLOCK_ACCESS_FS_MAKE_SYM |
-        LANDLOCK_ACCESS_FS_REFER;
+        LANDLOCK_ACCESS_FS_REFER |;
+        LANDLOCK_ACCESS_FS_TRUNCATE;
 
 ruleset_fd = landlock_create_ruleset(&attr, sizeof(attr), 0);
 if (ruleset_fd == -1) {
Signature · 1 line
2.39.2
#16 lore raw

Re: [PATCH 3/3] landlock.7: Document Landlock ABI v3 (file truncation; kernel 6.2)

Quoted 1 line · Günther Noack

https://lore.kernel.org/all/[email protected]/

We should point to the git (merge) commit once it is merged in the kernel:
https://git.kernel.org/torvalds/c/299e2b1967578b1442128ba8b3e86ed3427d3651

[...]

man7/landlock.7 attr.handled_access_fs = · line 404

Quoted 6 lines
man7/landlock.7 +1 -1
@@ -328,7 +401,8 @@ attr.handled_access_fs =
         LANDLOCK_ACCESS_FS_MAKE_FIFO |
         LANDLOCK_ACCESS_FS_MAKE_BLOCK |
         LANDLOCK_ACCESS_FS_MAKE_SYM |
-        LANDLOCK_ACCESS_FS_REFER;
+        LANDLOCK_ACCESS_FS_REFER |;

trailing ";"

man7/landlock.7 attr.handled_access_fs = · line 408

Quoted 5 lines
man7/landlock.7 +1 -0
+        LANDLOCK_ACCESS_FS_TRUNCATE;
 
 ruleset_fd = landlock_create_ruleset(&attr, sizeof(attr), 0);
 if (ruleset_fd == -1) {

2.39.2

#17 lore raw

Re: [PATCH 3/3] landlock.7: Document Landlock ABI v3 (file truncation; kernel 6.2)

Quoted 4 lines · Mickaël Salaün
Quoted 1 line · Günther Noack

https://lore.kernel.org/all/[email protected]/

We should point to the git (merge) commit once it is merged in the kernel:
https://git.kernel.org/torvalds/c/299e2b1967578b1442128ba8b3e86ed3427d3651

Ah, thanks. Will change it in the next patch version.

Quoted 8 lines

man7/landlock.7 attr.handled_access_fs = · line 404

Quoted 6 lines
man7/landlock.7 +1 -1
@@ -328,7 +401,8 @@ attr.handled_access_fs =
         LANDLOCK_ACCESS_FS_MAKE_FIFO |
         LANDLOCK_ACCESS_FS_MAKE_BLOCK |
         LANDLOCK_ACCESS_FS_MAKE_SYM |
-        LANDLOCK_ACCESS_FS_REFER;
+        LANDLOCK_ACCESS_FS_REFER |;

trailing ";"

Oops. Done.

#18 lore raw

Re: [PATCH 3/3] landlock.7: Document Landlock ABI v3 (file truncation; kernel 6.2)

In reply to Günther Noack

Hi Günther,

Quoted 1 line · Günther Noack

https://lore.kernel.org/all/[email protected]/

Please see some comments below.

Cheers,

Alex

Quoted 9 lines
---
  man7/landlock.7 | 80 +++++++++++++++++++++++++++++++++++++++++++++++--
  1 file changed, 77 insertions(+), 3 deletions(-)
man7/landlock.7 +0 -0
index 6321b56ab..b5b356642 100644

man7/landlock.7 A file can only receive these access rights: · line 66

Quoted 5 lines
man7/landlock.7 +1 -1
@@ -63,10 +63,38 @@ A file can only receive these access rights:
  Execute a file.
  .TP
  .B LANDLOCK_ACCESS_FS_WRITE_FILE
-Open a file with write access.
+Open a file with write access. Note that you might additionally need the

Again,
please use semantic newlines.

Also,
roff(7) requires two spaces after period in source code, to detect sentence endings.
I say this as a curiosity,
since due to the requirement of semantic newlines, we always write a newline after period.

Quoted 21 lines
man7/landlock.7 +18 -0
+.B LANDLOCK_ACCESS_FS_TRUNCATE
+right in order to overwrite files with
+.BR open (2)
+using
+.B O_TRUNC
+or
+.BR creat (2).
  .TP
  .B LANDLOCK_ACCESS_FS_READ_FILE
  Open a file with read access.
+.TP
+.B LANDLOCK_ACCESS_FS_TRUNCATE
+Truncate a file with
+.BR truncate (2),
+.BR ftruncate (2),
+.BR creat (2),
+or
+.BR open (2)
+with
+.BR O_TRUNC .
+Whether an opened file can be truncated with

man7/landlock.7 A file can only receive these access rights: · line 97

Quoted 10 lines
man7/landlock.7 +10 -0
+.BR ftruncate (2)
+is determined during
+.BR open (2),
+in the same way as read and write permissions are checked during
+.BR open (2)
+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.

Maybe it's simpler to say Landlock ABI v3? That's usual convention in software, so not using formal English for that is not a crime :).

Quoted 81 lines
man7/landlock.7 +48 -2
  .PP
  A directory can receive access rights related to files or directories.
  The following access right is applied to the directory itself,
@@ -228,6 +256,50 @@ To be allowed to use
  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 Truncating files
+The operations covered by
+.B LANDLOCK_ACCESS_FS_WRITE_FILE
+and
+.B LANDLOCK_ACCESS_FS_TRUNCATE
+both change the contents of a file and sometimes overlap in
+non-intuitive ways. It is recommended to always specify both of these
+together.
+.PP
+A particularly surprising example is
+.BR creat (2).
+The name suggests that this system call requires the rights to create
+and write files. However, it also requires the truncate right if an
+existing file under the same name is already present.
+.PP
+It should also be noted that truncating files does not require the
+.B LANDLOCK_ACCESS_FS_WRITE_FILE
+right.  Apart from the
+.BR truncate (2)
+system call, this can also be done through
+.BR open (2)
+with the flags
+.BR "O_RDONLY | O_TRUNC" .
+.PP
+When opening a file, the availability of the
+.B LANDLOCK_ACCESS_FS_TRUNCATE
+right is associated with the newly created file descriptor and will be used for
+subsequent truncation attempts using
+.BR ftruncate (2).
+The behavior is similar to opening a file for reading or writing,
+where permissions are checked during
+.BR open (2),
+but not during the subsequent
+.BR read (2)
+and
+.BR write (2)
+calls.
+.PP
+As a consequence, it is possible to have multiple open file descriptors for the
+same file, where one grants the right to truncate the file and the other does
+not.  It is also possible to pass such file descriptors between processes,
+keeping their Landlock properties, even when these processes do not have an
+enforced Landlock ruleset.
  .SH VERSIONS
  Landlock was introduced in Linux 5.13.
  .PP
@@ -254,6 +326,8 @@ _	_	_
  \^	\^	LANDLOCK_ACCESS_FS_MAKE_SYM
  _	_	_
  2	5.19	LANDLOCK_ACCESS_FS_REFER
+_	_	_
+3	6.2	LANDLOCK_ACCESS_FS_TRUNCATE
  .TE
  .PP
  To query the running kernel's Landlock ABI level, programs may pass
@@ -290,7 +364,6 @@ in kernel logs.
  It is currently not possible to restrict some file-related actions
  accessible through these system call families:
  .BR chdir (2),
-.BR truncate (2),
  .BR stat (2),
  .BR flock (2),
  .BR chmod (2),
@@ -328,7 +401,8 @@ attr.handled_access_fs =
          LANDLOCK_ACCESS_FS_MAKE_FIFO |
          LANDLOCK_ACCESS_FS_MAKE_BLOCK |
          LANDLOCK_ACCESS_FS_MAKE_SYM |
-        LANDLOCK_ACCESS_FS_REFER;
+        LANDLOCK_ACCESS_FS_REFER |;
+        LANDLOCK_ACCESS_FS_TRUNCATE;
 
  ruleset_fd = landlock_create_ruleset(&attr, sizeof(attr), 0);
  if (ruleset_fd == -1) {
Signature · 2 lines
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
#19 lore raw

Re: [PATCH 3/3] landlock.7: Document Landlock ABI v3 (file truncation; kernel 6.2)

Quoted 6 lines · Alex Colomar
Quoted 1 line · Günther Noack

+Open a file with write access. Note that you might additionally need the

Again,
please use semantic newlines.

Quoted 6 lines

Also,
roff(7) requires two spaces after period in source code, to detect sentence endings.
I say this as a curiosity,
since due to the requirement of semantic newlines, we always write a newline after period.

Applied semantic newlines. There are no single-space sentence ends left.

Quoted 6 lines
Quoted 6 lines
man7/landlock.7 +6 -0
+Whether an opened file can be truncated with
+.BR ftruncate (2)
+is determined during
+.BR open (2),
+in the same way as read and write permissions are checked during
+.BR open (2)
Quoted 8 lines

man7/landlock.7 A file can only receive these access rights: · line 97

Quoted 5 lines
man7/landlock.7 +5 -0
+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.

Maybe it's simpler to say Landlock ABI v3? That's usual convention in software, so not using formal English for that is not a crime :).

Hm, I took that sentence from the kernel documentation, and I would like to avoid deviating in minor wording aspects.
https://docs.kernel.org/userspace-api/landlock.html

I would be in favor of "ABI v3" as well though, for brevity. Mickaël, do you have a strong opinion on this?

Thank you for the review!
–Günther

#20 lore raw
In reply to Günther Noack

Hi Günther,

Quoted 3 lines · Günther Noack

Putting the warning there makes it more prominent. CAVEATS is a standard section that exists in many man pages and is also described in man-pages(7).

Patch applied.

Thanks,

Alex

Quoted 19 lines
---
  man7/landlock.7 | 2 +-
  1 file changed, 1 insertion(+), 1 deletion(-)
man7/landlock.7 +1 -1
index 0818b4bf9..099f68067 100644
@@ -201,7 +201,7 @@ command line parameter and further to the value of
  We can check that Landlock is enabled by looking for
  .I landlock: Up and running.
  in kernel logs.
-.PP
+.SH CAVEATS
  It is currently not possible to restrict some file-related actions
  accessible through these system call families:
  .BR chdir (2),

base-commit: 887b913eb2687f34bc056597c0501a4325bebf28

Signature · 2 lines
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5