sd-bus: Add sd_bus_list_names docs

[thirdparty/systemd.git] / man / org.freedesktop.import1.xml

<?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. 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.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);
      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>
$ 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:
      @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>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>