Merge pull request #27670 from poettering/switch-root-umount-all

[thirdparty/systemd.git] / man / ukify.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">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<refentry id="ukify" xmlns:xi="http://www.w3.org/2001/XInclude" conditional='ENABLE_UKIFY'>

  <refentryinfo>
    <title>ukify</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>ukify</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>ukify</refname>
    <refpurpose>Combine components into a signed Unified Kernel Image for UEFI systems</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>/usr/lib/systemd/ukify</command>
      <arg choice="opt"><replaceable>LINUX</replaceable></arg>
      <arg choice="opt" rep="repeat"><replaceable>INITRD</replaceable></arg>
      <arg choice="opt" rep="repeat">OPTIONS</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para>Note: this command is experimental for now. While it is intended to become a regular component of
    systemd, it might still change in behaviour and interface.</para>

    <para><command>ukify</command> is a tool that combines components (e.g.: a kernel and an initrd with
    a UEFI boot stub) to create a
    <ulink url="https://uapi-group.org/specifications/specs/unified_kernel_image/">Unified Kernel Image (UKI)</ulink>
    — a PE binary that can be executed by the firmware to start the embedded linux kernel.
    See <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>
    for details about the stub.</para>

    <para>Additional sections will be inserted into the UKI, either automatically or only if a specific
    option is provided. See the discussions of
    <varname>Cmdline=</varname>/<option>--cmdline=</option>,
    <varname>OSRelease=</varname>/<option>--os-release=</option>,
    <varname>DeviceTree=</varname>/<option>--devicetree=</option>,
    <varname>Splash=</varname>/<option>--splash=</option>,
    <varname>PCRPKey=</varname>/<option>--pcrpkey=</option>,
    <varname>Uname=</varname>/<option>--uname=</option>,
    and <option>--section=</option>
    below.</para>

    <para><command>ukify</command> can also be used to assemble a PE binary that is not executable but
    contains auxiliary data, for example additional kernel command line entries.</para>

    <para>If PCR signing keys are provided via the
    <varname>PCRPrivateKey=</varname>/<option>--pcr-private-key=</option> and
    <varname>PCRPublicKey=</varname>/<option>--pcr-public-key=</option> options, PCR values that will be seen
    after booting with the given kernel, initrd, and other sections, will be calculated, signed, and embedded
    in the UKI.
    <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry> is
    used to perform this calculation and signing.</para>

    <para>The calculation of PCR values is done for specific boot phase paths. Those can be specified with
    the <varname>Phases=</varname>/<option>--phases=</option> option. If not specified, the default provided
    by <command>systemd-measure</command> is used. It is also possible to specify the
    <varname>PCRPrivateKey=</varname>/<option>--pcr-private-key=</option>,
    <varname>PCRPublicKey=</varname>/<option>--pcr-public-key=</option>, and
    <varname>Phases=</varname>/<option>--phases=</option> arguments more than once. Signatures will then be
    performed with each of the specified keys. On the command line, when both <option>--phases=</option> and
    <option>--pcr-private-key=</option> are used, they must be specified the same number of times, and then
    the n-th boot phase path set will be signed by the n-th key. This can be used to build different trust
    policies for different phases of the boot. In the config file, <varname>PCRPrivateKey=</varname>,
    <varname>PCRPublicKey=</varname>, and <varname>Phases=</varname> are grouped into separate sections,
    describing separate boot phases.</para>

    <para>If a SecureBoot signing key is provided via the
    <varname>SecureBootPrivateKey=</varname>/<option>--secureboot-private-key=</option> option, the resulting
    PE binary will be signed as a whole, allowing the resulting UKI to be trusted by SecureBoot. Also see the
    discussion of automatic enrollment in
    <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
    </para>
  </refsect1>

  <refsect1>
    <title>Configuration settings</title>

    <para>Settings can appear in configuration files (the syntax with <varname
    index='false'>SomeSetting=<replaceable>value</replaceable></varname>) and on the command line (the syntax
    with <option index='false'>--some-setting=<replaceable>value</replaceable></option>). For some command
    line parameters, a single-letter shortcut is also allowed. In the configuration files, the setting must
    be in the appropriate section, so the descriptions are grouped by section below. When the same setting
    appears in the configuration file and on the command line, generally the command line setting has higher
    priority and overwrites the config file setting completely. If some setting behaves differently, this is
    described below.</para>

    <para>The <replaceable>LINUX</replaceable> and <replaceable>INITRD</replaceable> positional arguments, or
    the equivalent <varname>Linux=</varname> and <varname>Initrd=</varname> settings, are optional. If more
    than one initrd is specified, they will all be combined into a single PE section. This is useful to, for
    example, prepend microcode before the actual initrd.</para>

    <para>The following options and settings are understood:</para>

    <refsect2>
      <title>Commandline-only options</title>

      <variablelist>
        <varlistentry>
          <term><option>--config=<replaceable>PATH</replaceable></option></term>

          <listitem><para>Load configuration from the given config file. In general, settings specified in
          the config file have lower precedence than the settings specified via options. In cases where the
          commandline option does not fully override the config file setting are explicitly mentioned in the
          descriptions of individual options.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--measure</option></term>
          <term><option>--no-measure</option></term>

          <listitem><para>Enable or disable a call to
          <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
          to print pre-calculated PCR values. Defaults to false.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--section=<replaceable>NAME</replaceable>:<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term>

          <listitem><para>Specify an arbitrary additional section
          <literal><replaceable>NAME</replaceable></literal>. Note that the name is used as-is, and if the
          section name should start with a dot, it must be included in <replaceable>NAME</replaceable>. The
          argument may be a literal string, or <literal>@</literal> followed by a path name. This option may be
          specified more than once. Any sections specified in this fashion will be inserted (in order) before
          the <literal>.linux</literal> section which is always last.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--tools=<replaceable>DIRS</replaceable></option></term>

          <listitem><para>Specify one or more directories with helper tools. <command>ukify</command> will
          look for helper tools in those directories first, and if not found, try to load them from
          <varname>$PATH</varname> in the usual fashion.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--output=<replaceable>FILENAME</replaceable></option></term>

          <listitem><para>The output filename. If not specified, the name of the
          <replaceable>LINUX</replaceable> argument, with the suffix <literal>.unsigned.efi</literal> or
          <literal>.signed.efi</literal> will be used, depending on whether signing for SecureBoot was
          performed.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--summary</option></term>

          <listitem><para>Print a summary of loaded config and exit. This is useful to check how the options
          form the configuration file and the commandline are combined.</para></listitem>
        </varlistentry>

        <xi:include href="standard-options.xml" xpointer="help" />
        <xi:include href="standard-options.xml" xpointer="version" />
      </variablelist>
    </refsect2>

    <refsect2>
      <title>[UKI] section</title>

      <variablelist>
        <varlistentry>
          <term><varname>Linux=<replaceable>LINUX</replaceable></varname></term>
          <term>positional argument <replaceable>LINUX</replaceable></term>

          <listitem><para>A path to the kernel binary.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>Initrd=<replaceable>INITRD</replaceable>...</varname></term>
          <term>positional argument <replaceable>INITRD</replaceable></term>

          <listitem><para>Zero or more initrd paths. In the configuration file, items are separated by
          whitespace. The initrds are combined in the order of specification, with the initrds specified in
          the config file first.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>Cmdline=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></varname></term>
          <term><option>--cmdline=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term>

          <listitem><para>The kernel command line (the <literal>.cmdline</literal> section). The argument may
          be a literal string, or <literal>@</literal> followed by a path name. If not specified, no command
          line will be embedded.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>OSRelease=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></varname></term>
          <term><option>--os-release=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term>

          <listitem><para>The os-release description (the <literal>.osrel</literal> section). The argument
          may be a literal string, or <literal>@</literal> followed by a path name. If not specified, the
          <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file
          will be picked up from the host system.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>DeviceTree=<replaceable>PATH</replaceable></varname></term>
          <term><option>--devicetree=<replaceable>PATH</replaceable></option></term>

          <listitem><para>The devicetree description (the <literal>.dtb</literal> section). The argument is a
          path to a compiled binary DeviceTree file. If not specified, the section will not be present.
          </para></listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>Splash=<replaceable>PATH</replaceable></varname></term>
          <term><option>--splash=<replaceable>PATH</replaceable></option></term>

          <listitem><para>A picture to display during boot (the <literal>.splash</literal> section). The
          argument is a path to a BMP file. If not specified, the section will not be present.
          </para></listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>PCRPKey=<replaceable>PATH</replaceable></varname></term>
          <term><option>--pcrpkey=<replaceable>PATH</replaceable></option></term>

          <listitem><para>A path to a public key to embed in the <literal>.pcrpkey</literal> section. If not
          specified, and there's exactly one
          <varname>PCRPublicKey=</varname>/<option>--pcr-public-key=</option> argument, that key will be used.
          Otherwise, the section will not be present.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>Uname=<replaceable>VERSION</replaceable></varname></term>
          <term><option>--uname=<replaceable>VERSION</replaceable></option></term>

          <listitem><para>Specify the kernel version (as in <command>uname -r</command>, the
          <literal>.uname</literal> section). If not specified, an attempt will be made to extract the
          version string from the kernel image. It is recommended to pass this explicitly if known, because
          the extraction is based on heuristics and not very reliable. If not specified and extraction fails,
          the section will not be present.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>PCRBanks=<replaceable>PATH</replaceable></varname></term>
          <term><option>--pcr-banks=<replaceable>PATH</replaceable></option></term>

          <listitem><para>A comma or space-separated list of PCR banks to sign a policy for. If not present,
          all known banks will be used (<literal>sha1</literal>, <literal>sha256</literal>,
          <literal>sha384</literal>, <literal>sha512</literal>), which will fail if not supported by the
          system.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>SecureBootSigningTool=<replaceable>SIGNER</replaceable></varname></term>
          <term><option>--signtool=<replaceable>SIGNER</replaceable></option></term>

          <listitem><para>Whether to use <literal>sbsign</literal> or <literal>pesign</literal>.
          Depending on this choice, different parameters are required in order to sign an image.
          Defaults to <literal>sbsign</literal>.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>SecureBootPrivateKey=<replaceable>SB_KEY</replaceable></varname></term>
          <term><option>--secureboot-private-key=<replaceable>SB_KEY</replaceable></option></term>

          <listitem><para>A path to a private key to use for signing of the resulting binary. If the
          <varname>SigningEngine=</varname>/<option>--signing-engine=</option> option is used, this may also be
          an engine-specific designation. This option is required by
          <varname>SecureBootSigningTool=sbsign</varname>/<option>--signtool=sbsign</option>. </para></listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>SecureBootCertificate=<replaceable>SB_CERT</replaceable></varname></term>
          <term><option>--secureboot-certificate=<replaceable>SB_CERT</replaceable></option></term>

          <listitem><para>A path to a certificate to use for signing of the resulting binary. If the
          <varname>SigningEngine=</varname>/<option>--signing-engine=</option> option is used, this may also
          be an engine-specific designation. This option is required by
          <varname>SecureBootSigningTool=sbsign</varname>/<option>--signtool=sbsign</option>. </para></listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>SecureBootCertificateDir=<replaceable>SB_PATH</replaceable></varname></term>
          <term><option>--secureboot-certificate-dir=<replaceable>SB_PATH</replaceable></option></term>

          <listitem><para>A path to a nss certificate database directory to use for signing of the resulting binary.
          Takes effect when <varname>SecureBootSigningTool=pesign</varname>/<option>--signtool=pesign</option> is used.
          Defaults to <filename>/etc/pki/pesign</filename>.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>SecureBootCertificateName=<replaceable>SB_CERTNAME</replaceable></varname></term>
          <term><option>--secureboot-certificate-name=<replaceable>SB_CERTNAME</replaceable></option></term>

          <listitem><para>The name of the nss certificate database entry to use for signing of the resulting binary.
          This option is required by <varname>SecureBootSigningTool=pesign</varname>/<option>--signtool=pesign</option>.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>SigningEngine=<replaceable>ENGINE</replaceable></varname></term>
          <term><option>--signing-engine=<replaceable>ENGINE</replaceable></option></term>

          <listitem><para>An "engine" for signing of the resulting binary. This option is currently passed
          verbatim to the <option>--engine=</option> option of
          <citerefentry project='archlinux'><refentrytitle>sbsign</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
          </para></listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>SignKernel=<replaceable>BOOL</replaceable></varname></term>
          <term><option>--sign-kernel</option></term>
          <term><option>--no-sign-kernel</option></term>

          <listitem><para>Override the detection of whether to sign the Linux binary itself before it is
          embedded in the combined image. If not specified, it will be signed if a SecureBoot signing key is
          provided via the
          <varname>SecureBootPrivateKey=</varname>/<option>--secureboot-private-key=</option> option and the
          binary has not already been signed. If
          <varname>SignKernel=</varname>/<option>--sign-kernel</option> is true, and the binary has already
          been signed, the signature will be appended anyway.</para></listitem>
        </varlistentry>
      </variablelist>
    </refsect2>

    <refsect2>
      <title>[PCRSignature:<replaceable>NAME</replaceable>] section</title>

      <para>In the config file, those options are grouped by section. On the commandline, they
      must be specified in the same order. The sections specified in both sources are combined.
      </para>

      <variablelist>
        <varlistentry>
          <term><varname>PCRPrivateKey=<replaceable>PATH</replaceable></varname></term>
          <term><option>--pcr-private-key=<replaceable>PATH</replaceable></option></term>

          <listitem><para>A private key to use for signing PCR policies. On the commandline, this option may
          be specified more than once, in which case multiple signatures will be made.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>PCRPublicKey=<replaceable>PATH</replaceable></varname></term>
          <term><option>--pcr-public-key=<replaceable>PATH</replaceable></option></term>

          <listitem><para>A public key to use for signing PCR policies.</para>

          <para>On the commandline, this option may be specified more than once, similarly to the
          <option>--pcr-private-key=</option> option. If not present, the public keys will be extracted from
          the private keys. On the commandline, if present, the this option must be specified the same number
          of times as the <option>--pcr-private-key=</option> option.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>Phases=<replaceable>LIST</replaceable></varname></term>
          <term><option>--phases=<replaceable>LIST</replaceable></option></term>

          <listitem><para>A comma or space-separated list of colon-separated phase paths to sign a policy
          for. Each set of boot phase paths will be signed with the corresponding private key. If not
          present, the default of
          <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
          will be used.</para>

          <para>On the commandline, when this argument is present, it must appear the same number of times as
          the <option>--pcr-private-key=</option> option. </para></listitem>
        </varlistentry>
      </variablelist>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>Examples</title>

    <example>
      <title>Minimal invocation</title>

      <programlisting>$ ukify \
      /lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
      /some/path/initramfs-6.0.9-300.fc37.x86_64.img \
      --cmdline='quiet rw'
      </programlisting>

      <para>This creates an unsigned UKI <filename>./vmlinuz.unsigned.efi</filename>.</para>
    </example>

    <example>
      <title>All the bells and whistles</title>

      <programlisting># /usr/lib/systemd/ukify \
      /lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
      early_cpio \
      /some/path/initramfs-6.0.9-300.fc37.x86_64.img \
      --pcr-private-key=pcr-private-initrd-key.pem \
      --pcr-public-key=pcr-public-initrd-key.pem \
      --phases='enter-initrd' \
      --pcr-private-key=pcr-private-system-key.pem \
      --pcr-public-key=pcr-public-system-key.pem \
      --phases='enter-initrd:leave-initrd enter-initrd:leave-initrd:sysinit \
                enter-initrd:leave-initrd:sysinit:ready' \
      --pcr-banks=sha384,sha512 \
      --secureboot-private-key=sb.key \
      --secureboot-certificate=sb.cert \
      --sign-kernel \
      --cmdline='quiet rw rhgb'
      </programlisting>

      <para>This creates a signed UKI <filename index='false'>./vmlinuz.signed.efi</filename>.
      The initrd section contains two concatenated parts, <filename index='false'>early_cpio</filename>
      and <filename index='false'>initramfs-6.0.9-300.fc37.x86_64.img</filename>.
      The policy embedded in the <literal>.pcrsig</literal> section will be signed for the initrd (the
      <constant>enter-initrd</constant> phase) with the key
      <filename index='false'>pcr-private-initrd-key.pem</filename>, and for the main system (phases
      <constant>leave-initrd</constant>, <constant>sysinit</constant>, <constant>ready</constant>) with the
      key <filename index='false'>pcr-private-system-key.pem</filename>. The Linux binary and the resulting
      combined image will be signed with the SecureBoot key <filename index='false'>sb.key</filename>.</para>
    </example>

    <example>
      <title>All the bells and whistles, via a config file</title>

      <para>This is the same as the previous example, but this time the configuration is stored in a
      file:</para>

      <programlisting>$ cat ukify.conf
[UKI]
Initrd=early_cpio
Cmdline=quiet rw rhgb

SecureBootPrivateKey=sb.key
SecureBootCerificate=sb.cert
SignKernel=yes
PCRBanks=sha384,sha512

[PCRSignature:initrd]
PCRPrivateKey=pcr-private-initrd-key.pem
PCRPublicKey=pcr-public-initrd-key.pem
Phases=enter-initrd

[PCRSignature:system]
PCRPrivateKey=pcr-private-system-key.pem
PCRPublicKey=pcr-public-system-key.pem
Phases=enter-initrd:leave-initrd
       enter-initrd:leave-initrd:sysinit
       enter-initrd:leave-initrd:sysinit:ready

# /usr/lib/systemd/ukify -c ukify.conf \
        /lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
        /some/path/initramfs-6.0.9-300.fc37.x86_64.img
      </programlisting>

      <para>One "initrd" (<filename index='false'>early_cpio</filename>) is specified in the config file, and
      the other initrd (<filename index='false'>initramfs-6.0.9-300.fc37.x86_64.img</filename>) is specified
      on the commandline. This may be useful for example when the first initrd contains microcode for the CPU
      and does not need to be updated when the kernel version changes, unlike the actual initrd.</para>
    </example>

    <example>
      <title>Kernel command line auxiliary PE</title>

      <programlisting>ukify \
      --secureboot-private-key=sb.key \
      --secureboot-certificate=sb.cert \
      --cmdline='debug' \
      --output=debug.cmdline
      </programlisting>

      <para>This creates a signed PE binary that contains the additional kernel command line parameter
      <literal>debug</literal>.</para>
    </example>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
     </para>
  </refsect1>

</refentry>