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.5/docbookx.dtd" >
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   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 disk images. These images can be
  29     used by tools such as
  30     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> to run
  31     local containers. The service is used as the backend for <command>importctl pull-raw</command>,
  32     <command>importctl 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       ImportTarEx(in  h fd,
  60                   in  s local_name,
  61                   in  s class,
  62                   in  t flags,
  63                   out u transfer_id,
  64                   out o transfer_path);
  65       ImportRaw(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       ImportRawEx(in  h fd,
  72                   in  s local_name,
  73                   in  s class,
  74                   in  t flags,
  75                   out u transfer_id,
  76                   out o transfer_path);
  77       ImportFileSystem(in  h fd,
  78                        in  s local_name,
  79                        in  b force,
  80                        in  b read_only,
  81                        out u transfer_id,
  82                        out o transfer_path);
  83       ImportFileSystemEx(in  h fd,
  84                          in  s local_name,
  85                          in  s class,
  86                          in  t flags,
  87                          out u transfer_id,
  88                          out o transfer_path);
  89       ExportTar(in  s local_name,
  90                 in  h fd,
  91                 in  s format,
  92                 out u transfer_id,
  93                 out o transfer_path);
  94       ExportTarEx(in  s local_name,
  95                   in  s class,
  96                   in  h fd,
  97                   in  s format,
  98                   in  t flags,
  99                   out u transfer_id,
 100                   out o transfer_path);
 101       ExportRaw(in  s local_name,
 102                 in  h fd,
 103                 in  s format,
 104                 out u transfer_id,
 105                 out o transfer_path);
 106       ExportRawEx(in  s local_name,
 107                   in  s class,
 108                   in  h fd,
 109                   in  s format,
 110                   in  t flags,
 111                   out u transfer_id,
 112                   out o transfer_path);
 113       PullTar(in  s url,
 114               in  s local_name,
 115               in  s verify_mode,
 116               in  b force,
 117               out u transfer_id,
 118               out o transfer_path);
 119       PullTarEx(in  s url,
 120                 in  s local_name,
 121                 in  s class,
 122                 in  s verify_mode,
 123                 in  t flags,
 124                 out u transfer_id,
 125                 out o transfer_path);
 126       PullRaw(in  s url,
 127               in  s local_name,
 128               in  s verify_mode,
 129               in  b force,
 130               out u transfer_id,
 131               out o transfer_path);
 132       PullRawEx(in  s url,
 133                 in  s local_name,
 134                 in  s class,
 135                 in  s verify_mode,
 136                 in  t flags,
 137                 out u transfer_id,
 138                 out o transfer_path);
 139       ListTransfers(out a(usssdo) transfers);
 140       ListTransfersEx(in  s class,
 141                       in  t flags,
 142                       out a(ussssdo) transfers);
 143       CancelTransfer(in  u transfer_id);
 144       ListImages(in  s class,
 145                  in  t flags,
 146                  out a(ssssbtttttt) images);
 147     signals:
 148       TransferNew(u transfer_id,
 149                   o transfer_path);
 150       TransferRemoved(u transfer_id,
 151                       o transfer_path,
 152                       s result);
 153   };
 154   interface org.freedesktop.DBus.Peer { ... };
 155   interface org.freedesktop.DBus.Introspectable { ... };
 156   interface org.freedesktop.DBus.Properties { ... };
 157 };
 158     </programlisting>
 159
 160     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 161
 162     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.import1.Manager"/>
 163
 164     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.import1.Manager"/>
 165
 166     <variablelist class="dbus-method" generated="True" extra-ref="ImportTar()"/>
 167
 168     <variablelist class="dbus-method" generated="True" extra-ref="ImportTarEx()"/>
 169
 170     <variablelist class="dbus-method" generated="True" extra-ref="ImportRaw()"/>
 171
 172     <variablelist class="dbus-method" generated="True" extra-ref="ImportRawEx()"/>
 173
 174     <variablelist class="dbus-method" generated="True" extra-ref="ImportFileSystem()"/>
 175
 176     <variablelist class="dbus-method" generated="True" extra-ref="ImportFileSystemEx()"/>
 177
 178     <variablelist class="dbus-method" generated="True" extra-ref="ExportTar()"/>
 179
 180     <variablelist class="dbus-method" generated="True" extra-ref="ExportTarEx()"/>
 181
 182     <variablelist class="dbus-method" generated="True" extra-ref="ExportRaw()"/>
 183
 184     <variablelist class="dbus-method" generated="True" extra-ref="ExportRawEx()"/>
 185
 186     <variablelist class="dbus-method" generated="True" extra-ref="PullTar()"/>
 187
 188     <variablelist class="dbus-method" generated="True" extra-ref="PullTarEx()"/>
 189
 190     <variablelist class="dbus-method" generated="True" extra-ref="PullRaw()"/>
 191
 192     <variablelist class="dbus-method" generated="True" extra-ref="PullRawEx()"/>
 193
 194     <variablelist class="dbus-method" generated="True" extra-ref="ListTransfers()"/>
 195
 196     <variablelist class="dbus-method" generated="True" extra-ref="ListTransfersEx()"/>
 197
 198     <variablelist class="dbus-method" generated="True" extra-ref="CancelTransfer()"/>
 199
 200     <variablelist class="dbus-method" generated="True" extra-ref="ListImages()"/>
 201
 202     <variablelist class="dbus-signal" generated="True" extra-ref="TransferNew()"/>
 203
 204     <variablelist class="dbus-signal" generated="True" extra-ref="TransferRemoved()"/>
 205
 206     <!--End of Autogenerated section-->
 207
 208     <refsect2>
 209       <title>Methods</title>
 210
 211       <para><function>ImportTar()</function>/<function>ImportTarEx()</function> and
 212       <function>ImportRaw()</function>/<function>ImportRawEx()</function> import a disk image and place it
 213       into the image directory. The first argument should be a file descriptor (opened for reading) referring
 214       to the tar or raw file to import. It should reference a file on disk, a pipe or a socket. When
 215       <function>ImportTar()</function>/<function>ImportTarEx()</function> is used the file descriptor should
 216       refer to a tar file, optionally compressed with <citerefentry project="die-net"><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 217       <citerefentry project="die-net"><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry>, or
 218       <citerefentry project="die-net"><refentrytitle>xz</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 219       <command>systemd-importd</command> will detect the used compression scheme (if any) automatically. When
 220       <function>ImportRaw()</function>/<function>ImportRawEx()</function> is used the file descriptor should
 221       refer to a raw or qcow2 disk image containing an MBR or GPT disk label, also optionally compressed with
 222       gzip, bzip2 or xz. In either case, if the file is specified as a file descriptor on disk, progress
 223       information is generated for the import operation (as in that case we know the total size on disk). If
 224       a socket or pipe is specified, progress information is not available. The file descriptor argument is
 225       followed by a local name for the image. This should be a name suitable as a hostname and will be used
 226       to name the imported image below <filename>/var/lib/machines/</filename>. A tar import is placed as a
 227       directory tree or a <citerefentry project="url"><refentrytitle url="https://btrfs.readthedocs.io/en/latest/btrfs.html">btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 228       subvolume below the image directory under the specified name with no suffix appended. A raw import is
 229       placed as a file in the image directory with the <filename>.raw</filename> suffix appended. In case of
 230       <function>ImportTar()</function>/<function>ImportRaw()</function>, if the <option>force</option>
 231       argument is true, any pre-existing image with the same name is removed before starting the
 232       operation. Otherwise, the operation fails if an image with the same name already exists. The
 233       <option>read_only</option> argument controls whether to create a writable or read-only image. In case
 234       of <function>ImportTarEx()</function>/<function>ImportRawEx()</function> these boolean flags are
 235       provided via a 64bit flags parameter instead, with bit 0 mapping to the <option>force</option>
 236       parameter, and bit 1 mapping to <option>read_only</option>. The <option>class</option> parameter
 237       specifies the image class, and takes one of <literal>machine</literal>, <literal>portable</literal>,
 238       <literal>sysext</literal>, <literal>confext</literal>. All four methods return immediately after
 239       starting the import, with the import transfer ongoing. They return a pair of transfer identifier and
 240       object path, which may be used to retrieve progress information about the transfer or to cancel it. The
 241       transfer identifier is a simple numeric identifier, the object path references an
 242       <interfacename>org.freedesktop.import1.Transfer</interfacename> object, see below. Listen for a
 243       <function>TransferRemoved()</function> signal for the transfer ID in order to detect when a transfer is
 244       complete. The returned transfer object is useful to determine the current progress or log output of the
 245       ongoing import operation.</para>
 246
 247       <para><function>ExportTar()</function>/<function>ExportTarEx()</function> and
 248       <function>ExportRaw()</function>/<function>ExportRaw()</function> implement the reverse operation, and
 249       may be used to export a system image in order to place it in a tar or raw image. They take the machine
 250       name to export as their first parameter, followed by a file descriptor (opened for writing) where the
 251       tar or raw file will be written. It may either reference a file on disk or a pipe/socket. The third
 252       argument specifies in which compression format to write the image. It takes one of
 253       <literal>uncompressed</literal>, <literal>xz</literal>, <literal>bzip2</literal> or
 254       <literal>gzip</literal>, depending on which compression scheme is required. The image written to the
 255       specified file descriptor will be a tar file in case of
 256       <function>ExportTar()</function>/<function>ExportTarEx()</function> or a raw disk image in case of
 257       <function>ExportRaw()</function>/<function>ExportRawEx()</function>. Note that currently raw disk
 258       images may not be exported as tar files, and vice versa. This restriction might be lifted
 259       eventually. The method returns a transfer identifier and object path for cancelling or tracking the
 260       export operation, similarly to <function>ImportTar()</function>/<function>ImportTarEx()</function> or
 261       <function>ImportRaw()</function>/<function>ImportRawEx()</function> as described
 262       above. <function>ExportTarEx()</function>/<function>ExportRawEx()</function> expect the image class as
 263       additional parameter, as well as a 64bit flags parameter that currently must be specified as
 264       zero.</para>
 265
 266       <para><function>PullTar()</function>/<function>PullTarEx()</function> and
 267       <function>PullRaw()</function>/<function>PullRawEx()</function> may be used to download, verify and
 268       import a system image from a URL. They take a URL argument which should point to a tar or raw file on
 269       the <literal>http://</literal> or <literal>https://</literal> protocols, possibly compressed with xz,
 270       bzip2 or gzip. The second argument is a local name for the image. It should be suitable as a hostname,
 271       similarly to the matching argument of the
 272       <function>ImportTar()</function>/<function>ImportTarEx()</function> and
 273       <function>ImportRaw()</function>/<function>ImportRawEx()</function> methods above. The third argument
 274       indicates the verification mode for the image. It may be one of <literal>no</literal>,
 275       <literal>checksum</literal>, <literal>signature</literal>. <literal>no</literal> turns off any kind of
 276       verification of the image; <literal>checksum</literal> looks for a <filename>SHA256SUM</filename> file
 277       next to the downloaded image and verifies any SHA256 hash value in that file against the image;
 278       <literal>signature</literal> does the same but also tries to authenticate the
 279       <filename>SHA256SUM</filename> file via <citerefentry project="man-pages"><refentrytitle>gpg</refentrytitle><manvolnum>8</manvolnum></citerefentry> first. In
 280       case of <function>PullTar()</function>/<function>PullRaw()</function> the last argument indicates
 281       whether to replace a possibly pre-existing image with the same local name (if <literal>true</literal>),
 282       or whether to fail (if <literal>false</literal>). In case of
 283       <function>PullTarEx()</function>/<function>PullRawEx()</function> the last argument is a 64bit flags
 284       parameter, where bit 0 controls the <literal>force</literal> flag, bit 1 is a
 285       <literal>read_only</literal> flag that controls whether the created image shall be marked read-only,
 286       and bit 2 is a <literal>keep_download</literal> flag that indicates whether a pristine, read-only copy
 287       of the downloaded image shell be kept, in addition for the local copy of the image. The
 288       <function>…_Ex()</function> variants also expect an image class string (as above). Like the import and
 289       export calls above, these calls return a pair of transfer identifier and object path for the ongoing
 290       download.</para>
 291
 292       <para><function>ImportFileSystem()</function>/<function>ImportFileSystemEx()</function> are similar to
 293       <function>ImportTar()</function>/<function>ImportTarEx()</function> but import a directory tree. The
 294       first argument must refer to a directory file descriptor for the source hierarchy to import.</para>
 295
 296       <para><function>ListTransfers()</function>/<function>ListTransfersEx()</function> return a list of
 297       ongoing import, export or download operations as created with the six calls described above. They
 298       return an array of structures which consist of the numeric transfer identifier, a string indicating the
 299       operation (one of <literal>import-tar</literal>, <literal>import-raw</literal>,
 300       <literal>export-tar</literal>, <literal>export-raw</literal>, <literal>pull-tar</literal> or
 301       <literal>pull-raw</literal>), a string describing the remote file (in case of download operations this
 302       is the source URL, in case of import/export operations this is a short string describing the file
 303       descriptor passed in), a string with the local machine image name, the image class (only in case of
 304       <function>ListTransfersEx()</function>; one of <literal>machine</literal>, <literal>portable</literal>,
 305       <literal>sysext</literal>, <literal>confext</literal>), a progress value between 0.0 (for 0%) and 1.0
 306       (for 100%), as well as the transfer object path.</para>
 307
 308       <para><function>CancelTransfer()</function> may be used to cancel an ongoing import, export or download
 309       operation. Simply specify the transfer identifier to cancel the ongoing operation.</para>
 310
 311       <para><function>ListImages()</function> returns a list of currently installed images. It takes a image
 312       class string and a flags parameter. The image class is either the empty string or specifies one of the
 313       four image classes, by which it will then filter. The flags parameter must be zero at this time. It
 314       returns an array of items, each describing one image. The item fields are in order: the image class,
 315       the local image name, the image type, the image path, the read-only flag, the creation and modification
 316       times (in microseconds since the UNIX epoch), as well as the current disk usage in bytes (both overall,
 317       and exclusive), as well as any size limit in bytes set on the image (both overall and
 318       exclusive).</para>
 319     </refsect2>
 320
 321     <refsect2>
 322       <title>Signals</title>
 323
 324       <para>The <function>TransferNew()</function> signal is generated each time a new transfer is started with
 325       the import, export or download calls described above. It carries the transfer ID and object path that
 326       have just been created.</para>
 327
 328       <para>The <function>TransferRemoved()</function> signal is sent each time a transfer finishes,
 329       is canceled or fails. It also carries the transfer ID and object path, followed by a string indicating
 330       the result of the operation, which is one of <literal>done</literal> (on success),
 331       <literal>canceled</literal> or <literal>failed</literal>.</para>
 332     </refsect2>
 333   </refsect1>
 334
 335   <refsect1>
 336     <title>The Transfer Object</title>
 337
 338     <programlisting executable="systemd-importd" node="/org/freedesktop/import1/transfer/_1" interface="org.freedesktop.import1.Transfer">
 339 node /org/freedesktop/import1/transfer/_1 {
 340   interface org.freedesktop.import1.Transfer {
 341     methods:
 342       Cancel();
 343     signals:
 344       LogMessage(u priority,
 345                  s line);
 346       ProgressUpdate(d progress);
 347     properties:
 348       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 349       readonly u Id = ...;
 350       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 351       readonly s Local = '...';
 352       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 353       readonly s Remote = '...';
 354       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 355       readonly s Type = '...';
 356       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 357       readonly s Verify = '...';
 358       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 359       readonly d Progress = ...;
 360   };
 361   interface org.freedesktop.DBus.Peer { ... };
 362   interface org.freedesktop.DBus.Introspectable { ... };
 363   interface org.freedesktop.DBus.Properties { ... };
 364 };
 365     </programlisting>
 366
 367     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 368
 369     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.import1.Transfer"/>
 370
 371     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.import1.Transfer"/>
 372
 373     <variablelist class="dbus-method" generated="True" extra-ref="Cancel()"/>
 374
 375     <variablelist class="dbus-signal" generated="True" extra-ref="LogMessage()"/>
 376
 377     <variablelist class="dbus-signal" generated="True" extra-ref="ProgressUpdate()"/>
 378
 379     <variablelist class="dbus-property" generated="True" extra-ref="Id"/>
 380
 381     <variablelist class="dbus-property" generated="True" extra-ref="Local"/>
 382
 383     <variablelist class="dbus-property" generated="True" extra-ref="Remote"/>
 384
 385     <variablelist class="dbus-property" generated="True" extra-ref="Type"/>
 386
 387     <variablelist class="dbus-property" generated="True" extra-ref="Verify"/>
 388
 389     <variablelist class="dbus-property" generated="True" extra-ref="Progress"/>
 390
 391     <!--End of Autogenerated section-->
 392
 393     <refsect2>
 394       <title>Methods</title>
 395
 396       <para>The <function>Cancel()</function> method may be used to cancel the transfer. It takes no
 397       parameters. This method is pretty much equivalent to the <function>CancelTransfer()</function> method
 398       on the <structname>Manager</structname> interface (see above), but is exposed on the
 399       <structname>Transfer</structname> object itself instead of taking a transfer ID.</para>
 400     </refsect2>
 401
 402     <refsect2>
 403       <title>Properties</title>
 404
 405       <para>The <varname>Id</varname> property exposes the numeric transfer ID of the transfer object.</para>
 406
 407       <para>The <varname>Local</varname>, <varname>Remote</varname> and <varname>Type</varname> properties
 408       expose the local container name of this transfer, the remote source (in case of download: the URL, in
 409       case of import/export: a string describing the file descriptor passed in), and the type of operation
 410       (see the Manager's <function>ListTransfer()</function> method above for an explanation of the possible
 411       values).</para>
 412
 413       <para>The <varname>Verify</varname> property exposes the selected verification setting and is only
 414       defined for download operations (see above).</para>
 415
 416       <para>The <varname>Progress</varname> property exposes the current progress of the transfer as a value
 417       between 0.0 and 1.0. To show a progress bar on screen we recommend to query this value in regular
 418       intervals, for example every 500 ms or so.</para>
 419     </refsect2>
 420
 421     <refsect2>
 422       <title>Signals</title>
 423
 424       <para>The <function>LogMessage()</function> signal is emitted for log messages generated by a transfer. It
 425       carries a pair of syslog log level integer and log string.</para>
 426
 427       <para>The <function>ProgressUpdate()</function> signal is emitted in regular intervals when new
 428       download progress information is available for a transfer. It carries a double precision floating
 429       pointer number between 0.0 and 1.0 indicating the transfer progress.</para>
 430     </refsect2>
 431   </refsect1>
 432
 433   <refsect1>
 434     <title>Examples</title>
 435
 436     <example>
 437       <title>Introspect <interfacename>org.freedesktop.import1.Manager</interfacename> on the bus</title>
 438
 439       <programlisting>$ gdbus introspect --system \
 440   --dest org.freedesktop.import1 \
 441   --object-path /org/freedesktop/import1
 442       </programlisting>
 443     </example>
 444
 445     <example>
 446       <title>Introspect <interfacename>org.freedesktop.import1.Transfer</interfacename> on the bus</title>
 447
 448       <programlisting>$ gdbus introspect --system \
 449   --dest org.freedesktop.import1 \
 450   --object-path /org/freedesktop/import1/transfer/_1
 451       </programlisting>
 452     </example>
 453   </refsect1>
 454
 455   <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/>
 456   <refsect1>
 457     <title>History</title>
 458     <refsect2>
 459       <title>The Manager Object</title>
 460       <para><function>ImportTarEx()</function>, <function>ImportRawEx()</function>,
 461       <function>ImportFileSystemEx()</function>, <function>ExportTarEx()</function>,
 462       <function>ExportRawEx()</function>, <function>PullTarEx()</function>, <function>PullRawEx()</function>,
 463       <function>ListTransfersEx()</function>, <function>ListImages()</function> were added in version
 464       256.</para>
 465     </refsect2>
 466     <refsect2>
 467       <title>Transfer Objects</title>
 468       <para><function>ProgressUpdate()</function> was added in version 256.</para>
 469     </refsect2>
 470   </refsect1>
 471
 472 </refentry>