summaryrefslogtreecommitdiffstats
path: root/man/ukify.xml
blob: bf6f3285364e685c03339754a48f96ac4b9fa03b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
<?xml version="1.0"?>
<!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/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>ukify</command>
      <arg choice="opt" rep="repeat">OPTIONS</arg>
      <arg choice="plain">build</arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>ukify</command>
      <arg choice="opt" rep="repeat">OPTIONS</arg>
      <arg choice="plain">genkey</arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>ukify</command>
      <arg choice="opt" rep="repeat">OPTIONS</arg>
      <arg choice="plain">inspect</arg>
      <arg choice="plain" rep="repeat">FILE</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para><command>ukify</command> is a tool whose primary purpose is to combine components (usually a
    kernel, an initrd, and 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>
  </refsect1>

  <refsect1>
    <title>Commands</title>

    <para>The following commands are understood:</para>

    <refsect2>
      <title><command>build</command></title>

      <para>This command creates a Unified Kernel Image. The two primary options that should be specified for
      the <command>build</command> verb are <varname>Linux=</varname>/<option>--linux=</option>, and
      <varname>Initrd=</varname>/<option>--initrd=</option>. <varname>Initrd=</varname> accepts multiple
      whitespace-separated paths and <option>--initrd=</option> can be specified multiple times.</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>Microcode=</varname>/<option>--microcode=</option>,
      <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>,
      <varname>SBAT=</varname>/<option>--sbat=</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. If <varname>SigningEngine=</varname>/<option>--signing-engine=</option>
      is specified, then the private keys arguments will be passed verbatim to OpenSSL as URIs, and the public
      key arguments will be loaded as X.509 certificates, so that signing can be performed with an OpenSSL
      engine.</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>

      <para>If the stub and/or the kernel contain <literal>.sbat</literal> sections they will be merged in
      the UKI so that revocation updates affecting either are considered when the UKI is loaded by Shim. For
      more information on SBAT see
      <ulink url="https://github.com/rhboot/shim/blob/main/SBAT.md">Shim documentation</ulink>.
      </para>
    </refsect2>

    <refsect2>
      <title><command>genkey</command></title>

      <para>This command creates the keys for PCR signing and the key and certificate used for SecureBoot
      signing. The same configuration options that determine what keys and in which paths will be needed for
      signing when <command>build</command> is used, here determine which keys will be created. See the
      discussion of <varname>PCRPrivateKey=</varname>/<option>--pcr-private-key=</option>,
      <varname>PCRPublicKey=</varname>/<option>--pcr-public-key=</option>, and
      <varname>SecureBootPrivateKey=</varname>/<option>--secureboot-private-key=</option> below.</para>

      <para>The output files must not exist.</para>
    </refsect2>

    <refsect2>
      <title><command>inspect</command></title>

      <para>Display information about the sections in a given binary or binaries.
      If <option>--all</option> is given, all sections are shown.
      Otherwise, if <option>--section=</option> option is specified at least once, only those sections are shown.
      Otherwise, well-known sections that are typically included in an UKI are shown.
      For each section, its name, size, and sha256-digest is printed.
      For text sections, the contents are printed.</para>

      <para>Also see the description of <option>-j</option>/<option>--json=</option> and
      <option>--section=</option>.</para>

      <para>Other tools that may be useful for inspect UKIs:
      <citerefentry project='man-pages'><refentrytitle>llvm-objdump</refentrytitle><manvolnum>1</manvolnum></citerefentry>
      <option>-p</option> and <command>pe-inspect</command>.
      <!-- TODO: add link to pe-inspect man page when it gets one -->
      </para>
    </refsect2>
  </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>If no config file is provided via the option <option>--config=<replaceable>PATH</replaceable></option>,
    <command>ukify</command> will try to look for a default configuration file in the following paths in this
    order: <filename>/etc/systemd/ukify.conf</filename>, <filename>/run/systemd/ukify.conf</filename>,
    <filename>/usr/local/lib/systemd/ukify.conf</filename>, and <filename>/usr/lib/systemd/ukify.conf</filename>,
    and then load the first one found. <command>ukify</command> will proceed normally if no configuration file
    is specified and no default one is found.</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>Command line-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
          command line option does not fully override the config file setting are explicitly mentioned in the
          descriptions of individual options.</para>

          <xi:include href="version-info.xml" xpointer="v254"/></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>

          <xi:include href="version-info.xml" xpointer="v253"/></listitem>
        </varlistentry>

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

          <listitem><para>For all verbs except <command>inspect</command>, the first syntax is used.
          Specify an arbitrary additional section <literal><replaceable>NAME</replaceable></literal>.
          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>

          <para>For the <command>inspect</command> verb, the second syntax is used.
          The section <replaceable>NAME</replaceable> will be inspected (if found).
          If the second argument is <literal>text</literal>, the contents will be printed.
          If the third argument is given, the contents will be saved to file <replaceable>PATH</replaceable>.
          </para>

          <para>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>.</para>

          <xi:include href="version-info.xml" xpointer="v253"/>
          </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>

          <xi:include href="version-info.xml" xpointer="v253"/></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>

          <xi:include href="version-info.xml" xpointer="v253"/></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
          from the configuration file and the command line are combined.</para>

          <xi:include href="version-info.xml" xpointer="v254"/></listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--all</option></term>

          <listitem><para>Print all sections (with <command>inspect</command> verb).</para>

          <xi:include href="version-info.xml" xpointer="v255"/></listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--json</option></term>

          <listitem><para>Generate JSON output (with <command>inspect</command> verb).</para>

          <xi:include href="version-info.xml" xpointer="v255"/></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><option>--linux=<replaceable>LINUX</replaceable></option></term>

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

          <xi:include href="version-info.xml" xpointer="v254"/></listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>Initrd=<replaceable>INITRD</replaceable>...</varname></term>
          <term><option>--initrd=<replaceable>LINUX</replaceable></option></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>

          <xi:include href="version-info.xml" xpointer="v254"/></listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>Microcode=<replaceable>UCODE</replaceable></varname></term>
          <term><option>--microcode=<replaceable>UCODE</replaceable></option></term>

          <listitem><para>Path to initrd containing microcode updates. If not specified, the section
          will not be present.</para>

          <xi:include href="version-info.xml" xpointer="v256"/></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>

          <xi:include href="version-info.xml" xpointer="v253"/></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>

          <xi:include href="version-info.xml" xpointer="v253"/></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>

          <xi:include href="version-info.xml" xpointer="v253"/></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>

          <xi:include href="version-info.xml" xpointer="v253"/></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>

          <xi:include href="version-info.xml" xpointer="v253"/></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>

          <xi:include href="version-info.xml" xpointer="v253"/></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>

          <xi:include href="version-info.xml" xpointer="v253"/></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>

          <xi:include href="version-info.xml" xpointer="v254"/></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>

          <xi:include href="version-info.xml" xpointer="v253"/></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>

          <xi:include href="version-info.xml" xpointer="v253"/></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>

          <xi:include href="version-info.xml" xpointer="v254"/></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>

          <xi:include href="version-info.xml" xpointer="v254"/></listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>SecureBootCertificateValidity=<replaceable>DAYS</replaceable></varname></term>
          <term><option>--secureboot-certificate-validity=<replaceable>DAYS</replaceable></option></term>

          <listitem><para>Period of validity (in days) for a certificate created by
          <command>genkey</command>. Defaults to 3650, i.e. 10 years.</para>

          <xi:include href="version-info.xml" xpointer="v254"/></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>

          <xi:include href="version-info.xml" xpointer="v253"/></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>

          <xi:include href="version-info.xml" xpointer="v253"/></listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>SBAT=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></varname></term>
          <term><option>--sbat=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term>

          <listitem><para>SBAT metadata associated with the UKI or addon. SBAT policies are useful to revoke
          whole groups of UKIs or addons with a single, static policy update that does not take space in
          DBX/MOKX. If not specified manually, a default metadata entry consisting of
          <literal>uki,1,UKI,uki,1,https://uapi-group.org/specifications/specs/unified_kernel_image/</literal>
          for UKIs and
          <literal>uki-addon,1,UKI Addon,addon,1,https://www.freedesktop.org/software/systemd/man/latest/systemd-stub.html</literal>
          for addons will be used, to ensure it is always possible to revoke them. For more information on
          SBAT see <ulink url="https://github.com/rhboot/shim/blob/main/SBAT.md">Shim documentation</ulink>.
          </para>

          <xi:include href="version-info.xml" xpointer="v254"/></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 command line, 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 command line, this option may
          be specified more than once, in which case multiple signatures will be made.</para>

          <xi:include href="version-info.xml" xpointer="v253"/></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 command line, 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 command line, if present, this option must be specified the same number of
          times as the <option>--pcr-private-key=</option> option.</para>

          <xi:include href="version-info.xml" xpointer="v253"/></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 command line, when this argument is present, it must appear the same number of times as
          the <option>--pcr-private-key=</option> option. </para>

          <xi:include href="version-info.xml" xpointer="v253"/></listitem>
        </varlistentry>
      </variablelist>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>Examples</title>

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

      <programlisting>$ ukify build \
      --linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
      --initrd=/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>$ ukify build \
      --linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
      --initrd=early_cpio \
      --initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \
      --sbat='sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
      uki.author.myimage,1,UKI for System,uki.author.myimage,1,https://uapi-group.org/specifications/specs/unified_kernel_image/' \
      --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
SecureBootCertificate=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

$ ukify -c ukify.conf build \
        --linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
        --initrd=/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 command line. 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 build \
      --secureboot-private-key=sb.key \
      --secureboot-certificate=sb.cert \
      --cmdline='debug' \
      --sbat='sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
      uki-addon.author,1,UKI Addon for System,uki-addon.author,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html'
      --output=debug.cmdline
      </programlisting>

      <para>This creates a signed PE binary that contains the additional kernel command line parameter
      <literal>debug</literal> with SBAT metadata referring to the owner of the addon.</para>
    </example>

    <example>
      <title>Decide signing policy and create certificate and keys</title>

      <para>First, let's create an config file that specifies what signatures shall be made:</para>

      <programlisting># cat >/etc/kernel/uki.conf &lt;&lt;EOF
<xi:include href="uki.conf.example" parse="text" />EOF</programlisting>

      <para>Next, we can generate the certificate and keys:</para>
      <programlisting># ukify genkey --config=/etc/kernel/uki.conf
Writing SecureBoot private key to /etc/kernel/secure-boot.key.pem
Writing SecureBoot certificate to /etc/kernel/secure-boot.cert.pem
Writing private key for PCR signing to /etc/kernel/pcr-initrd.key.pem
Writing public key for PCR signing to /etc/kernel/pcr-initrd.pub.pem
Writing private key for PCR signing to /etc/kernel/pcr-system.key.pem
Writing public key for PCR signing to /etc/kernel/pcr-system.pub.pem
</programlisting>

      <para>(Both operations need to be done as root to allow write access
      to <filename>/etc/kernel/</filename>.)</para>

      <para>Subsequent invocations using the config file
      (<command>ukify build --config=/etc/kernel/uki.conf</command>)
      will use this certificate and key files. Note that the
      <citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      plugin <filename>60-ukify.install</filename> uses <filename>/etc/kernel/uki.conf</filename>
      by default, so after this file has been created, installations of kernels that create a UKI on the
      local machine using <command>kernel-install</command> will perform signing using this config.</para>
    </example>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para><simplelist type="inline">
      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
     </simplelist></para>
  </refsect1>

</refentry>