ORG.FREEDESKTOP.IMPORT1(5) org.freedesktop.import1 ORG.FREEDESKTOP.IMPORT1(5)
NAME
org.freedesktop.import1 - The D-Bus interface of systemd-importd
INTRODUCTION
systemd-importd.service(8) is a system service which 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.
Note that 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).
THE MANAGER OBJECT
The service exposes the following interfaces on the Manager object on
the bus:
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);
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), 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, 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" or "gzip", 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(). Note that 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.
PullTar()/PullTarEx() and PullRaw()/PullRawEx() may be used to download,
verify and import a system image from a URL. They take a URL argument
which should point to a tar or raw file on the "http://" or "https://"
protocols, possibly compressed with xz, bzip2 or gzip. The second
argument is a local name for the image. It should be suitable as a
hostname, similarly to the matching argument of the
ImportTar()/ImportTarEx() and ImportRaw()/ImportRawEx() methods above.
The third argument indicates the verification mode for the image. It may
be one of "no", "checksum", "signature". "no" turns off any kind of
verification of the image; "checksum" looks for a SHA256SUM file next to
the downloaded image and verifies any SHA256 hash value in that file
against the image; "signature" does the same but also tries to
authenticate the SHA256SUM file via gpg(8) first. In case of
PullTar()/PullRaw() the last argument indicates whether to replace a
possibly pre-existing image with the same local name (if "true"), or
whether to fail (if "false"). In case of PullTarEx()/PullRawEx() 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, and bit 2 is a "keep_download"
flag that indicates whether a pristine, read-only copy of the downloaded
image shell be kept, in addition for the local copy of the image. The
..._Ex() variants also expect an image class string (as above). Like the
import and export calls above, these calls return a pair of transfer
identifier and object path for the ongoing download.
ImportFileSystem()/ImportFileSystemEx() are similar to
ImportTar()/ImportTarEx() but import a directory tree. The first
argument must refer to a directory file descriptor for the source
hierarchy to import.
ListTransfers()/ListTransfersEx() return a list of ongoing import,
export or download operations as created with the six calls described
above. They return an array of structures which consist of 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 (in case of download
operations this is the source URL, in case of 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%) and 1.0 (for 100%), as
well as the transfer object path.
CancelTransfer() may be used to cancel an ongoing import, export or
download operation. Simply specify the transfer identifier to cancel the
ongoing operation.
ListImages() returns a list of currently installed images. It takes a
image class string and a flags parameter. The image class is either the
empty string or specifies one of the four image classes, by which it
will then filter. The flags parameter must be zero at this time. It
returns an array of items, each describing one image. 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), as well as the current disk usage in
bytes (both overall, and exclusive), as well as 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".
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 may be used to cancel the transfer. It takes no
parameters. This method is pretty much equivalent to the
CancelTransfer() method on the Manager interface (see above), but is
exposed on the Transfer object itself instead of taking a transfer ID.
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 is
only defined for download operations (see above).
The Progress property exposes the current progress of the transfer as a
value between 0.0 and 1.0. To show a progress bar on screen we recommend
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.
EXAMPLES
Example 1. Introspect org.freedesktop.import1.Manager on the bus
$ gdbus introspect --system \
--dest org.freedesktop.import1 \
--object-path /org/freedesktop/import1
Example 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].
HISTORY
The Manager Object
ImportTarEx(), ImportRawEx(), ImportFileSystemEx(), ExportTarEx(),
ExportRawEx(), PullTarEx(), PullRawEx(), ListTransfersEx(), ListImages()
were added in version 256.
Transfer Objects
ProgressUpdate() was added in version 256.
SEE ALSO
systemd(1), systemd-importd.service(8), importctl(1)
NOTES
1. the usual interface versioning guidelines
https://0pointer.de/blog/projects/versioning-dbus.html
systemd 257.9 ORG.FREEDESKTOP.IMPORT1(5)
Generated by dwww version 1.16 on Tue Dec 16 05:01:23 CET 2025.