Inspect and control systemd image transfers over D-Bus

This guide shows how to use the org.freedesktop.import1 D-Bus interface to inspect systemd-importd, list active image transfers, start a verified download and cancel it when necessary. The interface is the backend used by commands such as machinectl pull-tar and machinectl pull-raw, but calling it directly is useful when you need to see the exact method arguments and returned transfer object.

Allow about 15 minutes. You need a Linux host running systemd, the gdbus command from GLib, access to the system D-Bus, and enough space under /var/lib/machines/ for the image. This guide was checked against Ubuntu's systemd package version 255.4-1ubuntu8.17. The installed interface is a D-Bus API, not a configuration file to edit.

1. Check the service and prerequisites

Run these read-only checks as your normal user:

command -v gdbus
systemctl status systemd-importd.service --no-pager

The service is socket or bus activated and may show inactive (dead) before its first request. That is not, by itself, a failure. The unit should still be loaded, and the D-Bus service should start when a request reaches the system bus.

2. Inspect the Manager object

Ask the system bus for the live interface definition:

gdbus introspect --system \
  --dest org.freedesktop.import1 \
  --object-path /org/freedesktop/import1

Among the returned methods you should see ImportTar, ImportRaw, ImportFileSystem, ExportTar, ExportRaw, PullTar, PullRaw, ListTransfers and CancelTransfer. The object also emits TransferNew and TransferRemoved signals.

If the command reports that it cannot connect to the system bus, stop here. A shell running outside the host's normal system environment, a container without a system bus, or a broken system manager can all cause that error. Retrying the same command will not repair a missing bus.

3. List work already in progress

Listing transfers does not change any image:

gdbus call --system \
  --dest org.freedesktop.import1 \
  --object-path /org/freedesktop/import1 \
  --method org.freedesktop.import1.Manager.ListTransfers

An empty result means there are no active imports, exports or downloads. Otherwise, each entry contains a numeric transfer ID, an operation such as pull-tar, a remote or file-descriptor description, the local image name, a progress value from 0.0 to 1.0, and an object path. Save the numeric ID before starting any cancellation command. Do not assume that the ID names the same transfer after a later restart.

4. Start a verified tar-image pull

A pull method takes a URL, a local image name, a verification mode and a force flag. Use signature when the publisher provides a signed SHA256SUM file and the host has the required GnuPG setup. This makes systemd-importd verify the checksum file's signature before checking the image hash.

The following is a template. Replace both placeholders with a real HTTPS URL and a hostname-shaped local name. It starts a download and writes the resulting image below /var/lib/machines/:

gdbus call --system \
  --dest org.freedesktop.import1 \
  --object-path /org/freedesktop/import1 \
  --method org.freedesktop.import1.Manager.PullTar \
  "https://IMAGE-HOST.example/images/IMAGE.tar.xz" \
  "IMAGE-NAME" \
  "signature" \
  false

The returned pair contains a transfer ID and an object path. The call returns as soon as the transfer starts; it does not mean the image is ready. With false, an existing image with the same name causes the operation to fail. That is the safer default for a first run.

For an uncompressed or differently compressed tar file, keep the method the same. The service detects gzip, bzip2 and xz compression. For a raw or qcow2 disk image, use PullRaw instead; the method name is the meaningful change.

5. Follow or cancel the transfer

Poll the manager while the transfer runs:

gdbus call --system \
  --dest org.freedesktop.import1 \
  --object-path /org/freedesktop/import1 \
  --method org.freedesktop.import1.Manager.ListTransfers

For more detail, introspect the returned transfer path. Substitute the path printed by the pull call, including its numeric suffix:

gdbus introspect --system \
  --dest org.freedesktop.import1 \
  --object-path /org/freedesktop/import1/transfer/_TRANSFER_PATH

The transfer object exposes Id, Local, Remote, Type, Verify and Progress. Its Cancel method is equivalent to cancelling by ID on the manager object.

Cancel a transfer only after checking its ID:

gdbus call --system \
  --dest org.freedesktop.import1 \
  --object-path /org/freedesktop/import1 \
  --method org.freedesktop.import1.Manager.CancelTransfer \
  123

Replace 123 with the actual unsigned transfer ID. Cancellation is the recovery action for a mistaken URL, an unexpected destination or a transfer consuming unacceptable resources. It does not undo an image that has already completed. After cancelling, list transfers again and inspect /var/lib/machines/ before deciding whether any incomplete artefact needs separate cleanup.

6. Confirm completion

A transfer ends with a TransferRemoved signal whose result is one of the API values shown here:

done
canceled
failed

If you are polling rather than subscribing to signals, a transfer disappearing from ListTransfers means only that it has ended, so check the service log and the destination image as well:

journalctl -u systemd-importd.service --since "10 minutes ago" --no-pager
ls -ld /var/lib/machines/IMAGE-NAME

For a tar import, the destination is a directory or a Btrfs subvolume named exactly as requested. For a raw import, the destination has a .raw suffix. A failed transfer should not be treated as a usable image merely because a path exists.

Export methods work in the opposite direction, but they require a writable file descriptor and a format of uncompressed, xz, bzip2 or gzip. The interface does not currently convert tar images to raw images or raw images to tar files.