mirror of
https://github.com/troglobit/finit.git
synced 2026-10-02 14:02:52 +07:00
Aaron Andersen
373738f3d1
in an initramfs, then transition to the real root filesystem. Useful for systems requiring early boot tasks like LUKS unlock, LVM activation, or network boot before mounting the real root. Adds INIT_CMD_SWITCH_ROOT API command, `initctl switch-root` subcommand, and HOOK_SWITCH_ROOT plugin hook point. The implementation gracefully stops services, moves virtual filesystems (/dev, /proc, /sys, /run) to the new root, deletes initramfs contents to free memory, then execs the new init as PID 1. See GitHub Discussion #292 for background.
149 lines
4.0 KiB
Markdown
149 lines
4.0 KiB
Markdown
Switch Root
|
|
===========
|
|
|
|
Finit supports switching from an initramfs to a real root filesystem
|
|
using the `initctl switch-root` command. This is useful for systems
|
|
that use an initramfs for early boot (LUKS, LVM, network boot, etc.)
|
|
and need to transition to the real root before starting services.
|
|
|
|
|
|
Usage
|
|
-----
|
|
|
|
```sh
|
|
initctl switch-root NEWROOT [INIT]
|
|
```
|
|
|
|
- `NEWROOT`: Path to the mounted new root filesystem (e.g., `/mnt/root`)
|
|
- `INIT`: Optional path to init on the new root (default: `/sbin/init`)
|
|
|
|
|
|
Requirements
|
|
------------
|
|
|
|
1. Must be run during runlevel S (bootstrap) or runlevel 1
|
|
2. `NEWROOT` must be a mount point (different device than /)
|
|
3. `INIT` must exist and be executable on the new root
|
|
4. Finit must be running as PID 1 (in initramfs)
|
|
|
|
|
|
How It Works
|
|
------------
|
|
|
|
1. Runs `HOOK_SWITCH_ROOT` for any cleanup scripts/plugins
|
|
2. Runs `HOOK_SHUTDOWN` to notify plugins
|
|
3. Stops all services and kills remaining processes
|
|
4. Exits all plugins gracefully
|
|
5. Moves `/dev`, `/proc`, `/sys`, `/run` to new root
|
|
6. Deletes initramfs contents (if on tmpfs/ramfs) to free memory
|
|
7. Moves new root mount to `/`
|
|
8. Chroots to new root
|
|
9. Reopens `/dev/console` for stdin/stdout/stderr
|
|
10. Execs new init as PID 1
|
|
|
|
|
|
Example: Initramfs finit.conf
|
|
-----------------------------
|
|
|
|
Configuration file `/etc/finit.conf` in the initramfs:
|
|
|
|
```
|
|
# /etc/finit.conf in initramfs
|
|
|
|
# Mount the real root filesystem
|
|
run [S] name:mount-root /bin/mount /dev/sda1 /mnt/root -- Mounting root filesystem
|
|
|
|
# Switch to real root after mount completes
|
|
run [S] name:switch-root /sbin/initctl switch-root /mnt/root -- Switching to real root
|
|
```
|
|
|
|
For more complex setups (LUKS, LVM, etc.):
|
|
|
|
```
|
|
# Unlock LUKS volume
|
|
run [S] name:cryptsetup /sbin/cryptsetup open /dev/sda2 cryptroot -- Unlocking encrypted root
|
|
|
|
# Activate LVM
|
|
run [S] name:lvm /sbin/lvm vgchange -ay -- Activating LVM volumes
|
|
|
|
# Mount root
|
|
run [S] name:mount-root /bin/mount /dev/vg0/root /mnt/root -- Mounting root
|
|
|
|
# Switch root
|
|
run [S] name:switch-root /sbin/initctl switch-root /mnt/root -- Switching to real root
|
|
```
|
|
|
|
|
|
Example: Using Runlevel 1 for Switch Root
|
|
-----------------------------------------
|
|
|
|
For more complex initramfs setups where ordering of tasks becomes
|
|
difficult in runlevel S, you can perform the switch-root in runlevel 1:
|
|
|
|
```
|
|
# /etc/finit.conf in initramfs
|
|
|
|
# Start mdevd for device handling
|
|
service [S] name:mdevd notify:s6 /sbin/mdevd -D %n -- Device event daemon
|
|
run [S] name:coldplug <service/mdevd/ready> /sbin/mdevd-coldplug -- Coldplug devices
|
|
|
|
# Mount the real root filesystem (after devices are ready)
|
|
run [S] name:mount-root <run/coldplug/success> /bin/mount /dev/sda1 /mnt/root -- Mounting root
|
|
|
|
# Transition to runlevel 1 after all S tasks complete
|
|
# The switch-root runs cleanly in runlevel 1
|
|
run [1] name:switch-root /sbin/initctl switch-root /mnt/root -- Switching to real root
|
|
```
|
|
|
|
This approach separates the initramfs setup (runlevel S) from the
|
|
switch-root operation (runlevel 1), making task ordering simpler.
|
|
|
|
|
|
Hooks
|
|
-----
|
|
|
|
The `HOOK_SWITCH_ROOT` hook runs before the switch begins. Use it for:
|
|
|
|
- Saving state to the new root
|
|
- Unmounting initramfs-only mounts
|
|
- Cleanup tasks
|
|
|
|
Plugins can register for `HOOK_SWITCH_ROOT` just like other hooks:
|
|
|
|
```c
|
|
static void my_switch_root_hook(void *arg)
|
|
{
|
|
/* Cleanup before switch_root */
|
|
}
|
|
|
|
static plugin_t plugin = {
|
|
.name = "my-plugin",
|
|
.hook[HOOK_SWITCH_ROOT] = {
|
|
.cb = my_switch_root_hook
|
|
}
|
|
};
|
|
|
|
PLUGIN_INIT(plugin_init)
|
|
{
|
|
plugin_register(&plugin);
|
|
}
|
|
```
|
|
|
|
|
|
Conditions
|
|
----------
|
|
|
|
After switch_root, the new finit instance starts fresh. No conditions
|
|
or state are preserved across the switch. The new finit will:
|
|
|
|
1. Re-read `/etc/finit.conf` from the new root
|
|
2. Re-initialize all conditions
|
|
3. Start services according to the new configuration
|
|
|
|
|
|
See Also
|
|
--------
|
|
|
|
- [switch_root(8)](https://man7.org/linux/man-pages/man8/switch_root.8.html) - util-linux switch_root utility
|
|
- [Kernel initramfs documentation](https://docs.kernel.org/filesystems/ramfs-rootfs-initramfs.html)
|