How to Manage Versioned OS Images and Extension Directories in Ubuntu Using systemd-vpick

Modern Linux server administration increasingly relies on immutable infrastructure, discoverable disk images (DDIs), and modular system extensions (systemd-sysext and systemd-confext). In large-scale deployment pipelines and staging environments, managing multiple versions of operating system images, container root filesystems, and software overlays often leads to fragile symlink trees or brittle bash wrapper scripts that parse filenames with regular expressions. Beginning with systemd version 256 and continuing across modern Ubuntu releases, systemd-vpick standardises the discovery, sorting, and selection of versioned resources across the filesystem.

The systemd-vpick utility implements the Versioned Directory Pattern (the .v/ directory specification). By encapsulating versioned files within dedicated directories, systemd-vpick evaluates semantic versioning rules, hardware architecture tags, and cryptographic signatures dynamically, allowing system daemons and administrators to reference the latest stable image automatically without rewriting configuration files.

Understanding the Versioned Directory Pattern (.v/) Specification

A versioned resource is structured as a directory with the .v/ suffix containing multiple iterations of a file sharing the same base name. The directory name matches the target file name with .v appended:

/var/lib/machines/ubuntu-server.raw.v/
├── ubuntu-server_24.04.0_x86-64.raw
├── ubuntu-server_24.04.1_x86-64.raw
└── ubuntu-server_24.04.2_x86-64.raw

When a tool (or an administrator invoking systemd-vpick) requests /var/lib/machines/ubuntu-server.raw.v/, the vpick engine parses embedded version numbers, filters by CPU architecture, verifies signatures, and resolves to the highest valid version (e.g. ubuntu-server_24.04.2_x86-64.raw).

Key architectural components of the vpick specification include:

• Semantic Version Sorting: Versions are sorted according to standard distribution version comparison algorithms (similar to strverscmp), correctly sorting 1.10 above 1.2.
• Architecture Matching: Filenames can include architecture tags (such as _x86-64 or _arm64). The engine prioritizes the native host architecture while rejecting incompatible binaries.
• Cryptographic Verification: Companion signature files (such as .raw.sha256 or detached Verity signatures) residing within the .v/ directory are validated before the file is exposed to the runtime.

Prerequisites and Verifying systemd-vpick on Ubuntu

The systemd-vpick utility is available on systems running systemd version 256 and newer on Ubuntu.

Verify your systemd release and binary availability:

# Check systemd version
systemctl --version | head -n 1

# Confirm systemd-vpick binary location
which systemd-vpick

If operating on a supported release, systemd-vpick is ready for immediate execution without auxiliary daemon configuration.

Creating a Versioned Resource Directory Structure

To demonstrate versioned image management, create a versioned container directory for staging server disk images:

# Create directory following the .v specification
sudo mkdir -p /var/lib/machines/web-app.raw.v

# Create simulated versioned disk images
sudo touch /var/lib/machines/web-app.raw.v/web-app_1.0.0_x86-64.raw
sudo touch /var/lib/machines/web-app.raw.v/web-app_1.2.0_x86-64.raw
sudo touch /var/lib/machines/web-app.raw.v/web-app_1.10.0_x86-64.raw

Notice how a standard alphabetical sort would incorrectly rank 1.2.0 above 1.10.0. systemd-vpick handles numeric version segments natively.

Querying and Resolving Resources with systemd-vpick

To resolve the highest version matching host criteria, query the versioned directory:

# Resolve the latest version of the target image
systemd-vpick /var/lib/machines/web-app.raw.v/

The command resolves and outputs the absolute path to the latest candidate:

/var/lib/machines/web-app.raw.v/web-app_1.10.0_x86-64.raw

To inspect all recognized versions, candidate rankings, and metadata in a structured format, request JSON output:

# Output full version discovery table in JSON format
systemd-vpick --json=pretty /var/lib/machines/web-app.raw.v/

The JSON response details the version string, detected architecture, modification timestamp, and file size for every entry.

Filtering by Architecture and Version Constraints

When operating in heterogeneous build farms with multi-architecture image repositories (combining x86_64 and aarch64 images), enforce explicit architecture constraints:

# Query images matching a specific CPU architecture
systemd-vpick --architecture=arm64 /var/lib/machines/web-app.raw.v/

You can also constrain queries to specific version baselines or major branches, allowing staging systems to track version 1.x releases while canary environments test 2.x releases.

Integrating systemd-vpick into Systemd Services and UKI Bootloads

The primary power of the .v/ pattern lies in direct systemd unit integration. Systemd daemons natively recognize .v/ paths in unit configuration files without requiring external wrapper scripts.

For example, when running lightweight system containers with systemd-nspawn or virtual machines with systemd-vmspawn, point directly to the versioned directory:

[Unit]
Description=Production Web Application Container
After=network.target

[Service]
ExecStart=/usr/bin/systemd-nspawn --image=/var/lib/machines/web-app.raw.v/ --boot
Restart=always

[Install]
WantedBy=multi-user.target

When a newer disk image (e.g. web-app_1.11.0_x86-64.raw) is copied into the .v/ directory, simply restarting the systemd service (sudo systemctl restart web-app.service) causes the daemon to automatically boot the new version.

Rollback and Version Retirement Workflows

If an updated disk image encounters unexpected production faults, rolling back requires zero configuration edits. Simply move or rename the offending image file out of the .v/ folder:

# Quarantine the faulty release
sudo mv /var/lib/machines/web-app.raw.v/web-app_1.10.0_x86-64.raw /var/lib/machines/quarantine/

# Verify that systemd-vpick automatically falls back to the previous stable release
systemd-vpick /var/lib/machines/web-app.raw.v/

The utility instantly falls back to web-app_1.2.0_x86-64.raw.

By adopting systemd-vpick and the .v/ pattern on Ubuntu, system engineers eliminate complex symlink maintenance, streamline immutable OS rollouts, and ensure deterministic software versioning across data centre deployments.