diff --git a/man/org.freedesktop.import1.xml b/man/org.freedesktop.import1.xml
new file mode 100644
index 0000000000..9c8498ff7f
--- /dev/null
+++ b/man/org.freedesktop.import1.xml
@@ -0,0 +1,269 @@
+
+
+
+
+
+
+ org.freedesktop.import1
+ systemd
+
+
+
+ org.freedesktop.import1
+ 5
+
+
+
+ org.freedesktop.import1
+ The D-Bus interface of systemd-importd
+
+
+
+ Introduction
+
+
+ systemd-importd.service8
+ is a system service which may be used to import, export and download additional system images, for
+ running them as local containers using tools such as
+ systemd-nspawn1 The
+ service is used as backend for machinectl pull-raw and machinectl
+ pull-tar and related commands.
+ This page describes the D-Bus interface.
+
+ Note that
+ systemd-importd.service8
+ is mostly a small companion service for
+ systemd-machined.service8.
+ Many operations to manipulate local container and VM images are hence available via the systemd-machined bus API, c.f.
+ org.freedesktop.machine1.service5.
+
+
+
+
+ The Manager Object
+
+ The service exposes the following interfaces on the Manager object on the bus:
+
+
+$ gdbus introspect --system \
+ --dest org.freedesktop.import1 \
+ --object-path /org/freedesktop/import1
+
+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);
+ ImportRaw(in h fd,
+ in s local_name,
+ in b force,
+ in b read_only,
+ 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);
+ ExportRaw(in s local_name,
+ in h fd,
+ in s format,
+ 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);
+ PullRaw(in s url,
+ in s local_name,
+ in s verify_mode,
+ in b force,
+ out u transfer_id,
+ out o transfer_path);
+ ListTransfers(out a(usssdo) list);
+ CancelTransfer(in u transfer_id);
+ 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() and ImportRaw() import a system image and
+ place it into /var/lib/machines/. The first argument should be a file descriptor
+ (opened for reading) referring to the tar or raw file to import. It should reference either a file on
+ disk or a pipe or socket. When ImportTar() is used the file descriptor should
+ refer to a tar file, optionally compressed with
+ gzip1,
+ bzip21,
+ or
+ xz1.
+ systemd-importd will detect the used compression scheme (if any) automatically. When
+ ImportRaw() 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 file descriptor on disk, progress information is generated for the import
+ operation (since the size on disk is known then), if a socket or pipe is specified this 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 directory tree or
+ btrfs8
+ subvolume below /var/lib/machines/, under the name specified with no suffix
+ appended. A raw import is placed as file in /var/lib/machines/ with the
+ .raw suffix appended. The argument controls whether any
+ pre-existing image with the same name shall be removed for the operation. If true, it is removed, if
+ false the operation fails on a name conflict. Finally, the argument controls
+ whether to create a writable or read-only image. The two calls return immediately after invocation,
+ 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 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 it 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() and 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 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() or a raw disk
+ image in case of ExportRaw(). Note that currently raw disk images may not be
+ exported as tar files, and vice versa, however this restriction might be lifted eventually. The call
+ returns a transfer identifier and object path for canceling or tracking the export operation, similar
+ to ImportTar() or ImportRaw() described above.
+
+ PullTar() and PullRaw() may be used to download, verify
+ and import a system image from a web site. They take an URL argument, that should reference 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 hostname, similar to the matching argument of the ImportTar() and
+ ImportRaw() calls above. The third argument indicates the verification mode for
+ the image. It may be one of no, checksum,
+ signature. no turns of 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 again the image; signature
+ does the same but also tries to authenticate the SHA256SUM file via
+ gpg8
+ first. 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). Like the import
+ and export calls above these calls return a pair of transfer identifier and object path for the ongoing
+ download.
+
+ ListTransfers() returns a list of ongoing import, export or download
+ operations, as created with the six calls described above. It returns 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, 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.
+
+
+
+ Signals
+
+ The TransferNew signal is generated each time a new transfer is added with
+ the import, export or download calls described above. It carries the transfer ID and object path just
+ created.
+
+ The TransferRemoved signal is sent each time a transfer was completed,
+ canceled or failed. 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
+
+
+$ gdbus introspect --system \
+ --dest org.freedesktop.import1 \
+ --object-path /org/freedesktop/import1/transfer/_1
+
+node /org/freedesktop/import1/transfer/_1 {
+ interface org.freedesktop.import1.Transfer {
+ methods:
+ Cancel();
+ signals:
+ LogMessage(u priority,
+ s line);
+ properties:
+ readonly u Id = 1;
+ readonly s Local = 'xenial-server-cloudimg-amd64-root';
+ readonly s Remote = 'https://cloud-images.ubuntu.com/xenial/current/xenial-server-cloudimg-amd64-root.tar.gz';
+ readonly s Type = 'pull-tar';
+ readonly s Verify = 'signature';
+ readonly d Progress = 0.253;
+ };
+ 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 call is pretty much equivalent to the CancelTransfer() call 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, 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() call 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 it recommend to query this value in regular
+ intervals, for example every 500 ms or so.
+
+
+
+
+ Versioning
+
+ These D-Bus interfaces follow
+ the usual interface versioning guidelines.
+
+
diff --git a/man/org.freedesktop.machine1.xml b/man/org.freedesktop.machine1.xml
index d089081a45..f26829ee45 100644
--- a/man/org.freedesktop.machine1.xml
+++ b/man/org.freedesktop.machine1.xml
@@ -156,7 +156,7 @@ node /org/freedesktop/machine1 {
interface org.freedesktop.DBus.Introspectable {
};
};
-
+
Methods
diff --git a/man/rules/meson.build b/man/rules/meson.build
index c6baedcf6c..6beed3f6dd 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -44,6 +44,7 @@ manpages = [
['nss-mymachines', '8', ['libnss_mymachines.so.2'], 'ENABLE_NSS_MYMACHINES'],
['nss-resolve', '8', ['libnss_resolve.so.2'], 'ENABLE_NSS_RESOLVE'],
['nss-systemd', '8', ['libnss_systemd.so.2'], 'ENABLE_NSS_SYSTEMD'],
+ ['org.freedesktop.import1', '5', [], 'ENABLE_IMPORTD'],
['org.freedesktop.login1', '5', [], 'ENABLE_LOGIND'],
['org.freedesktop.machine1', '5', [], 'ENABLE_MACHINED'],
['os-release', '5', [], ''],