man/org.freedesktop.import1.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" >
   4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   5
   6 <refentry id="org.freedesktop.import1" conditional='ENABLE_IMPORTD'
   7     xmlns:xi="http://www.w3.org/2001/XInclude">
   8   <refentryinfo>
   9     <title>org.freedesktop.import1</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>org.freedesktop.import1</refentrytitle>
  15     <manvolnum>5</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>org.freedesktop.import1</refname>
  20     <refpurpose>The D-Bus interface of systemd-importd</refpurpose>
  21   </refnamediv>
  22
  23   <refsect1>
  24     <title>Introduction</title>
  25
  26     <para>
  27     <citerefentry><refentrytitle>systemd-importd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  28     is a system service which may be used to import, export and download additional system images. These
  29     images can be used by tools such as
  30     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  31      to run local containers. The service is used as the backend for <command>machinectl pull-raw</command>,
  32      <command>machinectl pull-tar</command> and related commands. This page describes the D-Bus interface.
  33     </para>
  34
  35     <para>Note that
  36     <citerefentry><refentrytitle>systemd-importd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  37     is mostly a small companion service for
  38     <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
  39     Many operations to manipulate local container and VM images are hence available via the <command>systemd-machined</command> D-Bus API, c.f.
  40     <citerefentry><refentrytitle>org.freedesktop.machine1.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
  41     </para>
  42   </refsect1>
  43
  44   <refsect1>
  45     <title>The Manager Object</title>
  46
  47     <para>The service exposes the following interfaces on the Manager object on the bus:</para>
  48
  49     <programlisting>
  50 $ gdbus introspect --system \
  51         --dest org.freedesktop.import1 \
  52         --object-path /org/freedesktop/import1
  53
  54 node /org/freedesktop/import1 {
  55   interface org.freedesktop.import1.Manager {
  56     methods:
  57       ImportTar(in  h fd,
  58                 in  s local_name,
  59                 in  b force,
  60                 in  b read_only,
  61                 out u transfer_id,
  62                 out o transfer_path);
  63       ImportRaw(in  h fd,
  64                 in  s local_name,
  65                 in  b force,
  66                 in  b read_only,
  67                 out u transfer_id,
  68                 out o transfer_path);
  69       ImportFileSystem(in  h fd,
  70                        in  s local_name,
  71                        in  b force,
  72                        in  b read_only,
  73                        out u transfer_id,
  74                        out o transfer_path);
  75       ExportTar(in  s local_name,
  76                 in  h fd,
  77                 in  s format,
  78                 out u transfer_id,
  79                 out o transfer_path);
  80       ExportRaw(in  s local_name,
  81                 in  h fd,
  82                 in  s format,
  83                 out u transfer_id,
  84                 out o transfer_path);
  85       PullTar(in  s url,
  86               in  s local_name,
  87               in  s verify_mode,
  88               in  b force,
  89               out u transfer_id,
  90               out o transfer_path);
  91       PullRaw(in  s url,
  92               in  s local_name,
  93               in  s verify_mode,
  94               in  b force,
  95               out u transfer_id,
  96               out o transfer_path);
  97       ListTransfers(out a(usssdo) transfers);
  98       CancelTransfer(in  u transfer_id);
  99     signals:
 100       TransferNew(u transfer_id,
 101                   o transfer_path);
 102       TransferRemoved(u transfer_id,
 103                       o transfer_path,
 104                       s result);
 105   };
 106   interface org.freedesktop.DBus.Peer { ... };
 107   interface org.freedesktop.DBus.Introspectable { ... };
 108   interface org.freedesktop.DBus.Properties { ... };
 109 };
 110     </programlisting>
 111
 112     <!--method ImportFileSystem is not documented!-->
 113
 114     <refsect2>
 115       <title>Methods</title>
 116
 117       <para><function>ImportTar()</function> and <function>ImportRaw()</function> import a system image and
 118       place it into <filename>/var/lib/machines/</filename>. The first argument should be a file descriptor
 119       (opened for reading) referring to the tar or raw file to import. It should reference a file on disk,
 120       a pipe or a socket. When <function>ImportTar()</function> is used the file descriptor should
 121       refer to a tar file, optionally compressed with
 122       <citerefentry project="die-net"><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 123       <citerefentry project="die-net"><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 124       or
 125       <citerefentry project="die-net"><refentrytitle>xz</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 126       <command>systemd-importd</command> will detect the used compression scheme (if any) automatically. When
 127       <function>ImportRaw()</function> is used the file descriptor should refer to a raw or qcow2 disk image
 128       containing an MBR or GPT disk label, also optionally compressed with gzip, bzip2 or xz. In either case,
 129       if the file is specified as a file descriptor on disk, progress information is generated for the import
 130       operation (as in that case we know the total size on disk). If a socket or pipe is specified, progress information is not
 131       available. The file descriptor argument is followed by a local name for the image. This should be a
 132       name suitable as a hostname and will be used to name the imported image below
 133       <filename>/var/lib/machines</filename>. A tar import is placed as a directory tree or a
 134       <citerefentry project="man-pages"><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 135       subvolume below <filename>/var/lib/machines/</filename> under the specified name with no suffix
 136       appended. A raw import is placed as a file in <filename>/var/lib/machines/</filename> with the
 137       <filename>.raw</filename> suffix appended. If the <option>force</option> argument is true, any
 138       pre-existing image with the same name is removed before starting the operation. Otherwise, the
 139       operation fails if an image with the same name already exists. Finally, the
 140       <option>read_only</option> argument controls
 141       whether to create a writable or read-only image. Both methods return immediately after starting the import,
 142       with the import transfer ongoing. They return a pair of transfer identifier and object path, which may
 143       be used to retrieve progress information about the transfer or to cancel it. The transfer identifier is a
 144       simple numeric identifier, the object path references an
 145       <interfacename>org.freedesktop.import1.Transfer</interfacename> object, see below. Listen for a
 146       <function>TransferRemoved</function> signal for the transfer ID in order to detect when a transfer is
 147       complete. The returned transfer object is useful to determine the current progress or log output of the
 148       ongoing import operation.</para>
 149
 150       <para><function>ExportTar()</function> and <function>ExportRaw()</function> implement the reverse
 151       operation, and may be used to export a system image in order to place it in a tar or raw image. They
 152       take the machine name to export as their first parameter, followed by a file descriptor (opened for writing)
 153       where the tar or raw file will be written. It may either reference a file on disk or a pipe/socket. The
 154       third argument specifies in which compression format to write the image. It takes one of
 155       <literal>uncompressed</literal>, <literal>xz</literal>, <literal>bzip2</literal> or
 156       <literal>gzip</literal>, depending on which compression scheme is required. The image written to the
 157       specified file descriptor will be a tar file in case of <function>ExportTar()</function> or a raw disk
 158       image in case of <function>ExportRaw()</function>. Note that currently raw disk images may not be
 159       exported as tar files, and vice versa. This restriction might be lifted eventually. The method
 160       returns a transfer identifier and object path for cancelling or tracking the export operation, similar
 161       to <function>ImportTar()</function> or <function>ImportRaw()</function> as described above.</para>
 162
 163       <para><function>PullTar()</function> and <function>PullRaw()</function> may be used to download, verify
 164       and import a system image from a URL. They take an URL argument which should point to a tar or
 165       raw file on the <literal>http://</literal> or <literal>https://</literal> protocols, possibly
 166       compressed with xz, bzip2 or gzip. The second argument is a local name for the image. It should be
 167       suitable as a hostname, similar to the matching argument of the <function>ImportTar()</function> and
 168       <function>ImportRaw()</function> methods above. The third argument indicates the verification mode for
 169       the image. It may be one of <literal>no</literal>, <literal>checksum</literal>,
 170       <literal>signature</literal>. <literal>no</literal> turns off any kind of verification of the image;
 171       <literal>checksum</literal> looks for a <filename>SHA256SUM</filename> file next to the downloaded
 172       image and verifies any SHA256 hash value in that file against the image; <literal>signature</literal>
 173       does the same but also tries to authenticate the <filename>SHA256SUM</filename> file via
 174       <citerefentry project="man-pages"><refentrytitle>gpg</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 175       first. The last argument indicates whether to replace a possibly pre-existing image with the same local
 176       name (if <literal>true</literal>), or whether to fail (if <literal>false</literal>). Like the import
 177       and export calls above, these calls return a pair of transfer identifier and object path for the ongoing
 178       download.</para>
 179
 180       <para><function>ListTransfers()</function> returns a list of ongoing import, export or download
 181       operations as created with the six calls described above. It returns an array of structures which
 182       consist of the numeric transfer identifier, a string indicating the operation (one of
 183       <literal>import-tar</literal>, <literal>import-raw</literal>, <literal>export-tar</literal>,
 184       <literal>export-raw</literal>, <literal>pull-tar</literal> or <literal>pull-raw</literal>), a string
 185       describing the remote file (in case of download operations this is the source URL, in case of
 186       import/export operations this is a short string describing the file descriptor passed in), a string
 187       with the local machine image name, a progress value between 0.0 (for 0%) and 1.0 (for 100%), as well as
 188       the transfer object path.</para>
 189
 190       <para><function>CancelTransfer()</function> may be used to cancel an ongoing import, export or download
 191       operation. Simply specify the transfer identifier to cancel the ongoing operation.</para>
 192     </refsect2>
 193
 194     <refsect2>
 195       <title>Signals</title>
 196
 197       <para>The <function>TransferNew</function> signal is generated each time a new transfer is started with
 198       the import, export or download calls described above. It carries the transfer ID and object path that
 199       have just been created.</para>
 200
 201       <para>The <function>TransferRemoved</function> signal is sent each time a transfer finishes,
 202       is canceled or fails. It also carries the transfer ID and object path, followed by a string indicating
 203       the result of the operation, which is one of <literal>done</literal> (on success),
 204       <literal>canceled</literal> or <literal>failed</literal>.</para>
 205     </refsect2>
 206   </refsect1>
 207
 208   <refsect1>
 209     <title>The Transfer Object</title>
 210
 211     <programlisting>
 212 $ gdbus introspect --system \
 213         --dest org.freedesktop.import1 \
 214         --object-path /org/freedesktop/import1/transfer/_1
 215
 216 node /org/freedesktop/import1/transfer/_1 {
 217   interface org.freedesktop.import1.Transfer {
 218     methods:
 219       Cancel();
 220     signals:
 221       LogMessage(u priority,
 222                  s line);
 223     properties:
 224       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 225       readonly u Id = ...;
 226       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 227       readonly s Local = '...';
 228       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 229       readonly s Remote = '...';
 230       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 231       readonly s Type = '...';
 232       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 233       readonly s Verify = '...';
 234       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 235       readonly d Progress = ...;
 236   };
 237   interface org.freedesktop.DBus.Peer { ... };
 238   interface org.freedesktop.DBus.Introspectable { ... };
 239   interface org.freedesktop.DBus.Properties { ... };
 240 };
 241     </programlisting>
 242
 243     <!--signal LogMessage is not documented!-->
 244
 245     <refsect2>
 246       <title>Methods</title>
 247
 248       <para>The <function>Cancel()</function> method may be used to cancel the transfer. It takes no
 249       parameters. This method is pretty much equivalent to the <function>CancelTransfer()</function> method
 250       on the <structname>Manager</structname> interface (see above), but is exposed on the
 251       <structname>Transfer</structname> object itself instead of taking a transfer ID.</para>
 252     </refsect2>
 253
 254     <refsect2>
 255       <title>Properties</title>
 256
 257       <para>The <varname>Id</varname> property exposes the numeric transfer ID of the transfer object.</para>
 258
 259       <para>The <varname>Local</varname>, <varname>Remote</varname> and <varname>Type</varname> properties
 260       expose the local container name of this transfer, the remote source (in case of download: the URL, in
 261       case of import/export: a string describing the file descriptor passed in), and the type of operation
 262       (see the Manager's <function>ListTransfer()</function> method above for an explanation of the possible
 263       values).</para>
 264
 265       <para>The <varname>Verify</varname> property exposes the selected verification setting and is only
 266       defined for download operations (see above).</para>
 267
 268       <para>The <varname>Progress</varname> property exposes the current progress of the transfer as a value
 269       between 0.0 and 1.0. To show a progress bar on screen we recommend to query this value in regular
 270       intervals, for example every 500 ms or so.</para>
 271     </refsect2>
 272   </refsect1>
 273
 274   <refsect1>
 275     <title>Versioning</title>
 276
 277     <para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
 278     the usual interface versioning guidelines</ulink>.</para>
 279   </refsect1>
 280 </refentry>