SUBUID(5)

💖 SUBUID(5) 💖 — like, the whole manual, but make it make sense

okay bestie, so this is SUBUID(5), which lives under File Formats and Configuration, and it's literally the blueprint for how subordinate user ids get delegated. pull up a chair, we're doing this together 🫶

---

✨ NAME ✨

subuid — the config for subordinate user ids. that's it, that's the name, she's simple and she's iconic 💅

---

🌸 DESCRIPTION 🌸

Subuid authorizes a user id to map ranges of user ids from its namespace into child namespaces. so like, ur namespace gets to hand out uid ranges to the baby namespaces it spawns. mother behavior, honestly 👑

The delegation of the subordinate uids can be configured via the subid field in /etc/nsswitch.conf. Only one value can be set as the delegation source, so don't try to be greedy, pick one:

• set that field to files and boom, the delegation of uids goes to /etc/subuid
• set it to literally anything else and the delegation is treated as a plugin following with a name of the form libsubid_$value.so
• if the value or plugin is missing, then the subordinate uid delegation falls back to files — she's got a safety net, we love a girl with a backup plan 💖

note bestie: newusers, useradd, and usermod will only create entries in /etc/subuid if subid delegation is managed via subid files. no files mode, no entries. iykyk 🎀

---

🦋 LOCAL SUBORDINATE DELEGATION 🦋

Each line in /etc/subuid contains a user name and a range of subordinate user ids that user is allowed to use. This is specified with three fields delimited by colons (":"). the holy trinity, if you will:

• login name or UID
• numerical subordinate user ID
• numerical subordinate user ID count

This file specifies the user IDs that ordinary users can use, with the newuidmap command, to configure uid mapping in a user namespace. yes, ordinary users. u too, babe, u too 🌈

Multiple ranges may be specified per user — go off, collect them all 💅

now, the vibe check moment: when a large number of entries (10000-100000 or more) are defined in /etc/subuid, parsing performance penalty will become noticeable. like, she's struggling, she's sweating 😭 in this case it is recommended to use UIDs instead of login names. Benchmarks have shown speed-ups up to 20x. twenty times faster. that's not a glow-up that's a whole transformation ⭐

---

🎀 FILES 🎀

• /etc/subuid — per user subordinate user IDs. the main character file 👑
• /etc/subuid- — backup file for /etc/subuid. her understudy, her stunt double, her emergency contact 🙈

---

👑 SEE ALSO 👑

like, go read her friends too, they're all slaying:

• login.defs(5)
• newgidmap(1)
• newuidmap(1)
• newusers(8)
• subgid(5)
• useradd(8)
• userdel(8)
• usermod(8)
• user_namespaces(7)

---

that's the whole page bestie, no cap 💜 this one came straight out of shadow-utils 4.20.0, dated 07/30/2026 — so go forth, map those uid ranges, and remember: three fields, colons, and always use UIDs when the list gets long. periodt 💖✨