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-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 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"> 50node /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"> 238node /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 <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/> 343</refentry> 344