Mastering nsenter: Debug Container Networks and Namespaces with Ease

Purpose

nsenter is a command from the util‑linux package that runs a program inside the namespace(s) of a target process. It is commonly used to enter a container’s network namespace when the container lacks basic networking tools such as ip, ping, telnet, ss, or tcpdump.

It can also enter other namespaces (mnt, uts, ipc, pid, user) and set a new root or working directory.

Usage

Syntax:

nsenter [options] [program [arguments]]
options:
 -t, --target pid          target process ID
 -m, --mount[=file]        enter mount namespace
 -u, --uts[=file]          enter UTS namespace
 -i, --ipc[=file]          enter IPC namespace
 -n, --net[=file]          enter network 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 new root directory
 -w, --wd[=directory]      set working directory
If no program is given, $SHELL is executed.

Example: obtain the PID of an nginx container and enter its network namespace:

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

In Kubernetes, you can retrieve the container ID with:

[root@node1 ~]# kubectl get pod test -oyaml | grep containerID
  - containerID: docker://cf0873782d587dbca6aa32f49605229da3748600a9926e85b36916141597ec85

Principle

Namespace

A Linux namespace isolates a set of resources for a group of processes. Linux currently provides mount, ipc, uts, net, pid, user, and cgroup namespaces.

mount : separate mount point hierarchy (since 2.4.19)

ipc : separate IPC objects (since 2.6.19)

uts : separate hostname/domain (since 2.6.19)

net : separate network stack (since 2.6.24)

pid : separate PID number space (since 2.6.24)

user : separate user ID mapping (2.6.23‑3.8)

cgroup : separate cgroup hierarchy (since 4.6)

clone

The clone system call creates a new process and can place it in one or more new namespaces using flags such as CLONE_NEWNET, CLONE_NEWUTS, etc.

#define _GNU_SOURCE
#include <sched.h>

int clone(int (*fn)(void *), void *child_stack,
          int flags, void *arg, ...);

Relevant flags include CLONE_NEWCGROUP, CLONE_NEWIPC, CLONE_NEWNET, CLONE_NEWNS, CLONE_NEWPID, CLONE_NEWUSER, CLONE_NEWUTS.

setns

The setns system call attaches the calling thread to an existing namespace identified by a file descriptor under /proc/PID/ns/. Passing 0 as the second argument allows entry into any namespace.

#define _GNU_SOURCE
#include <sched.h>

int setns(int fd, int nstype);

A typical usage sequence is to call setns to join the namespace and then execvp to run a program inside it.

pid = clone(childFunc, stackTop, CLONE_NEWUTS | SIGCHLD, argv[1]);

#define _GNU_SOURCE
#include <fcntl.h>
#include <sched.h>
#include <unistd.h>
#include <stdlib.h>
#include <stdio.h>

int main(int argc, char *argv[])
{
    int fd;
    if (argc < 3) {
        fprintf(stderr, "%s /proc/PID/ns/FILE cmd args...
", argv[0]);
        exit(EXIT_FAILURE);
    }
    fd = open(argv[1], O_RDONLY);
    if (fd == -1) perror("open");
    if (setns(fd, 0) == -1) perror("setns");
    execvp(argv[2], &argv[2]);
    perror("execvp");
}

Running the helper program:

./ns_exec /proc/3550/ns/uts /bin/bash

nsenter

nsenter

is a wrapper around setns that lets you specify a target PID instead of a namespace file descriptor, automatically locating /proc/PID/ns/* and executing the requested program inside the chosen namespace.