LinuxCommandLibrary

switch_root

Change root filesystem to another

TLDR

Move /proc, /dev, /sys and /run to the specified filesystem, use this filesystem as the new root and start the specified init process

$ switch_root [new_root] [/sbin/init]
copy

Display help
$ switch_root [[-h|--help]]
copy

SYNOPSIS

switch_root new_root init [args]

PARAMETERS

new_root
    The directory to become the new root filesystem. This must be a mount point.

init
    The program to execute as init on the new root filesystem (e.g., /sbin/init or /bin/systemd). The process with PID 1.

args
    Optional arguments to pass to the init program.

DESCRIPTION

The switch_root command is a simple utility primarily used during the Linux boot process, especially within initramfs or initrd environments. Its primary function is to transition the system's root filesystem from the initial ramdisk/ramfs to a new, persistent root filesystem (usually located on a hard drive or other storage device). It performs several crucial steps: moves all processes from the old root filesystem to the new one, unmounts the old root filesystem, and then executes the specified init program on the new root filesystem. This allows the system to transition from the temporary, minimal environment used for initial setup to the full operating system.
Important: This is a destructive operation. After switch_root executes, the previous root filesystem is no longer accessible. It can only be used once.

CAVEATS

switch_root is a very low-level tool and should typically only be used within initramfs scripts or other specialized boot environments. Incorrect usage can lead to a non-bootable system.
Be very careful when creating the new_root, especially with permissions.

ERROR HANDLING

If switch_root encounters an error, it will typically panic the kernel, leading to a system halt. Therefore, careful error checking and handling within the calling script (typically within the initramfs) are crucial. For example, check that the root partition is succesfully mounted at the 'new_root' point before calling switch_root.

INITRAMFS CONTEXT

The initramfs is a minimal root filesystem that is loaded into RAM during the early stages of booting. It contains essential drivers and utilities needed to mount the real root filesystem. switch_root is used to transition from this temporary environment to the persistent storage.

HISTORY

switch_root has been part of the util-linux package for a considerable time. It fills the niche of transitioning the root filesystem during the early stages of the boot process, prior to the full init system being available. Its purpose is to simplify the handoff from the initial RAM-based environment to the final storage where your os lives.

SEE ALSO

pivot_root(2), mount(8), umount(8)

Copied to clipboard