importctl

Download image in tarball format from a url via pull

$ sudo importctl pull-tar [URL] [path/to/directory]

$ sudo importctl pull-raw [https://example.com/source.ext] [name] --class=[machine|portable|sysext|confext]

$ importctl import-raw [path/to/file.ext] [name] --class=[machine|portable|sysext|confext]

$ importctl export-tar --class=[machine|portable|sysext|confext] [name] [path/to/file.ext]

importctl [OPTIONS...] {COMMAND}

import-raw FILE [NAME]
    Import raw disk image from FILE, optionally naming it NAME

import-iso FILE [NAME]
    Import ISO image from FILE, extracting partition contents

import-tar FILE [NAME]
    Import tar archive as disk image

import-oci-bundle DIR [NAME]
    Import OCI container bundle directory

import-directory DIR [NAME]
    Import directory as disk image

import-verityfeed FILE [NAME]
    Import verityfeed signature file for image verification

list
    List all imported images with details

remove IMAGE
    Remove specified image

export IMAGE FILE [--format=raw|tar]
    Export image to FILE in specified format

--help, -h
    Print help and exit

--version
    Print version information

--json=short|pretty|verbose
    Output in JSON format

--image-path=PATH
    Path to image store (default /var/lib/systemd/import)

--system
    Operate on system-wide images

--user
    Operate on user-specific images

The importctl command is a systemd utility for importing, exporting, listing, and removing disk images stored in /var/lib/systemd/import or user-specific directories.

It supports various formats including raw images, ISO files, tar archives, OCI bundles, directories, and verityfeed signatures. Imported images can be used by systemd-sysext to extend the host root filesystem with additional packages and configurations, or by portablectl for running portable services in isolated environments.

Key workflows include downloading extension images (e.g., from OSTree repositories), importing them with integrity verification via dm-verity where supported, and activating them. Images are named uniquely and can include OS release metadata for matching host architectures and versions.

This tool enhances systemd's modularity, enabling transactional updates to system extensions without full OS rebuilds. It integrates with systemd's image policy and verification mechanisms for security.

Requires systemd v253+. Images must match host architecture/version for sysext use. Verification (dm-verity) recommended for security; unverified imports may fail policy checks.
Root privileges often needed for system-wide operations.

Images stored as .raw files with optional .verity and .os-release metadata in /var/lib/systemd/import (system) or ~/.local/share/systemd/import (user).

Supports dm-verity for tamper-proof imports; use import-verityfeed for signed feeds from trusted sources.

Introduced in systemd v253 (March 2023) to consolidate image import logic previously scattered across sysext and portable tools. Enhanced in v254+ with OCI and verityfeed support for better container/OSTree integration.

systemd-sysext(8), portablectl(1), systemd-importd(8), machinectl(1)