The essentials
Quick reference
One focused task per row. Jump to the related section for complete, working examples.
| Use | Syntax | Examples |
|---|---|---|
| List namespace objects | lsns | View examples |
| Inspect one process | lsns --task 4242 | View examples |
| Read namespace links | readlink \
/proc/4242/ns/{user,mnt,pid,net,uts,ipc,cgroup,time} | View examples |
| Compare namespace identity | stat -Lc '%i' /proc/self/ns/net /proc/4242/ns/net | View examples |
| Map current user to root | unshare --user --map-root-user --mount /bin/sh | View examples |
| Preserve numeric identity | unshare --user --map-current-user id | View examples |
| Create private mount view | unshare --user --map-root-user --mount --propagation \
private /bin/sh | View examples |
| Create PID namespace | unshare --user --map-root-user --pid --fork --mount-proc \
--kill-child /bin/sh | View examples |
| Isolate hostname | unshare --user --map-root-user --uts sh -c \
'hostname lab && hostname' | View examples |
| Create network namespace | sudo unshare --net --fork ip link show | View examples |
| Enter mount namespace | sudo nsenter --target 4242 --mount -- findmnt | View examples |
| Enter network namespace | sudo nsenter --target 4242 --net -- ip address show | View examples |
| Enter target environment | sudo nsenter --target 4242 --all --root --wd -- /bin/sh | View examples |
| Persist UTS namespace | sudo unshare --uts=/run/namespaces/app-uts hostname \
app-sandbox | View examples |
| Release namespace handle | sudo umount /run/namespaces/app-uts | View examples |
Linux namespaces isolate selected kernel views; they are building blocks, not a complete security boundary. Start by identifying exactly which namespace types a workload uses, combine user namespaces with least privilege, and add filesystem, capability, resource, and syscall controls when containing untrusted code. Entering another process's namespaces can expose its mounts, network, credentials, and secrets, so production debugging should be authorized, audited, PID-specific, and as narrow as possible.
Step by step
Detailed examples
Identify namespace membership before debugging
Namespace symlinks under /proc/PID/ns identify objects by type and inode. Two processes share a namespace of a given type when the corresponding identifiers match. A PID can be reused, so obtain it from the service manager and verify command, start time, owner, and namespace identity immediately before privileged entry. Access to another process's procfs entries may be restricted by ownership, capabilities, ptrace policy, or procfs mount options.
target_pid=4242
ps -o pid=,ppid=,user=,lstart=,comm= -p "$target_pid"
lsns --task "$target_pid"
readlink /proc/"$target_pid"/ns/{user,mnt,pid,net,uts,ipc,cgroup,time}
stat -Lc '%n %i' /proc/self/ns/net /proc/"$target_pid"/ns/netPair user and mount namespaces for unprivileged experiments
A user namespace can map an unprivileged host user to UID 0 inside and grant capabilities only over resources owned by that user namespace. It does not grant host root. Creating the user namespace first allows it to own a simultaneously created mount namespace, subject to kernel and distribution policy. Mount propagation still matters: use a private propagation boundary and never assume a namespace alone prevents access to host files already visible in its mount tree.
unshare --user --map-root-user --mount --propagation private sh -eu -c '
id
findmnt -no TARGET,PROPAGATION /
printf "namespace session ends without modifying host mounts\n"
'Give PID namespaces a real init and matching procfs view
A process sees itself as PID 1 only after unshare forks a child into the new PID namespace; --fork is therefore essential. Mounting a new procfs view makes tools such as ps report that namespace rather than the caller's existing procfs. PID 1 has special signal and child-reaping semantics. --kill-child ties descendant lifetime to unshare, reducing orphaned workloads, but it is not a substitute for a supervisor in a long-running service.
unshare --user --map-root-user --pid --fork --mount-proc --kill-child sh -eu -c '
printf "inner PID: %s\n" "$$"
ps -o pid=,ppid=,stat=,comm=
'Treat UTS and network namespaces as different risk classes
A UTS namespace isolates hostname and NIS domain name, making it useful for low-impact demonstrations. A network namespace isolates devices, routing tables, firewall rules, ports, and sockets; a new one normally has only a down loopback device. Wiring veth devices, routes, forwarding, or firewall policy changes host networking and requires deliberate privileged configuration. The example performs inspection only; use an orchestrator or network-management workflow for production topology.
unshare --user --map-root-user --uts sh -eu -c 'hostname lab && hostname'
# CAUTION: sudo grants host-level authority to create the network namespace.
sudo unshare --net --fork sh -eu -c 'ip -brief link show; ip route show'Enter only the target contexts required for diagnosis
nsenter opens namespace handles from a target PID and runs a command after joining the selected namespaces. Entering a PID namespace affects subsequently created children, so nsenter forks by default for that case. --all is convenient but broad; --root and --wd can expose the target filesystem, while entering its user namespace normally changes credentials to UID and GID 0 inside. Prefer one read-only diagnostic command over an interactive shell and independently authorize access to production secrets.
target_pid=4242
# CAUTION: confirm PID identity immediately before each privileged entry.
ps -o pid=,user=,lstart=,comm= -p "$target_pid"
sudo nsenter --target "$target_pid" --mount -- findmnt
sudo nsenter --target "$target_pid" --net -- ip address showPersist namespace handles only with explicit ownership and cleanup
Namespace objects normally disappear after their final member and open reference are gone. util-linux can persist most namespace types by bind-mounting their procfs handle to a path; persistent PID namespaces additionally require a live init process. The handle directory must be a protected, non-shared mount for relevant cases. Unmounting the final handle can destroy the namespace, so treat cleanup as a disruptive operation and confirm no responder, service, or diagnostic session still depends on it.
# CAUTION: these privileged steps create and later release a persistent namespace handle.
sudo install -d -m 0700 /run/namespaces
sudo touch /run/namespaces/app-uts
sudo unshare --uts=/run/namespaces/app-uts hostname app-sandbox
sudo nsenter --uts=/run/namespaces/app-uts -- hostname
# Destructive to the final namespace reference; run only after dependency review.
sudo umount /run/namespaces/app-utsSources and further reading
References
Authoritative documentation used to verify and expand this cheat sheet.
- Linux man-pages projectnamespaces(7) — overview of Linux namespacesman7.org
- util-linux projectunshare(1) — run a program in new namespacesman7.org
- util-linux projectnsenter(1) — run a program in another process's namespacesman7.org
- Linux man-pages projectuser_namespaces(7) — Linux user namespacesman7.org
- Linux man-pages projectmount_namespaces(7) — mount isolation and propagationman7.org
Help us improve
Found a typo or missing example?
Tell us what would make this cheat sheet clearer, more complete, or more useful.