.TH switchroot 8

'''

.SH NAME

switchroot \- replace initramfs with a newly mounted root filesystem.

'''

.SH SYNOPSIS

switchroot \fI/mnt/newroot\fR \fI/sbin/init\fR ...

'''

.SH DESCRIPTION

switchroot is a single-use tool needed to get rid of initramfs once the real

root has been mounted.

.P

Initramfs is a special filesystem loaded into the kernel early during boot,

serving as the root filesystem until the real root gets mounted. Typically

it contains just enough of userspace code to find and mount the real rootfs.

.P

Unlike any other mounted filesystem, initramfs cannot be unmounted, and

exchanging it with the real root using \fBpivot_root\fR(2) is not allowed.

The real root must be mounted over initramfs, using move mount from its

original mountpoint to /.

.P

Before mounting the real root, initramfs must be wiped by unlinking all

the files there. Anything left behind will not be accessible but will still

waste kernel memory.

.P

When invoked, switchroot deletes everything on / without crossing file

system boundaries, move-mounts \fInewroot\fR to /, and executes

\fI/sbin/init\fR in the new root.

'''

.SH NOTES

switchroot does the equivalent of rm -r / before switching to the new root.

This is rather dangerous, so switchroot tries to make extra sure the files

being deleted reside on initramfs by calling \fBstatfs\fR(2).

.P

switchroot must always be run as pid 1, since it execs into \fBinit\fR(8).

This means the initramfs init must exec into switchroot.

.P

Any virtual filesystems that happen to be mounted onto initramfs will

be move-mounted onto the same location within newroot. Failing that,

switchroot will try to umount it.

'''

.SH SEE ALSO

\fBmount\fR(8), \fBmountvfs\fR(8), \fBmount\fR(2), \fBpivot_root\fR(2).