shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-12-22 17:35:35 +03:00
Code

man: document new importctl/importd functionality

Browse Source 
This also replaces the Fedora download example with another one from
Ubuntu, since Fedora's images these days no longer qualify as DDIs, they
have no distinctive partition type UUIDs set for multiple of their
partitions, hence the images cannot be booted. A bit sad. Let's provide
a command that just works in its place.
This commit is contained in:
Lennart Poettering 2024-02-27 09:39:57 +01:00
parent 5b7bfe0637
commit fd571c9df0
9 changed files with 665 additions and 374 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

442
man/importctl.xml Normal file
View File

@ -0,0 +1,442 @@
<?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>

298
man/machinectl.xml
View File

@ -80,6 +80,9 @@
<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>
@ -87,8 +90,9 @@
<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>
@ -361,8 +365,9 @@
</varlistentry>
</variablelist></refsect2>
<refsect2><title>Image Commands</title><variablelist>
<refsect2><title>Image Commands</title>
<variablelist>
<varlistentry>
<term><command>list-images</command></term>
@ -515,7 +520,7 @@
<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
@ -525,197 +530,6 @@
</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>
@ -834,8 +648,7 @@
<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>
@ -866,27 +679,6 @@
<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>
@ -926,28 +718,11 @@
<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>
@ -1069,58 +844,8 @@
<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>
@ -1140,6 +865,7 @@
<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>

267
man/org.freedesktop.import1.xml
View File

@ -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,22 +165,40 @@ 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-method" generated="True" extra-ref="ListImages()"/>
<variablelist class="dbus-signal" generated="True" extra-ref="TransferNew()"/>
<variablelist class="dbus-signal" generated="True" extra-ref="TransferRemoved()"/>
@ -140,81 +208,114 @@ node /org/freedesktop/import1 {
<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>
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> 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
<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>
@ -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"/>
@ -274,6 +374,8 @@ node /org/freedesktop/import1/transfer/_1 {
<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"/>
@ -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>

1
man/portablectl.xml
View File

@ -511,6 +511,7 @@
<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>

1
man/rules/meson.build
View File

@ -23,6 +23,7 @@ manpages = [
['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'],

12
man/systemd-importd.service.xml
View File

@ -29,12 +29,12 @@
<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>
@ -47,7 +47,7 @@
<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>

15
man/systemd-nspawn.xml
View File

@ -1800,19 +1800,7 @@ After=sys-subsystem-net-devices-ens1.device</programlisting>
<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>
@ -1921,6 +1909,7 @@ After=sys-subsystem-net-devices-ens1.device</programlisting>
<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>

1
man/systemd-sysext.xml
View File

@ -449,6 +449,7 @@
<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>

2
man/systemd-vmspawn.xml
View File

@ -485,6 +485,8 @@ $ systemd-vmspawn --image=image.raw
<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>