NEWUIDMAP(1)

💖 NEWUIDMAP — bestie edition 💖

okay so. newuidmap is the girl whose whole job is setting the uid mapping of a user namespace. that's it. that's the gig. she's giving sysadmin main character energy and honestly? she ate. 👑

---

✨ SYNOPSIS ✨

newuidmap pid uid loweruid count [uid loweruid count [ ... ]]

---

🌸 DESCRIPTION 🌸

so like, newuidmap sets /proc/[pid]/uid_map based on its command line arguments and the uids allowed. that's the whole vibe. ✨

and the subuid delegation? that can either be managed via /etc/subuid or through the configured NSS subid module. and bestie, these options are mutually exclusive — pick a lane, you cannot do both, no cap. 🚫

⚠️ and listen — the root user is not exempted from the requirement for a valid /etc/subuid entry. not even root. not even a little bit. the rules apply to everybody. periodt.

so after the pid argument, newuidmap expects sets of 3 integers:

• uid — the beginning of the range of UIDs inside the user namespace 🫧
• loweruid — the beginning of the range of UIDs outside the user namespace 🌈
• count — the length of the ranges (both inside and outside the user namespace, yes both, one number for both) 📏

then newuidmap verifies that the caller is the owner of the process indicated by pid and that for each of the above sets, each of the UIDs in the range [loweruid, loweruid+count) is allowed to the caller according to /etc/subuid — and only then does it set /proc/[pid]/uid_map. she checks her work first, as she should. 💅

🚨 also important: newuidmap may be used only once for a given process. one shot. one moment. make it count. 😭

okay and here's the lowkey genius part — instead of an integer process id, the first argument may be specified as fd:N, where the integer N is the file descriptor number for the calling process's opened file descriptor for the directory /proc/[pid]. in this case, newuidmap will use openat(2) to open the uid_map file under that directory, avoiding a TOCTTOU in case the process exits and the pid is immediately reused. iconic. no race condition, no drama, just vibes. 🦋

---

👑 OPTIONS 👑

there currently are no options to the newuidmap command.

that's it. that's the section. she said "no flags, no extras, we're doing this raw." and honestly? respect. 🙈

---

🎀 FILES 🎀

• /etc/subuid — list of user's subordinate user IDs. the sacred scroll. 📜
• /proc/[pid]/uid_map — mapping of uids from one between user namespaces. the place where the magic actually gets written. ✨

---

🔥 SEE ALSO 🔥

login.defs(5), newusers(8), subuid(5), useradd(8), usermod(8), userdel(8)

---

that's the whole page bestie, go forth and map some uids responsibly 💜

sign-off: this was shadow-utils 4.20.0 dated 07/30/2026 — mwah, love u, bye! 🎀💖🦋