Documentation/filesystems/idmappings.rst

1 .. SPDX-License-Identifier: GPL-2.0
12 ------------
32  u22 -> k10000
33  u23 -> k10001
34  u24 -> k10002
36 From a mathematical viewpoint ``U`` and ``K`` are well-ordered sets and an
38 order isomorphic. In fact, ``U`` and ``K`` are always well-ordered subsets of
45  k10000 -> u22
46  k10001 -> u23
47  k10002 -> u24
64 mapping ``k11000`` up to ``u1000``. Afterwards, we can map ``u1000`` down using
81 ``(uid_t)-1`` or overflowgid ``(gid_t)-1`` to userspace.
88 - If we want to map from left to right::
91    id - u + k = n
93 - If we want to map from right to left::
96    id - k + u = n
99 left" we can also say "up". Obviously mapping down and up invert each other.
109 idmapping. So we're mapping up in the first idmapping::
111  id     - k      + u  = n
112  k21000 - k20000 + u0 = u1000
119  id    - u    + k      = n
120  u1100 - u500 + k30000 = k30600
123 -------------
128  userspace-id:kernel-id:range
168 Other user namespaces usually have non-identity idmappings such as::
180 - If a filesystem were to be mounted in the initial user namespaces (as most
186 - If a filesystem were to be mounted with an idmapping of ``u0:k10000:r10000``
191 ----------------------
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
215  /* Map the kernel id up into a userspace id in the second idmapping. */
224  /* Map the kernel id up into a userspace id in the first idmapping. */
240 ownership information about the file the kernel can't simply map the id back up
244 So the kernel will map the id back up in the idmapping of the caller. Let's
246 ``u3000:k20000:r10000`` then ``k21000`` would map back up to ``u4000``.
256 Let's look at an example. We are given the following two idmappings::
265 1. Map the kernel id up into a userspace id in the first idmapping::
267     /* Map the kernel id up into a userspace id in the first idmapping. */
286 1. Map the kernel id up into a userspace id in the second idmapping::
288     /* Map the kernel id up into a userspace id in the second idmapping. */
296 Another way to look at this translation is to treat it as inverting one
317  /* Map the kernel id up into a userspace id in the first idmapping. */
320  /* INVALID: Map the userspace id up into a userspace id in the second idmapping. */
329 -------------------------------------------
331 The concepts of mapping an id down or mapping an id up are expressed in the two
338  /* Map the kernel id up into a userspace id. */
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
348 When creating a filesystem object the caller will look at the caller's
359    (To be precise, the kernel will simply look at the kernel ids stashed in the
362 2. Verify that the caller's kernel ids can be mapped up to userspace ids in the
366 the kernel id back up into a userspace id when writing to disk.
374 caller's idmapping and then maps that kernel id up according to the
380     - caller's idmapping (usually taken from ``current_user_ns()``)
381     - filesystem's idmapping (``sb->s_user_ns``)
382     - mount's idmapping (``mnt_idmap(vfsmnt)``)
430 2. Verify that the caller's kernel ids can be mapped up to userspace ids in the
433     from_kuid(u0:k20000:r10000, k11000) = u-1
437 ids could not be mapped up according to the filesystem's idmapping. So the
441 mounted with non-initial idmappings this is a general problem as we can see in
458 2. Verify that the caller's kernel ids can be mapped up to userspace ids in the
471 filesystems and not very flexible. But this is a use-case that is pretty
476 kernel ids map up into valid userspace ids in the caller's idmapping
482 2. Map kernel ids up to userspace ids in the caller's idmapping::
484     from_kuid(u0:k10000:r10000, k1000) = u-1
503 2. Map the kernel id up into a userspace id in the caller's idmapping::
505     from_kuid(u0:k10000:r10000, k1000) = u-1
508 filesystem idmapping cannot be mapped up to a userspace id in the caller's
529 2. Map the kernel id up into a userspace id in the caller's idmapping::
531     from_kuid(u0:k10000:r10000, k21000) = u-1
548 2. Map the kernel id up into a userspace id in the caller's idmapping::
553 -----------------------------
559 each other, an administrator may often use different non-overlapping idmappings
566 An administrator wanting to provide easy read-write access to the following set
662  uid_t <--> kuid_t <--> vfsuid_t
663  gid_t <--> kgid_t <--> vfsgid_t
702 of the remapping algorithm we've introduced earlier. We're going to look at:
704 - ``i_uid_into_vfsuid()`` and ``i_gid_into_vfsgid()``
709    /* Map the filesystem's kernel id up into a userspace id in the filesystem's idmapping. */
715 - ``mapped_fsuid()`` and ``mapped_fsgid()``
721    /* Map the caller's VFS id up into a userspace id in the mount's idmapping. */
727 - ``vfsuid_into_kuid()`` and ``vfsgid_into_kgid()``
744 kernel id up to a userspace id in the caller's idmapping.
751    /* Map the filesystem's kernel id up into a userspace id. */
770 be mapped up in the filesystem's idmapping directly this creation request
778     /* Map the caller's kernel id up into a userspace id in the mount's idmapping. */
784 When finally writing to disk the kernel will then map ``v21000`` up into a
790 As we can see, we end up with an invertible and therefore information
807 When the caller is using a non-initial idmapping the common case is to attach
818       /* Map the VFS id up into a userspace id in the mount's idmapping. */
851        /* Map the VFS id up into a userspace id in the mount's idmapping. */
885       /* Map the kernel id up into a userspace id in the filesystem's idmapping. */
891 3. Map the VFS id up into a userspace id in the caller's idmapping::
922       /* Map the kernel id up into a userspace id in the filesystem's idmapping. */
928 3. Map the VFS id up into a userspace id in the caller's idmapping::
942 idmappings when either the caller, the filesystem or both uses a non-initial
944 a non-initial idmapping. This mostly happens in the context of containerized
946 mounted with the initial idmapping and filesystems mounted with non-initial
956 and files on a per-mount basis.
964 lax permissions or ACLs and even if they can, they will end up with an annoying
969 depending on what ownership they would prefer to end up on the portable storage
991       /* Map the VFS id up into a userspace id in the mount's idmapping. */
1004 Now let's briefly look at what ownership the caller with id ``u1125`` will see
1022       /* Map the kernel id up into a userspace id in the filesystem's idmapping. */
1028 3. Map the VFS id up into a userspace id in the caller's idmapping::