Documentation/filesystems/idmappings.rst

6 Most filesystem developers will have encountered idmappings. They are used when
23 on, we will always prefix ids with ``u`` or ``k`` to make it clear whether
30 and write down the mappings it will generate::
41 Looking at this mathematically briefly will help us highlight some properties
80 third idmapping. The kernel will report unmapped ids as the overflowuid
84 need to verify that the range can contain our target id. We will skip this step
133 "userspace id" will be used to refer to the well known ``uid_t`` and ``gid_t``
134 types and "kernel id" will be used to refer to ``kuid_t`` and ``kgid_t``.
145 For the rest of this document we will prefix all userspace ids with ``u`` and
146 all kernel ids with ``k``. Ranges of idmappings will be prefixed with ``r``. So
147 an idmapping will be written as ``u0:k10000:r10000``.
181   filesystems are) then the initial idmapping will be used. As we saw this is
236 means ``u1000`` will be mapped to ``k21000`` which is what will be stored in
244 So the kernel will map the id back up in the idmapping of the caller. Let's
298 userspace id mapped. This will come in handy when working with idmapped mounts.
325 ``kuid_t`` and ``kgid_t`` the compiler will throw an error when they are
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
345 called. We will also assume that the directory we're creating filesystem
348 When creating a filesystem object the caller will look at the caller's
352 the caller but can differ. We will just assume they are always identical to not
359    (To be precise, the kernel will simply look at the kernel ids stashed in the
365 The second step is important as regular filesystem will ultimately need to map
368 written to disk. If it can't the kernel will refuse the creation request to not
371 The astute reader will have realized that this is simply a variation of the
385 idmappings. This will exhibit some problems we can hit. After that we will
407    For this second step the kernel will call the function
414 on. Ultimately the userspace id that lands on disk will be ``u1000``.
438 kernel will deny this creation request.
464 filesystem will ultimately put to disk will always be identical to the value of
474 Second, the caller will usually not be able to create any files or access
509 idmapping. Thus, the kernel will report the ownership of this file as the
535 idmapping. Thus, the kernel will report the ownership of this file as the
592 different login userspace ids. Most users will have ``u1000`` as the login id
593 on their machine at home and all files in their home directory will usually be
636 mountable inside user namespaces. We will touch on this further below.
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
692 a filesystem or caller idmapping will cause a compilation error.
695 kernel ids with ``k`` we will prefix all VFS ids with ``v``. So a mount
696 idmapping will be written as: ``u0:v10000:r10000``.
746 But when the caller is accessing the file on an idmapped mount the kernel will
757 Finally, when the kernel reports the owner to the caller it will turn the
773 But when the caller is accessing the file on an idmapped mount the kernel will
784 When finally writing to disk the kernel will then map ``v21000`` up into a
791 preserving algorithm. A file created from ``u1000`` on an idmapped mount will
829 So the ownership that lands on disk will be ``u1000``.
862 So the ownership that lands on disk will be ``u1000``.
898 filesystem's idmapping via the mount's idmapping. The file will now be created
964 lax permissions or ACLs and even if they can, they will end up with an annoying
1002 So ultimately the file will be created with ``u1000`` on disk.
1004 Now let's briefly look at what ownership the caller with id ``u1125`` will see
1033 So ultimately the caller will be reported that the file belongs to ``u1125``
1039 idmapping they will see all those files owned by ``u1000``.