NEWIDMAPD(8)

NAME
newidmapd, newidmapd.service, newidmapd.socket - daemon to set UID and GID mappings for user namespaces

SYNOPSIS

newidmapd.service

newidmapd.socket

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

DESCRIPTION

newidmapd is a systemd(1) socket-activated service that performs the privileged write of UID and GID mappings into a process's user namespace on behalf of unprivileged callers.

Writing to /proc/pid/uid_map and /proc/pid/gid_map normally requires elevated privileges. newidmapd accepts requests over a Varlink socket, validates them, and writes the mappings itself, so that tools such as newuidmap(1) and newgidmap(1) need no setuid bit.

Before writing any mapping, newidmapd verifies that:

    • The calling process owns the target process (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). 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).

When launched by systemd(1) via socket activation, the daemon exits automatically after 30 seconds of inactivity.

OPTIONS

-s, --socket
    Enable socket activation mode. In this mode the daemon inherits the listening socket from systemd and exits automatically after 30 seconds of idle time. This is the standard mode when running under systemd.

-d, --debug
    Enable debug mode (maximum log verbosity).

-v, --verbose
    Enable verbose logging.

-?, --help
    Give the help list.

--version
    Print program version.

VARLINK INTERFACE

newidmapd exposes the interface org.openSUSE.newidmapd over the Varlink socket /run/account/newidmapd-socket. The interface provides the following 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 are validated against /etc/subuid or /etc/subgid as appropriate.

    Input fields:

    PID (int)
        Process ID of the target process whose namespace mapping is to be written.

    Map (string)
        Which mapping file to write. Must be either uid_map or gid_map.

    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)
        Human-readable error description on failure.

Ping
    Returns Alive=true if the service is running. Useful to check that the daemon is reachable before issuing other calls.

Quit
    Requests the daemon to stop. An optional integer ExitCode can be supplied; 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.

The interface defines the following error types:

org.openSUSE.newidmapd.PermissionDenied
    The caller does not own the target process, or the requested mapping ranges are not 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 occurred while processing the request.

FILES

/usr/libexec/newidmapd
    The daemon binary.

/run/account/newidmapd-socket
    Varlink socket used to communicate with 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 written to apply UID mappings to a user namespace.

/proc/pid/gid_map
    Kernel file written to apply GID mappings to a user namespace.

SEE ALSO

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