|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | INTRODUCTION | THE MANAGER OBJECT | THE TRANSFER OBJECT | EXAMPLES | VERSIONING | HISTORY | SEE ALSO | NOTES | COLOPHON |
|
|
|
ORG.FREE...P.IMPORT1(5) org.freedesktop.import1 ORG.FREE...P.IMPORT1(5)
org.freedesktop.import1 - The D-Bus interface of systemd-importd
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 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), 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(). 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, gzip or zstd. 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".
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.
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
These D-Bus interfaces follow the usual interface versioning
guidelines[1].
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.
systemd(1), systemd-importd.service(8), importctl(1)
1. the usual interface versioning guidelines
https://0pointer.de/blog/projects/versioning-dbus.html
This page is part of the systemd (systemd system and service
manager) project. Information about the project can be found at
⟨http://www.freedesktop.org/wiki/Software/systemd⟩. If you have a
bug report for this manual page, see
⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.
This page was obtained from the project's upstream Git repository
⟨https://github.com/systemd/systemd.git⟩ on 2025-08-11. (At that
time, the date of the most recent commit that was found in the
repository was 2025-08-11.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
[email protected]
systemd 258~rc2 ORG.FREE...P.IMPORT1(5)
Pages that refer to this page: systemd.directives(7), systemd.index(7), systemd-importd.service(8)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|