LCTL-NOD...DD_OFFSET(8)

📦 version 2.17.58, in ubuntu stonking

💖 lctl-nodemap_add_offset — the LCTL-NODEMAP-ADD-OFFSET(8) page, bestie edition 💖

okay so you opened the manual for lctl-nodemap_add_offset from the Lustre Configuration Utilities section (that's section 8, the admin-tools one, iykyk) and you want the tea. here it is, no cap. 🫶

✨ NAME ✨

lctl-nodemap_add_offset — define the ID mapping offset for a nodemap 💅

🎀 SYNOPSIS 🎀

lowkey there's two ways to type it, pick your fighter:

lctl nodemap_add_offset

or

lctl nodemap add_offset --name NAME --offset OFFSET --limit FSID_COUNT

🌸 DESCRIPTION 🌸

so nodemap_add_offset adds an identity mapping offset to a nodemap, and it does it for the UID, GID and PROJID types all at once. periodt. ✨

the whole point? it lets admins create offset ranges for client systems so you don't get overlapping assignments in multi-tenant systems. the way that works is: FSID_COUNT tells you how many IDs the range maps, starting with the root(0) user/group/project ID and extending all the way through FSID_COUNT-1. 💯

one offset range cannot overlap into another's offset range. not even a little bit. 🚫

and now the important part, bestie, listen up: a nodemap can only have one offset defined. to modify the offset you already set, you just assign a new value. BUT — and this is the 😭 part — any existing files will not automatically be remapped to the new OFFSET range. the IDs have to be manually changed on all files for that nodemap, using chown(1) and lfs-project(1), on a trusted client that has access to the unmapped, canonical file system IDs. so like... modifying a nodemap offset should be avoided if possible. fr fr. 🙈

once an offset is set on a nodemap, please please please make sure the explicit mappings are defined so that they do not escape the offset range. what does that mean in practice? a few things, all of them giving "read the whole thing before you type" energy:

  • an explicit mapping should not map a client id to a file system id greater than FSID_COUNT-1
  • same deal for the squash_uid, squash_gid and squash_projid values — they should not be set to a value greater than FSID_COUNT-1
  • otherwise you'd produce file system IDs outside of the offset range 🚨

and finally, the offset limit FSID_COUNT should be defined so that the nobody user (65534) is included in the offset range. don't forget them, they're doing their best. 🥺

👑 OPTIONS 👑

  • --name NAME — the name of the nodemap that the offset will be applied to. like, which nodemap are we doing this to? that one. 🎯
  • --offset OFFSET — the given start value for the offset. this is where the range begins. 📍
  • --limit FSID_COUNT — the number of IDs in the offset range. counting szn. 🔢

🌈 EXAMPLES 🌈

ex. 1 — the classic

map the client UID, GID, and PROJID values from the range 0-99999 to the filesystem UID, GID, and PROJID values to the range 100000-199999:

# lctl nodemap_add_offset --name remotesite --offset 100000 --limit 100000

ex. 2 — the nobody-user glow-up

this maps the "-2" user ID used by some systems for the nobody user to the user ID 65534, which will then be offset by OFFSET to a final UID of 165534 in this example:

# lctl nodemap_add_idmap --name remotesite --idtype uid --idmap 4294967294:65534

ate. no crumbs. 💅

🦋 AVAILABILITY 🦋

lctl nodemap_add_offset is part of the lustre(7) filesystem package, and it's been here since release 2.16.0. iconic behavior. 👑

💜 SEE ALSO 💜

your reading list, bestie, go forth and click through:

okay that's the whole thing!! 💖 this page lives in the Lustre manual, it's dated 2024-08-21, and its manual-page handle is LCTL-NOD...DD_OFFSET(8) (yes the title got squished, we don't talk about it 😭). now go set that offset — carefully — and slay. 🎀✨🫶

📦 where this page comes from