diff options
Diffstat (limited to 'man/org.freedesktop.import1.xml')
| -rw-r--r-- | man/org.freedesktop.import1.xml | 283 |
1 files changed, 206 insertions, 77 deletions
diff --git a/man/org.freedesktop.import1.xml b/man/org.freedesktop.import1.xml index 3ef6264..2486eea 100644 --- a/man/org.freedesktop.import1.xml +++ b/man/org.freedesktop.import1.xml @@ -1,6 +1,6 @@ <?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" > + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" > <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> <refentry id="org.freedesktop.import1" conditional='ENABLE_IMPORTD' @@ -25,11 +25,11 @@ <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. + is a system service which may be used to import, export and download disk 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>importctl pull-raw</command>, + <command>importctl pull-tar</command> and related commands. This page describes the D-Bus interface. </para> <para>Note that @@ -56,42 +56,94 @@ node /org/freedesktop/import1 { in b read_only, out u transfer_id, out o transfer_path); + ImportTarEx(in h fd, + in s local_name, + in s class, + in t flags, + 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); + ImportRawEx(in h fd, + in s local_name, + in s class, + in t flags, + 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); + ImportFileSystemEx(in h fd, + in s local_name, + in s class, + in t flags, + 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); + ExportTarEx(in s local_name, + in s class, + in h fd, + in s format, + in t flags, + 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); + ExportRawEx(in s local_name, + in s class, + in h fd, + in s format, + in t flags, + 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); + PullTarEx(in s url, + in s local_name, + in s class, + in s verify_mode, + in t flags, + 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); + PullRawEx(in s url, + in s local_name, + in s class, + in s verify_mode, + in t flags, + out u transfer_id, + out o transfer_path); ListTransfers(out a(usssdo) transfers); + ListTransfersEx(in s class, + in t flags, + out a(ussssdo) transfers); CancelTransfer(in u transfer_id); + ListImages(in s class, + in t flags, + out a(ssssbtttttt) images); signals: TransferNew(u transfer_id, o transfer_path); @@ -105,8 +157,6 @@ node /org/freedesktop/import1 { }; </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"/> @@ -115,116 +165,167 @@ node /org/freedesktop/import1 { <variablelist class="dbus-method" generated="True" extra-ref="ImportTar()"/> + <variablelist class="dbus-method" generated="True" extra-ref="ImportTarEx()"/> + <variablelist class="dbus-method" generated="True" extra-ref="ImportRaw()"/> + <variablelist class="dbus-method" generated="True" extra-ref="ImportRawEx()"/> + <variablelist class="dbus-method" generated="True" extra-ref="ImportFileSystem()"/> + <variablelist class="dbus-method" generated="True" extra-ref="ImportFileSystemEx()"/> + <variablelist class="dbus-method" generated="True" extra-ref="ExportTar()"/> + <variablelist class="dbus-method" generated="True" extra-ref="ExportTarEx()"/> + <variablelist class="dbus-method" generated="True" extra-ref="ExportRaw()"/> + <variablelist class="dbus-method" generated="True" extra-ref="ExportRawEx()"/> + <variablelist class="dbus-method" generated="True" extra-ref="PullTar()"/> + <variablelist class="dbus-method" generated="True" extra-ref="PullTarEx()"/> + <variablelist class="dbus-method" generated="True" extra-ref="PullRaw()"/> + <variablelist class="dbus-method" generated="True" extra-ref="PullRawEx()"/> + <variablelist class="dbus-method" generated="True" extra-ref="ListTransfers()"/> + <variablelist class="dbus-method" generated="True" extra-ref="ListTransfersEx()"/> + <variablelist class="dbus-method" generated="True" extra-ref="CancelTransfer()"/> - <variablelist class="dbus-signal" generated="True" extra-ref="TransferNew"/> + <variablelist class="dbus-method" generated="True" extra-ref="ListImages()"/> + + <variablelist class="dbus-signal" generated="True" extra-ref="TransferNew()"/> - <variablelist class="dbus-signal" generated="True" extra-ref="TransferRemoved"/> + <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 + <para><function>ImportTar()</function>/<function>ImportTarEx()</function> and + <function>ImportRaw()</function>/<function>ImportRawEx()</function> import a disk image and place it + into the image directory. 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>/<function>ImportTarEx()</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="url"><refentrytitle url="https://btrfs.readthedocs.io/en/latest/btrfs.html">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 + <function>ImportRaw()</function>/<function>ImportRawEx()</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="url"><refentrytitle url="https://btrfs.readthedocs.io/en/latest/btrfs.html">btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> + subvolume below the image directory under the specified name with no suffix appended. A raw import is + placed as a file in the image directory with the <filename>.raw</filename> suffix appended. In case of + <function>ImportTar()</function>/<function>ImportRaw()</function>, 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. The + <option>read_only</option> argument controls whether to create a writable or read-only image. In case + of <function>ImportTarEx()</function>/<function>ImportRawEx()</function> these boolean flags are + provided via a 64bit flags parameter instead, with bit 0 mapping to the <option>force</option> + parameter, and bit 1 mapping to <option>read_only</option>. The <option>class</option> parameter + specifies the image class, and takes one of <literal>machine</literal>, <literal>portable</literal>, + <literal>sysext</literal>, <literal>confext</literal>. All four 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 + <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 + <para><function>ExportTar()</function>/<function>ExportTarEx()</function> and + <function>ExportRaw()</function>/<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, similarly - 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 a 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, similarly 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 + specified file descriptor will be a tar file in case of + <function>ExportTar()</function>/<function>ExportTarEx()</function> or a raw disk image in case of + <function>ExportRaw()</function>/<function>ExportRawEx()</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, similarly to <function>ImportTar()</function>/<function>ImportTarEx()</function> or + <function>ImportRaw()</function>/<function>ImportRawEx()</function> as described + above. <function>ExportTarEx()</function>/<function>ExportRawEx()</function> expect the image class as + additional parameter, as well as a 64bit flags parameter that currently must be specified as + zero.</para> + + <para><function>PullTar()</function>/<function>PullTarEx()</function> and + <function>PullRaw()</function>/<function>PullRawEx()</function> may be used to download, verify and + import a system image from a URL. They take a 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, + similarly to the matching argument of the + <function>ImportTar()</function>/<function>ImportTarEx()</function> and + <function>ImportRaw()</function>/<function>ImportRawEx()</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. In + case of <function>PullTar()</function>/<function>PullRaw()</function> 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>). In case of + <function>PullTarEx()</function>/<function>PullRawEx()</function> the last argument is a 64bit flags + parameter, where bit 0 controls the <literal>force</literal> flag, bit 1 is a + <literal>read_only</literal> flag that controls whether the created image shall be marked read-only, + and bit 2 is a <literal>keep_download</literal> flag that indicates whether a pristine, read-only copy + of the downloaded image shell be kept, in addition for the local copy of the image. The + <function>…_Ex()</function> variants also expect an image class string (as above). 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>ImportFileSystem()</function>/<function>ImportFileSystemEx()</function> are similar to + <function>ImportTar()</function>/<function>ImportTarEx()</function> but import a directory tree. The + first argument must refer to a directory file descriptor for the source hierarchy to import.</para> + + <para><function>ListTransfers()</function>/<function>ListTransfersEx()</function> return a list of + ongoing import, export or download operations as created with the six calls described above. They + return 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, the image class (only in case of + <function>ListTransfersEx()</function>; one of <literal>machine</literal>, <literal>portable</literal>, + <literal>sysext</literal>, <literal>confext</literal>), 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> + + <para><function>ListImages()</function> returns a list of currently installed images. It takes a image + class string and a flags parameter. The image class is either the empty string or specifies one of the + four image classes, by which it will then filter. The flags parameter must be zero at this time. It + returns an array of items, each describing one image. The item fields are in order: the image class, + the local image name, the image type, the image path, the read-only flag, the creation and modification + times (in microseconds since the UNIX epoch), as well as the current disk usage in bytes (both overall, + and exclusive), as well as any size limit in bytes set on the image (both overall and + exclusive).</para> </refsect2> <refsect2> <title>Signals</title> - <para>The <function>TransferNew</function> signal is generated each time a new transfer is started with + <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, + <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> @@ -242,6 +343,7 @@ node /org/freedesktop/import1/transfer/_1 { signals: LogMessage(u priority, s line); + ProgressUpdate(d progress); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u Id = ...; @@ -262,8 +364,6 @@ node /org/freedesktop/import1/transfer/_1 { }; </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"/> @@ -272,7 +372,9 @@ node /org/freedesktop/import1/transfer/_1 { <variablelist class="dbus-method" generated="True" extra-ref="Cancel()"/> - <variablelist class="dbus-signal" generated="True" extra-ref="LogMessage"/> + <variablelist class="dbus-signal" generated="True" extra-ref="LogMessage()"/> + + <variablelist class="dbus-signal" generated="True" extra-ref="ProgressUpdate()"/> <variablelist class="dbus-property" generated="True" extra-ref="Id"/> @@ -315,6 +417,17 @@ node /org/freedesktop/import1/transfer/_1 { 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> + + <refsect2> + <title>Signals</title> + + <para>The <function>LogMessage()</function> signal is emitted for log messages generated by a transfer. It + carries a pair of syslog log level integer and log string.</para> + + <para>The <function>ProgressUpdate()</function> signal is emitted in regular intervals when new + download progress information is available for a transfer. It carries a double precision floating + pointer number between 0.0 and 1.0 indicating the transfer progress.</para> + </refsect2> </refsect1> <refsect1> @@ -340,4 +453,20 @@ node /org/freedesktop/import1/transfer/_1 { </refsect1> <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/> + <refsect1> + <title>History</title> + <refsect2> + <title>The Manager Object</title> + <para><function>ImportTarEx()</function>, <function>ImportRawEx()</function>, + <function>ImportFileSystemEx()</function>, <function>ExportTarEx()</function>, + <function>ExportRawEx()</function>, <function>PullTarEx()</function>, <function>PullRawEx()</function>, + <function>ListTransfersEx()</function>, <function>ListImages()</function> were added in version + 256.</para> + </refsect2> + <refsect2> + <title>Transfer Objects</title> + <para><function>ProgressUpdate()</function> was added in version 256.</para> + </refsect2> + </refsect1> + </refentry> |