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