ORG.FREEDESKTOP.IMPORT1(5)
💖 NAME 💖
org.freedesktop.import1 — bestie, this is the D-Bus interface of systemd-importd, aka the page where the image-importing service shows off its method signatures 💅✨
🌸 INTRODUCTION 🌸
Okay so systemd-importd.service(8) is a system service that may be used to import, export and download disk images. These images can be used by tools such as systemd-nspawn(1) to run local containers. The service is used as the backend for importctl pull-raw, importctl pull-tar and related commands. This page describes the D-Bus interface. 🫶
Lowkey important note: systemd-importd.service(8) is mostly a small companion service for systemd-machined.service(8). Many operations to manipulate local container and VM images are hence available via the systemd-machined D-Bus API, c.f. org.freedesktop.machine1(5). So if you're looking for the whole image-manipulation vibe, don't forget that other page exists 💀✨
👑 THE MANAGER OBJECT 👑
The service exposes the following interfaces on the Manager object on the bus. Here's the whole node, exactly as it appears — no cap, this is the main-character block 🎀:
node /org/freedesktop/import1 {
interface org.freedesktop.import1.Manager {
methods:
ImportTar(in h fd,
in s local_name,
in b force,
in b read_only,
out u transfer_id,
out o transfer_path);
ImportTarEx(in h fd,
in s local_name,
in s class,
in t flags,
out u transfer_id,
out o transfer_path);
ImportRaw(in h fd,
in s local_name,
in b force,
in b read_only,
out u transfer_id,
out o transfer_path);
ImportRawEx(in h fd,
in s local_name,
in s class,
in t flags,
out u transfer_id,
out o transfer_path);
ImportFileSystem(in h fd,
in s local_name,
in b force,
in b read_only,
out u transfer_id,
out o transfer_path);
ImportFileSystemEx(in h fd,
in s local_name,
in s class,
in t flags,
out u transfer_id,
out o transfer_path);
ExportTar(in s local_name,
in h fd,
in s format,
out u transfer_id,
out o transfer_path);
ExportTarEx(in s local_name,
in s class,
in h fd,
in s format,
in t flags,
out u transfer_id,
out o transfer_path);
ExportRaw(in s local_name,
in h fd,
in s format,
out u transfer_id,
out o transfer_path);
ExportRawEx(in s local_name,
in s class,
in h fd,
in s format,
in t flags,
out u transfer_id,
out o transfer_path);
PullTar(in s url,
in s local_name,
in s verify_mode,
in b force,
out u transfer_id,
out o transfer_path);
PullTarEx(in s url,
in s local_name,
in s class,
in s verify_mode,
in t flags,
out u transfer_id,
out o transfer_path);
PullRaw(in s url,
in s local_name,
in s verify_mode,
in b force,
out u transfer_id,
out o transfer_path);
PullRawEx(in s url,
in s local_name,
in s class,
in s verify_mode,
in t flags,
out u transfer_id,
out o transfer_path);
PullOci(in s ref,
in s local_name,
in s class,
in t flags,
out u transfer_id,
out o transfer_path);
ListTransfers(out a(usssdo) transfers);
ListTransfersEx(in s class,
in t flags,
out a(ussssdo) transfers);
CancelTransfer(in u transfer_id);
ListImages(in s class,
in t flags,
out a(ssssbtttttt) images);
signals:
TransferNew(u transfer_id,
o transfer_path);
TransferRemoved(u transfer_id,
o transfer_path,
s result);
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};💅 Methods 💅
ImportTar()/ImportTarEx() and ImportRaw()/ImportRawEx() import a disk image and place it into the image directory. The first argument should be a file descriptor (opened for reading) referring to the tar or raw file to import. It should reference a file on disk, a pipe or a socket. 🌀
When ImportTar()/ImportTarEx() is used, the file descriptor should refer to a tar file, optionally compressed with gzip(1), zstd(1), bzip2(1), or xz(1). systemd-importd will detect the used compression scheme (if any) automatically. When ImportRaw()/ImportRawEx() is used, the file descriptor should refer to a raw or qcow2 disk image containing an MBR or GPT disk label, also optionally compressed with gzip, zstd, bzip2 or xz. In either case, if the file is specified as a file descriptor on disk, progress information is generated for the import operation (as in that case we know the total size on disk). If a socket or pipe is specified, progress information is not available. 😭
The file descriptor argument is followed by a local name for the image. This should be a name suitable as a hostname and will be used to name the imported image below /var/lib/machines/. A tar import is placed as a directory tree or a btrfs(8) subvolume below the image directory under the specified name with no suffix appended. A raw import is placed as a file in the image directory with the .raw suffix appended. 🎀
In case of ImportTar()/ImportRaw(), if the force argument is true, any pre-existing image with the same name is removed before starting the operation. Otherwise, the operation fails if an image with the same name already exists. The read_only argument controls whether to create a writable or read-only image. In case of ImportTarEx()/ImportRawEx() these boolean flags are provided via a 64bit flags parameter instead, with bit 0 mapping to the force parameter, and bit 1 mapping to read_only. The class parameter specifies the image class, and takes one of "machine", "portable", "sysext", "confext". ✨
All four methods return immediately after starting the import, with the import transfer ongoing. They return a pair of transfer identifier and object path, which may be used to retrieve progress information about the transfer or to cancel it. The transfer identifier is a simple numeric identifier, the object path references an org.freedesktop.import1.Transfer object, see below. Listen for a TransferRemoved() signal for the transfer ID in order to detect when a transfer is complete. The returned transfer object is useful to determine the current progress or log output of the ongoing import operation. 🫶
ExportTar()/ExportTarEx() and ExportRaw()/ExportRaw() implement the reverse operation, and may be used to export a system image in order to place it in a tar or raw image. They take the machine name to export as their first parameter, followed by a file descriptor (opened for writing) where the tar or raw file will be written. It may either reference a file on disk or a pipe/socket. The third argument specifies in which compression format to write the image. It takes one of "uncompressed", "xz", "bzip2", "gzip" or "zstd", depending on which compression scheme is required. The image written to the specified file descriptor will be a tar file in case of ExportTar()/ExportTarEx() or a raw disk image in case of ExportRaw()/ExportRawEx(). 🦋
Heads up, bestie: currently raw disk images may not be exported as tar files, and vice versa. This restriction might be lifted eventually. 👀
The method returns a transfer identifier and object path for cancelling or tracking the export operation, similarly to ImportTar()/ImportTarEx() or ImportRaw()/ImportRawEx() as described above. ExportTarEx()/ExportRawEx() expect the image class as additional parameter, as well as a 64bit flags parameter that currently must be specified as zero. Periodt 💅🔥
okay so PullTar()/PullTarEx() and PullRaw()/PullRawEx() are the download-girlie methods 💅 — they pull a whole system image down from a URL, verify it, and import it. Three cheers for not doing this by hand.
The URL argument should point to a tar or raw file on the "http://" or "https://" protocols, and it may or may not be compressed with xz, bzip2, gzip or zstd — she handles it either way, no cap.
The second argument is a local name for the image, and it needs to be suitable as a hostname — exactly like the matching argument of the ImportTar()/ImportTarEx() and ImportRaw()/ImportRawEx() methods we already talked about up above 👆.
The third argument picks the verification mode for the image. It's one of these three, and this is a vibe check you do not want to skip:
"no"— turns off any kind of verification of the image. zero thoughts, head empty, literally no checks 🫣"checksum"— looks for aSHA256SUMfile right next to the downloaded image, and verifies any SHA256 hash value in that file against the image ✨"signature"— does the exact same thing, but also tries to authenticate theSHA256SUMfile viagpg(8)first. the deluxe package, the main character option 👑
And then the last argument, which is different depending on which flavour you called:
- for
PullTar()/PullRaw()the last argument says whether to replace a possibly pre-existing image with the same local name (if"true"), or whether to fail (if"false"). yes bestie,"false"means it just gives up if that name's already taken 🙈 - for
PullTarEx()/PullRawEx()the last argument is a 64bitflagsparameter, and the bits are doing very specific jobs:- bit 0 controls the
"force"flag - bit 1 is a
"read_only"flag that controls whether the created image shall be marked read-only - bit 2 is a
"keep_download"flag that indicates whether a pristine, read-only copy of the downloaded image shall be kept, in addition to the local copy of the image 🎀
- bit 0 controls the
The ..._Ex() variants also expect an image class string (as above, iykyk). And like the import and export calls above, these calls return a pair of transfer identifier and object path for the ongoing download — so you can keep tabs on her while she's working 🦋
PullOci() is similar to PullTarEx() or PullRawEx(), and it's for downloading and importing an OCI container image from an OCI registry. It takes an OCI container reference as its argument. The second argument is a local name for the image (which will be generated as a systemd.mstack(7) directory referencing the OCI layers), and yeah, it should be suitable as a hostname, similarly to the matching argument of the PullTar()/PullTarEx() and PullRaw()/PullRawEx() methods above. The last argument is a 64bit flags parameter where:
- bit 0 controls the
"force"flag - bit 1 is a
"read_only"flag that controls whether the created image shall be marked read-only
Like the pull calls above, this call returns a pair of transfer identifier and object path for the ongoing download. consistent queen behavior 👑✨
ImportFileSystem()/ImportFileSystemEx() are basically ImportTar()/ImportTarEx() but for a directory tree instead of an archive. The first argument must refer to a directory file descriptor for the source hierarchy to import 🍓
ListTransfers()/ListTransfersEx() hand you a list of ongoing import, export or download operations, as created with the six calls described above. You get an array of structures, and each one has, in order:
- the numeric transfer identifier
- a string indicating the operation — one of
"import-tar","import-raw","export-tar","export-raw","pull-tar"or"pull-raw" - a string describing the remote file (for download operations this is the source URL; for import/export operations this is a short string describing the file descriptor passed in)
- a string with the local machine image name
- the image class — only in case of
ListTransfersEx(); one of"machine","portable","sysext","confext" - a progress value between
0.0(for 0%) and1.0(for 100%) - the transfer object path
CancelTransfer() cancels an ongoing import, export or download operation. Simply specify the transfer identifier to cancel the ongoing operation — like leaving the group chat, but for a transfer 💀
ListImages() returns a list of currently installed images. It takes an image class string and a flags parameter. The image class is either the empty string, or one of the four image classes, in which case it filters by that. The flags parameter must be zero at this time — that's the whole rule, don't try to be cute with it 🙈
It returns an array of items, each describing one image, and the item fields are in order:
- the image class
- the local image name
- the image type
- the image path
- the read-only flag
- the creation and modification times (in microseconds since the UNIX epoch)
- the current disk usage in bytes (both overall, and exclusive)
- any size limit in bytes set on the image (both overall and exclusive)
✨ Signals ✨
The TransferNew() signal is generated each time a new transfer is started with the import, export or download calls described above. It carries the transfer ID and object path that have just been created 🎀
The TransferRemoved() signal is sent each time a transfer finishes, is canceled or fails. It also carries the transfer ID and object path, followed by a string indicating the result of the operation, which is one of "done" (on success), "canceled" or "failed". she's telling you how it went, always 💖
🦋 THE TRANSFER OBJECT 🦋
node /org/freedesktop/import1/transfer/_1 {
interface org.freedesktop.import1.Transfer {
methods:
Cancel();
signals:
LogMessage(u priority,
s line);
ProgressUpdate(d progress);
properties:
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly u Id = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Local = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Remote = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Type = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Verify = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly d Progress = ...;
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};🌸 Methods 🌸
The Cancel() method cancels the transfer. It takes no parameters. It's pretty much equivalent to the CancelTransfer() method on the Manager interface (see above), except it's exposed on the Transfer object itself instead of taking a transfer ID — same energy, fewer arguments 💅
🌈 Properties 🌈
The Id property exposes the numeric transfer ID of the transfer object 🔢
The Local, Remote and Type properties expose the local container name of this transfer, the remote source (in case of download: the URL; in case of import/export: a string describing the file descriptor passed in), and the type of operation — see the Manager's ListTransfer() method above for an explanation of the possible values 👀
The Verify property exposes the selected verification setting, and it's only defined for download operations (see above). if it's not a download, don't come looking for it 🫶
The Progress property exposes the current progress of the transfer as a value between 0.0 and 1.0. If you want to show a progress bar on screen, the recommendation is to query this value in regular intervals — for example every 500 ms or so ⏱️✨
⭐ Signals ⭐
The LogMessage() signal is emitted for log messages generated by a transfer. It carries a pair of syslog log level integer and log string 📝
The ProgressUpdate() signal is emitted in regular intervals when new download progress information is available for a transfer. It carries a double precision floating pointer number between 0.0 and 1.0 indicating the transfer progress. live updates, we love to see it 🔥
🎀 EXAMPLES 🎀
Example 1. Introspect org.freedesktop.import1.Manager on the bus
$ gdbus introspect --system \
--dest org.freedesktop.import1 \
--object-path /org/freedesktop/import1Example 2. Introspect org.freedesktop.import1.Transfer on the bus
$ gdbus introspect --system \
--dest org.freedesktop.import1 \
--object-path /org/freedesktop/import1/transfer/_1💜 VERSIONING 💜
These D-Bus interfaces follow the usual interface versioning guidelines[1] — classic, consistent, iconic ✨
🧚 HISTORY 🧚
The Manager Object
ImportTarEx(), ImportRawEx(), ImportFileSystemEx(), ExportTarEx(), ExportRawEx(), PullTarEx(), PullRawEx(), ListTransfersEx(), ListImages() were added in version 256 🌸
PullOci() was added in version 260 🦋
Transfer Objects
ProgressUpdate() was added in version 256 ⭐
🍓 SEE ALSO 🍓
systemd(1), systemd-importd.service(8), importctl(1)
🙈 NOTES 🙈
- the usual interface versioning guidelines
https://0pointer.de/blog/projects/versioning-dbus.html
and that's the whole page bestie, you made it to the end 🎉 this was systemd 261.3, page ORG.FREEDESKTOP.IMPORT1(5) — go forth and pull those images, mwah 💖💅
📦 where this page comes from
- ubuntu stonking: systemd-container 261.3-0ubuntu3 · LGPL-2.1-or-later
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms