BOOTC-EX...LL-RESET(7)

okay bestie, pull up a chair 🫶 you're looking at bootc-experimental-install-reset, and yes, it lives in section 7 of the Miscellaneous Information Manual. it's giving "factory reset but make it careful" and we're gonna go through it together, every last flag, no skipping, periodt 💖

💅 NAME 💅

bootc-experimental-install-reset — Factory reset with bootc install reset ✨

---

🌸 DESCRIPTION 🌸

okay so first things first, the important part: this is an experimental feature. you gotta pass the --experimental flag to acknowledge that. no flag, no reset, that's the vibe check 🔥

🦋 Overview 🦋

the bootc install reset command lets you do a non-destructive factory reset of an existing bootc system. what that means, bestie, is it creates a fresh installation state in a new stateroot while preserving the existing system's files on disk. so nothing gets nuked 🙈

after you reboot into the new deployment, you can still get at the old system's data by poking around in /sysroot/ostree/deploy/<old-stateroot>/. the old stuff is right there, just chilling 💜

✨ How it works ✨

when you run bootc install reset, here's the whole sequence, in order:

1. a new stateroot gets created with an automatically generated name. the format is state-<year>-<serial>, e.g., s2025-0 ⭐
2. a fresh deployment is created in that new stateroot using the currently booted image (or, optionally, a different image if you pass --target-imgref) 🎀
3. kernel arguments related to root filesystem configuration are automatically inherited from the current deployment 👑
4. the /boot fstab entry is preserved from the current system if it exists 💖
5. the new deployment becomes the default boot target 🦋

after rebooting, you'll be running in a completely fresh system state:

• /etc contains only the configuration from the container image
• /var is empty (no user data or state from the previous system)
• the old stateroot's files remain on disk at /sysroot/ostree/deploy/<old-stateroot>/ and can be accessed for data recovery or inspection

🛠️ Usage 🛠️

basic usage, i.e. reset to the same image you're currently running:

bootc install reset --experimental

reset and switch to a different image:

bootc install reset --experimental --target-imgref quay.io/example/myimage:latest

reset with a custom stateroot name:

bootc install reset --experimental --stateroot production-2025

reset and immediately reboot:

bootc install reset --experimental --apply

add custom kernel arguments:

bootc install reset --experimental --karg=console=ttyS0,115200n8

skip inheriting root filesystem kernel arguments:

bootc install reset --experimental --no-root-kargs

🧚 Kernel arguments 🧚

by default, bootc install reset automatically inherits kernel arguments from the currently booted deployment that are related to root filesystem configuration. this includes:

• root= — root device specification
• rootflags= — root filesystem mount options
• rd.* arguments — initramfs arguments (e.g., for LVM, LUKS, network root)
• kernel arguments defined in /usr/lib/bootc/kargs.d/ and /etc/bootc/kargs.d/

and you can:

• add additional kernel arguments with --karg (can be specified multiple times)
• skip automatic root filesystem argument inheritance with --no-root-kargs

🌈 Use cases 🌈

• development/testing: quickly return to a clean state while preserving the ability to boot back to your development environment
• troubleshooting: reset to a known-good state without losing access to the problematic deployment for debugging
• system refresh: start fresh after accumulating configuration changes, while keeping the old state accessible
• image testing: test a new image version in a separate stateroot before committing to it

🧹 Cleaning up the old stateroot 🧹

after performing a factory reset and rebooting into the new stateroot, the old stateroot remains on disk at /sysroot/ostree/deploy/<old-stateroot>/. this lets you access files from the previous system if you need them. lowkey a safety net 💜

once you no longer need the old stateroot, you can remove it to free up disk space:

1. first, remove any remaining deployments from the old stateroot:

# List all deployments to find the old stateroot's deployment index
ostree admin status

# Remove the old deployment(s) by index
# The index is shown in the output (e.g., "1" for the second deployment)
ostree admin undeploy <index>

2. after all deployments from the old stateroot are removed, you can delete the stateroot directory:

# Replace "default" with your old stateroot name if different
mount -o remount,rw /sysroot
rm -rf /sysroot/ostree/deploy/default

Note: you cannot remove the stateroot directory while deployments still exist in it. OSTree protects deployment directories with filesystem-level mechanisms, so you must undeploy them first using ostree admin undeploy. no shortcuts, bestie 😭

🚧 Limitations 🚧

• this command requires the --experimental flag as the feature is still under development
• only works on systems already running bootc (not for initial installations)
• the old stateroot is not automatically removed and will consume disk space until manually deleted (see the "Cleaning up the old stateroot" section above)

👀 See also 👀

• bootc switch — switch to a different container image
• bootc status — view current deployment status

📚 SEE ALSO 📚

bootc(8), bootc-docs(7)

⭐ VERSION ⭐

v1.17.1

---

and that's the whole page, bestie 💅 you made it to the end, iconic behavior. this was bootc-experimental-install-reset from the Miscellaneous Information Manual, version v1.17.1 — go forth and reset responsibly, and don't forget the --experimental flag or nothing happens 🫶✨