Skip to contentSkip to conversation

mount_setattr.2: updates

PATCH In review Christian Brauner 2 participants 7 messages Jun 7, 2022 – Jun 8, 2022 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore

Christian Brauner

author
#0 lore raw

cover mount_setattr.2: updates

From: "Christian Brauner (Microsoft)" <[email protected]>

Hey everyone,

Here's a set of updates for the mount_setattr.2 man page. I would really appreciate it if groff syntax could be fixed up by maintainers. I tried my best to remember the guidelines though. :)

Thanks!
Christian

Christian Brauner (4):
mount_setattr.2: add and explain missing EBUSY error mount_setattr.2: update conditions to create ID-mapped mounts mount_setattr.2: update list of supported filesystems mount_setattr.2: ffix

 man2/mount_setattr.2 | 64 +++++++++++++++++++++++++++++++++++---------
 1 file changed, 52 insertions(+), 12 deletions(-)

base-commit: ae6b221882ce71ba82fcdbe02419a225111502f0

Signature · 1 line
2.34.1
author
#1 lore raw

PATCH 1/4 mount_setattr.2: add and explain missing EBUSY error

In order to ID-map a mount it must not have any writers. If the mount has writers and the caller tries to ID-map the mount EBUSY will be returned.

Signed-off-by Christian Brauner (Microsoft) <[email protected]>
---
 man2/mount_setattr.2 | 10 ++++++++++
 1 file changed, 10 insertions(+)
man2/mount_setattr.2 +10 -0
index 77233f589..2bf1b24da 100644
@@ -429,6 +429,13 @@ The caller tried to change the mount to
 .BR MOUNT_ATTR_RDONLY ,
 but the mount still holds files open for writing.
 .TP
+.B EBUSY
+The caller tried to create an ID-mapped mount raising
+.BR MOUNT_ATTR_IDMAP
+and specifying
+.I userns_fd
+but the mount still holds files open for writing.
+.TP
 .B EINVAL
 The pathname specified via the
 .I dirfd

@@ -662,6 +669,9 @@ This also implies that the ID mapping of a mount cannot be altered.
 The mount must be a detached mount;
 that is,
 it must have been created by calling
+.IP \(bu
+The mount must not have any writers.
+.\" commit 1bbcd277a53e08d619ffeec56c5c9287f2bf42f
 .BR open_tree (2)
 with the
 .B OPEN_TREE_CLONE
Signature · 1 line
2.34.1
author
#2 lore raw

PATCH 2/4 mount_setattr.2: update conditions to create ID-mapped mounts

In reply to Christian Brauner

Newer kernels in principle support the creation of ID-mapped mounts for filesystems mountable in non-initial user namespaces. Currently, no such filesystem has been ported to support this though. But we should nonetheless update the conditions.

Signed-off-by Christian Brauner (Microsoft) <[email protected]>
---
 man2/mount_setattr.2 | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)
man2/mount_setattr.2 +5 -4
index 2bf1b24da..0999373d6 100644
@@ -649,10 +649,11 @@ The following conditions must be met in order to create an ID-mapped mount:
 .IP \(bu 3
 The caller must have the
 .B CAP_SYS_ADMIN
-capability in the initial user namespace.
-.IP \(bu
-The filesystem must be mounted in a mount namespace
-that is owned by the initial user namespace.
+capability in the user namespace the filesystem was mounted in.
+.\" commit bd303368b776eead1c29e6cdda82bde7128b82a7
+.\" Christian Brauner
+.\"     Note, currently no filesystems mountable in non-initial user namespaces
+.\"     support ID-mapped mounts.
 .IP \(bu
 The underlying filesystem must support ID-mapped mounts.
 Currently, the
Signature · 1 line
2.34.1
author
#3 lore raw

PATCH 3/4 mount_setattr.2: update list of supported filesystems

In reply to Christian Brauner

Update list of filesystems that support ID-mapped mounts.

Signed-off-by Christian Brauner (Microsoft) <[email protected]>
---
 man2/mount_setattr.2 | 43 ++++++++++++++++++++++++++++++++++++-------
 1 file changed, 36 insertions(+), 7 deletions(-)
man2/mount_setattr.2 +36 -7
index 0999373d6..13d66db4f 100644
@@ -656,14 +656,43 @@ capability in the user namespace the filesystem was mounted in.
 .\"     support ID-mapped mounts.
 .IP \(bu
 The underlying filesystem must support ID-mapped mounts.
-Currently, the
-.BR xfs (5),
-.BR ext4 (5),
-and
-.B FAT
-filesystems support ID-mapped mounts
-with more filesystems being actively worked on.
+Currently, the following filesystems support ID-mapped mounts:
+.\" fs_flags = FS_ALLOW_IDMAP in kernel sources
+.PP
+.RS 3
+.PD 0
+.IP \(bu 3
+.BR xfs (5)
+(since Linux 5.12)
+.IP \(bu
+.BR ext4 (5)
+(since Linux 5.12)
+.IP \(bu
+.BR FAT
+(since Linux 5.12)
+.IP \(bu
+.BR btrfs (5)
+(since Linux 5.15)
+.\" commit 5b9b26f5d0b88b74001dcfe4ab8a8f2f4e744112
 .IP \(bu
+.BR ntfs3
+(since Linux 5.15)
+.\" commit 82cae269cfa953032fbb8980a7d554d60fb00b17
+.IP \(bu
+.BR f2fs
+(since Linux 5.18)
+.\" commit 984fc4e76d63345499f01c0c198a4b44860cf027
+.IP \(bu
+.BR erofs
+(since Linux 5.19)
+.\" commit 6c459b78d4793afbba6d864c466cc5cd2932459d
+.IP \(bu
+.BR overlayfs
+(ID-mapped lower and upper layers supported since Linux 5.19)
+.PD
+.RE
+.PP
+.IP \(bu 3
 The mount must not already be ID-mapped.
 This also implies that the ID mapping of a mount cannot be altered.
 .IP \(bu
Signature · 1 line
2.34.1
author
#4 lore raw

PATCH 4/4 mount_setattr.2: ffix

In reply to Christian Brauner

Fix a typo in my name.

Signed-off-by Christian Brauner (Microsoft) <[email protected]>
---
 man2/mount_setattr.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man2/mount_setattr.2 +1 -1
index 13d66db4f..f1b73e370 100644
@@ -543,7 +543,7 @@ a new peer group ID needs to be allocated for all mounts without a peer group
 ID set.
 This allocation failed because
 the kernel has run out of IDs.
-.\" Christian Bruner: i.e. someone has somehow managed to
+.\" Christian Brauner: i.e. someone has somehow managed to
 .\" allocate so many peer groups and managed to keep the kernel running
 .\" (???) that the ida has ran out of ids
 .\" Note that technically further error codes are possible that are
Signature · 1 line
2.34.1
#5 lore raw
In reply to Christian Brauner

Hi, Christian!

Quoted 7 lines · Christian Brauner

From: "Christian Brauner (Microsoft)" <[email protected]>

Hey everyone,

Here's a set of updates for the mount_setattr.2 man page. I would really appreciate it if groff syntax could be fixed up by maintainers. I tried my best to remember the guidelines though. :)

Sure! Mostly looks good. Applied; and I applied a small patch on top of them.

Just a small reminder from man(7):
.B Bold

.BI Bold alternating with italic

.BR Bold alternating with Roman

I fixed the current pages to have a consistent style. You can check out the alx/main branch from the official kernel.org repo.

Thanks,
Alex

Quoted 10 lines

Thanks!
Christian

Christian Brauner (4):
mount_setattr.2: add and explain missing EBUSY error mount_setattr.2: update conditions to create ID-mapped mounts mount_setattr.2: update list of supported filesystems mount_setattr.2: ffix

Quoted 5 lines
  man2/mount_setattr.2 | 64 +++++++++++++++++++++++++++++++++++---------
  1 file changed, 52 insertions(+), 12 deletions(-)

base-commit: ae6b221882ce71ba82fcdbe02419a225111502f0

man2/mount_setattr.2 +6 -6
index 718a4adae..352c8e852 100644
@@ -414,7 +414,7 @@ but the mount still holds files open for writing.
 .TP
 .B EBUSY
 The caller tried to create an ID-mapped mount raising
-.BR MOUNT_ATTR_IDMAP
+.B MOUNT_ATTR_IDMAP
 and specifying
 .I userns_fd
 but the mount still holds files open for writing.

@@ -651,26 +651,26 @@ Currently, the following filesystems support ID-mapped mounts:
 .BR ext4 (5)
 (since Linux 5.12)
 .IP \(bu
-.BR FAT
+.B FAT
 (since Linux 5.12)
 .IP \(bu
 .BR btrfs (5)
 (since Linux 5.15)
 .\" commit 5b9b26f5d0b88b74001dcfe4ab8a8f2f4e744112
 .IP \(bu
-.BR ntfs3
+.B ntfs3
 (since Linux 5.15)
 .\" commit 82cae269cfa953032fbb8980a7d554d60fb00b17
 .IP \(bu
-.BR f2fs
+.B f2fs
 (since Linux 5.18)
 .\" commit 984fc4e76d63345499f01c0c198a4b44860cf027
 .IP \(bu
-.BR erofs
+.B erofs
 (since Linux 5.19)
 .\" commit 6c459b78d4793afbba6d864c466cc5cd2932459d
 .IP \(bu
-.BR overlayfs
+.B overlayfs
 (ID-mapped lower and upper layers supported since Linux 5.19)
 .PD
 .RE
Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#6 lore raw
In reply to Christian Brauner
Quoted 8 lines · Christian Brauner

From: "Christian Brauner (Microsoft)" <[email protected]>

Hey everyone,

Here's a set of updates for the mount_setattr.2 man page. I would really appreciate it if groff syntax could be fixed up by maintainers. I tried my best to remember the guidelines though. :)

Quoted 8 lines

Thanks!
Christian

Christian Brauner (4):
mount_setattr.2: add and explain missing EBUSY error mount_setattr.2: update conditions to create ID-mapped mounts mount_setattr.2: update list of supported filesystems mount_setattr.2: ffix

BTW, for next time, it would help if you put the people that are CCd in the thread also in the patches as "Cc: ...". That would help a lot!

Cheers,

Alex

Quoted 6 lines
  man2/mount_setattr.2 | 64 +++++++++++++++++++++++++++++++++++---------
  1 file changed, 52 insertions(+), 12 deletions(-)

base-commit: ae6b221882ce71ba82fcdbe02419a225111502f0

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/