Factory Reset (shani-reset)

Updates & Config 2026-08-28

shani-reset wipes all persistent system state stored in /data and reboots the machine. On the next boot, systemd-tmpfiles recreates the /data structure, the /etc overlay starts fresh from the read-only root, and all services start as if this were a first-run.

What Gets Wiped

What	Location	Notes
All `/etc` modifications	`/data/overlay/etc/upper/`	Includes user accounts (`/etc/passwd`, `/etc/shadow`, `/etc/group`), hostname, locale, sshd config, enabled units, `subuid`/`subgid`
All `/var` overlay changes	`/data/overlay/var/upper/`	Only if `/var` overlay is in use
All persistent service state	`/data/varlib/*/`	Wi-Fi passwords, Bluetooth pairings, Tailscale key, TPM2 state, printer configs, etc.
Job scheduler spools	`/data/varspool/*/`	Cron jobs, at jobs, mail queue
Cached OS downloads	`/data/downloads/`	Skipped with `--keep-downloads`
Boot state markers	`/data/boot_*`	All failure and success markers
Deployment flag	`/data/deployment_pending`	Any in-flight deployment

What Is NOT Wiped

What	Notes
`/home`	User files in the `@home` subvolume — separate from `/data`
`/root`	Root home in the `@root` subvolume
`@blue` / `@green`	OS root subvolumes — system still boots the same slot
ESP / UKI boot images	System still boots correctly after reset
`/data/current-slot`	Preserved so the system boots into the correct slot

Usage

# Default: selective wipe of /data state directories, then reboot
sudo shani-reset

# Preview what would be wiped without making changes
sudo shani-reset --dry-run

# Hard wipe: remove everything under /data, let tmpfiles recreate
sudo shani-reset --hard

# Preserve cached OS images (can be several GB)
sudo shani-reset --keep-downloads

# Also wipe /home (all user files — irreversible, asks twice)
sudo shani-reset --home

# Skip the confirmation prompt (for scripted use)
sudo shani-reset --yes

shani-reset refuses to run while a shani-deploy is mid-flight (/data/deployment_pending exists) — complete or roll back the deployment first (sudo shani-deploy --rollback) before resetting.

Without --yes, confirmation requires typing the exact word, not just y: type reset to proceed, and — if --home is also given — a second prompt requires typing wipe home to actually wipe user files (declining just continues the reset without touching /home). After the reset completes, shani-reset reboots automatically after a 3-second countdown (Ctrl-C aborts the reboot, but the state has already been wiped by that point).

Soft Wipe vs Hard Wipe

Both modes produce the same end state after reboot. Choose based on your situation:

Soft wipe (default): Selectively clears the state directories. The bind-mount targets (e.g. /data/varlib/NetworkManager) are preserved as empty directories, which is required for the bind mounts to work immediately after reboot without a systemd-tmpfiles run.

Hard wipe (--hard): Removes everything under /data in one pass, including any files that accumulated outside the expected structure. systemd-tmpfiles recreates the full directory tree on the next boot. This is cleaner but requires tmpfiles to run before services can bind-mount their state.

User Accounts After Reset

Important: User accounts are stored in /etc/passwd, /etc/shadow, and /etc/group — which live in the /etc overlay (/data/overlay/etc/upper/). Resetting the overlay wipes all user accounts created after installation.

What happens after reboot:

The system boots into the reset state with only the default accounts from the read-only root
On a desktop system, the KDE (plasma-welcome) or GNOME (gnome-initial-setup) first-run wizard starts automatically and creates a new user account
The shani-user-setup service provisions the new user with the correct groups, shell, Flatpak remotes, and Nix channels
Files in /home are intact — once the account is re-created with the same username, all personal files are immediately accessible again

If you run the reset on a headless server without a first-run wizard, create the user manually after reboot:

# Create the user (the adduser wrapper ensures correct group membership)
sudo adduser myuser

# Or manually with usermod after useradd
sudo useradd -m myuser
sudo usermod -aG wheel,video,input,audio myuser
sudo passwd myuser

What Happens After Reboot

systemd-tmpfiles recreates /data structure from shanios-data-structure.conf
/etc overlay starts fresh from the @blue or @green read-only root
All services start in their initial state (first-time setup)
shani-update runs automatically and offers to update to the latest version
Desktop first-run wizard guides through locale, timezone, and user account creation

Examples

Reset a misconfigured system

# Preview what would be wiped
sudo shani-reset --dry-run

# Perform the reset
sudo shani-reset

Reset while preserving large OS downloads

sudo shani-reset --keep-downloads

Complete factory reset including user files

# This is irreversible — all personal files in /home will be deleted
sudo shani-reset --home

Scripted reset (no prompts)

sudo shani-reset --yes --keep-downloads