[PATCH 0/4] mount_setattr.2: updates

[PATCH 0/4] mount_setattr.2: updates

[Christian Brauner]

From: "Christian Brauner (Microsoft)" <brauner@kernel.org>

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

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

[Christian Brauner]

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) <brauner@kernel.org>
---
 man2/mount_setattr.2 | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/man2/mount_setattr.2 b/man2/mount_setattr.2
index 77233f589..2bf1b24da 100644
--- a/man2/mount_setattr.2
+++ b/man2/mount_setattr.2
@@ -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
-- 
2.34.1

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

[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) <brauner@kernel.org>
---
 man2/mount_setattr.2 | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/man2/mount_setattr.2 b/man2/mount_setattr.2
index 2bf1b24da..0999373d6 100644
--- a/man2/mount_setattr.2
+++ b/man2/mount_setattr.2
@@ -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
-- 
2.34.1

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

[Christian Brauner]

Update list of filesystems that support ID-mapped mounts.

Signed-off-by: Christian Brauner (Microsoft) <brauner@kernel.org>
---
 man2/mount_setattr.2 | 43 ++++++++++++++++++++++++++++++++++++-------
 1 file changed, 36 insertions(+), 7 deletions(-)

diff --git a/man2/mount_setattr.2 b/man2/mount_setattr.2
index 0999373d6..13d66db4f 100644
--- a/man2/mount_setattr.2
+++ b/man2/mount_setattr.2
@@ -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
-- 
2.34.1

[PATCH 4/4] mount_setattr.2: ffix

[Christian Brauner]

Fix a typo in my name.

Signed-off-by: Christian Brauner (Microsoft) <brauner@kernel.org>
---
 man2/mount_setattr.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man2/mount_setattr.2 b/man2/mount_setattr.2
index 13d66db4f..f1b73e370 100644
--- a/man2/mount_setattr.2
+++ b/man2/mount_setattr.2
@@ -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
-- 
2.34.1

Re: [PATCH 0/4] mount_setattr.2: updates

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 2507 bytes --]

Hi, Christian!

On 6/7/22 15:38, Christian Brauner wrote:
> From: "Christian Brauner (Microsoft)" <brauner@kernel.org>
> 
> 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


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

diff --git a/man2/mount_setattr.2 b/man2/mount_setattr.2
index 718a4adae..352c8e852 100644
--- a/man2/mount_setattr.2
+++ b/man2/mount_setattr.2
@@ -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


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

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 0/4] mount_setattr.2: updates

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1100 bytes --]

On 6/7/22 15:38, Christian Brauner wrote:
> From: "Christian Brauner (Microsoft)" <brauner@kernel.org>
> 
> 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

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

> 
>   man2/mount_setattr.2 | 64 +++++++++++++++++++++++++++++++++++---------
>   1 file changed, 52 insertions(+), 12 deletions(-)
> 
> 
> base-commit: ae6b221882ce71ba82fcdbe02419a225111502f0


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

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]