--- /dev/null
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % entities SYSTEM "custom-entities.ent" >
+%entities;
+]>
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="importctl" conditional='ENABLE_MACHINED'
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+
+ <refentryinfo>
+ <title>importctl</title>
+ <productname>systemd</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>importctl</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>importctl</refname>
+ <refpurpose>Download, import or export disk images</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>importctl</command>
+ <arg choice="opt" rep="repeat">OPTIONS</arg>
+ <arg choice="req">COMMAND</arg>
+ <arg choice="opt" rep="repeat">NAME</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para><command>importctl</command> may be used to download, import export disk images via
+ <citerefentry><refentrytitle>systemd-importd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
+
+ <para><command>importctl</command> operates both on block-level disk images (such as DDIs) as well as
+ file-system-level images (tarballs). It supports disk images are one of the four following
+ classes:</para>
+
+ <itemizedlist>
+ <listitem><para>VM images or full OS container images, that may be run via
+ <citerefentry><refentrytitle>systemd-vmspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> or
+ <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, and
+ managed via
+ <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
+
+ <listitem><para>Portable service images, that may be attached an managed via
+ <citerefentry><refentrytitle>portablectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
+
+ <listitem><para>System extension (sysext) images, that may be activated via
+ <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem>
+
+ <listitem><para>Configuration extension (confext) images, that may be activated via
+ <citerefentry><refentrytitle>systemd-confext</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem>
+ </itemizedlist>
+
+ <para>When images are downloaded or imported they are placed in the following directories, depending on
+ the <option>--class=</option> parameter:</para>
+
+ <table>
+ <title>Classes and Directories</title>
+ <tgroup cols='2'>
+ <colspec colname='class' />
+ <colspec colname='directory' />
+ <thead>
+ <row>
+ <entry>Class</entry>
+ <entry>Directory</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>machine</literal></entry>
+ <entry><filename>/var/lib/machines/</filename></entry>
+ </row>
+ <row>
+ <entry><literal>portable</literal></entry>
+ <entry><filename>/var/lib/portables/</filename></entry>
+ </row>
+ <row>
+ <entry><literal>sysext</literal></entry>
+ <entry><filename>/var/lib/extensions/</filename></entry>
+ </row>
+ <row>
+ <entry><literal>confext</literal></entry>
+ <entry><filename>/var/lib/confexts/</filename></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </refsect1>
+
+ <refsect1>
+ <title>Commands</title>
+
+ <para>The following commands are understood:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><command>pull-tar</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
+
+ <listitem><para>Downloads a <filename>.tar</filename> image from the specified URL, and makes it
+ available under the specified local name in the image directory for the selected
+ <option>--class=</option>. The URL must be of type <literal>http://</literal> or
+ <literal>https://</literal>, and must refer to a <filename>.tar</filename>,
+ <filename>.tar.gz</filename>, <filename>.tar.xz</filename> or <filename>.tar.bz2</filename> archive
+ file. If the local image name is omitted, it is automatically derived from the last component of the
+ URL, with its suffix removed.</para>
+
+ <para>The image is verified before it is made available, unless <option>--verify=no</option> is
+ specified. Verification is done either via an inline signed file with the name of the image and the
+ suffix <filename>.sha256</filename> or via separate <filename>SHA256SUMS</filename> and
+ <filename>SHA256SUMS.gpg</filename> files. The signature files need to be made available on the same
+ web server, under the same URL as the <filename>.tar</filename> file. With
+ <option>--verify=checksum</option>, only the SHA256 checksum for the file is verified, based on the
+ <filename>.sha256</filename> suffixed file or the <filename>SHA256SUMS</filename> file. With
+ <option>--verify=signature</option>, the sha checksum file is first verified with the inline
+ signature in the <filename>.sha256</filename> file or the detached GPG signature file
+ <filename>SHA256SUMS.gpg</filename>. The public key for this verification step needs to be available
+ in <filename>/usr/lib/systemd/import-pubring.gpg</filename> or
+ <filename>/etc/systemd/import-pubring.gpg</filename>.</para>
+
+ <para>If <option>-keep-download=yes</option> is specified the image will be downloaded and stored in
+ a read-only subvolume/directory in the image directory that is named after the specified URL and its
+ HTTP etag. A writable snapshot is then taken from this subvolume, and named after the specified local
+ name. This behavior ensures that creating multiple instances of the same URL is efficient, as
+ multiple downloads are not necessary. In order to create only the read-only image, and avoid creating
+ its writable snapshot, specify <literal>-</literal> as local name.</para>
+
+ <para>Note that pressing C-c during execution of this command will not abort the download. Use
+ <command>cancel-transfer</command>, described below.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>pull-raw</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
+
+ <listitem><para>Downloads a <filename>.raw</filename> disk image from the specified URL, and makes it
+ available under the specified local name in the image directory for the selected
+ <option>--class=</option>. The URL must be of type <literal>http://</literal> or
+ <literal>https://</literal>. The image must either be a <filename>.qcow2</filename> or raw disk
+ image, optionally compressed as <filename>.gz</filename>, <filename>.xz</filename>, or
+ <filename>.bz2</filename>. If the local name is omitted, it is automatically derived from the last
+ component of the URL, with its suffix removed.</para>
+
+ <para>Image verification is identical for raw and tar images (see above).</para>
+
+ <para>If the downloaded image is in <filename>.qcow2</filename> format it is converted into a raw
+ image file before it is made available.</para>
+
+ <para>If <option>-keep-download=yes</option> is specified the image will be downloaded and stored in
+ a read-only file in the image directory that is named after the specified URL and its HTTP etag. A
+ writable copy is then made from this file, and named after the specified local name. This behavior
+ ensures that creating multiple instances of the same URL is efficient, as multiple downloads are not
+ necessary. In order to create only the read-only image, and avoid creating its writable copy,
+ specify <literal>-</literal> as local name.</para>
+
+ <para>Note that pressing C-c during execution of this command will not abort the download. Use
+ <command>cancel-transfer</command>, described below.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>import-tar</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
+ <term><command>import-raw</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
+
+ <listitem><para>Imports a TAR or RAW image, and places it under the specified name in the image
+ directory for the image class selected via <option>--class=</option>. When
+ <command>import-tar</command> is used, the file specified as the first argument should be a tar
+ archive, possibly compressed with xz, gzip or bzip2. It will then be unpacked into its own
+ subvolume/directory. When <command>import-raw</command> is used, the file should be a qcow2 or raw
+ disk image, possibly compressed with xz, gzip or bzip2. If the second argument (the resulting image
+ name) is not specified, it is automatically derived from the file name. If the filename is passed as
+ <literal>-</literal>, the image is read from standard input, in which case the second argument is
+ mandatory.</para>
+
+ <para>No cryptographic validation is done when importing the images.</para>
+
+ <para>Much like image downloads, ongoing imports may be listed with <command>list</command>
+ and aborted with <command>cancel-transfer</command>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>import-fs</command> <replaceable>DIRECTORY</replaceable> [<replaceable>NAME</replaceable>]</term>
+
+ <listitem><para>Imports an image stored in a local directory into the image directory for the image
+ class selected via <option>--class=</option> and operates similarly to <command>import-tar</command>
+ or <command>import-raw</command>, but the first argument is the source directory. If supported, this
+ command will create a btrfs snapshot or subvolume for the new image.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>export-tar</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
+ <term><command>export-raw</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
+
+ <listitem><para>Exports a TAR or RAW image and stores it in the specified file. The first parameter
+ should be an image name. The second parameter should be a file path the TAR or RAW
+ image is written to. If the path ends in <literal>.gz</literal>, the file is compressed with gzip, if
+ it ends in <literal>.xz</literal>, with xz, and if it ends in <literal>.bz2</literal>, with bzip2. If
+ the path ends in neither, the file is left uncompressed. If the second argument is missing, the image
+ is written to standard output. The compression may also be explicitly selected with the
+ <option>--format=</option> switch. This is in particular useful if the second parameter is left
+ unspecified.</para>
+
+ <para>Much like image downloads and imports, ongoing exports may be listed with
+ <command>list</command> and aborted with <command>cancel-transfer</command>.</para>
+
+ <para>Note that, currently, only directory and subvolume images may be exported as TAR images, and
+ only raw disk images as RAW images.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>list-transfer</command></term>
+
+ <listitem><para>Shows a list of image downloads, imports and exports that are currently in
+ progress.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>cancel-transfer</command> <replaceable>ID</replaceable>…</term>
+
+ <listitem><para>Aborts a download, import or export of the image with the specified ID. To list
+ ongoing transfers and their IDs, use <command>list</command>. </para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>list-images</command></term>
+
+ <listitem><para>Shows a list of already downloaded/imported images.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Options</title>
+
+ <para>The following options are understood:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>--read-only</option></term>
+
+ <listitem>
+ <para>When used with <command>pull-raw</command>, <command>pull-tar</command>,
+ <command>import-raw</command>, <command>import-tar</command> or <command>import-fs</command> a
+ read-only image is created.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--verify=</option></term>
+
+ <listitem><para>When downloading an image, specify whether the image shall be verified before it is
+ made available. Takes one of <literal>no</literal>, <literal>checksum</literal> and
+ <literal>signature</literal>. If <literal>no</literal>, no verification is done. If
+ <literal>checksum</literal> is specified, the download is checked for integrity after the transfer is
+ complete, but no signatures are verified. If <literal>signature</literal> is specified, the checksum
+ is verified and the image's signature is checked against a local keyring of trustable vendors. It is
+ strongly recommended to set this option to <literal>signature</literal> if the server and protocol
+ support this. Defaults to <literal>signature</literal>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--force</option></term>
+
+ <listitem><para>When downloading an image, and a local copy by the specified local name already
+ exists, delete it first and replace it by the newly downloaded image.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--format=</option></term>
+
+ <listitem><para>When used with the <option>export-tar</option> or <option>export-raw</option>
+ commands, specifies the compression format to use for the resulting file. Takes one of
+ <literal>uncompressed</literal>, <literal>xz</literal>, <literal>gzip</literal>,
+ <literal>bzip2</literal>. By default, the format is determined automatically from the output image
+ file name passed.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-q</option></term>
+ <term><option>--quiet</option></term>
+
+ <listitem><para>Suppresses additional informational output while running.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+ </varlistentry>
+
+ <xi:include href="user-system-options.xml" xpointer="host" />
+
+ <varlistentry>
+ <term><option>-M</option></term>
+ <term><option>--machine=</option></term>
+
+ <listitem><para>Connect to
+ <citerefentry><refentrytitle>systemd-import.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ running in a local container, to perform the specified operation within the container.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--class=</option></term>
+ <term><option>-m</option></term>
+ <term><option>-P</option></term>
+ <term><option>-S</option></term>
+ <term><option>-C</option></term>
+
+ <listitem><para>Selects the image class for the downloaded images. This primarily selects the
+ directory to download into. The <option>--class=</option> switch takes <literal>machine</literal>,
+ <literal>portable</literal>, <literal>sysext</literal> or <literal>confext</literal> as argument. The
+ short options <option>-m</option>, <option>-P</option>, <option>-S</option>, <option>-C</option> are
+ shortcuts for <option>--class=machine</option>, <option>--class=portable</option>,
+ <option>--class=sysext</option>, <option>--class=confext</option>.</para>
+
+ <para>Note that <option>--keep-download=</option> defaults to true for
+ <option>--class=machine</option> and false otherwise, see below.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--keep-download=</option></term>
+ <term><option>-N</option></term>
+
+ <listitem><para>Takes a boolean argument. When specified with <command>pull-raw</command> or
+ <command>pull-tar</command>, selects whether to download directly into the specified local image
+ name, or whether to download into a read-only copy first of which to make a writable copy after the
+ download is completed. Defaults to true for <option>--class=machine</option>, false otherwise.</para>
+
+ <para>The <option>-N</option> switch is a shortcut for <option>--keep-download=no</option>.</para>
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+ </varlistentry>
+
+ <xi:include href="standard-options.xml" xpointer="json" />
+ <xi:include href="standard-options.xml" xpointer="j" />
+ <xi:include href="standard-options.xml" xpointer="no-pager" />
+ <xi:include href="standard-options.xml" xpointer="no-legend" />
+ <xi:include href="standard-options.xml" xpointer="no-ask-password" />
+ <xi:include href="standard-options.xml" xpointer="help" />
+ <xi:include href="standard-options.xml" xpointer="version" />
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Examples</title>
+ <example id="example-import-tar">
+ <title>Download an Ubuntu TAR image and open a shell in it</title>
+
+ <programlisting># importctl pull-tar -mN https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64-root.tar.xz
+# systemd-nspawn -M jammy-server-cloudimg-amd64-root</programlisting>
+
+ <para>This downloads and verifies the specified <filename>.tar</filename> image, and then uses
+ <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> to
+ open a shell in it.</para>
+ </example>
+
+ <example id="example-import-raw">
+ <title>Download an Ubuntu RAW image, set a root password in it, start
+ it as a service</title>
+
+ <programlisting># importctl pull-raw -mN \
+ https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64-disk-kvm.img \
+ jammy
+# systemd-firstboot --image=/var/lib/machines/jammy.raw --prompt-root-password --force
+# machinectl start jammy
+# machinectl login jammy</programlisting>
+
+ <para>This downloads the specified <filename>.raw</filename> image and makes it available under the
+ local name <literal>jammy</literal>. Then, a root password is set with
+ <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Afterwards
+ the machine is started as system service. With the last command a login prompt into the container is
+ requested.</para>
+ </example>
+
+ <example id="example-export-tar">
+ <title>Exports a container image as tar file</title>
+
+ <programlisting># importctl export-tar -m fedora myfedora.tar.xz</programlisting>
+
+ <para>Exports the container <literal>fedora</literal> as an xz-compressed tar file
+ <filename>myfedora.tar.xz</filename> into the current directory.</para>
+ </example>
+ </refsect1>
+
+ <refsect1>
+ <title>Exit status</title>
+
+ <para>On success, 0 is returned, a non-zero failure code
+ otherwise.</para>
+ </refsect1>
+
+ <xi:include href="common-variables.xml" />
+
+ <refsect1>
+ <title>See Also</title>
+ <para><simplelist type="inline">
+ <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd-importd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd-vmspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>portablectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd-confext</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+ <member><citerefentry project='die-net'><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry project='die-net'><refentrytitle>xz</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry project='die-net'><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry project='die-net'><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ </simplelist></para>
+ </refsect1>
+
+</refentry>
<listitem><para>The file system tree of the host OS itself.</para></listitem>
</itemizedlist>
+ <para>Images may be downloaded, imported and exported via the
+ <citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ tool.</para>
</refsect1>
<refsect1>
<para>The following commands are understood:</para>
- <refsect2><title>Machine Commands</title><variablelist>
+ <refsect2><title>Machine Commands</title>
+ <variablelist>
<varlistentry>
<term><command>list</command></term>
</varlistentry>
</variablelist></refsect2>
- <refsect2><title>Image Commands</title><variablelist>
+ <refsect2><title>Image Commands</title>
+ <variablelist>
<varlistentry>
<term><command>list-images</command></term>
<para>When combined with the <option>--all</option> switch removes all images, not just hidden ones. This
command effectively empties <filename>/var/lib/machines/</filename>.</para>
- <para>Note that commands such as <command>machinectl pull-tar</command> or <command>machinectl
+ <para>Note that commands such as <command>importctl pull-tar</command> or <command>importctl
pull-raw</command> usually create hidden, read-only, unmodified machine images from the downloaded image first,
before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are
reused multiple times. Use <command>machinectl clean</command> to remove old, hidden images created this
</varlistentry>
</variablelist></refsect2>
-
- <refsect2><title>Image Transfer Commands</title><variablelist>
-
- <varlistentry>
- <term><command>pull-tar</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
-
- <listitem><para>Downloads a <filename>.tar</filename>
- container image from the specified URL, and makes it available
- under the specified local machine name. The URL must be of
- type <literal>http://</literal> or
- <literal>https://</literal>, and must refer to a
- <filename>.tar</filename>, <filename>.tar.gz</filename>,
- <filename>.tar.xz</filename> or <filename>.tar.bz2</filename>
- archive file. If the local machine name is omitted, it
- is automatically derived from the last component of the URL,
- with its suffix removed.</para>
-
- <para>The image is verified before it is made available, unless
- <option>--verify=no</option> is specified.
- Verification is done either via an inline signed file with the name
- of the image and the suffix <filename>.sha256</filename> or via
- separate <filename>SHA256SUMS</filename> and
- <filename>SHA256SUMS.gpg</filename> files.
- The signature files need to be made available on the same web
- server, under the same URL as the <filename>.tar</filename> file.
- With <option>--verify=checksum</option>, only the SHA256 checksum
- for the file is verified, based on the <filename>.sha256</filename>
- suffixed file or the <filename>SHA256SUMS</filename> file.
- With <option>--verify=signature</option>, the sha checksum file is
- first verified with the inline signature in the
- <filename>.sha256</filename> file or the detached GPG signature file
- <filename>SHA256SUMS.gpg</filename>.
- The public key for this verification step needs to be available in
- <filename>/usr/lib/systemd/import-pubring.gpg</filename> or
- <filename>/etc/systemd/import-pubring.gpg</filename>.</para>
-
- <para>The container image will be downloaded and stored in a
- read-only subvolume in
- <filename>/var/lib/machines/</filename> that is named after
- the specified URL and its HTTP etag. A writable snapshot is
- then taken from this subvolume, and named after the specified
- local name. This behavior ensures that creating multiple
- container instances of the same URL is efficient, as multiple
- downloads are not necessary. In order to create only the
- read-only image, and avoid creating its writable snapshot,
- specify <literal>-</literal> as local machine name.</para>
-
- <para>Note that the read-only subvolume is prefixed with
- <filename>.tar-</filename>, and is thus not shown by
- <command>list-images</command>, unless <option>--all</option>
- is passed.</para>
-
- <para>Note that pressing C-c during execution of this command
- will not abort the download. Use
- <command>cancel-transfer</command>, described
- below.</para>
-
- <xi:include href="version-info.xml" xpointer="v219"/></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><command>pull-raw</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
-
- <listitem><para>Downloads a <filename>.raw</filename>
- container or VM disk image from the specified URL, and makes
- it available under the specified local machine name. The URL
- must be of type <literal>http://</literal> or
- <literal>https://</literal>. The container image must either
- be a <filename>.qcow2</filename> or raw disk image, optionally
- compressed as <filename>.gz</filename>,
- <filename>.xz</filename>, or <filename>.bz2</filename>. If the
- local machine name is omitted, it is automatically
- derived from the last component of the URL, with its suffix
- removed.</para>
-
- <para>Image verification is identical for raw and tar images
- (see above).</para>
-
- <para>If the downloaded image is in
- <filename>.qcow2</filename> format it is converted into a raw
- image file before it is made available.</para>
-
- <para>Downloaded images of this type will be placed as
- read-only <filename>.raw</filename> file in
- <filename>/var/lib/machines/</filename>. A local, writable
- (reflinked) copy is then made under the specified local
- machine name. To omit creation of the local, writable copy
- pass <literal>-</literal> as local machine name.</para>
-
- <para>Similarly to the behavior of <command>pull-tar</command>, the read-only image is prefixed with
- <filename>.raw-</filename>, and thus not shown by <command>list-images</command>, unless
- <option>--all</option> is passed.</para>
-
- <para>Note that pressing C-c during execution of this command
- will not abort the download. Use
- <command>cancel-transfer</command>, described
- below.</para>
-
- <xi:include href="version-info.xml" xpointer="v219"/></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><command>import-tar</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
- <term><command>import-raw</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
- <listitem><para>Imports a TAR or RAW container or VM image,
- and places it under the specified name in
- <filename>/var/lib/machines/</filename>. When
- <command>import-tar</command> is used, the file specified as
- the first argument should be a tar archive, possibly compressed
- with xz, gzip or bzip2. It will then be unpacked into its own
- subvolume in <filename>/var/lib/machines/</filename>. When
- <command>import-raw</command> is used, the file should be a
- qcow2 or raw disk image, possibly compressed with xz, gzip or
- bzip2. If the second argument (the resulting image name) is
- not specified, it is automatically derived from the file
- name. If the filename is passed as <literal>-</literal>, the
- image is read from standard input, in which case the second
- argument is mandatory.</para>
-
- <para>Optionally, the <option>--read-only</option> switch may be used to create a read-only container or VM
- image. No cryptographic validation is done when importing the images.</para>
-
- <para>Much like image downloads, ongoing imports may be listed
- with <command>list-transfers</command> and aborted with
- <command>cancel-transfer</command>.</para>
-
- <xi:include href="version-info.xml" xpointer="v220"/></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><command>import-fs</command> <replaceable>DIRECTORY</replaceable> [<replaceable>NAME</replaceable>]</term>
-
- <listitem><para>Imports a container image stored in a local directory into
- <filename>/var/lib/machines/</filename>, operates similarly to <command>import-tar</command> or
- <command>import-raw</command>, but the first argument is the source directory. If supported, this
- command will create a btrfs snapshot or subvolume for the new image.</para>
-
- <xi:include href="version-info.xml" xpointer="v240"/></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><command>export-tar</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
- <term><command>export-raw</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
- <listitem><para>Exports a TAR or RAW container or VM image and
- stores it in the specified file. The first parameter should be
- a VM or container image name. The second parameter should be a
- file path the TAR or RAW image is written to. If the path ends
- in <literal>.gz</literal>, the file is compressed with gzip, if
- it ends in <literal>.xz</literal>, with xz, and if it ends in
- <literal>.bz2</literal>, with bzip2. If the path ends in
- neither, the file is left uncompressed. If the second argument
- is missing, the image is written to standard output. The
- compression may also be explicitly selected with the
- <option>--format=</option> switch. This is in particular
- useful if the second parameter is left unspecified.</para>
-
- <para>Much like image downloads and imports, ongoing exports
- may be listed with <command>list-transfers</command> and
- aborted with
- <command>cancel-transfer</command>.</para>
-
- <para>Note that, currently, only directory and subvolume images
- may be exported as TAR images, and only raw disk images as RAW
- images.</para>
-
- <xi:include href="version-info.xml" xpointer="v220"/></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><command>list-transfers</command></term>
-
- <listitem><para>Shows a list of container or VM image
- downloads, imports and exports that are currently in
- progress.</para>
-
- <xi:include href="version-info.xml" xpointer="v219"/></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><command>cancel-transfer</command> <replaceable>ID</replaceable>…</term>
-
- <listitem><para>Aborts a download, import or export of the
- container or VM image with the specified ID. To list ongoing
- transfers and their IDs, use
- <command>list-transfers</command>. </para>
-
- <xi:include href="version-info.xml" xpointer="v219"/></listitem>
- </varlistentry>
-
- </variablelist></refsect2>
-
</refsect1>
<refsect1>
<listitem><para>When used with <command>bind</command>, creates a read-only bind mount.</para>
- <para>When used with <command>clone</command>, <command>import-raw</command> or <command>import-tar</command> a
- read-only container or VM image is created.</para>
+ <para>When used with <command>clone</command> a read-only container or VM image is created.</para>
<xi:include href="version-info.xml" xpointer="v219"/></listitem>
</varlistentry>
<xi:include href="version-info.xml" xpointer="v219"/></listitem>
</varlistentry>
- <varlistentry>
- <term><option>--verify=</option></term>
-
- <listitem><para>When downloading a container or VM image,
- specify whether the image shall be verified before it is made
- available. Takes one of <literal>no</literal>,
- <literal>checksum</literal> and <literal>signature</literal>.
- If <literal>no</literal>, no verification is done. If
- <literal>checksum</literal> is specified, the download is
- checked for integrity after the transfer is complete, but no
- signatures are verified. If <literal>signature</literal> is
- specified, the checksum is verified and the image's signature
- is checked against a local keyring of trustable vendors. It is
- strongly recommended to set this option to
- <literal>signature</literal> if the server and protocol
- support this. Defaults to
- <literal>signature</literal>.</para>
-
- <xi:include href="version-info.xml" xpointer="v219"/></listitem>
- </varlistentry>
-
<varlistentry>
<term><option>--runner=</option><option>nspawn</option>|<option>vmspawn</option></term>
<varlistentry>
<term><option>--force</option></term>
- <listitem><para>When downloading a container or VM image, and
- a local copy by the specified local machine name already
- exists, delete it first and replace it by the newly downloaded
- image.</para>
+ <listitem><para>Replace target file when copying files.</para>
<xi:include href="version-info.xml" xpointer="v219"/></listitem>
</varlistentry>
- <varlistentry>
- <term><option>--format=</option></term>
-
- <listitem><para>When used with the <option>export-tar</option>
- or <option>export-raw</option> commands, specifies the
- compression format to use for the resulting file. Takes one of
- <literal>uncompressed</literal>, <literal>xz</literal>,
- <literal>gzip</literal>, <literal>bzip2</literal>. By default,
- the format is determined automatically from the image file
- name passed.</para>
-
- <xi:include href="version-info.xml" xpointer="v220"/></listitem>
- </varlistentry>
-
<varlistentry>
<term><option>--max-addresses=</option></term>
<refsect1>
<title>Examples</title>
- <example>
- <title>Download a Ubuntu image and open a shell in it</title>
-
- <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
-# systemd-nspawn -M trusty-server-cloudimg-amd64-root</programlisting>
-
- <para>This downloads and verifies the specified
- <filename>.tar</filename> image, and then uses
- <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- to open a shell in it.</para>
- </example>
-
- <example>
- <title>Download a Fedora image, set a root password in it, start
- it as a service</title>
-
- <programlisting># machinectl pull-raw --verify=no \
- https://download.fedoraproject.org/pub/fedora/linux/releases/&fedora_latest_version;/Cloud/x86_64/images/Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86_64.raw.xz \
- Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86-64
-# systemd-nspawn -M Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86-64
-# passwd
-# exit
-# machinectl start Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86-64
-# machinectl login Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86-64</programlisting>
-
- <para>This downloads the specified <filename>.raw</filename>
- image with verification disabled. Then, a shell is opened in it
- and a root password is set. Afterwards the shell is left, and
- the machine started as system service. With the last command a
- login prompt into the container is requested.</para>
- </example>
-
- <example>
- <title>Exports a container image as tar file</title>
-
- <programlisting># machinectl export-tar fedora myfedora.tar.xz</programlisting>
-
- <para>Exports the container <literal>fedora</literal> as an
- xz-compressed tar file <filename>myfedora.tar.xz</filename> into the
- current directory.</para>
- </example>
-
- <example>
- <title>Create a new shell session</title>
-
- <programlisting># machinectl shell --uid=lennart</programlisting>
-
- <para>This creates a new shell session on the local host for
- the user ID <literal>lennart</literal>, in a <citerefentry
- project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like
- fashion.</para>
- </example>
+
+ <xi:include href="importctl.xml" xpointer="example-import-raw" />
</refsect1>
<member><citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry project='die-net'><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry project='die-net'><refentrytitle>xz</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry project='die-net'><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<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
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);
};
</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-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-method" generated="True" extra-ref="ListImages()"/>
+
<variablelist class="dbus-signal" generated="True" extra-ref="TransferNew()"/>
<variablelist class="dbus-signal" generated="True" extra-ref="TransferRemoved()"/>
<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
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>
signals:
LogMessage(u priority,
s line);
+ ProgressUpdate(d progress);
properties:
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly u Id = ...;
};
</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-signal" generated="True" extra-ref="LogMessage()"/>
+ <variablelist class="dbus-signal" generated="True" extra-ref="ProgressUpdate()"/>
+
<variablelist class="dbus-property" generated="True" extra-ref="Id"/>
<variablelist class="dbus-property" generated="True" extra-ref="Local"/>
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>
</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>
<member><citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>org.freedesktop.portable1</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-portabled.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
</simplelist></para>
</refsect1>
['hostname', '5', [], ''],
['hostnamectl', '1', [], 'ENABLE_HOSTNAMED'],
['hwdb', '7', [], 'ENABLE_HWDB'],
+ ['importctl', '1', [], 'ENABLE_MACHINED'],
['integritytab', '5', [], 'HAVE_LIBCRYPTSETUP'],
['iocost.conf', '5', [], ''],
['journal-remote.conf', '5', ['journal-remote.conf.d'], 'HAVE_MICROHTTPD'],
<refsect1>
<title>Description</title>
- <para><command>systemd-importd</command> is a system service that allows importing, exporting and downloading of
- system images suitable for running as VM or containers. It is a companion service for
- <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, and provides the implementation for
- <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
+ <para><command>systemd-importd</command> is a system service that allows importing, exporting and
+ downloading of disk images. It provides the implementation for
+ <citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
<command>pull-raw</command>, <command>pull-tar</command>, <command>import-raw</command>,
- <command>import-tar</command>, <command>import-fs</command>, <command>export-raw</command>, and <command>export-tar</command> commands.</para>
+ <command>import-tar</command>, <command>import-fs</command>, <command>export-raw</command>, and
+ <command>export-tar</command> commands.</para>
<para>See
<citerefentry><refentrytitle>org.freedesktop.import1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
<title>See Also</title>
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
- <member><citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
</simplelist></para>
<refsect1>
<title>Examples</title>
- <example>
- <title>Download a
- <ulink url="https://getfedora.org">Fedora</ulink> image and start a shell in it</title>
-
- <programlisting># machinectl pull-raw --verify=no \
- https://download.fedoraproject.org/pub/fedora/linux/releases/&fedora_latest_version;/Cloud/x86_64/images/Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86_64.raw.xz \
- Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86-64
-# systemd-nspawn -M Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86-64</programlisting>
-
- <para>This downloads an image using
- <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- and opens a shell in it.</para>
- </example>
+ <xi:include href="importctl.xml" xpointer="example-import-tar" />
<example>
<title>Build and boot a minimal Fedora distribution in a container</title>
<member><citerefentry project='mankier'><refentrytitle>zypper</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry project='url'><refentrytitle url='https://btrfs.readthedocs.io/en/latest/btrfs.html'>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
</simplelist></para>
</refsect1>
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
</simplelist></para>
</refsect1>
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>mkosi</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
</simplelist></para>
</refsect1>
</refentry>
projects / thirdparty / systemd.git / commitdiff
