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</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 executable="systemd-importd" node="/org/freedesktop/import1" interface="org.freedesktop.import1.Manager">
  50 node /org/freedesktop/import1 {
  51   interface org.freedesktop.import1.Manager {
  52     methods:
  53       ImportTar(in  h fd,
  54                 in  s local_name,
  55                 in  b force,
  56                 in  b read_only,
  57                 out u transfer_id,
  58                 out o transfer_path);
  59       ImportRaw(in  h fd,
  60                 in  s local_name,
  61                 in  b force,
  62                 in  b read_only,
  63                 out u transfer_id,
  64                 out o transfer_path);
  65       ImportFileSystem(in  h fd,
  66                        in  s local_name,
  67                        in  b force,
  68                        in  b read_only,
  69                        out u transfer_id,
  70                        out o transfer_path);
  71       ExportTar(in  s local_name,
  72                 in  h fd,
  73                 in  s format,
  74                 out u transfer_id,
  75                 out o transfer_path);
  76       ExportRaw(in  s local_name,
  77                 in  h fd,
  78                 in  s format,
  79                 out u transfer_id,
  80                 out o transfer_path);
  81       PullTar(in  s url,
  82               in  s local_name,
  83               in  s verify_mode,
  84               in  b force,
  85               out u transfer_id,
  86               out o transfer_path);
  87       PullRaw(in  s url,
  88               in  s local_name,
  89               in  s verify_mode,
  90               in  b force,
  91               out u transfer_id,
  92               out o transfer_path);
  93       ListTransfers(out a(usssdo) transfers);
  94       CancelTransfer(in  u transfer_id);
  95     signals:
  96       TransferNew(u transfer_id,
  97                   o transfer_path);
  98       TransferRemoved(u transfer_id,
  99                       o transfer_path,
 100                       s result);
 101   };
 102   interface org.freedesktop.DBus.Peer { ... };
 103   interface org.freedesktop.DBus.Introspectable { ... };
 104   interface org.freedesktop.DBus.Properties { ... };
 105 };
 106     </programlisting>
 107
 108     <!--method ImportFileSystem is not documented!-->
 109
 110     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 111
 112     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.import1.Manager"/>
 113
 114     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.import1.Manager"/>
 115
 116     <variablelist class="dbus-method" generated="True" extra-ref="ImportTar()"/>
 117
 118     <variablelist class="dbus-method" generated="True" extra-ref="ImportRaw()"/>
 119
 120     <variablelist class="dbus-method" generated="True" extra-ref="ImportFileSystem()"/>
 121
 122     <variablelist class="dbus-method" generated="True" extra-ref="ExportTar()"/>
 123
 124     <variablelist class="dbus-method" generated="True" extra-ref="ExportRaw()"/>
 125
 126     <variablelist class="dbus-method" generated="True" extra-ref="PullTar()"/>
 127
 128     <variablelist class="dbus-method" generated="True" extra-ref="PullRaw()"/>
 129
 130     <variablelist class="dbus-method" generated="True" extra-ref="ListTransfers()"/>
 131
 132     <variablelist class="dbus-method" generated="True" extra-ref="CancelTransfer()"/>
 133
 134     <variablelist class="dbus-signal" generated="True" extra-ref="TransferNew"/>
 135
 136     <variablelist class="dbus-signal" generated="True" extra-ref="TransferRemoved"/>
 137
 138     <!--End of Autogenerated section-->
 139
 140     <refsect2>
 141       <title>Methods</title>
 142
 143       <para><function>ImportTar()</function> and <function>ImportRaw()</function> import a system image and
 144       place it into <filename>/var/lib/machines/</filename>. The first argument should be a file descriptor
 145       (opened for reading) referring to the tar or raw file to import. It should reference a file on disk,
 146       a pipe or a socket. When <function>ImportTar()</function> is used the file descriptor should
 147       refer to a tar file, optionally compressed with
 148       <citerefentry project="die-net"><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 149       <citerefentry project="die-net"><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 150       or
 151       <citerefentry project="die-net"><refentrytitle>xz</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 152       <command>systemd-importd</command> will detect the used compression scheme (if any) automatically. When
 153       <function>ImportRaw()</function> is used the file descriptor should refer to a raw or qcow2 disk image
 154       containing an MBR or GPT disk label, also optionally compressed with gzip, bzip2 or xz. In either case,
 155       if the file is specified as a file descriptor on disk, progress information is generated for the import
 156       operation (as in that case we know the total size on disk). If a socket or pipe is specified, progress information is not
 157       available. The file descriptor argument is followed by a local name for the image. This should be a
 158       name suitable as a hostname and will be used to name the imported image below
 159       <filename>/var/lib/machines</filename>. A tar import is placed as a directory tree or a
 160       <citerefentry project="man-pages"><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 161       subvolume below <filename>/var/lib/machines/</filename> under the specified name with no suffix
 162       appended. A raw import is placed as a file in <filename>/var/lib/machines/</filename> with the
 163       <filename>.raw</filename> suffix appended. If the <option>force</option> argument is true, any
 164       pre-existing image with the same name is removed before starting the operation. Otherwise, the
 165       operation fails if an image with the same name already exists. Finally, the
 166       <option>read_only</option> argument controls
 167       whether to create a writable or read-only image. Both methods return immediately after starting the import,
 168       with the import transfer ongoing. They return a pair of transfer identifier and object path, which may
 169       be used to retrieve progress information about the transfer or to cancel it. The transfer identifier is a
 170       simple numeric identifier, the object path references an
 171       <interfacename>org.freedesktop.import1.Transfer</interfacename> object, see below. Listen for a
 172       <function>TransferRemoved</function> signal for the transfer ID in order to detect when a transfer is
 173       complete. The returned transfer object is useful to determine the current progress or log output of the
 174       ongoing import operation.</para>
 175
 176       <para><function>ExportTar()</function> and <function>ExportRaw()</function> implement the reverse
 177       operation, and may be used to export a system image in order to place it in a tar or raw image. They
 178       take the machine name to export as their first parameter, followed by a file descriptor (opened for writing)
 179       where the tar or raw file will be written. It may either reference a file on disk or a pipe/socket. The
 180       third argument specifies in which compression format to write the image. It takes one of
 181       <literal>uncompressed</literal>, <literal>xz</literal>, <literal>bzip2</literal> or
 182       <literal>gzip</literal>, depending on which compression scheme is required. The image written to the
 183       specified file descriptor will be a tar file in case of <function>ExportTar()</function> or a raw disk
 184       image in case of <function>ExportRaw()</function>. Note that currently raw disk images may not be
 185       exported as tar files, and vice versa. This restriction might be lifted eventually. The method
 186       returns a transfer identifier and object path for cancelling or tracking the export operation, similar
 187       to <function>ImportTar()</function> or <function>ImportRaw()</function> as described above.</para>
 188
 189       <para><function>PullTar()</function> and <function>PullRaw()</function> may be used to download, verify
 190       and import a system image from a URL. They take an URL argument which should point to a tar or
 191       raw file on the <literal>http://</literal> or <literal>https://</literal> protocols, possibly
 192       compressed with xz, bzip2 or gzip. The second argument is a local name for the image. It should be
 193       suitable as a hostname, similar to the matching argument of the <function>ImportTar()</function> and
 194       <function>ImportRaw()</function> methods above. The third argument indicates the verification mode for
 195       the image. It may be one of <literal>no</literal>, <literal>checksum</literal>,
 196       <literal>signature</literal>. <literal>no</literal> turns off any kind of verification of the image;
 197       <literal>checksum</literal> looks for a <filename>SHA256SUM</filename> file next to the downloaded
 198       image and verifies any SHA256 hash value in that file against the image; <literal>signature</literal>
 199       does the same but also tries to authenticate the <filename>SHA256SUM</filename> file via
 200       <citerefentry project="man-pages"><refentrytitle>gpg</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 201       first. The last argument indicates whether to replace a possibly pre-existing image with the same local
 202       name (if <literal>true</literal>), or whether to fail (if <literal>false</literal>). Like the import
 203       and export calls above, these calls return a pair of transfer identifier and object path for the ongoing
 204       download.</para>
 205
 206       <para><function>ListTransfers()</function> returns a list of ongoing import, export or download
 207       operations as created with the six calls described above. It returns an array of structures which
 208       consist of the numeric transfer identifier, a string indicating the operation (one of
 209       <literal>import-tar</literal>, <literal>import-raw</literal>, <literal>export-tar</literal>,
 210       <literal>export-raw</literal>, <literal>pull-tar</literal> or <literal>pull-raw</literal>), a string
 211       describing the remote file (in case of download operations this is the source URL, in case of
 212       import/export operations this is a short string describing the file descriptor passed in), a string
 213       with the local machine image name, a progress value between 0.0 (for 0%) and 1.0 (for 100%), as well as
 214       the transfer object path.</para>
 215
 216       <para><function>CancelTransfer()</function> may be used to cancel an ongoing import, export or download
 217       operation. Simply specify the transfer identifier to cancel the ongoing operation.</para>
 218     </refsect2>
 219
 220     <refsect2>
 221       <title>Signals</title>
 222
 223       <para>The <function>TransferNew</function> signal is generated each time a new transfer is started with
 224       the import, export or download calls described above. It carries the transfer ID and object path that
 225       have just been created.</para>
 226
 227       <para>The <function>TransferRemoved</function> signal is sent each time a transfer finishes,
 228       is canceled or fails. It also carries the transfer ID and object path, followed by a string indicating
 229       the result of the operation, which is one of <literal>done</literal> (on success),
 230       <literal>canceled</literal> or <literal>failed</literal>.</para>
 231     </refsect2>
 232   </refsect1>
 233
 234   <refsect1>
 235     <title>The Transfer Object</title>
 236
 237     <programlisting executable="systemd-importd" node="/org/freedesktop/import1/transfer/_1" interface="org.freedesktop.import1.Transfer">
 238 node /org/freedesktop/import1/transfer/_1 {
 239   interface org.freedesktop.import1.Transfer {
 240     methods:
 241       Cancel();
 242     signals:
 243       LogMessage(u priority,
 244                  s line);
 245     properties:
 246       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 247       readonly u Id = ...;
 248       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 249       readonly s Local = '...';
 250       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 251       readonly s Remote = '...';
 252       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 253       readonly s Type = '...';
 254       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 255       readonly s Verify = '...';
 256       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 257       readonly d Progress = ...;
 258   };
 259   interface org.freedesktop.DBus.Peer { ... };
 260   interface org.freedesktop.DBus.Introspectable { ... };
 261   interface org.freedesktop.DBus.Properties { ... };
 262 };
 263     </programlisting>
 264
 265     <!--signal LogMessage is not documented!-->
 266
 267     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 268
 269     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.import1.Transfer"/>
 270
 271     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.import1.Transfer"/>
 272
 273     <variablelist class="dbus-method" generated="True" extra-ref="Cancel()"/>
 274
 275     <variablelist class="dbus-signal" generated="True" extra-ref="LogMessage"/>
 276
 277     <variablelist class="dbus-property" generated="True" extra-ref="Id"/>
 278
 279     <variablelist class="dbus-property" generated="True" extra-ref="Local"/>
 280
 281     <variablelist class="dbus-property" generated="True" extra-ref="Remote"/>
 282
 283     <variablelist class="dbus-property" generated="True" extra-ref="Type"/>
 284
 285     <variablelist class="dbus-property" generated="True" extra-ref="Verify"/>
 286
 287     <variablelist class="dbus-property" generated="True" extra-ref="Progress"/>
 288
 289     <!--End of Autogenerated section-->
 290
 291     <refsect2>
 292       <title>Methods</title>
 293
 294       <para>The <function>Cancel()</function> method may be used to cancel the transfer. It takes no
 295       parameters. This method is pretty much equivalent to the <function>CancelTransfer()</function> method
 296       on the <structname>Manager</structname> interface (see above), but is exposed on the
 297       <structname>Transfer</structname> object itself instead of taking a transfer ID.</para>
 298     </refsect2>
 299
 300     <refsect2>
 301       <title>Properties</title>
 302
 303       <para>The <varname>Id</varname> property exposes the numeric transfer ID of the transfer object.</para>
 304
 305       <para>The <varname>Local</varname>, <varname>Remote</varname> and <varname>Type</varname> properties
 306       expose the local container name of this transfer, the remote source (in case of download: the URL, in
 307       case of import/export: a string describing the file descriptor passed in), and the type of operation
 308       (see the Manager's <function>ListTransfer()</function> method above for an explanation of the possible
 309       values).</para>
 310
 311       <para>The <varname>Verify</varname> property exposes the selected verification setting and is only
 312       defined for download operations (see above).</para>
 313
 314       <para>The <varname>Progress</varname> property exposes the current progress of the transfer as a value
 315       between 0.0 and 1.0. To show a progress bar on screen we recommend to query this value in regular
 316       intervals, for example every 500 ms or so.</para>
 317     </refsect2>
 318   </refsect1>
 319
 320   <refsect1>
 321     <title>Examples</title>
 322
 323     <example>
 324       <title>Introspect <interfacename>org.freedesktop.import1.Manager</interfacename> on the bus</title>
 325
 326       <programlisting>$ gdbus introspect --system \
 327   --dest org.freedesktop.import1 \
 328   --object-path /org/freedesktop/import1
 329       </programlisting>
 330     </example>
 331
 332     <example>
 333       <title>Introspect <interfacename>org.freedesktop.import1.Transfer</interfacename> on the bus</title>
 334
 335       <programlisting>$ gdbus introspect --system \
 336   --dest org.freedesktop.import1 \
 337   --object-path /org/freedesktop/import1/transfer/_1
 338       </programlisting>
 339     </example>
 340   </refsect1>
 341
 342   <refsect1>
 343     <title>Versioning</title>
 344
 345     <para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
 346     the usual interface versioning guidelines</ulink>.</para>
 347   </refsect1>
 348 </refentry>