4fb222c4b2
This replaces the api export tables with updated versions, and inserts comments for all "undocumented" items. The slow work of documented them is left for later ;) lxml does some formatting changes that are not significant for lxml processing, but generate spurious difference in the diff (namely: ulinks become one-line, and double quotes are used instead of single quotes for element attribute values). This should be a one-time thing: subsequent renegeration should be idempotent with regards to this.
280 lines
14 KiB
XML
280 lines
14 KiB
XML
<?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+ -->
|
||
|
||
<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, for
|
||
running them as local containers using tools such as
|
||
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> The
|
||
service is used as backend for <command>machinectl pull-raw</command> and <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> bus API, c.f.
|
||
<citerefentry><refentrytitle>org.freedesktop.machine1.service</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>
|
||
$ gdbus introspect --system \
|
||
--dest org.freedesktop.import1 \
|
||
--object-path /org/freedesktop/import1
|
||
|
||
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!-->
|
||
|
||
<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 either a file on
|
||
disk or a pipe or 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 file descriptor on disk, progress information is generated for the import
|
||
operation (since the size on disk is known then), if a socket or pipe is specified this 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 directory tree or
|
||
<citerefentry project="man-pages"><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
||
subvolume below <filename>/var/lib/machines/</filename>, under the name specified with no suffix
|
||
appended. A raw import is placed as file in <filename>/var/lib/machines/</filename> with the
|
||
<filename>.raw</filename> suffix appended. The <option>force</option> argument controls whether any
|
||
pre-existing image with the same name shall be removed for the operation. If true, it is removed, if
|
||
false the operation fails on a name conflict. Finally, the <option>read_only</option> argument controls
|
||
whether to create a writable or read-only image. The two calls return immediately after invocation,
|
||
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 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 it 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 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, however this restriction might be lifted eventually. The call
|
||
returns a transfer identifier and object path for canceling or tracking the export operation, similar
|
||
to <function>ImportTar()</function> or <function>ImportRaw()</function> described above.</para>
|
||
|
||
<para><function>PullTar()</function> and <function>PullRaw()</function> may be used to download, verify
|
||
and import a system image from a web site. They take an URL argument, that should reference 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 hostname, similar to the matching argument of the <function>ImportTar()</function> and
|
||
<function>ImportRaw()</function> calls 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 of 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 again 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.</para>
|
||
</refsect2>
|
||
|
||
<refsect2>
|
||
<title>Signals</title>
|
||
|
||
<para>The <function>TransferNew</function> signal is generated each time a new transfer is added with
|
||
the import, export or download calls described above. It carries the transfer ID and object path just
|
||
created.</para>
|
||
|
||
<para>The <function>TransferRemoved</function> signal is sent each time a transfer was completed,
|
||
canceled or failed. 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>
|
||
$ gdbus introspect --system \
|
||
--dest org.freedesktop.import1 \
|
||
--object-path /org/freedesktop/import1/transfer/_1
|
||
|
||
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!-->
|
||
|
||
<refsect2>
|
||
<title>Methods</title>
|
||
|
||
<para>The <function>Cancel()</function> method may be used to cancel the transfer. It takes no
|
||
parameters. This call is pretty much equivalent to the <function>CancelTransfer()</function> call 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>, <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> call 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 it recommend to query this value in regular
|
||
intervals, for example every 500 ms or so.</para>
|
||
</refsect2>
|
||
</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>
|