Skip to content

docs: Add man page for bootc-destructive-cleanup.service #1928

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
cgwalters wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: Add man page for bootc-destructive-cleanup.service #1928

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/src/SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@
- [`man bootc-install-to-disk`](man/bootc-install-to-disk.8.md)
- [`man bootc-install-to-filesystem`](man/bootc-install-to-filesystem.8.md)
- [`man bootc-install-to-existing-root`](man/bootc-install-to-existing-root.8.md)
- [`man bootc-destructive-cleanup.service`](man/bootc-destructive-cleanup.service.5.md)

# Bootc usage in containers

Expand Down
59 changes: 59 additions & 0 deletions docs/src/man/bootc-destructive-cleanup.service.5.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# NAME

bootc-destructive-cleanup.service

# DESCRIPTION

This systemd service runs on first boot after an "alongside" installation
using `bootc install to-existing-root --cleanup`. Its purpose is to clean up
files from the previous operating system.

The service runs as a oneshot unit and executes a distribution-specific cleanup
script located at `/usr/lib/bootc/fedora-bootc-destructive-cleanup` (for Fedora
derivatives).

## How it works

1. During `bootc install to-existing-root --cleanup`, a stamp file is created
at `/sysroot/etc/bootc-destructive-cleanup`
2. A systemd generator (`bootc-systemd-generator`) detects this stamp file at
boot time and enables the `bootc-destructive-cleanup.service` unit
3. The service runs the cleanup script on first boot

## What the cleanup script does

On Fedora derivatives, the cleanup script performs the following actions:

- Remounts `/sysroot` as read-write
- Removes all RPM packages installed in the physical root (the previous OS)
- Removes all container images from `/sysroot/var/lib/containers` using
`podman system prune --all -f`

**Note:** The cleanup script does not remove stopped containers, so some storage
may remain. This behavior may change in the future.

# CUSTOMIZING THE CLEANUP SCRIPT

The current implementation ships a Fedora-specific cleanup script. Other
distributions can provide their own cleanup script by creating an executable
at `/usr/lib/bootc/fedora-bootc-destructive-cleanup` or by modifying the
systemd unit file to reference a different path.
Comment on lines +37 to +40
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Jan 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The explanation on how to customize the cleanup script could be clearer for non-Fedora distributions, given the hardcoded Fedora-specific script path. Consider restructuring this section for better clarity. For example:

The service executes a script at the hardcoded path `/usr/lib/bootc/fedora-bootc-destructive-cleanup`.
Distributions can customize the cleanup behavior in two ways:

- Create an executable file at `/usr/lib/bootc/fedora-bootc-destructive-cleanup` to override the default script. Note that the filename is currently not generic.
- Modify the systemd unit file to execute a script at a different path.


For an example implementation, see the
[Fedora cleanup script](https://github.com/bootc-dev/bootc/blob/main/contrib/scripts/fedora-bootc-destructive-cleanup).

# PREVIOUS FILESYSTEM DATA

After an alongside installation, the previous root filesystem data is accessible
at `/sysroot` (the "physical root"). Previous mount points or subvolumes will
not be automatically mounted in the new system; for example, a btrfs subvolume
for /home will not be automatically mounted to /sysroot/home. These filesystems
persist and can be handled manually or defined as mount points in the bootc image.

# SEE ALSO

**bootc**(8), **bootc-install-to-existing-root**(8), **system-reinstall-bootc**(8)
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Jan 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The SEE ALSO section could be improved by including more relevant bootc commands and systemd man pages. bootc-install(8) is a relevant parent command, and systemd.generator(7) is relevant since the service is enabled by a generator, as mentioned in the description. The reference to system-reinstall-bootc(8) could be removed as it doesn't appear to be part of bootc.

Suggested change
**bootc**(8), **bootc-install-to-existing-root**(8), **system-reinstall-bootc**(8)
**bootc**(8), **bootc-install**(8), **bootc-install-to-existing-root**(8), **systemd.generator**(7)


# VERSION

<!-- VERSION PLACEHOLDER -->
Loading