From 20e6e6ed79b28ecdcbbf1681a1de5d9029eb93ac Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Thu, 12 Aug 2021 05:41:56 +0200 Subject: [PATCH] mount_setattr.2: Clarify the description of "detached" mounts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From email: >> Thanks. I made it "detached". Elsewhere, the page already explains >> that a detached mount is one that: >> >> must have been created by calling open_tree(2) with the >> OPEN_TREE_CLONE flag and it must not already have been >> visible in the filesystem. >> >> Which seems a fine explanation. >> >> ???? >> But, just a thought... "visible in the filesystem" seems not quite accurate. >> What you really mean I guess is that it must not already have been >> /visible in the filesystem hierarchy/previously mounted/something else/, >> right? I suppose that I should have clarified that my main problem was that you were using the word "filesystem" in a way that I find unconventional/ambiguous. I mean, I normally take the term "filesystem" to be "a storage system for folding files". Here, you are using "filesystem" to mean something else, what I might call like "the single directory hierarchy" or "the filesystem hierarchy" or "the list of mount points". > A detached mount is created via the OPEN_TREE_CLONE flag. It is a > separate new mount so "previously mounted" is not applicable. > A detached mount is _related_ to what the MS_BIND flag gives you with > mount(2). However, they differ conceptually and technically. A MS_BIND > mount(2) is always visible in the fileystem when mount(2) returns, i.e. > it is discoverable by regular path-lookup starting within the > filesystem. > > However, a detached mount can be seen as a split of MS_BIND into two > distinct steps: > 1. fd_tree = open_tree(OPEN_TREE_CLONE): create a new mount > 2. move_mount(fd_tree, ): attach the mount to the filesystem > > 1. and 2. together give you the equivalent of MS_BIND. > In between 1. and 2. however the mount is detached. For the kernel > "detached" means that an anonymous mount namespace is attached to it > which doen't appear in proc and has a 0 sequence number (Technically, > there's a bit of semantical argument to be made that "attached" and > "detached" are ambiguous as they could also be taken to mean "does or > does not have a parent mount". This ambiguity e.g. appears in > do_move_mount(). That's why the kernel itself calls it an "anonymous > mount". However, an OPEN_TREE_CLONE-detached mount of course doesn't > have a parent mount so it works.). > > For userspace it's better to think of detached and attached in terms of > visibility in the filesystem or in a mount namespace. That's more > straightfoward, more relevant, and hits the target in 90% of the cases. > > However, the better and clearer picture is to say that a > OPEN_TREE_CLONE-detached mount is a mount that has never been > move_mount()ed. Which in turn can be defined as the detached mount has > never been made visible in a mount namespace. Once that has happened the > mount is irreversibly an attached mount. > > I keep thinking that maybe we should just say "anonymous mount" > everywhere. So changing the wording to: I'm not against the word "detached". To user space, I think it is a little more meaningful than "anonymous". For the moment, I'll stay with "detached", but if you insist on "anonymous", I'll probably change it. > [...] > EINVAL The mount that is to be ID mapped is not an anonymous mount; > that is, the mount has already been visible in a mount namespace. I like that text *a lot* better! Thanks very much for suggesting wordings. It makes my life much easier. I've made the text: EINVAL The mount that is to be ID mapped is not a detached mount; that is, the mount has not previously been visible in a mount namespace. > [...] > The mount must be an anonymous mount; that is, it must have been > created by calling open_tree(2) with the OPEN_TREE_CLONE flag and it > must not already have been visible in a mount namespace, i.e. it must > not have been attached to the filesystem hierarchy with syscalls such > as move_mount() syscall. And that too! I've made the text: • The mount must be a detached mount; that is, it must have been created by calling open_tree(2) with the OPEN_TREE_CLONE flag and it must not already have been visible in a mount namespace. (To put things another way: the mount must not have been attached to the filesystem hierarchy with a system call such as move_mount(2).) Reported-by: Christian Brauner Signed-off-by: Michael Kerrisk --- man2/mount_setattr.2 | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/man2/mount_setattr.2 b/man2/mount_setattr.2 index 6ffe5e009..aa893f8c0 100644 --- a/man2/mount_setattr.2 +++ b/man2/mount_setattr.2 @@ -502,7 +502,7 @@ The underlying filesystem does not support ID-mapped mounts. .TP .B EINVAL The mount that is to be ID mapped is not a detached mount; -that is, the mount is already visible in the filesystem. +that is, the mount has not previously been visible in a mount namespace. .TP .B EINVAL A partial access-time setting was specified in @@ -652,7 +652,11 @@ it must have been created by calling .BR open_tree (2) with the .B OPEN_TREE_CLONE -flag and it must not already have been visible in the filesystem. +flag and it must not already have been visible in a mount namespace. +(To put things another way: +the mount must not have been attached to the filesystem hierarchy +with a system call such as +.BR move_mount (2).) .PP ID mappings can be created for user IDs, group IDs, and project IDs. An ID mapping is essentially a mapping of a range of user or group IDs into