| SYSTEMD-IMPORT-GENERATOR(8) | systemd-import-generator | SYSTEMD-IMPORT-GENERATOR(8) |
.SH "NAME" systemd-import-generator - Generator for automatically
downloading disk images at boot
.SH "SYNOPSIS"
.PP /usr/lib/systemd/system-generators/systemd-import-generator
.SH "DESCRIPTION"
.PP systemd-import-generator may be used to automatically download
disk images (tarballs or DDIs) via systemd-importd.service(8) at
boot, based on parameters on the kernel command line or via system
credentials. This is useful for automatically deploying an
systemd-confext(8), systemd-sysext(8),
systemd-nspawn(1)/ systemd-vmspawn(1) or
systemd-portabled.service(8) image at boot. This provides
functionality equivalent to importctl(1), but accessible via the
kernel command line and system credentials.
.PP systemd-import-generator implements systemd.generator(7).
.SH "KERNEL COMMAND LINE"
.PP systemd-import-generator understands the following
kernel-command-line(7) parameters:
.PP systemd.pull=
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 http://, https://, file:// schemes. The
option string itself is a comma separated list of options:
.PP rw, ro
Controls whether to mark the local image as read-only. If not specified
read-only defaults to off.
Added in version 257.
.RE
.PP verify=
Controls whether to cryptographically validate the download before installing
it in place. Takes one of no, checksum, or signature (the default if not
specified). For details see the --verify= of importctl(1).
Added in version 257.
.RE
.PP sysext, confext, machine, portable
Controls the image class to download, and thus ultimately the target
directory for the image, depending on this choice the target directory
/var/lib/extensions/, /var/lib/confexts/, /var/lib/machines/ or
/var/lib/portables/ is selected.
Specification of exactly one of these options is mandatory.
Added in version 257.
.RE
.PP tar, raw
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).
Specification of exactly one of these options is mandatory.
Added in version 257.
.RE
.PP blockdev
If this option is specified the downloaded image is attached to a loopback
block device (via systemd-loop@.service) after completion. This permits
booting from downloaded disk images. This is only supported for raw disk
images.
Note when this option is used with the purpose of mounting a disk image
conforming to the UAPI.3 Discoverable Disk Image Specification[1] as
root file system, and the automatic GPT partition discovery logic as
implemented by systemd-gpt-auto-generator(8) shall process it, it's
essential to specify rootdisk as the local name for the import. Moreover,
root=gpt-auto must be specified on the kernel command line explicitly. Also,
prefix the systemd.pull= command line option with rd. to ensure it is
executed in the initial RAM disk (initrd) already, also see below.
Added in version 258.
.RE
.PP bootorigin
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 one to automatically derive the
URLs for disk images from the original boot URL used to invoke the kernel or
boot loader.
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.
Added in version 258.
.RE
.PP runtime=
Takes a boolean argument. If set to true, the image is downloaded below the
/run/ hierarchy, if set to false below the /var/lib/ hierarchy. If not
specified defaults to true in the initial RAM disk (initrd) and to false on
the host system.
Added in version 258.
.RE
.sp
Added in version 257.
.RE
.PP systemd.pull.success_action=,
systemd.pull.failure_action=
Controls whether to execute an action such as reboot, power-off and similar
after completing the download successfully, or unsuccessfully. See
SuccessAction=/FailureAction= on systemd.unit(5) for
details about the available actions. If not specified, no action is taken,
and the system will continue to boot normally.
Added in version 257.
.RE
.PP These kernel command line options are interpreted by the host system
only. If these options are prefixed with rd. they are interpreted by the
initial RAM disk (initrd) instead.
.SH "CREDENTIALS"
.PP systemd-import-generator supports the system credentials logic.
The following credentials are used when passed in:
.PP import.pull
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 systemd.pull= kernel command line option described above.
Added in version 257.
.RE
.SH "EXAMPLES"
.PP Example 1. Download Configuration Extension
systemd.pull=raw,confext::https://example.com/myconfext.raw.gz
.PP 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.
.PP Example 2. Download System Extension (Without
Validation)
systemd.pull=tar,sysext,verify=no::https://example.com/mysysext.tar.gz
.PP 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!
.PP Example 3. Download root disk image (raw) into memory,
for booting into it
rd.systemd.pull=raw,machine,verify=no,blockdev:image:https://example.com/image.raw.xz root=/dev/disk/by-loop-ref/image.raw-part2
.PP This downloads the specified disk image, saving it locally under the name
image, and attaches it to a loopback block device on completion. It then
boots from the 2nd partition in the image.
.PP Example 4. Boot into disk image (raw), with URL derived
from UEFI HTTP network booting
rd.systemd.pull=raw,machine,verify=no,blockdev,bootorigin:rootdisk:image.raw.xz root=gpt-auto
.PP 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 http://example.com/image.efi this would result
in a root disk being downloaded from http://example.com/image.raw.xz.
Moreover this uses the systemd-gpt-auto-generator(8) logic to mount
the root file system from the disk image.
.PP Example 5. Boot into disk image (tar), with URL derived
from UEFI HTTP network booting
rd.systemd.pull=tar,machine,verify=no,bootorigin:root:image.tar.xz root=bind:/run/machines/root
.PP 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.
.SH "SEE ALSO"
.PP systemd(1), systemd-importd.service(8),
kernel-command-line(7), systemd.system-credentials(7),
importctl(1), systemd-loop@.service(8),
systemd-gpt-auto-generator(8)
NOTES
- 1.
- UAPI.3 Discoverable Disk Image Specification
| systemd 262.2 |