# systemd-import-generator

## NAME



           systemd-import-generator - Generator for automatically downloading
           disk images at boot
    


## SYNOPSIS



           /usr/lib/systemd/system-generators/systemd-import-generator
    


## DESCRIPTION



           **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.
    
           systemd-import-generator implements systemd.generator(7).
    


## KERNEL COMMAND LINE



           systemd-import-generator understands the following
           kernel-command-line(7) parameters:
    
           _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:
    
               rw, ro
                   Controls whether to mark the local image as read-only. If
                   not specified read-only defaults to off.
    
                   Added in version 257.
    
               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.
    
               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.
    
               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.
    
               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 **Discoverable Disk Image**
                   **Specification******[1] as root file system, and the automatic
                   GPT partition discovery logic as implemented bysystemd-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.
    
               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.
    
               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.
    
               Added in version 257.
    
           _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.
    
           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.
    


## CREDENTIALS



           **systemd-import-generator** supports the system credentials logic.
           The following credentials are used when passed in:
    
           _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.
    


## EXAMPLES



           **Example 1. Download Configuration Extension**
    
               systemd.pull=raw,confext::https://example.com/myconfext.raw.gz
    
           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.
    
           **Example 2. Download System Extension (Without Validation)**
    
               systemd.pull=tar,sysext,verify=no::https://example.com/mysysext.tar.gz
    
           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!
    
           **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
    
           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.
    
           **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
    
           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.
    
           **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
    
           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.
    


## NOTES



            1. Discoverable Disk Image Specification
               https://uapi-group.org/specifications/specs/discoverable_disk_image/
    


* * *