]>
Commit | Line | Data |
---|---|---|
2fe60ff1 ZJS |
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> | |
b441a1d4 DDM |
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> | |
2fe60ff1 ZJS |
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>. | |
b441a1d4 | 39 | Many operations to manipulate local container and VM images are hence available via the <command>systemd-machined</command> D-Bus API, c.f. |
2fe60ff1 ZJS |
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 | ||
48f99d7c | 49 | <programlisting executable="systemd-importd" node="/org/freedesktop/import1" interface="org.freedesktop.import1.Manager"> |
2fe60ff1 ZJS |
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); | |
4fb222c4 ZJS |
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); | |
2fe60ff1 ZJS |
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); | |
4fb222c4 | 93 | ListTransfers(out a(usssdo) transfers); |
2fe60ff1 ZJS |
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 | }; | |
4fb222c4 ZJS |
102 | interface org.freedesktop.DBus.Peer { ... }; |
103 | interface org.freedesktop.DBus.Introspectable { ... }; | |
104 | interface org.freedesktop.DBus.Properties { ... }; | |
2fe60ff1 | 105 | }; |
4fb222c4 ZJS |
106 | </programlisting> |
107 | ||
108 | <!--method ImportFileSystem is not documented!--> | |
2fe60ff1 | 109 | |
00bb75d7 ZJS |
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 | ||
2fe60ff1 ZJS |
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 | |
b441a1d4 DDM |
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 | |
2fe60ff1 ZJS |
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, | |
b441a1d4 DDM |
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 | |
2fe60ff1 ZJS |
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 | |
b441a1d4 | 159 | <filename>/var/lib/machines</filename>. A tar import is placed as a directory tree or a |
2fe60ff1 | 160 | <citerefentry project="man-pages"><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
b441a1d4 DDM |
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, | |
2fe60ff1 | 168 | with the import transfer ongoing. They return a pair of transfer identifier and object path, which may |
b441a1d4 | 169 | be used to retrieve progress information about the transfer or to cancel it. The transfer identifier is a |
2fe60ff1 ZJS |
170 | simple numeric identifier, the object path references an |
171 | <interfacename>org.freedesktop.import1.Transfer</interfacename> object, see below. Listen for a | |
b441a1d4 | 172 | <function>TransferRemoved</function> signal for the transfer ID in order to detect when a transfer is |
2fe60ff1 ZJS |
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 | |
b441a1d4 | 178 | take the machine name to export as their first parameter, followed by a file descriptor (opened for writing) |
2fe60ff1 ZJS |
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 | |
89fc6fd3 | 185 | exported as tar files, and vice versa. This restriction might be lifted eventually. The method |
b441a1d4 DDM |
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> | |
2fe60ff1 ZJS |
188 | |
189 | <para><function>PullTar()</function> and <function>PullRaw()</function> may be used to download, verify | |
b441a1d4 | 190 | and import a system image from a URL. They take an URL argument which should point to a tar or |
2fe60ff1 ZJS |
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 | |
b441a1d4 DDM |
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 | |
2fe60ff1 | 195 | the image. It may be one of <literal>no</literal>, <literal>checksum</literal>, |
b441a1d4 | 196 | <literal>signature</literal>. <literal>no</literal> turns off any kind of verification of the image; |
2fe60ff1 | 197 | <literal>checksum</literal> looks for a <filename>SHA256SUM</filename> file next to the downloaded |
b441a1d4 | 198 | image and verifies any SHA256 hash value in that file against the image; <literal>signature</literal> |
2fe60ff1 ZJS |
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 | |
b441a1d4 | 203 | and export calls above, these calls return a pair of transfer identifier and object path for the ongoing |
2fe60ff1 ZJS |
204 | download.</para> |
205 | ||
206 | <para><function>ListTransfers()</function> returns a list of ongoing import, export or download | |
b441a1d4 | 207 | operations as created with the six calls described above. It returns an array of structures which |
2fe60ff1 ZJS |
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 | |
b441a1d4 | 217 | operation. Simply specify the transfer identifier to cancel the ongoing operation.</para> |
2fe60ff1 ZJS |
218 | </refsect2> |
219 | ||
220 | <refsect2> | |
221 | <title>Signals</title> | |
222 | ||
b441a1d4 DDM |
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> | |
2fe60ff1 | 226 | |
b441a1d4 DDM |
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 | |
2fe60ff1 ZJS |
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 | ||
48f99d7c | 237 | <programlisting executable="systemd-importd" node="/org/freedesktop/import1/transfer/_1" interface="org.freedesktop.import1.Transfer"> |
2fe60ff1 ZJS |
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: | |
4fb222c4 ZJS |
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 = ...; | |
2fe60ff1 | 258 | }; |
4fb222c4 ZJS |
259 | interface org.freedesktop.DBus.Peer { ... }; |
260 | interface org.freedesktop.DBus.Introspectable { ... }; | |
261 | interface org.freedesktop.DBus.Properties { ... }; | |
2fe60ff1 | 262 | }; |
4fb222c4 ZJS |
263 | </programlisting> |
264 | ||
265 | <!--signal LogMessage is not documented!--> | |
2fe60ff1 | 266 | |
00bb75d7 ZJS |
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 | ||
2fe60ff1 ZJS |
291 | <refsect2> |
292 | <title>Methods</title> | |
293 | ||
294 | <para>The <function>Cancel()</function> method may be used to cancel the transfer. It takes no | |
89fc6fd3 DDM |
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 | |
2fe60ff1 ZJS |
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 | ||
b441a1d4 | 305 | <para>The <varname>Local</varname>, <varname>Remote</varname> and <varname>Type</varname> properties |
2fe60ff1 | 306 | expose the local container name of this transfer, the remote source (in case of download: the URL, in |
b441a1d4 DDM |
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 | |
2fe60ff1 ZJS |
309 | values).</para> |
310 | ||
b441a1d4 | 311 | <para>The <varname>Verify</varname> property exposes the selected verification setting and is only |
2fe60ff1 ZJS |
312 | defined for download operations (see above).</para> |
313 | ||
b441a1d4 DDM |
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 | |
2fe60ff1 ZJS |
316 | intervals, for example every 500 ms or so.</para> |
317 | </refsect2> | |
318 | </refsect1> | |
319 | ||
48f99d7c ZJS |
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 | ||
2fe60ff1 ZJS |
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> |