From: Sebastien Buisson Date: Thu, 20 Mar 2025 16:09:14 +0000 (+0100) Subject: LUDOC-550 sec: doc update for nodemap mapping offset X-Git-Url: https://git.whamcloud.com/?a=commitdiff_plain;h=refs%2Fchanges%2F83%2F58483%2F6;p=doc%2Fmanual.git LUDOC-550 sec: doc update for nodemap mapping offset This patch adds the "Defining Mapping Offsets" section in the Lustre Operations Manual to introduce mapping offset capability as implemented by LU-18109. Signed-off-by: Sebastien Buisson Change-Id: I7ff2aeb5f32b2783ae27a54a7ff3f1ed4b4f9335 Reviewed-on: https://review.whamcloud.com/c/doc/manual/+/58483 Tested-by: jenkins Reviewed-by: Marc Vef Reviewed-by: Andreas Dilger --- diff --git a/LustreNodemap.xml b/LustreNodemap.xml index 4b49c7b..14090ea 100644 --- a/LustreNodemap.xml +++ b/LustreNodemap.xml @@ -280,6 +280,59 @@ drwxr-xr-x 3 root root 4096 Jul 23 09:02 .. projid type: mgs# lctl nodemap_add_idmap --name BirdResearchSite --idtype projid --idmap 33:1 +
+ Defining Mapping Offsets + Mapping offsets map all client ids to a new range specified by an + offset, such that fs_id = client_id + offset. The + nodemap_add_offset command defines a mapping offset for + a given nodemap and applies the offset to all UID, GID, and PROJID + types. + lctl nodemap add_offset --name NAME --offset OFFSET --limit FSID_COUNT + This command allows admins to create offset ranges for client + systems to avoid overlapping assignments in multi-tenant systems. The + FSID_COUNT specifies the number of IDs mapped by the + range, starting with the root(0) user/group/project ID + and extending through FSID_COUNT-1. + An offset range cannot overlap with another offset range. A + nodemap can only have one offset defined. To modify the offset already + defined, just assign a new value, or set to 0 to deactivate. Any existing + files will not automatically be remapped to the new + OFFSET range. IDs must be manually changed on all files + for that nodemap with chown(1) and + lfs-project(1) on a trusted client that has access to + the unmapped, canonical file system IDs. Therefore modifying a nodemap + offset should be avoided if possible. + For example, to map the client UID, GID, and PROJID values from the + range 0-199999 to the filesystem UID, GID, and PROJID values to the range + 100000-299999: + mgs# lctl nodemap_add_offset --name remotesite --offset 100000 --limit 200000 + Once an offset is set on a nodemap, please make sure the explicit + mappings are defined so that they do not escape the offset range. This + means an explicit mapping should not map a client id to a file system id + greater than FSID_COUNT-1. Similarly, the + squash_uid, squash_gid and + squash_projid values should not be set to a value + greater than FSID_COUNT-1. Otherwise this would + produce file system ids outside of the offset range. + + If not zero, the mapping offset is always applied as the last stage + of the mapping process. + gives a + simplified view of the identity mapping process that happens when nodemap is + activated, to convert a client id to a file system canonical id. +
+ Flow chart: nodemap identity mapping + + + + + + Flow chart: nodemap identity mapping + + +
+
diff --git a/figures/id_mapping_flow_chart.png b/figures/id_mapping_flow_chart.png new file mode 100644 index 0000000..5585f74 Binary files /dev/null and b/figures/id_mapping_flow_chart.png differ