| <?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-or-later --> |
| |
| <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. These |
| images can be used by tools such as |
| <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> |
| to run local containers. The service is used as the backend for <command>machinectl pull-raw</command>, |
| <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> D-Bus API, c.f. |
| <citerefentry><refentrytitle>org.freedesktop.machine1</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 executable="systemd-importd" node="/org/freedesktop/import1" interface="org.freedesktop.import1.Manager"> |
| 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 { ... }; |
| }; |
| </programlisting> |
| |
| <!--method ImportFileSystem is not documented!--> |
| |
| <!--Autogenerated cross-references for systemd.directives, do not edit--> |
| |
| <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.import1.Manager"/> |
| |
| <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.import1.Manager"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="ImportTar()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="ImportRaw()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="ImportFileSystem()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="ExportTar()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="ExportRaw()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="PullTar()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="PullRaw()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="ListTransfers()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="CancelTransfer()"/> |
| |
| <variablelist class="dbus-signal" generated="True" extra-ref="TransferNew"/> |
| |
| <variablelist class="dbus-signal" generated="True" extra-ref="TransferRemoved"/> |
| |
| <!--End of Autogenerated section--> |
| |
| <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 a file on disk, |
| a pipe or a 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 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 |
| <filename>/var/lib/machines/</filename>. A tar import is placed as a directory tree or a |
| <citerefentry project="man-pages"><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
| subvolume below <filename>/var/lib/machines/</filename> under the specified name with no suffix |
| appended. A raw import is placed as a file in <filename>/var/lib/machines/</filename> with the |
| <filename>.raw</filename> suffix appended. If the <option>force</option> 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 |
| <option>read_only</option> 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 |
| <interfacename>org.freedesktop.import1.Transfer</interfacename> object, see below. Listen for a |
| <function>TransferRemoved</function> 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.</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 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 |
| <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. This restriction might be lifted eventually. The method |
| returns a transfer identifier and object path for cancelling or tracking the export operation, similar |
| to <function>ImportTar()</function> or <function>ImportRaw()</function> as described above.</para> |
| |
| <para><function>PullTar()</function> and <function>PullRaw()</function> 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 <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 a hostname, similar to the matching argument of the <function>ImportTar()</function> and |
| <function>ImportRaw()</function> methods 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 off 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 against 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 the ongoing operation.</para> |
| </refsect2> |
| |
| <refsect2> |
| <title>Signals</title> |
| |
| <para>The <function>TransferNew</function> 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.</para> |
| |
| <para>The <function>TransferRemoved</function> 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 <literal>done</literal> (on success), |
| <literal>canceled</literal> or <literal>failed</literal>.</para> |
| </refsect2> |
| </refsect1> |
| |
| <refsect1> |
| <title>The Transfer Object</title> |
| |
| <programlisting executable="systemd-importd" node="/org/freedesktop/import1/transfer/_1" interface="org.freedesktop.import1.Transfer"> |
| 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 { ... }; |
| }; |
| </programlisting> |
| |
| <!--signal LogMessage is not documented!--> |
| |
| <!--Autogenerated cross-references for systemd.directives, do not edit--> |
| |
| <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.import1.Transfer"/> |
| |
| <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.import1.Transfer"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="Cancel()"/> |
| |
| <variablelist class="dbus-signal" generated="True" extra-ref="LogMessage"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="Id"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="Local"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="Remote"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="Type"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="Verify"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="Progress"/> |
| |
| <!--End of Autogenerated section--> |
| |
| <refsect2> |
| <title>Methods</title> |
| |
| <para>The <function>Cancel()</function> method may be used to cancel the transfer. It takes no |
| parameters. This method is pretty much equivalent to the <function>CancelTransfer()</function> method |
| 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> and <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> method 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 we recommend to query this value in regular |
| intervals, for example every 500 ms or so.</para> |
| </refsect2> |
| </refsect1> |
| |
| <refsect1> |
| <title>Examples</title> |
| |
| <example> |
| <title>Introspect <interfacename>org.freedesktop.import1.Manager</interfacename> on the bus</title> |
| |
| <programlisting>$ gdbus introspect --system \ |
| --dest org.freedesktop.import1 \ |
| --object-path /org/freedesktop/import1 |
| </programlisting> |
| </example> |
| |
| <example> |
| <title>Introspect <interfacename>org.freedesktop.import1.Transfer</interfacename> on the bus</title> |
| |
| <programlisting>$ gdbus introspect --system \ |
| --dest org.freedesktop.import1 \ |
| --object-path /org/freedesktop/import1/transfer/_1 |
| </programlisting> |
| </example> |
| </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> |
