newgidmap - Man Page

set the gid mapping of a user namespace

Synopsis

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

Description

The newgidmap sets /proc/[pid]/gid_map based on its command line arguments and the gids allowed​. Subgid delegation can either be managed via /etc/subgid or through the configured NSS subid module​. These options are mutually exclusive​.

Note that the root group is not exempted from the requirement for a valid /etc/subgid entry​.

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

gid

Beginning of the range of GIDs inside the user namespace​.

lowergid

Beginning of the range of GIDs outside the user namespace​.

count

Length of the ranges (both inside and outside the user namespace)​.

newgidmap verifies that the caller is the owner of the process indicated by pid and that for each of the above sets, each of the GIDs in the range [lowergid, lowergid+count) is allowed to the caller according to /etc/subgid before setting /proc/[pid]/gid_map​.

Note that newgidmap may be used only once for a given process​.

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, newgidmap will use openat(2) to open the gid_map file under that directory, avoiding a TOCTTOU in case the process exits and the pid is immediately reused​.

Options

There currently are no options to the newgidmap command​.

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)​.

Info

10/15/2026 shadow-utils 4.20.0