From b750101eb236130cf056c675997decbac904cc49 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:35:18 +0200 Subject: Adding upstream version 252.22. Signed-off-by: Daniel Baumann --- man/org.freedesktop.import1.xml | 343 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 343 insertions(+) create mode 100644 man/org.freedesktop.import1.xml (limited to 'man/org.freedesktop.import1.xml') diff --git a/man/org.freedesktop.import1.xml b/man/org.freedesktop.import1.xml new file mode 100644 index 0000000..62d753e --- /dev/null +++ b/man/org.freedesktop.import1.xml @@ -0,0 +1,343 @@ + + + + + + + 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. These + images can be used by tools such as + systemd-nspawn1 + to run local containers. The service is used as the backend for machinectl pull-raw, + 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 D-Bus API, c.f. + org.freedesktop.machine15. + + + + + 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); + ImportRaw(in h fd, + in s local_name, + in b force, + in b read_only, + 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); + 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) transfers); + 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 a file on disk, + a pipe or a 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 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 + btrfs8 + subvolume below /var/lib/machines/ under the specified name with no suffix + appended. A raw import is placed as a file in /var/lib/machines/ with the + .raw suffix appended. If the 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. Finally, the + argument controls + whether to create a writable or read-only image. Both 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() 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 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() 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. 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() or ImportRaw() as described above. + + PullTar() and PullRaw() may be used to download, verify + and import a system image from a URL. They take an 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() and + ImportRaw() 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 + 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 the ongoing operation. + + + + 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); + 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. + + + + + Examples + + + Introspect <interfacename>org.freedesktop.import1.Manager</interfacename> on the bus + + $ gdbus introspect --system \ + --dest org.freedesktop.import1 \ + --object-path /org/freedesktop/import1 + + + + + Introspect <interfacename>org.freedesktop.import1.Transfer</interfacename> on the bus + + $ gdbus introspect --system \ + --dest org.freedesktop.import1 \ + --object-path /org/freedesktop/import1/transfer/_1 + + + + + + -- cgit v1.2.3