How to Inspect and Mount Discoverable Disk Images in Ubuntu Using systemd-dissect

Modern Linux container architectures, system extensions, and portable root filesystems frequently package operating system images as raw Discoverable Disk Images (DDIs) conforming to the UAPI Discoverable Partitions Specification (DPS). Unlike traditional disk images that require manual loopback device binding, partition scanning via kpartx, and explicit mount parameters, systemd provides systemd-dissect. This tool inspects partition tables, validates dm-verity cryptographic signatures, mounts root filesystems automatically, and copies files directly into or out of raw disk images.

In this guide, you will learn how to dissect raw OS disk images, mount and unmount partitions, copy files without mounting, and verify image integrity in Ubuntu using systemd-dissect.

Understanding Discoverable Disk Images (DDIs)

A Discoverable Disk Image is a GPT (GUID Partition Table) disk image where partition types and mount locations are defined strictly by standardized partition GUIDs rather than configuration files like /etc/fstab. For example:

  • Root Partition: Identified by architecture-specific GUIDs (such as 4f68bce3-e8cd-4db1-96e7-fbcaf984b709 for x86-64 root).
  • Verity Partition: Contains dm-verity hash trees to guarantee tamper-proof root validation.
  • System Extensions (sysext) & Config Extensions (confext): Lightweight overlay images designed to extend system capabilities at runtime.

The systemd-dissect command operates on both raw .raw images and block devices, abstracting away complex loop device management.

Inspecting Disk Image Partitions and Metadata

To inspect the partition structure and operating system identification of a raw disk image without mounting it to your filesystem, run systemd-dissect directly against the image path:

systemd-dissect ubuntu-cloud-image.raw

The utility prints an exhaustive overview detailing:

  • Operating System & Architecture: OS release name, version ID, machine architecture, and build ID.
  • Partition Table: Partition indices, assigned UUIDs, filesystem types (e.g., ext4, btrfs, vfat), and designator labels.
  • Cryptographic Status: Whether dm-verity or LUKS encryption is active across root or usr partitions.

To view the output formatted as machine-readable JSON for automated deployment scripts, pass the --json=pretty flag:

systemd-dissect --json=pretty ubuntu-cloud-image.raw

Mounting and Unmounting Disk Images Interactively

Traditionally, mounting an OS image required identifying the byte offset of each partition using fdisk -l, calculating offsets, and creating loop devices. With systemd-dissect, you can mount the entire discoverable partition hierarchy to a directory in a single step:

# Create an empty mount point
sudo mkdir -p /mnt/cloud-image

# Mount the discoverable image
sudo systemd-dissect --mount ubuntu-cloud-image.raw /mnt/cloud-image

When executed, systemd-dissect automatically maps root, usr, boot, and EFI partitions into their corresponding directory locations within /mnt/cloud-image.

Verify the mounted filesystem hierarchy using findmnt:

findmnt /mnt/cloud-image

To unmount the disk image safely and release all underlying kernel loop devices:

sudo systemd-dissect --umount /mnt/cloud-image

Spawning a Shell Inside an Image without Manual Chroot

If you need to investigate configuration files, check installed packages, or debug library dependencies inside an OS disk image, you can spawn an interactive shell directly inside the image environment:

sudo systemd-dissect --shell ubuntu-cloud-image.raw

This command mounts the image to a temporary private namespace and invokes systemd-nspawn or standard chroot facilities, launching an interactive root bash prompt inside the image. Type exit to terminate the session, and the image is instantly unmounted cleanly.

Copying Files Into and Out of Disk Images

One of the most practical administrative features of systemd-dissect is the ability to extract or inject individual configuration files, SSH keys, or scripts without mounting the image to a directory.

Extracting Files from an Image

To copy a file out of the disk image to your local host filesystem, use --copy-from:

sudo systemd-dissect --copy-from ubuntu-cloud-image.raw /etc/os-release ./extracted-os-release

Inspect the copied file:

cat ./extracted-os-release

Injecting Files into an Image

To provision cloud-init scripts, custom network configurations, or SSH authorized keys into a raw image before booting it on a hypervisor, use --copy-to:

sudo systemd-dissect --copy-to ubuntu-cloud-image.raw ./id_ed25519.pub /root/.ssh/authorized_keys

The file is safely written to the specified path inside the image’s root partition without altering other partition structures.

Validating Cryptographic dm-verity Signatures

Immutable container base images and signed OS images rely on dm-verity root hashes to guarantee that the operating system has not been modified or tampered with.

To validate the integrity of a signed disk image using its known root hash:

sudo systemd-dissect --root-hash=4f68bce3e8cd4db196e7fbcaf984b709... ubuntu-cloud-image.raw --validate

If any block within the filesystem has been altered, systemd-dissect rejects the image and aborts with a verification failure, protecting deployment pipelines against tampered disk payloads.

Get the best tech tips delivered straight to your inbox.

Join thousands of readers mastering Apple, Google, Microsoft, and Linux.