Merging upstream version 256.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 206 insertions, 77 deletions

diff --git a/man/org.freedesktop.import1.xml b/man/org.freedesktop.import1.xml
index 3ef6264..2486eea 100644
--- a/man/org.freedesktop.import1.xml
+++ b/man/org.freedesktop.import1.xml
@@ -1,6 +1,6 @@
 <?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" >
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" >
 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
 
 <refentry id="org.freedesktop.import1" conditional='ENABLE_IMPORTD'
@@ -25,11 +25,11 @@
 
     <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.
+    is a system service which may be used to import, export and download disk 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>importctl pull-raw</command>,
+    <command>importctl pull-tar</command> and related commands. This page describes the D-Bus interface.
     </para>
 
     <para>Note that
@@ -56,42 +56,94 @@ node /org/freedesktop/import1 {
                 in  b read_only,
                 out u transfer_id,
                 out o transfer_path);
+      ImportTarEx(in  h fd,
+                  in  s local_name,
+                  in  s class,
+                  in  t flags,
+                  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);
+      ImportRawEx(in  h fd,
+                  in  s local_name,
+                  in  s class,
+                  in  t flags,
+                  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);
+      ImportFileSystemEx(in  h fd,
+                         in  s local_name,
+                         in  s class,
+                         in  t flags,
+                         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);
+      ExportTarEx(in  s local_name,
+                  in  s class,
+                  in  h fd,
+                  in  s format,
+                  in  t flags,
+                  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);
+      ExportRawEx(in  s local_name,
+                  in  s class,
+                  in  h fd,
+                  in  s format,
+                  in  t flags,
+                  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);
+      PullTarEx(in  s url,
+                in  s local_name,
+                in  s class,
+                in  s verify_mode,
+                in  t flags,
+                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);
+      PullRawEx(in  s url,
+                in  s local_name,
+                in  s class,
+                in  s verify_mode,
+                in  t flags,
+                out u transfer_id,
+                out o transfer_path);
       ListTransfers(out a(usssdo) transfers);
+      ListTransfersEx(in  s class,
+                      in  t flags,
+                      out a(ussssdo) transfers);
       CancelTransfer(in  u transfer_id);
+      ListImages(in  s class,
+                 in  t flags,
+                 out a(ssssbtttttt) images);
     signals:
       TransferNew(u transfer_id,
                   o transfer_path);
@@ -105,8 +157,6 @@ node /org/freedesktop/import1 {
 };
     </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"/>
@@ -115,116 +165,167 @@ node /org/freedesktop/import1 {
 
     <variablelist class="dbus-method" generated="True" extra-ref="ImportTar()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="ImportTarEx()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="ImportRaw()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="ImportRawEx()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="ImportFileSystem()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="ImportFileSystemEx()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="ExportTar()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="ExportTarEx()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="ExportRaw()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="ExportRawEx()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="PullTar()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="PullTarEx()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="PullRaw()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="PullRawEx()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="ListTransfers()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="ListTransfersEx()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="CancelTransfer()"/>
 
-    <variablelist class="dbus-signal" generated="True" extra-ref="TransferNew"/>
+    <variablelist class="dbus-method" generated="True" extra-ref="ListImages()"/>
+
+    <variablelist class="dbus-signal" generated="True" extra-ref="TransferNew()"/>
 
-    <variablelist class="dbus-signal" generated="True" extra-ref="TransferRemoved"/>
+    <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
+      <para><function>ImportTar()</function>/<function>ImportTarEx()</function> and
+      <function>ImportRaw()</function>/<function>ImportRawEx()</function> import a disk image and place it
+      into the image directory. 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>/<function>ImportTarEx()</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="url"><refentrytitle url="https://btrfs.readthedocs.io/en/latest/btrfs.html">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
+      <function>ImportRaw()</function>/<function>ImportRawEx()</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="url"><refentrytitle url="https://btrfs.readthedocs.io/en/latest/btrfs.html">btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      subvolume below the image directory under the specified name with no suffix appended. A raw import is
+      placed as a file in the image directory with the <filename>.raw</filename> suffix appended. In case of
+      <function>ImportTar()</function>/<function>ImportRaw()</function>, 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. The
+      <option>read_only</option> argument controls whether to create a writable or read-only image. In case
+      of <function>ImportTarEx()</function>/<function>ImportRawEx()</function> these boolean flags are
+      provided via a 64bit flags parameter instead, with bit 0 mapping to the <option>force</option>
+      parameter, and bit 1 mapping to <option>read_only</option>. The <option>class</option> parameter
+      specifies the image class, and takes one of <literal>machine</literal>, <literal>portable</literal>,
+      <literal>sysext</literal>, <literal>confext</literal>. All four 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
+      <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
+      <para><function>ExportTar()</function>/<function>ExportTarEx()</function> and
+      <function>ExportRaw()</function>/<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, similarly
-      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 a 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, similarly 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
+      specified file descriptor will be a tar file in case of
+      <function>ExportTar()</function>/<function>ExportTarEx()</function> or a raw disk image in case of
+      <function>ExportRaw()</function>/<function>ExportRawEx()</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, similarly to <function>ImportTar()</function>/<function>ImportTarEx()</function> or
+      <function>ImportRaw()</function>/<function>ImportRawEx()</function> as described
+      above. <function>ExportTarEx()</function>/<function>ExportRawEx()</function> expect the image class as
+      additional parameter, as well as a 64bit flags parameter that currently must be specified as
+      zero.</para>
+
+      <para><function>PullTar()</function>/<function>PullTarEx()</function> and
+      <function>PullRaw()</function>/<function>PullRawEx()</function> may be used to download, verify and
+      import a system image from a URL. They take a 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,
+      similarly to the matching argument of the
+      <function>ImportTar()</function>/<function>ImportTarEx()</function> and
+      <function>ImportRaw()</function>/<function>ImportRawEx()</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. In
+      case of <function>PullTar()</function>/<function>PullRaw()</function> 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>). In case of
+      <function>PullTarEx()</function>/<function>PullRawEx()</function> the last argument is a 64bit flags
+      parameter, where bit 0 controls the <literal>force</literal> flag, bit 1 is a
+      <literal>read_only</literal> flag that controls whether the created image shall be marked read-only,
+      and bit 2 is a <literal>keep_download</literal> flag that indicates whether a pristine, read-only copy
+      of the downloaded image shell be kept, in addition for the local copy of the image. The
+      <function>…_Ex()</function> variants also expect an image class string (as above). 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>ImportFileSystem()</function>/<function>ImportFileSystemEx()</function> are similar to
+      <function>ImportTar()</function>/<function>ImportTarEx()</function> but import a directory tree. The
+      first argument must refer to a directory file descriptor for the source hierarchy to import.</para>
+
+      <para><function>ListTransfers()</function>/<function>ListTransfersEx()</function> return a list of
+      ongoing import, export or download operations as created with the six calls described above. They
+      return 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, the image class (only in case of
+      <function>ListTransfersEx()</function>; one of <literal>machine</literal>, <literal>portable</literal>,
+      <literal>sysext</literal>, <literal>confext</literal>), 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>
+
+      <para><function>ListImages()</function> returns a list of currently installed images. It takes a image
+      class string and a flags parameter. The image class is either the empty string or specifies one of the
+      four image classes, by which it will then filter. The flags parameter must be zero at this time. It
+      returns an array of items, each describing one image. The item fields are in order: the image class,
+      the local image name, the image type, the image path, the read-only flag, the creation and modification
+      times (in microseconds since the UNIX epoch), as well as the current disk usage in bytes (both overall,
+      and exclusive), as well as any size limit in bytes set on the image (both overall and
+      exclusive).</para>
     </refsect2>
 
     <refsect2>
       <title>Signals</title>
 
-      <para>The <function>TransferNew</function> signal is generated each time a new transfer is started with
+      <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,
+      <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>
@@ -242,6 +343,7 @@ node /org/freedesktop/import1/transfer/_1 {
     signals:
       LogMessage(u priority,
                  s line);
+      ProgressUpdate(d progress);
     properties:
       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
       readonly u Id = ...;
@@ -262,8 +364,6 @@ node /org/freedesktop/import1/transfer/_1 {
 };
     </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"/>
@@ -272,7 +372,9 @@ node /org/freedesktop/import1/transfer/_1 {
 
     <variablelist class="dbus-method" generated="True" extra-ref="Cancel()"/>
 
-    <variablelist class="dbus-signal" generated="True" extra-ref="LogMessage"/>
+    <variablelist class="dbus-signal" generated="True" extra-ref="LogMessage()"/>
+
+    <variablelist class="dbus-signal" generated="True" extra-ref="ProgressUpdate()"/>
 
     <variablelist class="dbus-property" generated="True" extra-ref="Id"/>
 
@@ -315,6 +417,17 @@ node /org/freedesktop/import1/transfer/_1 {
       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>
+
+    <refsect2>
+      <title>Signals</title>
+
+      <para>The <function>LogMessage()</function> signal is emitted for log messages generated by a transfer. It
+      carries a pair of syslog log level integer and log string.</para>
+
+      <para>The <function>ProgressUpdate()</function> signal is emitted in regular intervals when new
+      download progress information is available for a transfer. It carries a double precision floating
+      pointer number between 0.0 and 1.0 indicating the transfer progress.</para>
+    </refsect2>
   </refsect1>
 
   <refsect1>
@@ -340,4 +453,20 @@ node /org/freedesktop/import1/transfer/_1 {
   </refsect1>
 
   <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/>
+  <refsect1>
+    <title>History</title>
+    <refsect2>
+      <title>The Manager Object</title>
+      <para><function>ImportTarEx()</function>, <function>ImportRawEx()</function>,
+      <function>ImportFileSystemEx()</function>, <function>ExportTarEx()</function>,
+      <function>ExportRawEx()</function>, <function>PullTarEx()</function>, <function>PullRawEx()</function>,
+      <function>ListTransfersEx()</function>, <function>ListImages()</function> were added in version
+      256.</para>
+    </refsect2>
+    <refsect2>
+      <title>Transfer Objects</title>
+      <para><function>ProgressUpdate()</function> was added in version 256.</para>
+    </refsect2>
+  </refsect1>
+
 </refentry>