pivot_root - change the root mount

#include <sys/syscall.h> /* Definition of SYS_* constants */
#include <unistd.h>
int syscall(SYS_pivot_root, const char *new_root, const char *put_old);

Note: glibc provides no wrapper for pivot_root(), necessitating the use of syscall(2).

pivot_root() changes the root mount in the mount namespace of the calling process. More precisely, it moves the root mount to the directory put_old and makes new_root the new root mount. The calling process must have the CAP_SYS_ADMIN capability in the user namespace that owns the caller's mount namespace.

pivot_root() changes the root directory and the current working directory of each process or thread in the same mount namespace to new_root if they point to the old root directory. (See also NOTES.) On the other hand, pivot_root() does not change the caller's current working directory (unless it is on the old root directory), and thus it should be followed by a chdir("/") call.

The following restrictions apply:

• new_root and put_old must be directories.

• new_root and put_old must not be on the same mount as the current root.

• put_old must be at or underneath new_root; that is, adding some nonnegative number of "/.." suffixes to the pathname pointed to by put_old must yield the same directory as new_root.

• new_root must be a path to a mount point, but can't be "/". A path that is not already a mount point can be converted into one by bind mounting the path onto itself.

• The propagation type of the parent mount of new_root and the parent mount of the current root directory must not be MS_SHARED; similarly, if put_old is an existing mount point, its propagation type must not be MS_SHARED. These restrictions ensure that pivot_root() never propagates any changes to another mount namespace.

• The current root directory must be a mount point.

On success, zero is returned. On error, -1 is returned, and errno is set to indicate the error.

The program below demonstrates the use of pivot_root() inside a mount namespace that is created using clone(2). After pivoting to the root directory named in the program's first command-line argument, the child created by clone(2) then executes the program named in the remaining command-line arguments.

We demonstrate the program by creating a directory that will serve as the new root filesystem and placing a copy of the (statically linked) busybox(1) executable in that directory.

$ mkdir /tmp/rootfs
$ ls -id /tmp/rootfs    # Show inode number of new root directory
319459 /tmp/rootfs
$ cp $(which busybox) /tmp/rootfs
$ PS1='bbsh$ ' sudo ./pivot_root_demo /tmp/rootfs /busybox sh
bbsh$ PATH=/
bbsh$ busybox ln busybox ln
bbsh$ ln busybox echo
bbsh$ ln busybox ls
bbsh$ ls
busybox  echo     ln       ls
bbsh$ ls -id /          # Compare with inode number above
319459 /
bbsh$ echo 'hello world'
hello world

Program source

/* pivot_root_demo.c */
#define _GNU_SOURCE
#include <err.h>
#include <limits.h>
#include <sched.h>
#include <signal.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/mman.h>
#include <sys/mount.h>
#include <sys/stat.h>
#include <sys/syscall.h>
#include <sys/wait.h>
#include <unistd.h>
static int
pivot_root(const char *new_root, const char *put_old)
{
    return syscall(SYS_pivot_root, new_root, put_old);
}
#define STACK_SIZE (1024 * 1024)
static int              /* Startup function for cloned child */
child(void *arg)
{
    char        path[PATH_MAX];
    char        **args = arg;
    char        *new_root = args[0];
    const char  *put_old = "/oldrootfs";
    /* Ensure that 'new_root' and its parent mount don't have
       shared propagation (which would cause pivot_root() to
       return an error), and prevent propagation of mount
       events to the initial mount namespace. */
    if (mount(NULL, "/", NULL, MS_REC | MS_PRIVATE, NULL) == -1)
        err(EXIT_FAILURE, "mount-MS_PRIVATE");
    /* Ensure that 'new_root' is a mount point. */
    if (mount(new_root, new_root, NULL, MS_BIND, NULL) == -1)
        err(EXIT_FAILURE, "mount-MS_BIND");
    /* Create directory to which old root will be pivoted. */
    snprintf(path, sizeof(path), "%s/%s", new_root, put_old);
    if (mkdir(path, 0777) == -1)
        err(EXIT_FAILURE, "mkdir");
    /* And pivot the root filesystem. */
    if (pivot_root(new_root, path) == -1)
        err(EXIT_FAILURE, "pivot_root");
    /* Switch the current working directory to "/". */
    if (chdir("/") == -1)
        err(EXIT_FAILURE, "chdir");
    /* Unmount old root and remove mount point. */
    if (umount2(put_old, MNT_DETACH) == -1)
        perror("umount2");
    if (rmdir(put_old) == -1)
        perror("rmdir");
    /* Execute the command specified in argv[1]... */
    execv(args[1], &args[1]);
    err(EXIT_FAILURE, "execv");
}
int
main(int argc, char *argv[])
{
    char *stack;
    /* Create a child process in a new mount namespace. */
    stack = mmap(NULL, STACK_SIZE, PROT_READ | PROT_WRITE,
                 MAP_PRIVATE | MAP_ANONYMOUS | MAP_STACK, -1, 0);
    if (stack == MAP_FAILED)
        err(EXIT_FAILURE, "mmap");
    if (clone(child, stack + STACK_SIZE,
              CLONE_NEWNS | SIGCHLD, &argv[1]) == -1)
        err(EXIT_FAILURE, "clone");
    /* Parent falls through to here; wait for child. */
    if (wait(NULL) == -1)
        err(EXIT_FAILURE, "wait");
    exit(EXIT_SUCCESS);
}

chdir(2), chroot(2), mount(2), stat(2), initrd(4), mount_namespaces(7), pivot_root(8), switch_root(8)