How to Reset a User's Home Directory to Defaults on Bluefin#

Overview#

Sometimes a user's home directory ends up in a state where it can't be easily untangled from the inside. A single malformed dotfile can trigger a login loop. A bad shell configuration can leave every terminal session broken. A corrupted GNOME extension or desktop environment setting can make it impossible to reach a working graphical session at all.

When targeted fixes aren't an option, the cleanest recovery path is to start the home directory fresh from a known-good baseline — keeping the user account intact, but replacing their configuration state with defaults.

Common scenarios where this is necessary:

This guide walks through replacing a user's home directory with a fresh copy populated from /etc/skel, the system-provided skeleton directory, while preserving all existing data in a .old backup for selective recovery.

⚠️ This is not the same as ujust powerwash. That command performs a full system factory reset via bootc install reset --experimental, which creates an entirely new stateroot and wipes all user data in /home and /var. This guide only resets a specific user's home directory — the rest of the system and all other user accounts are completely unaffected.

Bluefin's Filesystem Architecture#

On Bluefin (and all Fedora Atomic desktops), /home is a symlink to /var/home 1. The /var directory is persistent — it survives every bootc image update and atomic deployment. This means:

• Your user's home directory lives at /var/home/<username>
• The .old backup you create in this guide also lives in /var/home/ and will survive system updates
• Always use /var/home/<username> paths in administrative commands to avoid any ambiguity from symlink resolution

Prerequisites#

Before starting, make sure the following conditions are met. Skipping these steps can lead to partial results or data corruption.

1. The Target User Must Be Fully Logged Out#

The user whose home directory you're resetting must have no active sessions — no graphical session, no active TTY, no lingering background processes. Operating on a home directory while a user session is live can corrupt application state or cause files to be recreated mid-operation.

2. No Processes Running Under the Target Account#

Verify that the user has no active processes:

ps aux | grep <username>

If any processes appear (other than the grep command itself), terminate them before proceeding:

sudo loginctl terminate-user <username>

3. Run Commands from a TTY as Root or an Administrative User#

These commands must be run from a separate administrative context — not from a graphical terminal opened in the target user's session. Switch to a TTY with Ctrl+Alt+F3 and log in as root or another wheel-group user.

4. Back Up Any Data You Want to Preserve#

⚠️ Read this before continuing. The rename operation in Step 1 of the procedure preserves all existing data as a .old backup, but that backup is only useful if you know what you want to recover from it afterward. Before proceeding:

• Note the user's important data directories: Documents, Downloads, Pictures, Music, Videos
• Consider exporting browser bookmarks or other application-specific data first
• If you're uncertain what configuration caused the problem, don't delete the .old backup until you've confirmed the system works correctly for an extended period

Tools available for additional backup before starting:

# Archive the home directory to external media or another location
sudo tar -czf /mnt/backup/<username>-home-$(date +%Y%m%d).tar.gz /var/home/<username>

Reset Procedure#

Run all of the following commands from a TTY session (Ctrl+Alt+F3) as root or another administrative user. Replace <username> with the actual username in every command.

Step 1: Back Up the Current Home Directory#

sudo mv /var/home/<username> /var/home/<username>.old

This renames the entire home directory in a single atomic operation. Because it's a rename within the same filesystem, this completes instantly regardless of how large the home directory is — no data is duplicated or copied. The original directory is now preserved at /var/home/<username>.old for selective recovery later.

Because this backup lives inside /var, it will persist across bootc system updates and image deployments 1.

Step 2: Create a Fresh Home Directory with Correct Permissions#

sudo mkdir /var/home/<username>
sudo chown <username>:<username> /var/home/<username>
sudo chmod 700 /var/home/<username>

Each command has a specific role:

Note: If you're unsure of the user's primary group name, it is typically the same as the username on Fedora-based systems. You can verify with id <username>.

Step 3: Populate with Default Configuration Files#

sudo cp -rT /etc/skel /var/home/<username>
sudo chown -R <username>:<username> /var/home/<username>

/etc/skel is the skeleton directory — the template that the system uses to initialize new user home directories. When a new user account is created, the contents of /etc/skel are copied into their home directory automatically. This step replicates that process manually.

Flag breakdown:

What /etc/skel contains on Bluefin:

On a standard Bluefin installation, /etc/skel includes:

• Standard shell initialization files (.bashrc, .bash_profile, .profile) from the base Fedora image
• Flatpak sandbox overrides for VS Code (Wayland + Podman socket) and Chrome 2 3
• The Catppuccin Dynamic color palette for the GNOME Ptyxis terminal 4
• On Bluefin DX: default VS Code settings (settings.json) with Cascadia Code font and auto-update disabled 5

The second chown -R command ensures that all files copied from /etc/skel — which were placed by root — are recursively re-owned by the target user.

After completing these three steps, the user has a clean home directory built from Bluefin's defaults. Proceed to the Verification section before logging the user back in.

Bluefin-Specific Considerations#

Home Directory Path: /var/home vs /home#

On Bluefin (and all Fedora Atomic desktops), /home is a symbolic link to /var/home. Both paths point to the same physical location on disk. However, always use /var/home/<username> in administrative commands to avoid any ambiguity from symlink traversal behavior — especially in scripts, chown -R operations, or any tool that may not follow symlinks consistently 1.

/home → /var/home (symlink)
/var/home/<username>/ (actual location)

What Happens on First Login After the Reset#

Bluefin runs a user-level systemd service, ublue-user-setup.service, that fires automatically when a user starts a graphical session 6. This service:

• Executes all scripts in /usr/share/ublue-os/user-setup.hooks.d/
• Applies hardware-specific GNOME settings (e.g., font scaling on Framework 13, natural scrolling on Framework laptops, Ampere logo on Thelio Astra systems)
• On Bluefin DX: installs VS Code remote extensions and copies the default settings.json if not already present
• Tracks which hooks have run via ~/.local/share/ublue/setup_versioning.json to avoid repeating them on subsequent logins 7

After a home directory reset, all setup hooks will re-run from scratch — since setup_versioning.json no longer exists, every hook is treated as if it's running for the first time. This is the correct behavior and is what you want: the user gets the same first-login experience as a fresh install.

Scope of the Reset: What Is and Isn't Restored#

Understanding what this procedure covers helps you know what to recover from the .old backup:

⚠️ SSH and GPG keys are particularly important. Do not proceed without first verifying that backups of ~/.ssh/ and ~/.gnupg/ exist in the .old directory, or exported to safe storage, if the user relies on them.

/var Persistence Across System Updates#

The .old backup you created in Step 1 lives inside /var, which means it persists across all bootc image updates, system rollbacks, and deployments. You do not need to rush to recover data from it — it will still be there after a system update or reboot. Only delete it after you have confirmed the new home directory is working correctly and all important data has been recovered 1.

Alternative: btrfs Snapshot Backup#

If your Bluefin installation uses btrfs (the default filesystem for Bluefin Stable), you can use a btrfs subvolume snapshot as a more space-efficient alternative to the mv rename approach for backing up the home directory .

btrfs or XFS? Bluefin Stable defaults to btrfs with zstd:1 compression. Bluefin LTS defaults to XFS. Check with findmnt -T /var/home to confirm the filesystem type on your system. The snapshot commands below apply only to btrfs.

Creating a Snapshot Backup#

sudo btrfs subvolume snapshot /var/home/<username> /var/home/<username>.backup

Advantages over mv:

To create multiple timestamped snapshots before attempting incremental fixes:

sudo btrfs subvolume snapshot /var/home/<username> /var/home/<username>.backup-$(date +%Y%m%d-%H%M)

Restoring from a btrfs Snapshot#

If you need to roll back to the snapshot state:

sudo btrfs subvolume delete /var/home/<username>
sudo btrfs subvolume snapshot /var/home/<username>.backup /var/home/<username>
sudo chown -R <username>:<username> /var/home/<username>

⚠️ Subvolume deletion is not the same as rm -rf. btrfs subvolume delete removes the subvolume entry and schedules its data for asynchronous cleanup. If the home directory is not a btrfs subvolume (just a regular directory on a btrfs filesystem), use rm -rf followed by the snapshot restore instead .

⚠️ Snapshots are not recursive. If the home directory contains nested btrfs subvolumes, those are not included in the snapshot — they appear as empty stub entries. This is rarely a concern for typical user home directories, but worth noting for advanced setups .

Cleaning Up Snapshots#

Once you have confirmed the reset home directory works correctly:

sudo btrfs subvolume delete /var/home/<username>.backup

Or if you used a simple directory snapshot (not a subvolume):

sudo rm -rf /var/home/<username>.backup

Recovering Personal Data#

Once you have confirmed the user can log in successfully with the reset home directory (see Verification), you can selectively restore data from the .old backup. Approach this carefully — the goal is to recover data without accidentally restoring the configuration that caused the original problem.

Restoring User Data Directories#

Personal data (documents, downloads, media) is safe to copy back without concern:

# Restore common personal data directories
sudo cp -r /var/home/<username>.old/Documents /var/home/<username>/
sudo cp -r /var/home/<username>.old/Downloads /var/home/<username>/
sudo cp -r /var/home/<username>.old/Pictures /var/home/<username>/
sudo cp -r /var/home/<username>.old/Music /var/home/<username>/
sudo cp -r /var/home/<username>.old/Videos /var/home/<username>/

# Fix ownership on all restored data
sudo chown -R <username>:<username> \
  /var/home/<username>/Documents \
  /var/home/<username>/Downloads \
  /var/home/<username>/Pictures \
  /var/home/<username>/Music \
  /var/home/<username>/Videos

Restoring SSH and GPG Keys#

SSH and GPG keys should be among the first things you restore, as they're often critical for workflow:

# Restore SSH keys
sudo cp -r /var/home/<username>.old/.ssh /var/home/<username>/
sudo chown -R <username>:<username> /var/home/<username>/.ssh
sudo chmod 700 /var/home/<username>/.ssh
sudo chmod 600 /var/home/<username>/.ssh/id_*
sudo chmod 644 /var/home/<username>/.ssh/id_*.pub
sudo chmod 644 /var/home/<username>/.ssh/authorized_keys 2>/dev/null || true

# Restore GPG keys
sudo cp -r /var/home/<username>.old/.gnupg /var/home/<username>/
sudo chown -R <username>:<username> /var/home/<username>/.gnupg
sudo chmod 700 /var/home/<username>/.gnupg

Selectively Restoring Application Configurations#

For application configuration (under ~/.config/ and ~/.local/share/), restore directories one at a time and test after each one. This lets you isolate which configuration caused the original problem if it reappears.

# Example: Restore only a specific application's config
sudo cp -r /var/home/<username>.old/.config/gedit /var/home/<username>/.config/
sudo chown -R <username>:<username> /var/home/<username>/.config/gedit

Restoring browser data selectively (bookmarks only, not the full profile):

# Example: Firefox bookmarks without restoring the full profile
# Find the profile directory name first
ls /var/home/<username>.old/.mozilla/firefox/

# Then copy only the bookmarks database
sudo cp /var/home/<username>.old/.mozilla/firefox/<profile-name>/places.sqlite \
        /var/home/<username>/.mozilla/firefox/<profile-name>/
sudo chown <username>:<username> /var/home/<username>/.mozilla/firefox/<profile-name>/places.sqlite

Pro tip: Restore in batches — data directories first, then low-risk application configs, then any configuration you suspect might be related to the original problem. This way, if the issue reappears, you can narrow it down to the last batch you restored.

Restoring Flatpak Application Data#

Flatpak application data lives under ~/.var/app/ and is generally safe to restore (it's data, not system configuration):

sudo cp -r /var/home/<username>.old/.var /var/home/<username>/
sudo chown -R <username>:<username> /var/home/<username>/.var

However, if a Flatpak application's configuration was the source of the original problem, restore its directory with caution.

Verification#

After completing the reset procedure, verify the new home directory is working correctly before declaring success (and before removing the .old backup).

1. Confirm the User Can Log In#

From the display manager, log in as the target user. The login should proceed without looping or crashing. If it loops immediately, the issue may be at the PAM or systemd session level rather than in the home directory itself.

2. Verify the Desktop Environment Loads#

The GNOME desktop should appear normally. Check for:

• No crash dialogs on startup
• GNOME Shell functioning correctly (Activities overview, top bar, notifications)
• Wallpaper and basic theming applied

If the GNOME session crashes, check the journal for clues:

journalctl --user -b | grep -E "(error|crash|fail)" | head -50

3. Check that ublue-user-setup.service Ran Successfully#

Open a terminal and verify the user setup service completed without errors 6:

systemctl --user status ublue-user-setup.service

Expected output shows Active: inactive (dead) with a successful exit code (Succeeded). If it failed, check the logs:

journalctl --user -u ublue-user-setup.service

The ~/.local/share/ublue/setup_versioning.json file should have been created, indicating the setup hooks ran 7:

cat ~/.local/share/ublue/setup_versioning.json

4. Confirm Shell Initialization Works#

Open a terminal. The shell prompt should appear without errors. Test basic functionality:

echo $HOME # Should show /var/home/<username> or /home/<username>
echo $SHELL # Should show your configured shell
ls -la ~/ # Should show the new skel-populated contents

5. Test Essential Applications#

Launch a few key applications — file manager, text editor, a browser — and confirm they open without errors. First-launch behavior (fresh configuration dialogs) is expected and normal.

Quick Verification Checklist#

Cleanup#

Once you have verified that the reset home directory works correctly and you have recovered all necessary data from the .old backup, you can safely remove it:

sudo rm -rf /var/home/<username>.old

⚠️ This is irreversible. Once the .old directory is deleted, the original home directory data is gone. Only run this command after:

• Confirming the user can log in and the desktop environment works correctly
• Recovering all personal data (documents, SSH keys, GPG keys, application data)
• Spending enough time with the reset configuration to be confident the original problem is not resurfacing from a different source

There is no urgency to delete the backup. Because /var persists across bootc updates and system reboots 1, the .old directory will remain available indefinitely until you remove it. It is perfectly acceptable to leave it for days or weeks while you confirm the new configuration is stable.

If you used a btrfs snapshot instead of the mv approach, remove it with:

sudo btrfs subvolume delete /var/home/<username>.old

Or if it was a regular directory on a btrfs filesystem:

sudo rm -rf /var/home/<username>.old

Related Documentation#

• Storage and Partitioning — Covers Bluefin's filesystem layout, the role of /var, and partition defaults for Stable vs. LTS variants.

• Btrfs Snapshots and Subvolumes — Detailed guidance on btrfs snapshot strategies, incremental backup with btrfs send/btrfs receive, and backup tooling like Pika Backup and Déjà Dup.

• Bootc System Reset (ujust powerwash) — For full system factory resets. Unlike this guide, ujust powerwash creates a new stateroot and wipes all user data. Use this guide when you only need to reset a single user's configuration.

• OSTree/bootc User and Group Management — Explains how user accounts and group memberships work on an immutable ostree-backed system, including the 3-way merge behavior of /etc/passwd and /etc/group.

• bootc Filesystem Documentation — Upstream reference for the /var, /etc, and /usr persistence model underlying Bluefin's storage architecture 1.