systemctl-mount-image

Mount an image at a specific path inside the unit's mount namespace

$ systemctl mount-image [unit] /[path/to/image] /[path/to/directory_inside_unit]

$ systemctl mount-image [unit] /[path/to/image] /[path/to/directory_inside_unit] root:ro,nosuid

$ systemctl mount-image --mkdir [unit] /[path/to/image] /[path/to/directory_inside_unit]

$ systemctl mount-image --read-only [unit] /[path/to/image] /[path/to/directory_inside_unit]

systemctl mount-image [OPTIONS] UNIT IMAGE [PATH [PARTITION_NAME:MOUNT_OPTIONS]]

UNIT
    Name of the systemd unit whose mount namespace will receive the image

IMAGE
    Path to the source image file on the host (e.g., .raw, .qcow2, or block device)

PATH
    Destination directory inside the unit’s mount namespace (default: root of the namespace)

PARTITION_NAME:MOUNT_OPTIONS
    Optional colon‑separated tuple: the partition name inside the image and a comma‑separated list of mount options (e.g., root:ro,nosuid)

--read-only
    Mount the image read‑only, regardless of options supplied in the tuple

--mkdir
    Create the target PATH inside the namespace before performing the mount

systemctl mount-image mounts a disk image or filesystem image from the host into the mount namespace of a specific systemd unit. It is primarily used with services that run in a private mount namespace (e.g., those configured with RootImage=, RootDirectory=, or PrivateMounts=). The command takes the unit name, the path to the image file, an optional target directory inside the unit’s namespace, and an optional partition_name:mount_options tuple that mirrors the MountImages= unit setting. Options such as --read-only and --mkdir can be supplied to control the mount’s read‑only status and to create the target directory if it does not exist. If the kernel supports it, the new mount replaces any existing mount on the target; otherwise the previous mount remains over‑mounted and inaccessible. This feature was introduced in systemd 248 and is useful for container‑like workloads that need to expose immutable or pre‑populated filesystems without altering the host’s mount table.

Only works for units that run inside a mount namespace (RootImage=, PrivateMounts=, etc.). The kernel must support over‑mounting; otherwise previous mounts become hidden but remain pinned. The command cannot be used on units that share the host’s global mount namespace.

systemctl mount-image foo.service /tmp/img.raw /var/lib/image root:ro,nosuid
systemctl mount-image --mkdir bar.service /tmp/img.raw /var/lib/baz/img

The mount-image verb was added to systemctl in systemd version 248 (released early 2021) to complement the MountImages= unit setting, enabling on‑demand image mounting from the command line.

systemctl(1), mount(2), systemd.exec(5), systemd.unit(5)