Bazzite is an Atomic operating system designed for stability, security, and reliability. Bazzite utilizes bootc to manage the base image for your system, pin specific versions, and perform rollbacks when needed. For systems with customized software via layered packages, rpm-ostree becomes essential for installing, upgrading, and managing those additions. 

Why do this? Each tool is chosen for its strengths: bootc offers robust control over base images, ensuring that your core system remains unchanged unless you explicitly update it, while rpm-ostree provides flexibility for managing additional software without compromising the integrity of the atomic base. This separation helps maintain stability and security.

Bazzite uses bootc for managing system images and rpm-ostree for adding layered packages. This guide covers:

• Checking your system image status
• Pinning a specific image for stability
• Rolling back to a previous image
• Removing a pinned image
• Managing layered packages with rpm-ostree
• Modifying kernel arguments with rpm-ostree

1. Checking Your System Image Status

To see the current state of your system's image, run:

sudo bootc status

Key Details:

• Staged Image = Will be applied after reboot
• Booted Image = Currently active image
• Rollback Image = Previous image for recovery

Why check the status? Checking your system image status lets you verify which image is active, which one is pending, and what you can fall back to in case of an error. This is crucial for troubleshooting and ensuring that the system is running the desired version.

2. Pinning a Specific Image for Stability

Pinning an image is useful to prevent automatic updates and ensure stability. If you experience issues with newer updates, pinning a known good image can prevent unexpected changes.

Why pin an image? Pinning helps lock your system to a tested, stable version. This is especially important in environments where stability is critical, as it prevents unintentional changes from automatic updates that might introduce bugs or incompatibilities.

If NO Layered Packages Are Present:
When no layered packages are installed, pinning is straightforward using bootc. The <digest> refers to the unique identifier of the image version you want to pin (you can get this from the bootc status output). Run the following command to pin your current system state:

sudo bootc switch ghcr.io/ublue-os/bazzite:stable@sha256:<digest> --enforce-container-sigpolicy

The --enforce-container-sigpolicy flag ensures that the system validates the container signature according to the configured security policy, maintaining the integrity and authenticity of the image before switching to it.

Why use the signature policy flag? This flag is essential for security. It verifies that the image you are pinning is legitimate and hasn’t been tampered with, protecting your system from potentially malicious modifications.

If Layered Packages Are Present:
If you have layered packages installed, bootc cannot directly manage your image state. Instead, you must clean up old deployments to ensure the system correctly aligns with the pinned state:

sudo rpm-ostree cleanup -m

Why clean up with rpm-ostree? When layered packages are in use, they create additional deployments that can conflict with pinning. Cleaning up ensures that the system's state is streamlined, preventing conflicts and ensuring that only the desired image is active.

3. Rolling Back to a Previous Image

Rolling back reverts your system to the last known working image. If you've pinned a digest or modified the system image, a rollback may be necessary if things go wrong.

Why perform a rollback? Rollbacks provide a safety net. If an update introduces instability or breaks functionality, reverting to a previous, stable image can quickly restore system reliability and minimize downtime.

If NO Layered Packages Are Present:

sudo bootc rollback sudo systemctl reboot

Why use bootc for rollback without layered packages? In systems without layered packages, bootc handles all image management tasks effectively. Using bootc ensures that the rollback process is straightforward and consistent with the way the system was updated.

If Layered Packages Are Present:

sudo rpm-ostree rollback sudo systemctl reboot

Why use rpm-ostree for rollback with layered packages? When layered packages are present, rpm-ostree is responsible for managing the entire deployment, including any additional packages. This command ensures that the rollback incorporates both the base image and the layered packages, maintaining system consistency.

4. Removing a Pinned Image

If NO Layered Packages Are Present:

sudo bootc switch ghcr.io/ublue-os/bazzite:stable --enforce-container-sigpolicy

Why remove a pin? Removing a pinned image allows your system to resume normal update operations. This is useful if you’ve resolved the issues that led you to pin the image or if you want to take advantage of new features and improvements in updated versions.

If Layered Packages Are Present:

sudo rpm-ostree cleanup -m

Why perform cleanup with layered packages? With layered packages, cleaning up old deployments effectively removes the pinning effect, enabling the system to align with the latest updates while still preserving the custom software layers.

5. Managing Layered Packages with rpm-ostree

Layered packages are additional software installed on top of the base image. Unlike the core system image (which is Atomic), layered packages allow you to customize your system by adding software that persists across image updates. Use rpm-ostree to add, remove, or update these packages independently from the main image updates.

Why manage layered packages separately? Managing layered packages separately provides flexibility. It allows you to tailor your system with additional tools and applications without impacting the stability of the core image. This separation is crucial for maintaining system reliability while allowing customization.

What Are Layered Packages?
When you "layer" a package in Bazzite, you're installing it on top of your Atomic base image. These packages remain installed even when the underlying system image is updated. This is in contrast to the base image, which gets replaced entirely during updates.

Why is this distinction important? Understanding the difference between base and layered packages is key to managing updates correctly. Since bootc only controls the base image, any modifications made via layered packages must be managed by rpm-ostree to ensure that your customizations persist properly during updates.

How to Check If You Have Layered Packages:
Run the following command to see if you have any layered packages:

rpm-ostree status

Look for the section that says "Layered packages" in the output.

Why check for layered packages? Knowing whether layered packages are installed helps determine which management commands to use. It clarifies whether to rely on bootc or rpm-ostree for further operations, ensuring that you apply the correct update or rollback process.

Add a Package from Repository:

sudo rpm-ostree install <package-name>

Examples:

sudo rpm-ostree install htopsudo rpm-ostree install neofetch vim

Why add packages via rpm-ostree? This approach integrates additional software into your system in a controlled manner. It ensures that these packages are properly layered over the atomic base image, allowing for easy updates and rollbacks without disrupting system stability.

Add a Local RPM Package:
You can also install RPM packages that you've downloaded:

sudo rpm-ostree install /path/to/package.rpm

Example:

sudo rpm-ostree install ~/Downloads/custom-app-1.0.rpm

Why install a local RPM? Installing a local RPM allows you to add custom or third-party software that might not be available in the standard repositories, giving you the freedom to use specialized tools while still benefiting from the atomic update model.

Install from a URL:
You can install directly from a URL:

sudo rpm-ostree install https://example.com/path/to/package.rpm

Why install from a URL? This method streamlines the process of deploying packages directly from remote sources, reducing the steps required to download and install software and ensuring that you can quickly integrate important updates or tools.

Remove a Package:

sudo rpm-ostree uninstall <package-name>

Example:

sudo rpm-ostree uninstall htop

Why remove a package? Removing unnecessary or problematic packages keeps your system lean and can resolve conflicts or resource issues. It also helps maintain a secure environment by eliminating software that is no longer needed.

Remove Multiple Packages:

sudo rpm-ostree uninstall package1 package2 package3

Why is a reboot necessary? A reboot ensures that all changes are fully applied and that the new deployment, with the updated set of layered packages, is properly activated. This step is critical for system stability and consistency.

List Layered Packages:

rpm-ostree status

Why list layered packages? Listing the layered packages provides a clear overview of all custom additions to your system. This helps in troubleshooting, managing updates, and ensuring that all desired software remains installed after system updates.

Update System with Layered Packages:

sudo rpm-ostree upgrade

This will update both your base system image and any layered packages you've installed.

Why upgrade with rpm-ostree? Upgrading via rpm-ostree ensures that both the atomic base image and the additional packages are updated in a coordinated manner. This maintains compatibility between system components and reduces the risk of conflicts during updates.

How Layered Packages Affect Your System:

When you install layered packages:

• A new deployment is created with your packages added
• You must reboot to activate the new deployment
• System updates require using rpm-ostree instead of bootc
• Each set of layered packages creates a new "deployment" that you can roll back to

Why understand these effects? Recognizing the impact of layered packages on your system helps you plan for updates and rollbacks. It ensures that you know when a reboot is required and that you use the correct tools for managing your system’s state, preserving both functionality and stability.

Display Detailed Package Information:

rpm-ostree db list <package-name>

Why display detailed info? Viewing detailed information about a package allows you to verify its version, dependencies, and other critical metadata, which is essential for troubleshooting and ensuring compatibility within your system.

Rollback to Previous Layered Setup:

sudo rpm-ostree rollback sudo systemctl reboot

Why rollback a layered setup? Just like with base images, rolling back a layered setup allows you to revert to a previously stable configuration if a recent change causes issues. This helps maintain system reliability even after customizations have been applied.

6. Modifying Kernel Arguments with rpm-ostree

Since bootc cannot modify kernel arguments, you must use rpm-ostree to manage them:

Why modify kernel arguments? Kernel arguments allow you to fine-tune the system’s behavior at boot time. This might be necessary to optimize performance, enable specific hardware support, or adjust security settings. rpm-ostree is the tool that bridges this gap, ensuring these changes are applied consistently.

View Current Kernel Arguments:

rpm-ostree kargs

Add a New Kernel Argument:

sudo rpm-ostree kargs --append=<your-argument>

Why add a kernel argument? Adding kernel arguments can enable new features or tweak system performance. This command allows you to introduce changes without needing to rebuild the entire system image.

Remove a Kernel Argument:

sudo rpm-ostree kargs --delete=<your-argument>

Why remove a kernel argument? Removing an argument is just as important as adding one. It lets you revert previous changes that may no longer be beneficial or that are causing conflicts, ensuring that your system continues to operate optimally.

Summary

• Use bootc for managing system images, pinning, and rollbacks if no layered packages are present.
• Use rpm-ostree for managing layered packages, kernel arguments, and handling rollbacks or pinning if layered packages are present.

Overall Why Combine Both Tools? By combining bootc and rpm-ostree, you can take full advantage of the strengths of an atomic operating system: secure, immutable base images managed by bootc, and flexible customization provided by rpm-ostree. This approach ensures maximum stability, security, and adaptability for your Bazzite system.

By combining both tools effectively, you can keep your Bazzite system stable and customized for your needs.