man/importctl.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
   4 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   8
   9 <refentry id="importctl" conditional='ENABLE_MACHINED'
  10     xmlns:xi="http://www.w3.org/2001/XInclude">
  11
  12   <refentryinfo>
  13     <title>importctl</title>
  14     <productname>systemd</productname>
  15   </refentryinfo>
  16
  17   <refmeta>
  18     <refentrytitle>importctl</refentrytitle>
  19     <manvolnum>1</manvolnum>
  20   </refmeta>
  21
  22   <refnamediv>
  23     <refname>importctl</refname>
  24     <refpurpose>Download, import or export disk images</refpurpose>
  25   </refnamediv>
  26
  27   <refsynopsisdiv>
  28     <cmdsynopsis>
  29       <command>importctl</command>
  30       <arg choice="opt" rep="repeat">OPTIONS</arg>
  31       <arg choice="req">COMMAND</arg>
  32       <arg choice="opt" rep="repeat">NAME</arg>
  33     </cmdsynopsis>
  34   </refsynopsisdiv>
  35
  36   <refsect1>
  37     <title>Description</title>
  38
  39     <para><command>importctl</command> may be used to download, import, and export disk images via
  40     <citerefentry><refentrytitle>systemd-importd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
  41
  42     <para><command>importctl</command> operates both on block-level disk images (such as DDIs) as well as
  43     file-system-level images (tarballs). It supports disk images are one of the four following
  44     classes:</para>
  45
  46     <itemizedlist>
  47       <listitem><para>VM images or full OS container images, that may be run via
  48       <citerefentry><refentrytitle>systemd-vmspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> or
  49       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, and
  50       managed via
  51       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
  52
  53       <listitem><para>Portable service images, that may be attached an managed via
  54       <citerefentry><refentrytitle>portablectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
  55
  56       <listitem><para>System extension (sysext) images, that may be activated via
  57       <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem>
  58
  59       <listitem><para>Configuration extension (confext) images, that may be activated via
  60       <citerefentry><refentrytitle>systemd-confext</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem>
  61     </itemizedlist>
  62
  63     <para>When images are downloaded or imported they are placed in the following directories, depending on
  64     the <option>--class=</option> parameter:</para>
  65
  66     <table>
  67       <title>Classes and Directories</title>
  68       <tgroup cols='2'>
  69         <colspec colname='class' />
  70         <colspec colname='directory' />
  71         <thead>
  72           <row>
  73             <entry>Class</entry>
  74             <entry>Directory</entry>
  75           </row>
  76         </thead>
  77         <tbody>
  78           <row>
  79             <entry><literal>machine</literal></entry>
  80             <entry><filename>/var/lib/machines/</filename></entry>
  81           </row>
  82           <row>
  83             <entry><literal>portable</literal></entry>
  84             <entry><filename>/var/lib/portables/</filename></entry>
  85           </row>
  86           <row>
  87             <entry><literal>sysext</literal></entry>
  88             <entry><filename>/var/lib/extensions/</filename></entry>
  89           </row>
  90           <row>
  91             <entry><literal>confext</literal></entry>
  92             <entry><filename>/var/lib/confexts/</filename></entry>
  93           </row>
  94         </tbody>
  95       </tgroup>
  96     </table>
  97   </refsect1>
  98
  99   <refsect1>
 100     <title>Commands</title>
 101
 102     <para>The following commands are understood:</para>
 103
 104     <variablelist>
 105       <varlistentry>
 106         <term><command>pull-tar</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
 107
 108         <listitem><para>Downloads a <filename>.tar</filename> image from the specified URL, and makes it
 109         available under the specified local name in the image directory for the selected
 110         <option>--class=</option>. The URL must be of type <literal>http://</literal> or
 111         <literal>https://</literal>, and must refer to a <filename>.tar</filename>,
 112         <filename>.tar.gz</filename>, <filename>.tar.xz</filename> or <filename>.tar.bz2</filename> archive
 113         file. If the local image name is omitted, it is automatically derived from the last component of the
 114         URL, with its suffix removed.</para>
 115
 116         <para>The image is verified before it is made available, unless <option>--verify=no</option> is
 117         specified.  Verification is done either via an inline signed file with the name of the image and the
 118         suffix <filename>.sha256</filename> or via separate <filename>SHA256SUMS</filename> and
 119         <filename>SHA256SUMS.gpg</filename> files.  The signature files need to be made available on the same
 120         web server, under the same URL as the <filename>.tar</filename> file.  With
 121         <option>--verify=checksum</option>, only the SHA256 checksum for the file is verified, based on the
 122         <filename>.sha256</filename> suffixed file or the <filename>SHA256SUMS</filename> file.  With
 123         <option>--verify=signature</option>, the sha checksum file is first verified with the inline
 124         signature in the <filename>.sha256</filename> file or the detached GPG signature file
 125         <filename>SHA256SUMS.gpg</filename>.  The public key for this verification step needs to be available
 126         in <filename>/usr/lib/systemd/import-pubring.gpg</filename> or
 127         <filename>/etc/systemd/import-pubring.gpg</filename>.</para>
 128
 129         <para>If <option>-keep-download=yes</option> is specified the image will be downloaded and stored in
 130         a read-only subvolume/directory in the image directory that is named after the specified URL and its
 131         HTTP etag. A writable snapshot is then taken from this subvolume, and named after the specified local
 132         name. This behavior ensures that creating multiple instances of the same URL is efficient, as
 133         multiple downloads are not necessary. In order to create only the read-only image, and avoid creating
 134         its writable snapshot, specify <literal>-</literal> as local name.</para>
 135
 136         <para>Note that pressing C-c during execution of this command will not abort the download. Use
 137         <command>cancel-transfer</command>, described below.</para>
 138
 139         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 140       </varlistentry>
 141
 142       <varlistentry>
 143         <term><command>pull-raw</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
 144
 145         <listitem><para>Downloads a <filename>.raw</filename> disk image from the specified URL, and makes it
 146         available under the specified local name in the image directory for the selected
 147         <option>--class=</option>. The URL must be of type <literal>http://</literal> or
 148         <literal>https://</literal>. The image must either be a <filename>.qcow2</filename> or raw disk
 149         image, optionally compressed as <filename>.gz</filename>, <filename>.xz</filename>, or
 150         <filename>.bz2</filename>. If the local name is omitted, it is automatically derived from the last
 151         component of the URL, with its suffix removed.</para>
 152
 153         <para>Image verification is identical for raw and tar images (see above).</para>
 154
 155         <para>If the downloaded image is in <filename>.qcow2</filename> format it is converted into a raw
 156         image file before it is made available.</para>
 157
 158         <para>If <option>-keep-download=yes</option> is specified the image will be downloaded and stored in
 159         a read-only file in the image directory that is named after the specified URL and its HTTP etag. A
 160         writable copy is then made from this file, and named after the specified local name. This behavior
 161         ensures that creating multiple instances of the same URL is efficient, as multiple downloads are not
 162         necessary. In order to create only the read-only image, and avoid creating its writable copy,
 163         specify <literal>-</literal> as local name.</para>
 164
 165         <para>Note that pressing C-c during execution of this command will not abort the download. Use
 166         <command>cancel-transfer</command>, described below.</para>
 167
 168         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 169       </varlistentry>
 170
 171       <varlistentry>
 172         <term><command>import-tar</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
 173         <term><command>import-raw</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
 174
 175         <listitem><para>Imports a TAR or RAW image, and places it under the specified name in the image
 176         directory for the image class selected via <option>--class=</option>. When
 177         <command>import-tar</command> is used, the file specified as the first argument should be a tar
 178         archive, possibly compressed with xz, gzip or bzip2. It will then be unpacked into its own
 179         subvolume/directory. When <command>import-raw</command> is used, the file should be a qcow2 or raw
 180         disk image, possibly compressed with xz, gzip or bzip2. If the second argument (the resulting image
 181         name) is not specified, it is automatically derived from the file name. If the filename is passed as
 182         <literal>-</literal>, the image is read from standard input, in which case the second argument is
 183         mandatory.</para>
 184
 185         <para>No cryptographic validation is done when importing the images.</para>
 186
 187         <para>Much like image downloads, ongoing imports may be listed with <command>list</command>
 188         and aborted with <command>cancel-transfer</command>.</para>
 189
 190         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 191       </varlistentry>
 192
 193       <varlistentry>
 194         <term><command>import-fs</command> <replaceable>DIRECTORY</replaceable> [<replaceable>NAME</replaceable>]</term>
 195
 196         <listitem><para>Imports an image stored in a local directory into the image directory for the image
 197         class selected via <option>--class=</option> and operates similarly to <command>import-tar</command>
 198         or <command>import-raw</command>, but the first argument is the source directory. If supported, this
 199         command will create a btrfs snapshot or subvolume for the new image.</para>
 200
 201         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 202       </varlistentry>
 203
 204       <varlistentry>
 205         <term><command>export-tar</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
 206         <term><command>export-raw</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
 207
 208         <listitem><para>Exports a TAR or RAW image and stores it in the specified file. The first parameter
 209         should be an image name. The second parameter should be a file path the TAR or RAW
 210         image is written to. If the path ends in <literal>.gz</literal>, the file is compressed with gzip, if
 211         it ends in <literal>.xz</literal>, with xz, and if it ends in <literal>.bz2</literal>, with bzip2. If
 212         the path ends in neither, the file is left uncompressed. If the second argument is missing, the image
 213         is written to standard output. The compression may also be explicitly selected with the
 214         <option>--format=</option> switch. This is in particular useful if the second parameter is left
 215         unspecified.</para>
 216
 217         <para>Much like image downloads and imports, ongoing exports may be listed with
 218         <command>list</command> and aborted with <command>cancel-transfer</command>.</para>
 219
 220         <para>Note that, currently, only directory and subvolume images may be exported as TAR images, and
 221         only raw disk images as RAW images.</para>
 222
 223         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 224       </varlistentry>
 225
 226       <varlistentry>
 227         <term><command>list-transfer</command></term>
 228
 229         <listitem><para>Shows a list of image downloads, imports and exports that are currently in
 230         progress.</para>
 231
 232         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 233       </varlistentry>
 234
 235       <varlistentry>
 236         <term><command>cancel-transfer</command> <replaceable>ID</replaceable>…</term>
 237
 238         <listitem><para>Aborts a download, import or export of the image with the specified ID. To list
 239         ongoing transfers and their IDs, use <command>list</command>. </para>
 240
 241         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 242       </varlistentry>
 243
 244       <varlistentry>
 245         <term><command>list-images</command></term>
 246
 247         <listitem><para>Shows a list of already downloaded/imported images.</para>
 248
 249         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 250       </varlistentry>
 251
 252     </variablelist>
 253   </refsect1>
 254
 255   <refsect1>
 256     <title>Options</title>
 257
 258     <para>The following options are understood:</para>
 259
 260     <variablelist>
 261       <varlistentry>
 262         <term><option>--read-only</option></term>
 263
 264         <listitem>
 265           <para>When used with <command>pull-raw</command>, <command>pull-tar</command>,
 266           <command>import-raw</command>, <command>import-tar</command> or <command>import-fs</command> a
 267           read-only image is created.</para>
 268
 269           <xi:include href="version-info.xml" xpointer="v256"/>
 270         </listitem>
 271       </varlistentry>
 272
 273       <varlistentry>
 274         <term><option>--verify=</option></term>
 275
 276         <listitem><para>When downloading an image, specify whether the image shall be verified before it is
 277         made available. Takes one of <literal>no</literal>, <literal>checksum</literal> and
 278         <literal>signature</literal>.  If <literal>no</literal>, no verification is done. If
 279         <literal>checksum</literal> is specified, the download is checked for integrity after the transfer is
 280         complete, but no signatures are verified. If <literal>signature</literal> is specified, the checksum
 281         is verified and the image's signature is checked against a local keyring of trustable vendors. It is
 282         strongly recommended to set this option to <literal>signature</literal> if the server and protocol
 283         support this. Defaults to <literal>signature</literal>.</para>
 284
 285         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 286       </varlistentry>
 287
 288       <varlistentry>
 289         <term><option>--force</option></term>
 290
 291         <listitem><para>When downloading an image, and a local copy by the specified local name already
 292         exists, delete it first and replace it by the newly downloaded image.</para>
 293
 294         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 295       </varlistentry>
 296
 297       <varlistentry>
 298         <term><option>--format=</option></term>
 299
 300         <listitem><para>When used with the <option>export-tar</option> or <option>export-raw</option>
 301         commands, specifies the compression format to use for the resulting file. Takes one of
 302         <literal>uncompressed</literal>, <literal>xz</literal>, <literal>gzip</literal>,
 303         <literal>bzip2</literal>. By default, the format is determined automatically from the output image
 304         file name passed.</para>
 305
 306         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 307       </varlistentry>
 308
 309       <varlistentry>
 310         <term><option>-q</option></term>
 311         <term><option>--quiet</option></term>
 312
 313         <listitem><para>Suppresses additional informational output while running.</para>
 314
 315         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 316       </varlistentry>
 317
 318       <xi:include href="user-system-options.xml" xpointer="host" />
 319
 320       <varlistentry>
 321         <term><option>-M</option></term>
 322         <term><option>--machine=</option></term>
 323
 324         <listitem><para>Connect to
 325         <citerefentry><refentrytitle>systemd-import.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 326         running in a local container, to perform the specified operation within the container.</para>
 327
 328         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 329       </varlistentry>
 330
 331       <varlistentry>
 332         <term><option>--class=</option></term>
 333         <term><option>-m</option></term>
 334         <term><option>-P</option></term>
 335         <term><option>-S</option></term>
 336         <term><option>-C</option></term>
 337
 338         <listitem><para>Selects the image class for the downloaded images. This primarily selects the
 339         directory to download into. The <option>--class=</option> switch takes <literal>machine</literal>,
 340         <literal>portable</literal>, <literal>sysext</literal> or <literal>confext</literal> as argument. The
 341         short options <option>-m</option>, <option>-P</option>, <option>-S</option>, <option>-C</option> are
 342         shortcuts for <option>--class=machine</option>, <option>--class=portable</option>,
 343         <option>--class=sysext</option>, <option>--class=confext</option>.</para>
 344
 345         <para>Note that <option>--keep-download=</option> defaults to true for
 346         <option>--class=machine</option> and false otherwise, see below.</para>
 347
 348         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 349       </varlistentry>
 350
 351       <varlistentry>
 352         <term><option>--keep-download=</option></term>
 353         <term><option>-N</option></term>
 354
 355         <listitem><para>Takes a boolean argument. When specified with <command>pull-raw</command> or
 356         <command>pull-tar</command>, selects whether to download directly into the specified local image
 357         name, or whether to download into a read-only copy first of which to make a writable copy after the
 358         download is completed. Defaults to true for <option>--class=machine</option>, false otherwise.</para>
 359
 360         <para>The <option>-N</option> switch is a shortcut for <option>--keep-download=no</option>.</para>
 361         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 362       </varlistentry>
 363
 364       <xi:include href="standard-options.xml" xpointer="json" />
 365       <xi:include href="standard-options.xml" xpointer="j" />
 366       <xi:include href="standard-options.xml" xpointer="no-pager" />
 367       <xi:include href="standard-options.xml" xpointer="no-legend" />
 368       <xi:include href="standard-options.xml" xpointer="no-ask-password" />
 369       <xi:include href="standard-options.xml" xpointer="help" />
 370       <xi:include href="standard-options.xml" xpointer="version" />
 371     </variablelist>
 372   </refsect1>
 373
 374   <refsect1>
 375     <title>Examples</title>
 376     <example id="example-import-tar">
 377       <title>Download an Ubuntu TAR image and open a shell in it</title>
 378
 379       <programlisting># importctl pull-tar -mN https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64-root.tar.xz
 380 # systemd-nspawn -M jammy-server-cloudimg-amd64-root</programlisting>
 381
 382       <para>This downloads and verifies the specified <filename>.tar</filename> image, and then uses
 383       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> to
 384       open a shell in it.</para>
 385     </example>
 386
 387     <example id="example-import-raw">
 388       <title>Download an Ubuntu RAW image, set a root password in it, start
 389       it as a service</title>
 390
 391       <programlisting># importctl pull-raw -mN \
 392       https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64-disk-kvm.img \
 393       jammy
 394 # systemd-firstboot --image=/var/lib/machines/jammy.raw --prompt-root-password --force
 395 # machinectl start jammy
 396 # machinectl login jammy</programlisting>
 397
 398       <para>This downloads the specified <filename>.raw</filename> image and makes it available under the
 399       local name <literal>jammy</literal>. Then, a root password is set with
 400       <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Afterwards
 401       the machine is started as system service. With the last command a login prompt into the container is
 402       requested.</para>
 403     </example>
 404
 405     <example id="example-export-tar">
 406       <title>Exports a container image as tar file</title>
 407
 408       <programlisting># importctl export-tar -m fedora myfedora.tar.xz</programlisting>
 409
 410       <para>Exports the container <literal>fedora</literal> as an xz-compressed tar file
 411       <filename>myfedora.tar.xz</filename> into the current directory.</para>
 412     </example>
 413   </refsect1>
 414
 415   <refsect1>
 416     <title>Exit status</title>
 417
 418     <para>On success, 0 is returned, a non-zero failure code
 419     otherwise.</para>
 420   </refsect1>
 421
 422   <xi:include href="common-variables.xml" />
 423
 424   <refsect1>
 425     <title>See Also</title>
 426     <para><simplelist type="inline">
 427       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 428       <member><citerefentry><refentrytitle>systemd-importd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 429       <member><citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 430       <member><citerefentry><refentrytitle>systemd-vmspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 431       <member><citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 432       <member><citerefentry><refentrytitle>portablectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 433       <member><citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 434       <member><citerefentry><refentrytitle>systemd-confext</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 435       <member><citerefentry project='die-net'><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 436       <member><citerefentry project='die-net'><refentrytitle>xz</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 437       <member><citerefentry project='die-net'><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 438       <member><citerefentry project='die-net'><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 439     </simplelist></para>
 440   </refsect1>
 441
 442 </refentry>