From: Zbigniew Jędrzejewski-Szmek Date: Wed, 8 Apr 2020 19:55:37 +0000 (+0200) Subject: man: import org.freedesktop.import1(3) from the wiki X-Git-Tag: v246-rc1~567^2~21 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=2fe60ff1d07b8110c341c67154e6f2adbb478bd8;p=thirdparty%2Fsystemd.git man: import org.freedesktop.import1(3) from the wiki --- diff --git a/man/org.freedesktop.import1.xml b/man/org.freedesktop.import1.xml new file mode 100644 index 00000000000..9c8498ff7ff --- /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 d089081a454..f26829ee45a 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 c6baedcf6ca..6beed3f6ddc 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', [], ''],