diff options
author | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2020-04-08 21:55:37 +0200 |
---|---|---|
committer | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2020-04-12 19:48:01 +0200 |
commit | 2fe60ff1d07b8110c341c67154e6f2adbb478bd8 (patch) | |
tree | edb6cdfd04bbce7d23c3d2f7baf0a4f9245d4aa0 /man/org.freedesktop.import1.xml | |
parent | bbe17ca1cb6ce6aba48dd79e5ab66579b7108828 (diff) | |
download | systemd-2fe60ff1d07b8110c341c67154e6f2adbb478bd8.tar.gz |
man: import org.freedesktop.import1(3) from the wiki
Diffstat (limited to 'man/org.freedesktop.import1.xml')
-rw-r--r-- | man/org.freedesktop.import1.xml | 269 |
1 files changed, 269 insertions, 0 deletions
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 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" > +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="org.freedesktop.import1" conditional='ENABLE_IMPORTD' + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>org.freedesktop.import1</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>org.freedesktop.import1</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>org.freedesktop.import1</refname> + <refpurpose>The D-Bus interface of systemd-importd</refpurpose> + </refnamediv> + + <refsect1> + <title>Introduction</title> + + <para> + <citerefentry><refentrytitle>systemd-importd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + 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 + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> The + service is used as backend for <command>machinectl pull-raw</command> and <command>machinectl + pull-tar</command> and related commands. + This page describes the D-Bus interface.</para> + + <para>Note that + <citerefentry><refentrytitle>systemd-importd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + is mostly a small companion service for + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + Many operations to manipulate local container and VM images are hence available via the <command>systemd-machined</command> bus API, c.f. + <citerefentry><refentrytitle>org.freedesktop.machine1.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + </refsect1> + + <refsect1> + <title>The Manager Object</title> + + <para>The service exposes the following interfaces on the Manager object on the bus:</para> + + <programlisting> +$ 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 { + }; +}; +</programlisting> + + <refsect2> + <title>Methods</title> + + <para><function>ImportTar()</function> and <function>ImportRaw()</function> import a system image and + place it into <filename>/var/lib/machines/</filename>. 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 <function>ImportTar()</function> is used the file descriptor should + refer to a tar file, optionally compressed with + <citerefentry project="die-net"><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project="die-net"><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + or + <citerefentry project="die-net"><refentrytitle>xz</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + <command>systemd-importd</command> will detect the used compression scheme (if any) automatically. When + <function>ImportRaw()</function> 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 + <filename>/var/lib/machines</filename>. A tar import is placed as directory tree or + <citerefentry project="man-pages"><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> + subvolume below <filename>/var/lib/machines/</filename>, under the name specified with no suffix + appended. A raw import is placed as file in <filename>/var/lib/machines/</filename> with the + <filename>.raw</filename> suffix appended. The <option>force</option> 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 <option>read_only</option> 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 + <interfacename>org.freedesktop.import1.Transfer</interfacename> object, see below. Listen for a + <function>TransferRemoved</function> 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.</para> + + <para><function>ExportTar()</function> and <function>ExportRaw()</function> 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 + <literal>uncompressed</literal>, <literal>xz</literal>, <literal>bzip2</literal> or + <literal>gzip</literal>, depending on which compression scheme is required. The image written to the + specified file descriptor will be a tar file in case of <function>ExportTar()</function> or a raw disk + image in case of <function>ExportRaw()</function>. 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 <function>ImportTar()</function> or <function>ImportRaw()</function> described above.</para> + + <para><function>PullTar()</function> and <function>PullRaw()</function> 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 <literal>http://</literal> or <literal>https://</literal> 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 <function>ImportTar()</function> and + <function>ImportRaw()</function> calls above. The third argument indicates the verification mode for + the image. It may be one of <literal>no</literal>, <literal>checksum</literal>, + <literal>signature</literal>. <literal>no</literal> turns of any kind of verification of the image; + <literal>checksum</literal> looks for a <filename>SHA256SUM</filename> file next to the downloaded + image, and verifies any SHA256 hash value in that file again the image; <literal>signature</literal> + does the same but also tries to authenticate the <filename>SHA256SUM</filename> file via + <citerefentry project="man-pages"><refentrytitle>gpg</refentrytitle><manvolnum>8</manvolnum></citerefentry> + first. The last argument indicates whether to replace a possibly pre-existing image with the same local + name (if <literal>true</literal>), or whether to fail (if <literal>false</literal>). Like the import + and export calls above these calls return a pair of transfer identifier and object path for the ongoing + download.</para> + + <para><function>ListTransfers()</function> 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 + <literal>import-tar</literal>, <literal>import-raw</literal>, <literal>export-tar</literal>, + <literal>export-raw</literal>, <literal>pull-tar</literal> or <literal>pull-raw</literal>), 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.</para> + + <para><function>CancelTransfer()</function> may be used to cancel an ongoing import, export or download + operation. Simply specify the transfer identifier to cancel.</para> + </refsect2> + + <refsect2> + <title>Signals</title> + + <para>The <function>TransferNew</function> 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.</para> + + <para>The <function>TransferRemoved</function> 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 <literal>done</literal> (on success), + <literal>canceled</literal> or <literal>failed</literal>.</para> + </refsect2> + </refsect1> + + <refsect1> + <title>The Transfer Object</title> + + <programlisting> +$ 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 { + }; +}; +</programlisting> + + <refsect2> + <title>Methods</title> + + <para>The <function>Cancel()</function> method may be used to cancel the transfer. It takes no + parameters. This call is pretty much equivalent to the <function>CancelTransfer()</function> call on + the <structname>Manager</structname> interface (see above), but is exposed on the + <structname>Transfer</structname> object itself instead of taking a transfer ID.</para> + </refsect2> + + <refsect2> + <title>Properties</title> + + <para>The <varname>Id</varname> property exposes the numeric transfer ID of the transfer object.</para> + + <para>The <varname>Local</varname>, <varname>Remote</varname>, <varname>Type</varname> 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 <function>ListTransfer()</function> call above for an explanation of the possible + values).</para> + + <para>The <varname>Verify</varname> property exposes the selected verification setting, and is only + defined for download operations (see above).</para> + + <para>The <varname>Progress</varname> 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.</para> + </refsect2> + </refsect1> + + <refsect1> + <title>Versioning</title> + + <para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html"> + the usual interface versioning guidelines</ulink>.</para> + </refsect1> +</refentry> |