A Step-by-Step Guide to Testing Sealed Bootable Container Images for Fedora Atomic Desktops

Overview

Fedora Atomic Desktops now offer sealed bootable container images—a major step forward in secure system boot. These images combine a verified boot chain from firmware to the operating system, using Secure Boot on UEFI systems. In this guide, you'll learn what sealed images are, how to test them, and how to build your own. Whether you're a developer, system administrator, or advanced user, this tutorial will help you get started safely and avoid common pitfalls.

The sealed images integrate three core components: systemd-boot as the bootloader, a Unified Kernel Image (UKI) containing the kernel, initrd, and command line, and a composefs repository with fs-verity enabled. Both the bootloader and UKI are signed for Secure Boot, though these test images use non-official keys. The ultimate benefit is the ability to enable passwordless disk unlocking via TPM in a reasonably secure way.

Prerequisites

Before diving in, ensure you have the following:

• Hardware: A system with UEFI firmware (x86_64 or aarch64) and Secure Boot capable. Note: Legacy BIOS boot is not supported.
• Software:
  • A working installation of podman and buildah for container operations.
  • bootc installed (the bootable container tooling).
  • Basic familiarity with the command line.
• Download: Access to the test images from the fedora-atomic-desktops-sealed repository.
• Backup: These are testing images. Do not use on production systems. Always have a backup of any important data.

Make sure your system meets the UEFI Secure Boot requirement. You can check by running bootctl status (if using systemd-boot) or consulting your firmware settings.

Step-by-Step Instructions

Download the Pre-built Test Images

The simplest way to test sealed images is to use the pre-built disk images provided in the GitHub repository. Navigate to the Releases page and download the appropriate image for your architecture. For example, a .qcow2 image for x86_64 can be used with virtualization tools like qemu.

Alternatively, you can boot directly on bare metal using a USB disk. Follow the repository's instructions to write the image to a USB drive using dd or similar tool. Ensure Secure Boot is enabled in your firmware settings before booting.

Boot from the Sealed Image

1. Copy the downloaded image to your target machine or virtual machine.
2. If using a virtual machine, configure it to use UEFI firmware (e.g., OVMF for QEMU).
3. Boot from the image. The first boot may take a few moments as the images are not pre-built with a default password; the root account has no password set.
4. After boot, you can log in via the console or SSH (sshd is enabled by default for debugging).

Important: Because these are test images, the UKI and systemd-boot are signed with test keys, not the official Fedora keys. Your system may display a warning during Secure Boot verification; you may need to enroll the test key or disable Secure Boot temporarily. See the repository for details on key enrollment.

Verify the Boot Chain Integrity

Once booted, you can verify that the sealed boot chain is intact:

• Check that systemd-boot is the bootloader: run bootctl status.
• Verify the UKI is properly loaded: look for the kernel command line and ensure it matches the expected parameters.
• Confirm composefs is enabled: use composefs-info or check /sys/fs/composefs.

If you intend to test TPM-based disk unlocking, ensure your system has a TPM 2.0 module and that it is enabled in firmware. The sealed images are designed to work with TPM out of the box, but you may need to configure additional policies.

Build Your Own Sealed Image

For those who want to customize, the repository provides a script to generate sealed images. Follow these steps:

1. Clone the repository: git clone https://github.com/travier/fedora-atomic-desktops-sealed.git
2. Ensure you have all dependencies (podman, buildah, bootc, and optionally qemu for testing).
3. Use the provided build.sh script. For example: ./build.sh --arch x86_64. This will create a container image with the UKI and composefs.
4. Convert the container image into a disk image using bootc install to-disk or similar method. Refer to the bootc documentation for detailed options.

You can modify the base image or kernel parameters by editing the configuration files in the repository before building. The resulting image will be signed with test keys; for production, you would need to replace them with your own certificates.

Common Mistakes and Troubleshooting

Failing to Enable UEFI and Secure Boot

Sealed images only boot via UEFI with Secure Boot. If you try to boot on a legacy BIOS system, the boot process will fail immediately. Double-check your firmware settings.

Using Official Fedora Secure Boot Keys

These test images are signed with test keys, not official Fedora keys. Do not expect them to pass verification with the default Fedora Secure Boot CA. You must either disable Secure Boot or enroll the test key provided in the repository.

Ignoring the Root Password Warning

The root account has no password. This is intentional for debugging but poses a security risk. Never expose these test images to a network without first setting a password or disabling SSH. Also, do not use them in production environments.

Incorrect Architecture

Ensure you download or build the image for your system's architecture (x86_64 or aarch64). Booting an aarch64 image on x86_64 hardware will not work despite UEFI support.

Overlooking TPM Requirements

If you wish to test TPM-based unlocking, verify that your TPM is firmware-managed and supported by Linux. Some older TPM modules may not work. Check dmesg for TPM-related messages.

Summary

Sealed bootable container images for Fedora Atomic Desktops provide a complete verified boot chain using Secure Boot, UKI, and composefs. Testing these images is straightforward: download pre-built images, boot them on UEFI-capable hardware, and verify the chain. For customization, build your own images using the provided repository scripts. Remember these are test images with no root password and non-official signatures—use them only in controlled environments. By following this guide, you'll be well-prepared to explore the future of secure, containerized operating systems.

For deeper understanding, refer to presentations at FOSDEM 2025, Devconf.cz 2025, and ASG 2025, as well as the composefs backend documentation in bootc. Provide feedback and report issues to the GitHub repository to help improve the project.