man/ukify.xml

   1 <?xml version="1.0"?>
   2 <!--*-nxml-*-->
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   4   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   5 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   6 <refentry id="ukify" xmlns:xi="http://www.w3.org/2001/XInclude" conditional='ENABLE_UKIFY'>
   7
   8   <refentryinfo>
   9     <title>ukify</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>ukify</refentrytitle>
  15     <manvolnum>1</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>ukify</refname>
  20     <refpurpose>Combine components into a signed Unified Kernel Image for UEFI systems</refpurpose>
  21   </refnamediv>
  22
  23   <refsynopsisdiv>
  24     <cmdsynopsis>
  25       <command>/usr/lib/systemd/ukify</command>
  26       <arg choice="opt" rep="repeat">OPTIONS</arg>
  27       <arg choice="plain">build</arg>
  28       <arg choice="plain">genkey</arg>
  29     </cmdsynopsis>
  30   </refsynopsisdiv>
  31
  32   <refsect1>
  33     <title>Description</title>
  34
  35     <para>Note: this command is experimental for now. While it is intended to become a regular component of
  36     systemd, it might still change in behaviour and interface.</para>
  37
  38     <para><command>ukify</command> is a tool whose primary purpose is to combine components (usually a
  39     kernel, an initrd, and a UEFI boot stub) to create a
  40     <ulink url="https://uapi-group.org/specifications/specs/unified_kernel_image/">Unified Kernel Image (UKI)</ulink>
  41     — a PE binary that can be executed by the firmware to start the embedded linux kernel.
  42     See <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>
  43     for details about the stub.</para>
  44   </refsect1>
  45
  46   <refsect1>
  47     <title>Commands</title>
  48
  49     <para>The following commands are understood:</para>
  50
  51     <refsect2>
  52       <title><command>build</command></title>
  53
  54       <para>This command creates a Unified Kernel Image. The two primary options that should be specified for
  55       the <command>build</command> verb are <varname>Linux=</varname>/<option>--linux=</option>, and
  56       <varname>Initrd=</varname>/<option>--initrd=</option>. <varname>Initrd=</varname> accepts multiple
  57       whitespace-separated paths and <option>--initrd=</option> can be specified multiple times.</para>
  58
  59       <para>Additional sections will be inserted into the UKI, either automatically or only if a specific
  60       option is provided. See the discussions of
  61       <varname>Cmdline=</varname>/<option>--cmdline=</option>,
  62       <varname>OSRelease=</varname>/<option>--os-release=</option>,
  63       <varname>DeviceTree=</varname>/<option>--devicetree=</option>,
  64       <varname>Splash=</varname>/<option>--splash=</option>,
  65       <varname>PCRPKey=</varname>/<option>--pcrpkey=</option>,
  66       <varname>Uname=</varname>/<option>--uname=</option>,
  67       <varname>SBAT=</varname>/<option>--sbat=</option>,
  68       and <option>--section=</option>
  69       below.</para>
  70
  71       <para><command>ukify</command> can also be used to assemble a PE binary that is not executable but
  72       contains auxiliary data, for example additional kernel command line entries.</para>
  73
  74       <para>If PCR signing keys are provided via the
  75       <varname>PCRPrivateKey=</varname>/<option>--pcr-private-key=</option> and
  76       <varname>PCRPublicKey=</varname>/<option>--pcr-public-key=</option> options, PCR values that will be seen
  77       after booting with the given kernel, initrd, and other sections, will be calculated, signed, and embedded
  78       in the UKI.
  79       <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry> is
  80       used to perform this calculation and signing.</para>
  81
  82       <para>The calculation of PCR values is done for specific boot phase paths. Those can be specified with
  83       the <varname>Phases=</varname>/<option>--phases=</option> option. If not specified, the default provided
  84       by <command>systemd-measure</command> is used. It is also possible to specify the
  85       <varname>PCRPrivateKey=</varname>/<option>--pcr-private-key=</option>,
  86       <varname>PCRPublicKey=</varname>/<option>--pcr-public-key=</option>, and
  87       <varname>Phases=</varname>/<option>--phases=</option> arguments more than once. Signatures will then be
  88       performed with each of the specified keys. On the command line, when both <option>--phases=</option> and
  89       <option>--pcr-private-key=</option> are used, they must be specified the same number of times, and then
  90       the n-th boot phase path set will be signed by the n-th key. This can be used to build different trust
  91       policies for different phases of the boot. In the config file, <varname>PCRPrivateKey=</varname>,
  92       <varname>PCRPublicKey=</varname>, and <varname>Phases=</varname> are grouped into separate sections,
  93       describing separate boot phases.</para>
  94
  95       <para>If a SecureBoot signing key is provided via the
  96       <varname>SecureBootPrivateKey=</varname>/<option>--secureboot-private-key=</option> option, the resulting
  97       PE binary will be signed as a whole, allowing the resulting UKI to be trusted by SecureBoot. Also see the
  98       discussion of automatic enrollment in
  99       <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 100       </para>
 101     </refsect2>
 102
 103     <refsect2>
 104       <title><command>genkey</command></title>
 105
 106       <para>This command creates the keys for PCR signing and the key and certificate used for SecureBoot
 107       signing. The same configuration options that determine what keys and in which paths will be needed for
 108       signing when <command>build</command> is used, here determine which keys will be created. See the
 109       discussion of <varname>PCRPrivateKey=</varname>/<option>--pcr-private-key=</option>,
 110       <varname>PCRPublicKey=</varname>/<option>--pcr-public-key=</option>, and
 111       <varname>SecureBootPrivateKey=</varname>/<option>--secureboot-private-key=</option> below.</para>
 112
 113       <para>The output files must not exist.</para>
 114     </refsect2>
 115   </refsect1>
 116
 117   <refsect1>
 118     <title>Configuration settings</title>
 119
 120     <para>Settings can appear in configuration files (the syntax with <varname
 121     index='false'>SomeSetting=<replaceable>value</replaceable></varname>) and on the command line (the syntax
 122     with <option index='false'>--some-setting=<replaceable>value</replaceable></option>). For some command
 123     line parameters, a single-letter shortcut is also allowed. In the configuration files, the setting must
 124     be in the appropriate section, so the descriptions are grouped by section below. When the same setting
 125     appears in the configuration file and on the command line, generally the command line setting has higher
 126     priority and overwrites the config file setting completely. If some setting behaves differently, this is
 127     described below.</para>
 128
 129     <para>The <replaceable>LINUX</replaceable> and <replaceable>INITRD</replaceable> positional arguments, or
 130     the equivalent <varname>Linux=</varname> and <varname>Initrd=</varname> settings, are optional. If more
 131     than one initrd is specified, they will all be combined into a single PE section. This is useful to, for
 132     example, prepend microcode before the actual initrd.</para>
 133
 134     <para>The following options and settings are understood:</para>
 135
 136     <refsect2>
 137       <title>Commandline-only options</title>
 138
 139       <variablelist>
 140         <varlistentry>
 141           <term><option>--config=<replaceable>PATH</replaceable></option></term>
 142
 143           <listitem><para>Load configuration from the given config file. In general, settings specified in
 144           the config file have lower precedence than the settings specified via options. In cases where the
 145           commandline option does not fully override the config file setting are explicitly mentioned in the
 146           descriptions of individual options.</para></listitem>
 147         </varlistentry>
 148
 149         <varlistentry>
 150           <term><option>--measure</option></term>
 151           <term><option>--no-measure</option></term>
 152
 153           <listitem><para>Enable or disable a call to
 154           <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 155           to print pre-calculated PCR values. Defaults to false.</para></listitem>
 156         </varlistentry>
 157
 158         <varlistentry>
 159           <term><option>--section=<replaceable>NAME</replaceable>:<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term>
 160
 161           <listitem><para>Specify an arbitrary additional section
 162           <literal><replaceable>NAME</replaceable></literal>. Note that the name is used as-is, and if the
 163           section name should start with a dot, it must be included in <replaceable>NAME</replaceable>. The
 164           argument may be a literal string, or <literal>@</literal> followed by a path name. This option may be
 165           specified more than once. Any sections specified in this fashion will be inserted (in order) before
 166           the <literal>.linux</literal> section which is always last.</para></listitem>
 167         </varlistentry>
 168
 169         <varlistentry>
 170           <term><option>--tools=<replaceable>DIRS</replaceable></option></term>
 171
 172           <listitem><para>Specify one or more directories with helper tools. <command>ukify</command> will
 173           look for helper tools in those directories first, and if not found, try to load them from
 174           <varname>$PATH</varname> in the usual fashion.</para></listitem>
 175         </varlistentry>
 176
 177         <varlistentry>
 178           <term><option>--output=<replaceable>FILENAME</replaceable></option></term>
 179
 180           <listitem><para>The output filename. If not specified, the name of the
 181           <replaceable>LINUX</replaceable> argument, with the suffix <literal>.unsigned.efi</literal> or
 182           <literal>.signed.efi</literal> will be used, depending on whether signing for SecureBoot was
 183           performed.</para></listitem>
 184         </varlistentry>
 185
 186         <varlistentry>
 187           <term><option>--summary</option></term>
 188
 189           <listitem><para>Print a summary of loaded config and exit. This is useful to check how the options
 190           form the configuration file and the commandline are combined.</para></listitem>
 191         </varlistentry>
 192
 193         <xi:include href="standard-options.xml" xpointer="help" />
 194         <xi:include href="standard-options.xml" xpointer="version" />
 195       </variablelist>
 196     </refsect2>
 197
 198     <refsect2>
 199       <title>[UKI] section</title>
 200
 201       <variablelist>
 202         <varlistentry>
 203           <term><varname>Linux=<replaceable>LINUX</replaceable></varname></term>
 204           <term><option>--linux=<replaceable>LINUX</replaceable></option></term>
 205
 206           <listitem><para>A path to the kernel binary.</para></listitem>
 207         </varlistentry>
 208
 209         <varlistentry>
 210           <term><varname>Initrd=<replaceable>INITRD</replaceable>...</varname></term>
 211           <term><option>--initrd=<replaceable>LINUX</replaceable></option></term>
 212
 213           <listitem><para>Zero or more initrd paths. In the configuration file, items are separated by
 214           whitespace. The initrds are combined in the order of specification, with the initrds specified in
 215           the config file first.</para></listitem>
 216         </varlistentry>
 217
 218         <varlistentry>
 219           <term><varname>Cmdline=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></varname></term>
 220           <term><option>--cmdline=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term>
 221
 222           <listitem><para>The kernel command line (the <literal>.cmdline</literal> section). The argument may
 223           be a literal string, or <literal>@</literal> followed by a path name. If not specified, no command
 224           line will be embedded.</para></listitem>
 225         </varlistentry>
 226
 227         <varlistentry>
 228           <term><varname>OSRelease=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></varname></term>
 229           <term><option>--os-release=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term>
 230
 231           <listitem><para>The os-release description (the <literal>.osrel</literal> section). The argument
 232           may be a literal string, or <literal>@</literal> followed by a path name. If not specified, the
 233           <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file
 234           will be picked up from the host system.</para></listitem>
 235         </varlistentry>
 236
 237         <varlistentry>
 238           <term><varname>DeviceTree=<replaceable>PATH</replaceable></varname></term>
 239           <term><option>--devicetree=<replaceable>PATH</replaceable></option></term>
 240
 241           <listitem><para>The devicetree description (the <literal>.dtb</literal> section). The argument is a
 242           path to a compiled binary DeviceTree file. If not specified, the section will not be present.
 243           </para></listitem>
 244         </varlistentry>
 245
 246         <varlistentry>
 247           <term><varname>Splash=<replaceable>PATH</replaceable></varname></term>
 248           <term><option>--splash=<replaceable>PATH</replaceable></option></term>
 249
 250           <listitem><para>A picture to display during boot (the <literal>.splash</literal> section). The
 251           argument is a path to a BMP file. If not specified, the section will not be present.
 252           </para></listitem>
 253         </varlistentry>
 254
 255         <varlistentry>
 256           <term><varname>PCRPKey=<replaceable>PATH</replaceable></varname></term>
 257           <term><option>--pcrpkey=<replaceable>PATH</replaceable></option></term>
 258
 259           <listitem><para>A path to a public key to embed in the <literal>.pcrpkey</literal> section. If not
 260           specified, and there's exactly one
 261           <varname>PCRPublicKey=</varname>/<option>--pcr-public-key=</option> argument, that key will be used.
 262           Otherwise, the section will not be present.</para></listitem>
 263         </varlistentry>
 264
 265         <varlistentry>
 266           <term><varname>Uname=<replaceable>VERSION</replaceable></varname></term>
 267           <term><option>--uname=<replaceable>VERSION</replaceable></option></term>
 268
 269           <listitem><para>Specify the kernel version (as in <command>uname -r</command>, the
 270           <literal>.uname</literal> section). If not specified, an attempt will be made to extract the
 271           version string from the kernel image. It is recommended to pass this explicitly if known, because
 272           the extraction is based on heuristics and not very reliable. If not specified and extraction fails,
 273           the section will not be present.</para></listitem>
 274         </varlistentry>
 275
 276         <varlistentry>
 277           <term><varname>PCRBanks=<replaceable>PATH</replaceable></varname></term>
 278           <term><option>--pcr-banks=<replaceable>PATH</replaceable></option></term>
 279
 280           <listitem><para>A comma or space-separated list of PCR banks to sign a policy for. If not present,
 281           all known banks will be used (<literal>sha1</literal>, <literal>sha256</literal>,
 282           <literal>sha384</literal>, <literal>sha512</literal>), which will fail if not supported by the
 283           system.</para></listitem>
 284         </varlistentry>
 285
 286         <varlistentry>
 287           <term><varname>SecureBootSigningTool=<replaceable>SIGNER</replaceable></varname></term>
 288           <term><option>--signtool=<replaceable>SIGNER</replaceable></option></term>
 289
 290           <listitem><para>Whether to use <literal>sbsign</literal> or <literal>pesign</literal>.
 291           Depending on this choice, different parameters are required in order to sign an image.
 292           Defaults to <literal>sbsign</literal>.</para></listitem>
 293         </varlistentry>
 294
 295         <varlistentry>
 296           <term><varname>SecureBootPrivateKey=<replaceable>SB_KEY</replaceable></varname></term>
 297           <term><option>--secureboot-private-key=<replaceable>SB_KEY</replaceable></option></term>
 298
 299           <listitem><para>A path to a private key to use for signing of the resulting binary. If the
 300           <varname>SigningEngine=</varname>/<option>--signing-engine=</option> option is used, this may also be
 301           an engine-specific designation. This option is required by
 302           <varname>SecureBootSigningTool=sbsign</varname>/<option>--signtool=sbsign</option>. </para></listitem>
 303         </varlistentry>
 304
 305         <varlistentry>
 306           <term><varname>SecureBootCertificate=<replaceable>SB_CERT</replaceable></varname></term>
 307           <term><option>--secureboot-certificate=<replaceable>SB_CERT</replaceable></option></term>
 308
 309           <listitem><para>A path to a certificate to use for signing of the resulting binary. If the
 310           <varname>SigningEngine=</varname>/<option>--signing-engine=</option> option is used, this may also
 311           be an engine-specific designation. This option is required by
 312           <varname>SecureBootSigningTool=sbsign</varname>/<option>--signtool=sbsign</option>. </para></listitem>
 313         </varlistentry>
 314
 315         <varlistentry>
 316           <term><varname>SecureBootCertificateDir=<replaceable>SB_PATH</replaceable></varname></term>
 317           <term><option>--secureboot-certificate-dir=<replaceable>SB_PATH</replaceable></option></term>
 318
 319           <listitem><para>A path to a nss certificate database directory to use for signing of the resulting binary.
 320           Takes effect when <varname>SecureBootSigningTool=pesign</varname>/<option>--signtool=pesign</option> is used.
 321           Defaults to <filename>/etc/pki/pesign</filename>.</para></listitem>
 322         </varlistentry>
 323
 324         <varlistentry>
 325           <term><varname>SecureBootCertificateName=<replaceable>SB_CERTNAME</replaceable></varname></term>
 326           <term><option>--secureboot-certificate-name=<replaceable>SB_CERTNAME</replaceable></option></term>
 327
 328           <listitem><para>The name of the nss certificate database entry to use for signing of the resulting binary.
 329           This option is required by <varname>SecureBootSigningTool=pesign</varname>/<option>--signtool=pesign</option>.</para></listitem>
 330         </varlistentry>
 331
 332         <varlistentry>
 333           <term><varname>SecureBootCertificateValidity=<replaceable>DAYS</replaceable></varname></term>
 334           <term><option>--secureboot-certificate-validity=<replaceable>DAYS</replaceable></option></term>
 335
 336           <listitem><para>Period of validity (in days) for a certificate created by
 337           <command>genkey</command>. Defaults to 3650, i.e. 10 years.</para></listitem>
 338         </varlistentry>
 339
 340         <varlistentry>
 341           <term><varname>SigningEngine=<replaceable>ENGINE</replaceable></varname></term>
 342           <term><option>--signing-engine=<replaceable>ENGINE</replaceable></option></term>
 343
 344           <listitem><para>An "engine" for signing of the resulting binary. This option is currently passed
 345           verbatim to the <option>--engine=</option> option of
 346           <citerefentry project='archlinux'><refentrytitle>sbsign</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 347           </para></listitem>
 348         </varlistentry>
 349
 350         <varlistentry>
 351           <term><varname>SignKernel=<replaceable>BOOL</replaceable></varname></term>
 352           <term><option>--sign-kernel</option></term>
 353           <term><option>--no-sign-kernel</option></term>
 354
 355           <listitem><para>Override the detection of whether to sign the Linux binary itself before it is
 356           embedded in the combined image. If not specified, it will be signed if a SecureBoot signing key is
 357           provided via the
 358           <varname>SecureBootPrivateKey=</varname>/<option>--secureboot-private-key=</option> option and the
 359           binary has not already been signed. If
 360           <varname>SignKernel=</varname>/<option>--sign-kernel</option> is true, and the binary has already
 361           been signed, the signature will be appended anyway.</para></listitem>
 362         </varlistentry>
 363       </variablelist>
 364     </refsect2>
 365
 366     <refsect2>
 367       <title>[PCRSignature:<replaceable>NAME</replaceable>] section</title>
 368
 369       <para>In the config file, those options are grouped by section. On the commandline, they
 370       must be specified in the same order. The sections specified in both sources are combined.
 371       </para>
 372
 373       <variablelist>
 374         <varlistentry>
 375           <term><varname>PCRPrivateKey=<replaceable>PATH</replaceable></varname></term>
 376           <term><option>--pcr-private-key=<replaceable>PATH</replaceable></option></term>
 377
 378           <listitem><para>A private key to use for signing PCR policies. On the commandline, this option may
 379           be specified more than once, in which case multiple signatures will be made.</para></listitem>
 380         </varlistentry>
 381
 382         <varlistentry>
 383           <term><varname>PCRPublicKey=<replaceable>PATH</replaceable></varname></term>
 384           <term><option>--pcr-public-key=<replaceable>PATH</replaceable></option></term>
 385
 386           <listitem><para>A public key to use for signing PCR policies.</para>
 387
 388           <para>On the commandline, this option may be specified more than once, similarly to the
 389           <option>--pcr-private-key=</option> option. If not present, the public keys will be extracted from
 390           the private keys. On the commandline, if present, the this option must be specified the same number
 391           of times as the <option>--pcr-private-key=</option> option.</para></listitem>
 392         </varlistentry>
 393
 394         <varlistentry>
 395           <term><varname>Phases=<replaceable>LIST</replaceable></varname></term>
 396           <term><option>--phases=<replaceable>LIST</replaceable></option></term>
 397
 398           <listitem><para>A comma or space-separated list of colon-separated phase paths to sign a policy
 399           for. Each set of boot phase paths will be signed with the corresponding private key. If not
 400           present, the default of
 401           <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 402           will be used.</para>
 403
 404           <para>On the commandline, when this argument is present, it must appear the same number of times as
 405           the <option>--pcr-private-key=</option> option. </para></listitem>
 406         </varlistentry>
 407       </variablelist>
 408     </refsect2>
 409
 410     <refsect2>
 411       <title>[Addon:<replaceable>NAME</replaceable>] section</title>
 412
 413       <para>Currently, these options only apply when building PE addons.</para>
 414
 415       <variablelist>
 416         <varlistentry>
 417           <term><varname>SBAT=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></varname></term>
 418           <term><option>--sbat=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term>
 419
 420           <listitem><para>SBAT metadata associated with the addon. SBAT policies are useful to revoke whole
 421           groups of addons with a single, static policy update that does not take space in DBX/MOKX. If not
 422           specified manually, a default metadata entry consisting of
 423           <literal>uki.addon.systemd,1,UKI Addon,uki.addon.systemd,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html</literal>
 424           will be used, to ensure it is always possible to revoke addons. For more information on SBAT see
 425           <ulink url="https://github.com/rhboot/shim/blob/main/SBAT.md">Shim's documentation.</ulink></para>
 426           </listitem>
 427         </varlistentry>
 428       </variablelist>
 429     </refsect2>
 430   </refsect1>
 431
 432   <refsect1>
 433     <title>Examples</title>
 434
 435     <example>
 436       <title>Minimal invocation</title>
 437
 438       <programlisting>$ ukify build \
 439       --linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
 440       --initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \
 441       --cmdline='quiet rw'
 442       </programlisting>
 443
 444       <para>This creates an unsigned UKI <filename>./vmlinuz.unsigned.efi</filename>.</para>
 445     </example>
 446
 447     <example>
 448       <title>All the bells and whistles</title>
 449
 450       <programlisting>$ /usr/lib/systemd/ukify build \
 451       --linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
 452       --initrd=early_cpio \
 453       --initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \
 454       --pcr-private-key=pcr-private-initrd-key.pem \
 455       --pcr-public-key=pcr-public-initrd-key.pem \
 456       --phases='enter-initrd' \
 457       --pcr-private-key=pcr-private-system-key.pem \
 458       --pcr-public-key=pcr-public-system-key.pem \
 459       --phases='enter-initrd:leave-initrd enter-initrd:leave-initrd:sysinit \
 460                 enter-initrd:leave-initrd:sysinit:ready' \
 461       --pcr-banks=sha384,sha512 \
 462       --secureboot-private-key=sb.key \
 463       --secureboot-certificate=sb.cert \
 464       --sign-kernel \
 465       --cmdline='quiet rw rhgb'
 466       </programlisting>
 467
 468       <para>This creates a signed UKI <filename index='false'>./vmlinuz.signed.efi</filename>.
 469       The initrd section contains two concatenated parts, <filename index='false'>early_cpio</filename>
 470       and <filename index='false'>initramfs-6.0.9-300.fc37.x86_64.img</filename>.
 471       The policy embedded in the <literal>.pcrsig</literal> section will be signed for the initrd (the
 472       <constant>enter-initrd</constant> phase) with the key
 473       <filename index='false'>pcr-private-initrd-key.pem</filename>, and for the main system (phases
 474       <constant>leave-initrd</constant>, <constant>sysinit</constant>, <constant>ready</constant>) with the
 475       key <filename index='false'>pcr-private-system-key.pem</filename>. The Linux binary and the resulting
 476       combined image will be signed with the SecureBoot key <filename index='false'>sb.key</filename>.</para>
 477     </example>
 478
 479     <example>
 480       <title>All the bells and whistles, via a config file</title>
 481
 482       <para>This is the same as the previous example, but this time the configuration is stored in a
 483       file:</para>
 484
 485       <programlisting>$ cat ukify.conf
 486 [UKI]
 487 Initrd=early_cpio
 488 Cmdline=quiet rw rhgb
 489
 490 SecureBootPrivateKey=sb.key
 491 SecureBootCerificate=sb.cert
 492 SignKernel=yes
 493 PCRBanks=sha384,sha512
 494
 495 [PCRSignature:initrd]
 496 PCRPrivateKey=pcr-private-initrd-key.pem
 497 PCRPublicKey=pcr-public-initrd-key.pem
 498 Phases=enter-initrd
 499
 500 [PCRSignature:system]
 501 PCRPrivateKey=pcr-private-system-key.pem
 502 PCRPublicKey=pcr-public-system-key.pem
 503 Phases=enter-initrd:leave-initrd
 504        enter-initrd:leave-initrd:sysinit
 505        enter-initrd:leave-initrd:sysinit:ready
 506
 507 $ /usr/lib/systemd/ukify -c ukify.conf build \
 508         --linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
 509         --initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img
 510       </programlisting>
 511
 512       <para>One "initrd" (<filename index='false'>early_cpio</filename>) is specified in the config file, and
 513       the other initrd (<filename index='false'>initramfs-6.0.9-300.fc37.x86_64.img</filename>) is specified
 514       on the commandline. This may be useful for example when the first initrd contains microcode for the CPU
 515       and does not need to be updated when the kernel version changes, unlike the actual initrd.</para>
 516     </example>
 517
 518     <example>
 519       <title>Kernel command line auxiliary PE</title>
 520
 521       <programlisting>ukify build \
 522       --secureboot-private-key=sb.key \
 523       --secureboot-certificate=sb.cert \
 524       --cmdline='debug' \
 525       --sbat='sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
 526       uki.addon.author,1,UKI Addon for System,uki.addon.author,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html'
 527       --output=debug.cmdline
 528       </programlisting>
 529
 530       <para>This creates a signed PE binary that contains the additional kernel command line parameter
 531       <literal>debug</literal> with SBAT metadata referring to the owner of the addon.</para>
 532     </example>
 533
 534     <example>
 535       <title>Decide signing policy and create certificate and keys</title>
 536
 537       <para>First, let's create an config file that specifies what signatures shall be made:</para>
 538
 539       <programlisting># cat >/etc/kernel/uki.conf &lt;&lt;EOF
 540 <xi:include href="uki.conf.example" parse="text" />EOF</programlisting>
 541
 542       <para>Next, we can generate the certificate and keys:</para>
 543       <programlisting># /usr/lib/systemd/ukify genkey --config=/etc/kernel/uki.conf
 544 Writing SecureBoot private key to /etc/kernel/secure-boot.key.pem
 545 Writing SecureBoot certificate to /etc/kernel/secure-boot.cert.pem
 546 Writing private key for PCR signing to /etc/kernel/pcr-initrd.key.pem
 547 Writing public key for PCR signing to /etc/kernel/pcr-initrd.pub.pem
 548 Writing private key for PCR signing to /etc/kernel/pcr-system.key.pem
 549 Writing public key for PCR signing to /etc/kernel/pcr-system.pub.pem
 550 </programlisting>
 551
 552       <para>(Both operations need to be done as root to allow write access
 553       to <filename>/etc/kernel/</filename>.)</para>
 554
 555       <para>Subsequent invocations of using the config file
 556       (<command>/usr/lib/systemd/ukify build --config=/etc/kernel/uki.conf</command>)
 557       will use this certificate and key files. Note that the
 558       <citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 559       plugin <filename>60-ukify.install</filename> uses <filename>/etc/kernel/uki.conf</filename>
 560       by default, so after this file has been created, installations of kernels that create a UKI on the
 561       local machine using <command>kernel-install</command> would perform signing using this config.</para>
 562     </example>
 563   </refsect1>
 564
 565   <refsect1>
 566     <title>See Also</title>
 567     <para>
 568       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 569       <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 570       <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 571       <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 572       <citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 573      </para>
 574   </refsect1>
 575
 576 </refentry>