mirror of
https://github.com/morgan9e/systemd
synced 2026-04-14 08:25:20 +09:00
f8825c1364
So far the gpt-auto logic only looked for the partition table of devices that the ESP/XBOOTLDR partition used to boot was on. This works great for local boots, but is more problematic if we boot a UKI via UEFI HTTP boot, because there is no ESP in play in that case. Let's introduce an alternative to communicate the intended default root disk to cover for this situation: any loopback block device whose backing file field (i.e. the userspace controlled freeform field we use for /dev/disk/by-loop-ref/ naming) is set to "rootdisk" will be consider for gpt-auto will be consider for gpt-auto. With this in place we should have nice automatic behaviour: 1. If we are booted locally we'll get the ESP/XBOOTLDR data, and derive the root disk from that. 2. If we are booted via UEFI HTTP boot we expect that the caller makes the loopback device appear with the right loop-ref identifier, and then will use that.
283 lines
14 KiB
XML
283 lines
14 KiB
XML
<?xml version="1.0"?>
|
||
<!--*-nxml-*-->
|
||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||
<!ENTITY % entities SYSTEM "custom-entities.ent" >
|
||
%entities;
|
||
]>
|
||
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
|
||
<refentry id="systemd-import-generator"
|
||
xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
||
<refentryinfo>
|
||
<title>systemd-import-generator</title>
|
||
<productname>systemd</productname>
|
||
</refentryinfo>
|
||
|
||
<refmeta>
|
||
<refentrytitle>systemd-import-generator</refentrytitle>
|
||
<manvolnum>8</manvolnum>
|
||
</refmeta>
|
||
|
||
<refnamediv>
|
||
<refname>systemd-import-generator</refname>
|
||
<refpurpose>Generator for automatically downloading disk images at boot</refpurpose>
|
||
</refnamediv>
|
||
|
||
<refsynopsisdiv>
|
||
<para><filename>/usr/lib/systemd/system-generators/systemd-import-generator</filename></para>
|
||
</refsynopsisdiv>
|
||
|
||
<refsect1>
|
||
<title>Description</title>
|
||
|
||
<para><command>systemd-import-generator</command> may be used to automatically download disk images
|
||
(tarballs or DDIs) via
|
||
<citerefentry><refentrytitle>systemd-importd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
||
at boot, based on parameters on the kernel command line or via system credentials. This is useful for
|
||
automatically deploying an
|
||
<citerefentry><refentrytitle>systemd-confext</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
||
<citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
||
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>/
|
||
<citerefentry><refentrytitle>systemd-vmspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> or
|
||
<citerefentry><refentrytitle>systemd-portabled.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
||
image at boot. This provides functionality equivalent to
|
||
<citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, but
|
||
accessible via the kernel command line and system credentials.</para>
|
||
|
||
<para><filename>systemd-import-generator</filename> implements
|
||
<citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Kernel Command Line</title>
|
||
|
||
<para><filename>systemd-import-generator</filename> understands the following
|
||
<citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
||
parameters:</para>
|
||
|
||
<variablelist class='kernel-commandline-options'>
|
||
<varlistentry>
|
||
<term><varname>systemd.pull=</varname></term>
|
||
|
||
<listitem><para>This option takes a colon separate triplet of option string, local target image name
|
||
and remote URL. The local target image name can be specified as an empty string, in which case the
|
||
name is derived from the specified remote URL. The remote URL must using the
|
||
<literal>http://</literal>, <literal>https://</literal>, <literal>file://</literal> schemes. The
|
||
option string itself is a comma separated list of options:</para>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>rw</term>
|
||
<term>ro</term>
|
||
|
||
<listitem><para>Controls whether to mark the local image as read-only. If not
|
||
specified read-only defaults to off.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v257"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term>verify=</term>
|
||
|
||
<listitem><para>Controls whether to cryptographically validate the download before installing it
|
||
in place. Takes one of <literal>no</literal>, <literal>checksum</literal> or
|
||
<literal>signature</literal> (the latter being the default if not specified). For details see the
|
||
<option>--verify=</option> of
|
||
<citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v257"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term>sysext</term>
|
||
<term>confext</term>
|
||
<term>machine</term>
|
||
<term>portable</term>
|
||
|
||
<listitem><para>Controls the image class to download, and thus ultimately the target directory
|
||
for the image, depending on this choice the target directory
|
||
<filename>/var/lib/extensions/</filename>, <filename>/var/lib/confexts/</filename>,
|
||
<filename>/var/lib/machines/</filename> or <filename>/var/lib/portables/</filename> is
|
||
selected.</para>
|
||
|
||
<para>Specification of exactly one of these options is mandatory.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v257"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term>tar</term>
|
||
<term>raw</term>
|
||
|
||
<listitem><para>Controls the type of resource to download, i.e. a (possibly compressed) tarball
|
||
that needs to be unpacked into a file system tree, or (possibly compressed) raw disk image (DDI).</para>
|
||
|
||
<para>Specification of exactly one of these options is mandatory.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v257"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term>blockdev</term>
|
||
|
||
<listitem><para>If this option is specified the downloaded image is attached to a loopback block
|
||
device (via <filename>systemd-loop@.service</filename>) after completion. This permits booting
|
||
from downloaded disk images. This is only supported for <literal>raw</literal> disk images.</para>
|
||
|
||
<para>Note when this option is used with the purpose of mounting a disk image conforming to the
|
||
<ulink url="https://uapi-group.org/specifications/specs/discoverable_disk_image/">Discoverable
|
||
Disk Image Specification</ulink> as root file system, and the automatic GPT partition discovery
|
||
logic as implemented by
|
||
<citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
||
shall process it, it's essential to specify <literal>rootdisk</literal> as the local name for the
|
||
import. Moreover, <literal>root=gpt-auto</literal> must be specified on the kernel command line
|
||
explicitly. Also, prefix the <literal>systemd.pull=</literal> commmand line option with
|
||
<literal>rd.</literal> to ensure it is executed in the initial RAM disk (initrd) already, also
|
||
see below.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term>bootorigin</term>
|
||
|
||
<listitem><para>If this option is specified, in place of the URL a simple filename may be
|
||
specified. If the system is booted via UEFI HTTP network booting the last component of the
|
||
network boot origin URL is replaced by this filename and used as download source. This hence
|
||
allows to automatically derive the URLs for disk images from the original boot URL used to invoke
|
||
the kernel or boot loader.</para>
|
||
|
||
<para>If this option is used and the system is not actually booted via UEFI HTTP network booting,
|
||
the download is gracefully skipped. Or in other words without other modifications it is possible
|
||
to put together an initrd image that will boot from a local disk if available, or from downloaded
|
||
disk image if used via network booting.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term>runtime=</term>
|
||
|
||
<listitem><para>Takes a boolean argument. If set to true, the image is downloaded below the
|
||
<filename>/run/</filename> hierarchy, if set to false below the <filename>/var/lib/</filename>
|
||
hierarchy. If not specified defaults to true in the initial RAM disk (initrd) and to false on the
|
||
host system.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v257"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>systemd.pull.success_action=</varname></term>
|
||
<term><varname>systemd.pull.failure_action=</varname></term>
|
||
|
||
<listitem><para>Controls whether to execute an action such as reboot, power-off and similar after
|
||
completing the download successfully, or unsuccessfully. See
|
||
<varname>SuccessAction=</varname>/<varname>FailureAction=</varname> on
|
||
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
|
||
details about the available actions. If not specified, no action is taken, and the system will
|
||
continue to boot normally.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v257"/></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>These kernel command line options are interpreted by the host system only. If these options are
|
||
prefixed with <literal>rd.</literal> they are interpreted by the initial RAM disk (initrd)
|
||
instead.</para>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Credentials</title>
|
||
|
||
<para><command>systemd-import-generator</command> supports the system credentials logic. The following
|
||
credentials are used when passed in:</para>
|
||
|
||
<variablelist class='system-credentials'>
|
||
<varlistentry>
|
||
<term><varname>import.pull</varname></term>
|
||
|
||
<listitem><para>This credential should be a text file, with each line referencing one download
|
||
operation. Each line should follow the same format as the value of the
|
||
<varname>systemd.pull=</varname> kernel command line option described above.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v257"/></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Examples</title>
|
||
|
||
<example>
|
||
<title>Download Configuration Extension</title>
|
||
|
||
<programlisting>systemd.pull=raw,confext::https://example.com/myconfext.raw.gz</programlisting>
|
||
|
||
<para>With a kernel command line option like the above a configuration extension DDI is downloaded
|
||
automatically at boot from the specified URL, validated cryptographically, uncompressed and installed.</para>
|
||
</example>
|
||
|
||
<example>
|
||
<title>Download System Extension (Without Validation)</title>
|
||
|
||
<programlisting>systemd.pull=tar,sysext,verify=no::https://example.com/mysysext.tar.gz</programlisting>
|
||
|
||
<para>With a kernel command line option like the above a system extension tarball is downloaded
|
||
automatically at boot from the specified URL, uncompressed and installed – without any cryptographic
|
||
validation. This is useful for development purposes in virtual machines and containers. Warning: do not
|
||
deploy a system with validation disabled like this!</para>
|
||
</example>
|
||
|
||
<example>
|
||
<title>Download root disk image (raw) into memory, for booting into it</title>
|
||
|
||
<programlisting>rd.systemd.pull=raw,machine,verify=no,blockdev:image:https://example.com/image.raw.xz root=/dev/disk/by-loop-ref/image.raw-part2</programlisting>
|
||
|
||
<para>This downloads the specified disk image, saving it locally under the name
|
||
<literal>image</literal>, and attaches it to a loopback block device on completion. It then boots from
|
||
the 2nd partition in the image.</para>
|
||
</example>
|
||
|
||
<example>
|
||
<title>Boot into disk image (raw), with URL derived from UEFI HTTP network booting</title>
|
||
|
||
<programlisting>rd.systemd.pull=raw,machine,verify=no,blockdev,bootorigin:rootdisk:image.raw.xz root=gpt-auto</programlisting>
|
||
|
||
<para>This is similar to the previous example, but this time the source URL is automatically derived
|
||
from the UEFI HTTP network boot URL. For example, if an UKI is booted from an URL
|
||
<literal>http://example.com/image.efi</literal> this would result in a root disk being downloaded from
|
||
<literal>http://example.com/image.raw.xz</literal>. Moreover this uses the
|
||
<citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
||
logic to mount the root file system from the disk image.</para>
|
||
</example>
|
||
|
||
<example>
|
||
<title>Boot into disk image (tar), with URL derived from UEFI HTTP network booting</title>
|
||
|
||
<programlisting>rd.systemd.pull=tar,machine,verify=no,bootorigin:root:image.tar.xz root=bind:/run/machines/root</programlisting>
|
||
|
||
<para>This is similar to the previous example, but instead of a raw (i.e. block device based) disk
|
||
image the system boots into a tarball that is downloaded from the originating UEFI network
|
||
server.</para>
|
||
</example>
|
||
</refsect1>
|
||
|
||
<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>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
|
||
<member><citerefentry><refentrytitle>systemd.system-credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
|
||
<member><citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
|
||
<member><citerefentry><refentrytitle>systemd-loop@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
|
||
<member><citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
|
||
</simplelist></para>
|
||
</refsect1>
|
||
</refentry>
|