unshare(2)

Synopsis

#define _GNU_SOURCE
#include <sched.h>

int unshare(int flags);

Rod's take

unshare(CLONE_NEWPID) does not move the caller into the new PID namespace. The caller stays where it is. The next fork creates a child that sees itself as PID 1. This surprises everyone once. Mount a new /proc before anything tries to read it. CLONE_NEWUSER is the exception to the CAP_SYS_ADMIN rule: unprivileged processes can create user namespaces, write uid_map and gid_map, and own root inside; this is rootless containers. FreeBSD's jail does the same job with one call and fewer footguns, but you can't compose namespace types independently. The composability is both the feature and the reason container runtimes are thousands of lines of C.

Flags and arguments that matter

Errors you will actually hit

Example

#define _GNU_SOURCE
#include <sched.h>
#include <err.h>

/* private mount and UTS namespaces */
if (unshare(CLONE_NEWNS | CLONE_NEWUTS) < 0)
    err(1, "unshare");

/* PID namespace: caller stays in parent ns; child is PID 1 */
if (unshare(CLONE_NEWPID) < 0)
    err(1, "unshare NEWPID");
pid_t child = fork();
if (child == 0) {
    /* PID 1 in new namespace; mount /proc before any ps(1) */
    mount("proc", "/proc", "proc", 0, NULL);
    execvp(argv[0], argv);
}

Trimmed from the full walkthrough in setns and unshare: moving between Linux namespaces.

BSD equivalent

FreeBSD: jail(2) (FreeBSD 4.0) wraps filesystem, network, and PID visibility in one coarser-grained call. OpenBSD: none; isolation is pledge(2), unveil(2), and chroot(2).