diff options
Diffstat (limited to 'man/importctl.xml')
| -rw-r--r-- | man/importctl.xml | 442 |
1 files changed, 442 insertions, 0 deletions
diff --git a/man/importctl.xml b/man/importctl.xml new file mode 100644 index 0000000..3e2e33f --- /dev/null +++ b/man/importctl.xml @@ -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, and 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> |