mirror of
https://github.com/troglobit/finit.git
synced 2026-10-24 11:54:36 +00:00
Implement switch_root functionality allowing Finit to serve as the init
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.
This commit is contained in:
Aaron Andersen committed
1 parent
e6d3eb2526
commit
373738f3d1
15 files changed
+654
-1
No files matched your search
@@ -288,4 +288,27 @@ Rescue mode can be disabled at build time with `configure --without-rescue`.
|
||||
See the [Rescue Mode](config/rescue.md) section for more information.
|
||||
|
||||
|
||||
**Switch Root**
|
||||
|
||||
Finit supports switching from an initramfs to a real root filesystem using
|
||||
the built-in `initctl switch-root` command. This allows Finit to serve as
|
||||
the init system in an initramfs for early boot tasks (LUKS unlock, LVM
|
||||
activation, network boot) before transitioning to the real root.
|
||||
|
||||
```bash
|
||||
# In initramfs, after mounting the real root:
|
||||
initctl switch-root /mnt/root
|
||||
```
|
||||
|
||||
The switch-root operation:
|
||||
|
||||
1. Runs the `HOOK_SWITCH_ROOT` hook for cleanup
|
||||
2. Stops all services gracefully
|
||||
3. Moves virtual filesystems (`/dev`, `/proc`, `/sys`, `/run`) to the new root
|
||||
4. Deletes initramfs contents to free memory
|
||||
5. Pivots to the new root and execs the new init
|
||||
|
||||
See the [Switch Root](switchroot.md) section for complete documentation.
|
||||
|
||||
|
||||
[5]: https://en.wikipedia.org/wiki/Runlevel
|
||||
@@ -39,6 +39,7 @@ Features
|
||||
* [Cgroups v2](config/cgroups.md), both configuration and monitoring in [`initctl top`](initctl.md)
|
||||
* [Plugin support](plugins.md) for customization
|
||||
* Proper [rescue mode](config/rescue.md) with bundled `sulogin` for protected maintenance shell
|
||||
* [Switch root](switchroot.md) support for initramfs-to-real-root transitions
|
||||
* Integration with [watchdogd][] for full system supervision
|
||||
* [Logging](config/logging.md) to kernel ring buffer before `syslogd` has started, see the
|
||||
recommended [sysklogd][] project for complete logging integration
|
||||
|
||||
@@ -65,6 +65,7 @@ Commands:
|
||||
halt Halt system
|
||||
poweroff Halt and power off system
|
||||
suspend Suspend system
|
||||
switch-root NEWROOT [INIT] Switch to new root filesystem (initramfs only)
|
||||
|
||||
utmp show Raw dump of UTMP/WTMP db
|
||||
```
|
||||
@@ -143,3 +144,24 @@ Apr 8 12:37:46 alpine authpriv.info dropbear[2300]: Exit (root) from <192.168.1
|
||||
Apr 8 15:02:11 alpine authpriv.info dropbear[2634]: Child connection from 192.168.121.1:48576
|
||||
Apr 8 15:02:12 alpine authpriv.notice dropbear[2634]: Password auth succeeded for 'root' from 192.168.121.1:48576
|
||||
```
|
||||
|
||||
|
||||
Switch Root
|
||||
-----------
|
||||
|
||||
The `switch-root` command is used when running Finit in an initramfs to
|
||||
transition to the real root filesystem. This is similar to the standalone
|
||||
`switch_root(8)` utility but integrated into Finit.
|
||||
|
||||
```
|
||||
initctl switch-root /mnt/root [/sbin/init]
|
||||
```
|
||||
|
||||
Requirements:
|
||||
|
||||
- Must be run during runlevel S (bootstrap) or runlevel 1
|
||||
- The new root must be a mount point (different device than /)
|
||||
- Can only be used when Finit is running as PID 1 in an initramfs
|
||||
|
||||
For complete documentation and usage examples, see the dedicated
|
||||
[Switch Root](switchroot.md) section.
|
||||
@@ -205,6 +205,16 @@ hook points:
|
||||
new runlevel have been been stopped. When the hook has completed,
|
||||
Finit continues to start all services in the new runlevel.
|
||||
|
||||
### Switch Root Hooks
|
||||
|
||||
* `HOOK_SWITCH_ROOT`, `hook/sys/switchroot`: Called when
|
||||
`initctl switch-root` is issued, before the transition begins. Use
|
||||
this hook to save state, unmount initramfs-only filesystems, or perform
|
||||
cleanup before switching to the new root. Only runs when Finit is
|
||||
operating as PID 1 in an initramfs.
|
||||
|
||||
See the [Switch Root](switchroot.md) section for more information.
|
||||
|
||||
### Shutdown Hooks
|
||||
|
||||
* `HOOK_NETWORK_DN`, `hook/net/down`: Called right after having changed
|
||||
|
||||
@@ -0,0 +1,148 @@
|
||||
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)
|
||||
Reference in new issue
Block a user