NEWIDMAPD(8)

📦
version 1.4.0 · 2 versions
, in ubuntu stonking

✨ newidmapd — the manual page, bestie edition ✨

okay so you picked up the NEWIDMAPD(8) page, congrats, you're about to be obsessed 💖 this is the newidmapd corner of the account-utils universe and it is lowkey doing SO much heavy lifting behind the scenes. let's get into it.

🌸 NAME 🌸

newidmapd, newidmapd.service, newidmapd.socket — the daemon that sets UID and GID mappings for user namespaces 💅

🦋 SYNOPSIS 🦋

newidmapd.service

newidmapd.socket

/usr/libexec/newidmapd [OPTIONS...]

✨ DESCRIPTION ✨

so newidmapd is a systemd(1) socket-activated service, and its whole vibe is: it does the privileged write of UID and GID mappings into a process's user namespace, on behalf of unprivileged callers. like, it's the friend who's allowed into the VIP section and it picks up the phone for you 🫶

writing to /proc/pid/uid_map and /proc/pid/gid_map normally requires elevated privileges — which is, frankly, a lot. so newidmapd takes requests over a Varlink socket, validates them, and writes the mappings itself. the payoff? tools like newuidmap(1) and newgidmap(1) need no setuid bit. no cap 🔥 iconic behavior.

before it writes any mapping, newidmapd runs a vibe check, and it verifies:

  • the calling process owns the target process — meaning the /proc/pid directory is owned by the caller's UID and GID.
  • every requested subordinate ID range is listed for the caller in /etc/subuid (for UID mappings) or /etc/subgid (for GID mappings). heads up: a process is always allowed to map its own UID or GID.
  • the number of mapping entries does not exceed the kernel limit of 340 ranges (enforced since Linux 4.16).

and when systemd(1) launches it via socket activation, the daemon exits automatically after 30 seconds of inactivity. it knows when to leave the party 😌

💅 OPTIONS 💅

  • -s, --socket — turns on socket activation mode. here the daemon inherits the listening socket from systemd and dips out automatically after 30 seconds of idle time. this is the standard mode when running under systemd.
  • -d, --debug — debug mode, i.e. maximum log verbosity. it will tell you everything, no filter.
  • -v, --verbose — verbose logging, the chill middle child of log levels.
  • -?, --help — gives you the help list. the little menu, the lay of the land.
  • --version — prints the program version. slay.

newidmapd exposes the interface org.openSUSE.newidmapd over the Varlink socket /run/account/newidmapd-socket. the interface hands out these methods:

WriteMappings

writes UID or GID mappings for the user namespace of a given process. the caller must own the target process. the requested ranges get validated against /etc/subuid or /etc/subgid, whichever one is appropriate for the job.

Input fields:

  • PID (int) — process ID of the target process whose namespace mapping is going to be written.
  • Map (string) — which mapping file to write. must be either uid_map or gid_map. it's giving very specific.
  • MapRanges (array of MapRange) — array of mapping entries. each entry is a MapRange object with three integer fields: upper (first ID inside the namespace), lower (first ID outside the namespace), and count (length of the range). at most 340 entries are accepted.

Output fields:

  • Success (bool) — whether the operation succeeded.
  • ErrorMsg (string, optional) — a human-readable error description on failure.

Ping

returns Alive=true if the service is running. so useful for checking the daemon is reachable before you go issuing other calls. it's the "you up?" text of the Varlink world 🙈

Quit

requests the daemon to stop. you can optionally supply an integer ExitCode; it will be used as the process exit status.

SetLogLevel

adjusts the maximum log level at runtime. the Level field uses BSD syslog integer values (0 = emergency ... 7 = debug).

GetEnvironment

returns the daemon's current environment block as an array of strings in KEY=VALUE form.

and the interface also defines these error types:

  • org.openSUSE.newidmapd.PermissionDenied — the caller doesn't own the target process, or the requested mapping ranges aren't permitted by the subordinate ID configuration.
  • org.openSUSE.newidmapd.InvalidParameter — a required parameter was missing, out of range, or otherwise invalid.
  • org.openSUSE.newidmapd.InternalError — an unexpected internal error happened while processing the request. 😭

🎀 FILES 🎀

  • /usr/libexec/newidmapd — the daemon binary itself, the main character 👑
  • /run/account/newidmapd-socket — the Varlink socket used to talk to the daemon. created with mode 0666 so any local user can connect.
  • /etc/subuid — defines the subordinate UID ranges allocated to each user. consulted when validating uid_map requests.
  • /etc/subgid — defines the subordinate GID ranges allocated to each user. consulted when validating gid_map requests.
  • /proc/pid/uid_map — kernel file that gets written to apply UID mappings to a user namespace.
  • /proc/pid/gid_map — kernel file that gets written to apply GID mappings to a user namespace.

🌈 SEE ALSO 🌈

newuidmap(1), newgidmap(1), subuid(5), subgid(5), user_namespaces(7), systemd(1)

ok bestie that's the whole page, every last flag and field present and accounted for, no notes 💖

and for the cute sign-off: this whole thing comes from account-utils version 1.4.0, dated 07/17/2026 — so yeah, she's recent, she's maintained, she's that girl 🫶✨

📦 where this page comes from