nsenter

Run a specific command using the same namespaces as an existing process

$ nsenter [[-t|--target]] [pid] [[-a|--all]] [command] [command_arguments]

$ nsenter [[-t|--target]] [pid] --[mount|uts|ipc|net|pid|user|cgroup] [command] [command_arguments]

$ nsenter [[-t|--target]] [pid] [[-u|--uts]] [[-T|--time]] [[-i|--ipc]] -- [command] [command_arguments]

$ nsenter [[-p|--pid=]]/proc/[pid]/pid/net -- [command] [command_arguments]

nsenter [options] [--] <command> [<arguments>]

-t, --target <PID>
    Specify the target process ID whose namespaces will be entered. This is a mandatory option for most common use cases.

-m, --mount[=<file>]
    Enter the mount namespace of the target process. Optionally, specify a path to a mount namespace file (e.g., /proc/<PID>/ns/mnt) instead of the target PID's default.

-u, --uts[=<file>]
    Enter the UTS (hostname/domain name) namespace of the target process. Optionally, specify a path to a UTS namespace file.

-i, --ipc[=<file>]
    Enter the IPC (Inter-Process Communication) namespace of the target process. Optionally, specify a path to an IPC namespace file.

-n, --network[=<file>]
    Enter the network namespace of the target process. Crucial for debugging network configurations within isolated environments. Optionally, specify a path to a network namespace file.

-p, --pid[=<file>]
    Enter the PID namespace of the target process. This means the newly executed command will have a PID within that namespace, potentially different from its host PID. Optionally, specify a path to a PID namespace file.

-C, --cgroup[=<file>]
    Enter the Cgroup namespace of the target process. Optionally, specify a path to a Cgroup namespace file.

-U, --user[=<file>]
    Enter the user namespace of the target process. This changes the user ID and group ID mappings for the new process, which can make it appear as root (UID 0) inside the target namespace. Optionally, specify a path to a user namespace file.

-S, --setid <uid> <gid>
    Set the user ID and group ID for the command executed inside the namespace. This is applied after entering the user namespace (if -U is used).

-r, --root[=<directory>]
    Set the root directory for the command. Similar to chroot, but can be combined with namespace entry. If no directory is specified, it defaults to the target process's root.

-w, --wd[=<directory>]
    Set the working directory for the command. If no directory is specified, it defaults to the target process's current working directory.

-F, --no-fork
    Do not fork a new process before executing the command. This means nsenter itself will be replaced by the command, which can affect signal handling.

-Z, --follow-context
    Set the SELinux context for the command according to the target process's context.

-v, --version
    Display version information and exit.

-h, --help
    Display help information and exit.

nsenter is a powerful utility from the util-linux package that allows an administrator to run a program within the context of specific namespaces of another running process. Linux namespaces provide isolation for various system resources, including Process IDs (PID), network interfaces, mount points, Inter-Process Communication (IPC), UTS (hostname/domain name), Cgroup, and user IDs.

This command is exceptionally valuable for debugging and managing containerized applications. It enables users to "step inside" a container's isolated environment without relying on the container runtime's specific `exec` commands (like `docker exec`). By targeting a process's PID, nsenter can attach to its pre-existing namespaces and then execute a command, effectively making the command operate as if it were running within that isolated environment. This provides a low-level, flexible, and powerful way to inspect, configure, and troubleshoot issues within isolated Linux environments from the host system.

Privileges: nsenter generally requires root privileges or the CAP_SYS_ADMIN capability to attach to other process's namespaces.

Target Process: The target process (specified by PID) must be actively running for nsenter to successfully join its namespaces.

PID Namespace: Entering a PID namespace (-p) does not automatically make your command PID 1 within that namespace. The command will receive a new PID within the target namespace, but its parent will still be the original nsenter process from the host's PID namespace.

User Namespace Complexity: When entering a user namespace (-U), your user ID and group ID mappings will change according to that namespace's configuration. You might appear as root (UID 0) within the target namespace, even if you're a non-root user on the host.

At its core, nsenter leverages the setns(2) system call, which allows a process to reassociate itself with a specified namespace. This is how it 'jumps' into the environment of another process.

Beyond general system debugging, nsenter is heavily used in container troubleshooting. For instance, an administrator might use it to:
- Inspect network configurations inside a container's network namespace.
- Debug issues with mount points by entering a container's mount namespace.
- Run a diagnostic command that isn't present in the container's image.

To use nsenter, you often need to find the PID of a process running within the target environment (e.g., a container). Tools like docker inspect (for Docker) or ps aux on the host combined with grep can help identify the main process PID of a container.

nsenter is a relatively modern addition to the util-linux project, which provides a comprehensive suite of essential system utilities for Linux. Its emergence is closely tied to the increasing adoption and sophistication of Linux container technologies like Docker and Kubernetes. As namespaces became fundamental for process isolation in these environments, there was a growing need for a direct, low-level tool to inspect and interact with these isolated contexts. nsenter fills this gap, offering a powerful alternative to container-runtime-specific `exec` commands for advanced debugging and system administration tasks within isolated environments.

unshare(1), chroot(1), setns(2), namespaces(7), docker(1), lxc(1), lxc-attach(1), lslns(8)