How to Download and Manage OS Disk Images in Ubuntu Using importctl

Image Management Architecture with systemd-importd and importctl

Modern Linux virtualization and containerization workflows rely heavily on prefabricated operating system disk images (such as qcow2, raw GPT disk images, and tarball filesystem trees). Historically, downloading and provisioning these images required administrators to assemble fragile shell scripts combining curl, sha256sum, GPG signature verification, xz decompression, and manual placement into /var/lib/machines/. If a network interruption occurred midway through downloading or if hash validation failed, corrupted images could linger undetected in storage.

Introduced in systemd 256 and integrated into Ubuntu 24.04 LTS and modern cloud platforms, importctl provides a dedicated, unified command-line interface to the system background service systemd-importd. It formalises the entire lifecycle of pulling, downloading, cryptographically verifying, converting, unpacking, and exporting VM and container images. Rather than treating images as loose arbitrary files, importctl interacts with btrfs subvolumes, raw sparse disk files, and systemd machine storage pools to provide atomic, verified image deployments.

By delegating downloads and image conversion to systemd-importd via D-Bus IPC, importctl executes transfers asynchronously in the background. It automatically retrieves companion SHA256SUMS and signature files over HTTPS, verifies authenticity before writing bits to disk, and integrates directly with systemd-nspawn and systemd-vmspawn.

Verifying System Requirements and Service Readiness in Ubuntu

To use importctl, ensure your Ubuntu system runs systemd version 256 or later and that the systemd-container package is installed:

# Check systemd version on Ubuntu
systemd --version

# Install systemd container and VM utilities if not present
sudo apt update
sudo apt install -y systemd-container

Verify that the underlying systemd-importd service is installed and operational:

# Check status of systemd-importd daemon
systemctl status systemd-importd

The daemon is socket-activated and will start on demand whenever importctl issues an IPC request. Verify command-line utility readiness:

# Verify importctl CLI tool
importctl --version

Listing Installed and Downloadable Machine Images

Before pulling new operating system images, audit the local machine image catalogue stored under /var/lib/machines/ using importctl list:

# List existing local machine images
importctl list

The output presents a structured overview of local images, detailing image formats (raw, subvolume, directory), read-only flags, and disk usage:

NAME             TYPE      RO  USAGE    CREATED
ubuntu-noble     raw       no  2.1G     Sun 2026-11-08 10:15:30 UTC
debian-bookworm  subvolume yes 850M     Fri 2026-11-06 14:22:10 UTC

To inspect detailed metadata for a specific machine image, execute importctl status:

# Inspect metadata and partition structure of target image
importctl status ubuntu-noble

Downloading and Verifying Remote Raw Disk Images with pull-raw

The pull-raw command downloads a remote raw disk image (or compressed archive such as .raw.xz or .raw.gz) over HTTPS, verifies cryptographic checksums, unpacks the stream on the fly, and registers the resulting sparse image in /var/lib/machines/.

To pull a cloud-init capable Ubuntu cloud image:

# Download, verify, and unpack a raw Ubuntu cloud image
sudo importctl pull-raw https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img ubuntu-cloud-noble

During execution, systemd-importd queries the remote web server for companion verification files:

• It attempts to download SHA256SUMS located in the same directory.
• If found, it computes the SHA-256 hash of the downloaded stream and rejects corrupted downloads automatically.
• It optionally checks for a detached GPG signature (SHA256SUMS.gpg) to validate origin authenticity.

To control verification strictness, pass the --verify= parameter:

# Enforce strict signature verification
sudo importctl pull-raw --verify=signature https://example.com/images/os.raw.xz my-secure-os

# Allow hash verification without GPG signature
sudo importctl pull-raw --verify=checksum https://example.com/images/os.raw.xz my-checksum-os

# Disable verification (recommended only for trusted internal networks)
sudo importctl pull-raw --verify=no http://192.168.1.50/dev-build.raw dev-image

Downloading and Unpacking Root Filesystem Tarballs with pull-tar

Container runtimes and systemd-nspawn often operate on directory trees rather than partitioned raw disk images. The pull-tar command downloads a tarball archive, verifies hashes, and unpacks the directory tree into a dedicated btrfs subvolume or standard directory:

# Pull and unpack a container root filesystem tarball
sudo importctl pull-tar https://images.linuxcontainers.org/images/alpine/edge/amd64/default/rootfs.tar.xz alpine-edge

If /var/lib/machines/ is mounted on a btrfs filesystem, importctl creates a native btrfs subvolume, enabling near-instantaneous copy-on-write snapshotting and cloning.

Importing Local Disk Images and Tar Archives

If you have already generated custom disk images using Packer, Mkosi, or debootstrap on local storage, use the import-raw or import-tar verbs to ingest them into the machine catalogue:

# Import an existing local raw disk image into /var/lib/machines/
sudo importctl import-raw /home/ubuntu/builds/custom-server.raw custom-server

# Import an existing local tarball
sudo importctl import-tar /tmp/staging/alpine-tree.tar.gz alpine-staging

importctl safely copies or hardlinks the image into the machine storage pool and sets appropriate permissions.

Exporting Images to External Storage

Conversely, when you need to distribute an updated machine template across secondary compute nodes or backup clusters, use export-raw or export-tar to serialize the machine image to stdout or an external file:

# Export local raw machine image to compressed archive
sudo importctl export-raw ubuntu-cloud-noble /mnt/backups/ubuntu-cloud-noble.raw.xz

# Pipe image stream directly over SSH to a remote server
sudo importctl export-raw ubuntu-cloud-noble - | ssh admin@backup-host "cat > /storage/images/noble.raw.xz"

Spawning and Running Imported Images

Once imported, the image is immediately accessible to systemd execution tools without requiring path resolution:

# Boot the imported image in a lightweight container using systemd-nspawn
sudo systemd-nspawn -b -M ubuntu-cloud-noble

# Or boot the raw image in a full QEMU virtual machine using systemd-vmspawn
sudo systemd-vmspawn -M ubuntu-cloud-noble

By leveraging importctl, Ubuntu engineers replace manual, error-prone download scripts with a standardized, cryptographically secure image pipeline integrated directly into the systemd architecture.