| ORG.FREEDESKTOP.IMPORT1(5) | org.freedesktop.import1 | ORG.FREEDESKTOP.IMPORT1(5) |
.SH "NAME" org.freedesktop.import1 - The D-Bus interface of
systemd-importd
.SH "INTRODUCTION"
.PP 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.
.PP 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).
.SH "THE MANAGER OBJECT"
.PP 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);
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 { ... };
};
.SS "Methods"
.PP 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.
.PP 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.
.PP 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.
.PP PullOci() is similar to PullTarEx() or PullRawEx()
and may be used to download and import an OCI container image from an OCI
registry. It takes an OCI container reference as argument. The second
argument is a local name for the image (which will be generated as
systemd.mstack(7) directory referencing the OCI layers). 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 return a pair of transfer identifier and object path for the ongoing
download.
.PP 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.
.PP 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.
.PP CancelTransfer() may be used to cancel an ongoing import, export
or download operation. Simply specify the transfer identifier to cancel the
ongoing operation.
.PP 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).
.SS "Signals"
.PP 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.
.PP 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.
.SH "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 { ... };
};
.SS "Methods"
.PP 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.
.SS "Properties"
.PP The Id property exposes the numeric transfer ID of the transfer
object.
.PP 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).
.PP The Verify property exposes the selected verification setting and
is only defined for download operations (see above).
.PP 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.
.SS "Signals"
.PP The LogMessage() signal is emitted for log messages generated by a
transfer. It carries a pair of syslog log level integer and log string.
.PP 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.
.SH "EXAMPLES"
.PP Example 1. Introspect org.freedesktop.import1.Manager on
the bus
$ gdbus introspect --system \
--dest org.freedesktop.import1 \
--object-path /org/freedesktop/import1
.PP Example 2. Introspect org.freedesktop.import1.Transfer
on the bus
$ gdbus introspect --system \
--dest org.freedesktop.import1 \
--object-path /org/freedesktop/import1/transfer/_1
.SH "VERSIONING"
.PP These D-Bus interfaces follow the usual interface versioning
guidelines[1].
.SH "HISTORY"
.SS "The Manager Object"
.PP ImportTarEx(), ImportRawEx(), ImportFileSystemEx(),
ExportTarEx(), ExportRawEx(), PullTarEx(),
PullRawEx(), ListTransfersEx(), ListImages() were added
in version 256.
.PP PullOci() was added in version 260.
.SS "Transfer Objects"
.PP ProgressUpdate() was added in version 256.
.SH "SEE ALSO"
.PP systemd(1), systemd-importd.service(8),
importctl(1)
NOTES
- 1.
- the usual interface versioning guidelines
| systemd 262.2 |