mirror of
https://github.com/systemd/systemd.git
synced 2024-10-27 01:55:22 +03:00
195 lines
8.7 KiB
XML
195 lines
8.7 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>
|
||
</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>
|
||
</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>
|
||
</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>
|
||
</simplelist></para>
|
||
</refsect1>
|
||
</refentry>
|