Documentation/filesystems/idmappings.rst

23 on, we will always prefix ids with ``u`` or ``k`` to make it clear whether
24 we're talking about an id in the upper or lower idmapset.
42 that make it easier to understand how we can translate between idmappings. For
43 example, we know that the inverse idmapping is an order isomorphism as well::
49 Given that we are dealing with order isomorphisms plus the fact that we're
50 dealing with subsets we can embed idmappings into each other, i.e. we can
51 sensibly translate between different idmappings. For example, assume we've been
61 Because we're dealing with order isomorphic subsets it is meaningful to ask
64 mapping ``k11000`` up to ``u1000``. Afterwards, we can map ``u1000`` down using
69 If we were given the same task for the following three idmappings::
75 we would fail to translate as the sets aren't order isomorphic over the full
79 an id mapped. We can simply say that ``u1000`` is unmapped in the second and
83 The algorithm to calculate what a given id maps to is pretty simple. First, we
84 need to verify that the range can contain our target id. We will skip this step
85 for simplicity. After that if we want to know what ``id`` maps to we can do
88 - If we want to map from left to right::
93 - If we want to map from right to left::
98 Instead of "left to right" we can also say "down" and instead of "right to
99 left" we can also say "up". Obviously mapping down and up invert each other.
107 Assume we are given ``k21000`` in the lower idmapset of the first idmapping. We
109 idmapping. So we're mapping up in the first idmapping::
114 Now assume we are given the id ``u1100`` in the upper idmapset of the second
115 idmapping and we want to know what this id maps down to in the lower idmapset
116 of the second idmapping. This means we're mapping down in the second
142 Note that we are only concerned with idmappings as the kernel stores them not
145 For the rest of this document we will prefix all userspace ids with ``u`` and
155 with user namespaces. Since we mainly care about how idmappings work we're not
181   filesystems are) then the initial idmapping will be used. As we saw this is
193 We've already seen briefly that it is possible to translate between different
194 idmappings. We'll now take a closer look how that works.
203 If we've been given ``k11000`` from one idmapping we can map that id up in
211 and we are mapping ``u1000`` down to ``k11000`` in the first idmapping . We can
218 Note, how we can get back to the kernel id in the first idmapping by inverting
256 Let's look at an example. We are given the following two idmappings::
261 and we are given ``k11000`` in the first idmapping. In order to translate this
262 kernel id in the first idmapping into a kernel id in the second idmapping we
275 As you can see we used the userspace idmapset in both idmappings to translate
278 This allows us to answer the question what kernel id we would need to use to
283 Note, how we can easily get back to the kernel id in the first idmapping by
332 kernel functions filesystem developers are rather familiar with and which we've
341 We will take an abbreviated look into how idmappings figure into creating
342 filesystem objects. For simplicity we will only look at what happens when the
344 itself. So we're concerned with what happens when e.g. ``vfs_mkdir()`` is
345 called. We will also assume that the directory we're creating filesystem
352 the caller but can differ. We will just assume they are always identical to not
360    credentials of the current task but for our education we'll pretend this
372 crossmapping algorithm we mentioned above in a previous section. First, the
385 idmappings. This will exhibit some problems we can hit. After that we will
387 they can solve the problems we observed before.
441 mounted with non-initial idmappings this is a general problem as we can see in
463 We can see that the translation always succeeds. The userspace id that the
468 First, that we can't allow a caller to ultimately write to disk with another
469 userspace id. We could only do this if we were to mount the whole filesystem
540 idmapping it would be trivial. So we only consider a filesystem with an
555 The examples we've seen in the previous section where the caller's idmapping
622 idmapping and vica versa using the remapping algorithm we introduced above.
636 mountable inside user namespaces. We will touch on this further below.
641 With the introduction of idmapped mounts we need to distinguish between
650 then we will use the ``kuid_t`` and ``kgid_t`` types. However, if a uid or gid
651 has been generated using a mount idmapping then we will be using the dedicated
655 ``vfsuid_t`` and ``vfsgid_t`` types and we will be able to rely on the compiler
665 Whenever we report ownership based on a ``vfsuid_t`` or ``vfsgid_t`` type,
667 based on a ``vfsuid_t`` or ``vfsgid_t`` type, e.g., during ``chown()`` we can
670 To illustrate why this helper currently exists, consider what happens when we
671 change ownership of an inode from an idmapped mount. After we generated
672 a ``vfsuid_t`` or ``vfsgid_t`` based on the mount idmapping we later commit to
674 Thus, we are turning the ``vfsuid_t`` or ``vfsgid_t`` into a global ``kuid_t``
683 We already noted that ``vfsuid_t`` and ``vfsgid_t`` types are generated based
694 Similar to how we prefix all userspace ids in this document with ``u`` and all
695 kernel ids with ``k`` we will prefix all VFS ids with ``v``. So a mount
702 of the remapping algorithm we've introduced earlier. We're going to look at:
764 We can test whether this algorithm really works by verifying what happens when
765 we create a new file. Let's say the user is creating a file with ``u1000``.
790 As we can see, we end up with an invertible and therefore information
808 the same idmapping to the mount. We now perform three steps:
875 the translation algorithm we introduced earlier:
912 steps using the translation algorithm we introduced earlier:
941 We've seen above how idmapped mounts can be used to translate between
945 workloads. The consequence is as we have seen that for both, filesystem's
950 As we've seen above idmapped mounts provide a solution to this by remapping the
975 when they create a file the kernel performs the following steps we already know