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
Display help
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)