LCTL-NODEMAP_MODIFY(8)

📦 version 2.17.58, in ubuntu stonking

💖 LCTL-NODEMAP_MODIFY(8) 💖

okay bestie, listen — this page lives in the Lustre Configuration Utilities corner of the manual, and it does exactly one job: changing a single property on a nodemap. tiny job. huge main character energy. let's go 🫶

🎀 NAME 🎀

lctl-nodemap_modify — modify a nodemap property. that's the whole name, and honestly? it ate.

✨ SYNOPSIS ✨

lctl nodemap_modify

or

lctl nodemap modify --name NODEMAP_NAME --property
                    PROPERTY_NAME{=VALUE|--value VALUE}

either form, same energy 💅

🌸 DESCRIPTION 🌸

nodemap_modify modifies a property of the given nodemap. that's it. that's the description. it finds the nodemap you named and it flips the property you told it to flip. no cap.

🔥 OPTIONS 🔥

  • --name NODEMAP_NAME — the name of the nodemap you wanna modify. yes, you have to tell it which one. it's not a mind reader 🦋
  • --property PROPERTY_NAME{=VALUE|--value VALUE} — pick your property, bestie. it has to be one of these:
    • admin — defaults to 0. if you set it to 1, then root will NOT be squashed. by default, the root user is mapped to the value of squash_uid.
    • trusted — defaults to 0. if you set it to 1, then user mapping will be disabled for all non-root users. this means the identities provided by the client will be trusted to match the identities of the file system. by default, the client user identities are mapped to the file system identities based on the nodemap rules.
    • squash_uid — defaults to NODEMAP_NOBODY_UID if not specified, which is 65534 to match the standard Linux nobody user ID. this is the user ID that unknown users (if not trusted) and root (if not admin) should be mapped to. when offsets are defined on the nodemap, the squash value should be in the offset range [ 0, offset_limit-1 ], otherwise squashed UIDs would escape offsetting. note: squashing to UID 0 (root) is not permitted. nope. absolutely not. 🙈
    • squash_gid — defaults to NODEMAP_NOBODY_UID if not specified, which is 65534 to match the standard Linux nobody user ID. this is the group ID that unknown groups (if not trusted) and root (if not admin) should be mapped to. when offsets are defined on the nodemap, the squash value should be in the offset range [ 0, offset_limit-1 ], otherwise squashed GIDs would escape offsetting. note: squashing to GID 0 (root) is not permitted. same rule, same drama 💜
    • squash_projid — defaults to NODEMAP_NOBODY_UID if not specified, which is 65534 to match the standard Linux nobody user ID. this is the project ID that unknown projects (if not trusted) should be mapped to. when offsets are defined on the nodemap, the squash value should be in the offset range [ 0, offset_limit-1 ], otherwise squashed PROJIDs would escape offsetting.
    • deny_unknown — defaults to 0. if you set it to 1, then unknown (squashed) users will be denied access to the filesystem completely, instead of just being squashed. a user is considered unknown by nodemap if the admin flag is off and the user is root, or trusted are set to off and the user is not mapped.
⚠️ Note: directory entries cached by a Lustre client may be visible to unknown users located on the same client, though the contents of the files will not be. so like… the folder is showing but the tea inside is locked. 💀
  • audit_mode — defaults to 1, which lets clients record file system access events to the Changelogs, if Changelogs are otherwise activated. if you set it to 0, events from these clients are not logged into the Changelogs, no matter if Changelogs are activated or not. why would you ever not record file system events from given clients? to prevent some nodes (e.g. backup, HSM agent nodes) from flooding the Changelogs. it's giving "please stop spamming the group chat" 😭
  • map_mode — defaults to all, which means the nodemap maps UIDs, GIDs, and PROJIDs. other possible values (multiple can be specified, comma separated) are uid to map UIDs, gid to map GIDs, both to map UIDs and GIDs, and projid to map PROJIDs.
  • forbid_encryption — defaults to 0, which means encryption is allowed. set it to 1 to prevent clients from using encryption. 🔒
  • child_raise_privileges — defaults to none, allowing child nodemaps to only lower privileges established by parent nodemap. other possible values (multiple can be specified, comma separated) are the nodemap properties names that support privilege raise:
    • admin
    • trusted
    • deny_unknown
    • readonly_mount
    • forbid_encryption
    • child_raise_privs
    • caps
    • deny_mount

it is also possible to specify any roles accepted by the rbac property (see below). any privilege not explicitly specified cannot be raised. to allow all privileges to be raised, use the all value. it's giving "you may raise the vibe, but only these specific vibes" 👑

  • readonly_mount — defaults to 0, which lets clients mount in read-write mode. if you set it to 1, clients are forced to a read-only mount if not specified explicitly.
  • deny_mount — defaults to 0, accepting client mounts from nodes assigned to the nodemap. if you set it to 1, nodes assigned to the nodemap can no longer mount new Lustre clients. existing clients remain operational until a remount is attempted. so like, they're grandfathered in til they try again 🚪
  • rbac — property available on regular nodemaps but also on the default nodemap. defaults to 'all', which means all roles are allowed. other possible values (multiple can be specified, comma separated) are:
    • -byfid_ops — allow operations by FID (e.g. lfs-rmfid(1), lfs-fid2path(1)).
    • -chlg_ops — allow use of Changelogs (e.g. lfs-changelog(1)).
    • -dne_ops — allow client DNE operations (e.g. lfs-setdirstripe(1)).
    • -file_perms — allow changing file permissions and owners (e.g. chmod(1), chown(1)).
    • -foreign_ops — create foreign dirs (e.g. 'lfs setdirstripe --foreign').
    • -fscrypt_admin — allow fscrypt related admin tasks (create or modify protectors/policies). note that even without this role, it is still possible to lock or unlock encrypted directories, as these operations only need read access to fscrypt metadata.
    • -hsm_ops — allow client HSM operations (e.g. lfs-hsm(1)).
    • -ignore_root_prjquota — project quota not enforced for root user.
    • -immutable_flags — allow setting and clearing the immutable and append-only flags on files (e.g. chattr(1) +/-i/a).
    • -local_admin — allow mapped root file operations, unless squashed (e.g. chown(1), chgrp(1)). unavailable on default nodemap, as there are id mappings or offsets possible on the default nodemap.
    • -lqa_quota_ops — to allow LQA quota modifications (e.g. lctl-lqa(8), 'lfs setquota --lqa').
    • -pool_quota_ops — allow pool quota changes (e.g. 'lfs setquota --pool').
    • -projid_set — to allow setting project ID on files and directories (e.g.. lfs-project(1), chattr(1)).
    • -quota_ops — allow UID/GID/ProjID quota changes (e.g. lfs-setquota(1)).
    • -server_upcall — to define which identity upcall to use (see mdt.identity_upcall(4)). if set, identity upcall is defined by server side tunable. if not set, identity upcall is forced to INTERNAL, so that servers trust supplementary groups as provided by clients.

apart from 'all', any role not explicitly specified is forbidden. to forbid all roles, use 'none'.

roles can also be updated incrementally using + and - operators (e.g., use '+dne_ops' to add a role, or '-file_perms' to remove a role) without specifying the full set of roles. it's giving "add to cart" but for permissions 🛒✨

  • gssonly_identification — if set to 1, clients for this nodemap are no longer identified based on their NIDs, but instead by the GSS token they are using to authenticate. consequently, a nodemap with this property set cannot have any NID ranges defined. any client using the GSS token associated with this nodemap to authenticate is considered part of this nodemap. defaults to 0. 🪪
  • --value VALUE — the value to set for the property. should be 0 or 1 for admin and trusted.
🚨 heads up bestie: the use of both --property PROPERTY_NAME=VALUE and --value VALUE is invalid. pick a lane, you can't do both.

💫 EXAMPLES 💫

commands illustrating how to modify nodemap properties, served fresh:

# lctl nodemap_modify --name remotesite --property trusted --value 1
# lctl nodemap_modify --name remotesite --property admin --value 1
# lctl nodemap_modify --name remotesite --property map_mode --value uid
# lctl nodemap_modify --name remotesite --property rbac=all
# lctl nodemap_modify --name remotesite --property rbac=+hsm_ops,-file_perms
# lctl nodemap_modify --name remotesite --property rbac=-immutable_flags
# lctl nodemap_modify --name othersite --property squash_uid --value 101

see how the last one's a whole different nodemap? othersite said "my squash_uid, my rules" 😌

🦋 AVAILABILITY 🦋

lctl nodemap_modify is part of the lustre(7) filesystem package since release 2.6.0. she's been here a minute. veteran behavior 💅

🌈 SEE ALSO 🌈

lustre(7), mdt.enable_foreign_dir(4), mdt.enable_remote_dir(4), mdt.identity_upcall(4), lctl-nodemap-activate(8), lctl-nodemap-add-idmap(8), lctl-nodemap-add-offset(8), lctl-nodemap-add-range(8), lctl-nodemap-del(8), lctl-nodemap-del-idmap(8), lctl-nodemap-del-offset(8), lctl-nodemap-del-range(8), lctl-nodemap-new(8)

and that's the whole page, bestie 🫶 this one came out of the Lustre collection, dated 2025-07-09, filed under LCTL-NODEMAP_MODIFY(8). go forth and modify responsibly, ily 💖✨

📦 where this page comes from