summaryrefslogtreecommitdiffstats
path: root/man/org.freedesktop.import1.xml
blob: 9558ee138f8ab70c903d0e181b209693239f68c2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
<?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-or-later -->

<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</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 executable="systemd-importd" node="/org/freedesktop/import1" interface="org.freedesktop.import1.Manager">
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 executable="systemd-importd" node="/org/freedesktop/import1/transfer/_1" interface="org.freedesktop.import1.Transfer">
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>Examples</title>

    <example>
      <title>Introspect <interfacename>org.freedesktop.import1.Manager</interfacename> on the bus</title>

      <programlisting>$ gdbus introspect --system \
  --dest org.freedesktop.import1 \
  --object-path /org/freedesktop/import1
      </programlisting>
    </example>

    <example>
      <title>Introspect <interfacename>org.freedesktop.import1.Transfer</interfacename> on the bus</title>

      <programlisting>$ gdbus introspect --system \
  --dest org.freedesktop.import1 \
  --object-path /org/freedesktop/import1/transfer/_1
      </programlisting>
    </example>
  </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>