Mastering nsenter: Debug Container Networks and Linux Namespaces

nsenter is a command from the util‑linux package that runs a program in the namespace of a specified process.

Use Cases

A typical use is to enter a container’s network namespace to run host tools such as ip address, ping, telnet, tcpdump for debugging, without needing the container to include those utilities.

nsenter can also enter other namespaces such as mnt, uts, ipc, pid, and user, and can set a root and working directory.

Usage

Syntax:

nsenter [options] [program [arguments]]
options:
 -t, --target pid          target process PID
 -m, --mount[=file]        enter mount namespace
 -u, --uts[=file]         enter uts namespace
 -i, --ipc[=file]         enter ipc namespace
 -n, --net[=file]         enter net namespace
 -p, --pid[=file]         enter pid namespace
 -U, --user[=file]        enter user namespace
 -G, --setgid gid         set GID for the program
 -S, --setuid uid         set UID for the program
 -r, --root[=directory]   set root directory
 -w, --wd[=directory]     set working directory
If no program is given, $SHELL is executed.

Example: obtain the PID of an nginx container, then enter its network namespace and run ip addr to view interfaces.

[root@host ~]# docker inspect -f {{.State.Pid}} nginx
5645
[root@host ~]# nsenter -n -t5645
[root@host ~]# ip addr
…

In Kubernetes, you can retrieve the container ID or PID with kubectl get pod … -oyaml or a template command, then use nsenter similarly.

Principles

Namespaces

Linux namespaces isolate resources such as mount, ipc, uts, net, pid, user, and cgroup. Each process has a set of namespace entries visible under /proc/PID/ns.

clone

The clone system call creates a new process and can place it in new namespaces using flags like CLONE_NEWNET, CLONE_NEWUTS, etc.

#define _GNU_SOURCE
#include <sched.h>
int clone(int (*fn)(void *), void *child_stack,
          int flags, void *arg, ...);

setns

setns

attaches the calling thread to an existing namespace identified by a file descriptor under /proc/PID/ns.

#define _GNU_SOURCE
#include <sched.h>
int setns(int fd, int nstype);

Typical usage: open the namespace file, call setns(fd, 0), then execvp the desired program.

#include <fcntl.h>
#include <sched.h>
#include <unistd.h>
int main(int argc, char *argv[]) {
    int fd = open(argv[1], O_RDONLY);
    setns(fd, 0);
    execvp(argv[2], &argv[2]);
}

References

Container network debugging guide

nsenter man page

clone man page

setns man page