ukify: add new --extend= switch for importing an existing UKI's sections to later extend

This options is pretty simple, it allows specifying an UKI whose
sections to import first, and place at the beginning of the new UKI.

This is useful for generating multi-profile UKIs piecemeal: generate the
base UKI first, then append a profile, and another one and another one.

The sections imported this way are not included in any PCR signature,
the assumption is that that already happened before in the imported UKI.

1 files changed, 54 insertions, 0 deletions

diff --git a/man/ukify.xml b/man/ukify.xml
index 1c52c9414b..5e7681279b 100644
--- a/man/ukify.xml
+++ b/man/ukify.xml
@@ -229,6 +229,18 @@
         </varlistentry>
 
         <varlistentry>
+          <term><option>--extend=<replaceable>PATH</replaceable></option></term>
+
+          <listitem><para>Takes a path to an existing PE file to import into the newly generated PE file. If
+          this option is used all UKI PE sections of the specified PE file are copied into the target PE file
+          before any new PE sections are appended. This is useful for generating multi-profile UKIs. Note
+          that this only copies PE sections that are defined by the UKI specification, and ignores any other,
+          for example <literal>.text</literal> or similar.</para>
+
+          <xi:include href="version-info.xml" xpointer="v257"/></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
@@ -703,6 +715,48 @@ Writing public key for PCR signing to /etc/kernel/pcr-system.pub.pem
       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>
+
+    <example>
+      <title>Multi-Profile PE</title>
+
+      <para>First, create the base UKI:</para>
+      <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' \
+      --output=base.efi
+      </programlisting>
+
+      <para>Then, extend the base UKI with information about profile @0:</para>
+
+      <programlisting>$ ukify build \
+      --extend=base.efi \
+      --profile='TITLE=Base' \
+      --output=base-with-profile-0.efi
+      </programlisting>
+
+      <para>Add a second profile (@1):</para>
+
+      <programlisting>$ ukify build \
+      --extend=base-with-profile-0.efi \
+      --profile='TITLE=Boot into Storage Target Mode
+ID=storagetm' \
+      --cmdline='quiet rw rd.systemd.unit=stroage-target-mode.target' \
+      --output=base-with-profile-0-1.efi
+      </programlisting>
+
+      <para>Add a third profile (@2):</para>
+
+      <programlisting>$ ukify build \
+      --extend=base-with-profile-0-1.efi \
+      --profile='TITLE=Factory Reset
+ID=factory-reset' \
+      --cmdline='quiet rw systemd.unit=factory-reset.target' \
+      --output=base-with-profile-0-1-2.efi
+      </programlisting>
+
+      <para>The resulting UKI <filename>base-with-profile-0-1-2.efi</filename> will now contain three profiles.</para>
+    </example>
   </refsect1>
 
   <refsect1>