NEWGIDMAP(1)

💖 NEWGIDMAP — bestie edition 💖

okay so <rainbow>newgidmap</rainbow> is a lil user command from the shadow-utils fam, and its whole job is: set the gid mapping of a user namespace. that's it. that's the vibe. 🫶

---

✨ SYNOPSIS ✨

newgidmap pid gid lowergid count [gid lowergid count [ ... ]]

---

🌸 DESCRIPTION 🌸

so newgidmap sets /proc/[pid]/gid_map based on the stuff you typed on the command line and the gids that are allowed. and here's the tea ☕ — subgid delegation can be managed either via /etc/subgid or through the configured NSS subid module. those two options? mutually exclusive, periodt. pick one, not both, bestie.

⚠️ also note: the root group is NOT exempted from the requirement for a valid /etc/subgid entry. like, not even root gets a free pass. iconic? maybe. strict? absolutely. 💅

after the pid argument, newgidmap expects sets of 3 integers:

• gid — the beginning of the range of GIDs inside the user namespace 🎀
• lowergid — the beginning of the range of GIDs outside the user namespace 🦋
• count — the length of the ranges (both inside and outside the user namespace, yes both, she's doing double duty) ⭐

then newgidmap does a lil vibe check 🔍: it verifies that the caller is the owner of the process indicated by pid, and that for each of the above sets, every single GID in the range [lowergid, lowergid+count) is allowed to the caller according to /etc/subgid — all of that before it sets /proc/[pid]/gid_map.

😭 and heads up: newgidmap may be used only once for a given process. one shot. no takebacks. no reruns. choose wisely bestie.

---

🧚 the fd:N glow-up (TOCTTOU protection, we love to see it)

instead of an integer process id, that first argument can 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 that case, newgidmap will use openat(2) to open the gid_map file under that directory — which avoids a TOCTTOU in case the process exits and the pid is immediately reused. race condition? not on her watch. 🔥

---

💅 OPTIONS 💅

• there currently are no options to the newgidmap command.

like literally none. she's lowkey a minimalist. no flags, no frills, just vibes and integers. ✨

---

🍓 FILES 🍓

• /etc/subgid — list of user's subordinate group IDs. 📋
• /proc/[pid]/gid_map — mapping of gids from one between user namespaces. 🗺️

---

👑 SEE ALSO 👑

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

go read those too, they're the supporting cast and they ate. 💜

---

and that's the whole page bestie!! 🌈 this was brought to you by shadow-utils 4.20.0, dated 07/30/2026 — so you know it's fresh, it's current, and it's giving main character energy. mwah 💖🎀🦋