man: Use ukify instead of objcopy in examples

These hardcoded VMA section offsets are a terrible thing and should
vanish from earth.

diff --git a/man/systemd-measure.xml b/man/systemd-measure.xml
index 42871b0c77152b58cd1517e1c8330e103719f062..14ce533772916d0da6bfa060d1ecc71bad597509 100644 (file)
--- a/man/systemd-measure.xml
+++ b/man/systemd-measure.xml
@@ -208,22 +208,13 @@
     <example>
       <title>Generate a unified kernel image, and calculate the expected TPM PCR 11 value</title>
 
-      <programlisting># objcopy \
-    --add-section .linux=vmlinux --change-section-vma .linux=0x2000000 \
-    --add-section .osrel=os-release.txt --change-section-vma .osrel=0x20000 \
-    --add-section .cmdline=cmdline.txt --change-section-vma .cmdline=0x30000 \
-    --add-section .initrd=initrd.cpio --change-section-vma .initrd=0x3000000 \
-    --add-section .splash=splash.bmp --change-section-vma .splash=0x100000 \
-    --add-section .dtb=devicetree.dtb --change-section-vma .dtb=0x40000 \
-    /usr/lib/systemd/boot/efi/linuxx64.efi.stub \
-    foo.efi
-# systemd-measure calculate \
-     --linux=vmlinux \
-     --osrel=os-release.txt \
-     --cmdline=cmdline.txt \
-     --initrd=initrd.cpio \
-     --splash=splash.bmp \
-     --dtb=devicetree.dtb
+      <programlisting># ukify --output foo.efi \
+     --os-release @os-release.txt \
+     --cmdline @cmdline.txt \
+     --splash splash.bmp \
+     --devicetree devicetree.dtb \
+     --measure \
+     vmlinux initrd.cpio
 11:sha1=d775a7b4482450ac77e03ee19bda90bd792d6ec7
 11:sha256=bc6170f9ce28eb051ab465cd62be8cf63985276766cf9faf527ffefb66f45651
 11:sha384=1cf67dff4757e61e5a73d2a21a6694d668629bbc3761747d493f7f49ad720be02fd07263e1f93061243aec599d1ee4b4
@@ -249,17 +240,15 @@
      --bank=sha256 \
      --private-key=tpm2-pcr-private.pem \
      --public-key=tpm2-pcr-public.pem > tpm2-pcr-signature.json
-# objcopy \
-    --add-section .linux=vmlinux --change-section-vma .linux=0x2000000 \
-    --add-section .osrel=os-release.txt --change-section-vma .osrel=0x20000 \
-    --add-section .cmdline=cmdline.txt --change-section-vma .cmdline=0x30000 \
-    --add-section .initrd=initrd.cpio --change-section-vma .initrd=0x3000000 \
-    --add-section .splash=splash.bmp --change-section-vma .splash=0x100000 \
-    --add-section .dtb=devicetree.dtb --change-section-vma .dtb=0x40000 \
-    --add-section .pcrsig=tpm2-pcr-signature.json --change-section-vma .pcrsig=0x80000 \
-    --add-section .pcrpkey=tpm2-pcr-public.pem --change-section-vma .pcrpkey=0x90000 \
-    /usr/lib/systemd/boot/efi/linuxx64.efi.stub \
-    foo.efi</programlisting>
+# ukify --output foo.efi \
+     --os-release @os-release.txt \
+     --cmdline @cmdline.txt \
+     --splash splash.bmp \
+     --devicetree devicetree.dtb \
+     --pcr-private-key tpm2-pcr-private.pem \
+     --pcr-public-key tpm2-pcr-public.pem \
+     --pcr-banks sha1,sha256 \
+     vmlinux initrd.cpio</programlisting>
 
      <para>Later on, enroll the signed PCR policy on a LUKS volume:</para>
 
@@ -314,17 +303,16 @@
      --public-key=tpm2-pcr-initrd-public.pem \
      --phase=enter-initrd \
      --append=tpm2-pcr-signature.json.tmp >tpm2-pcr-signature.json
-# objcopy \
-    --add-section .linux=vmlinux --change-section-vma .linux=0x2000000 \
-    --add-section .osrel=os-release.txt --change-section-vma .osrel=0x20000 \
-    --add-section .cmdline=cmdline.txt --change-section-vma .cmdline=0x30000 \
-    --add-section .initrd=initrd.cpio --change-section-vma .initrd=0x3000000 \
-    --add-section .splash=splash.bmp --change-section-vma .splash=0x100000 \
-    --add-section .dtb=devicetree.dtb --change-section-vma .dtb=0x40000 \
-    --add-section .pcrsig=tpm2-pcr-signature.json --change-section-vma .pcrsig=0x80000 \
-    --add-section .pcrpkey=tpm2-pcr-public.pem --change-section-vma .pcrpkey=0x90000 \
-    /usr/lib/systemd/boot/efi/linuxx64.efi.stub \
-    foo.efi</programlisting>
+# ukify --output foo.efi \
+     --os-release @os-release.txt \
+     --cmdline @cmdline.txt \
+     --splash splash.bmp \
+     --devicetree devicetree.dtb \
+     --pcr-private-key tpm2-pcr-initrd-private.pem \
+     --pcr-public-key tpm2-pcr-initrd-public.pem \
+     --section .pcrsig=@tpm2-pcr-signature.json \
+     --section .pcrpkey=@tpm2-pcr-public.pem \
+     vmlinux initrd.cpio</programlisting>
     </example>
 
     <para>Note that in this example the <literal>.pcrpkey</literal> PE section contains the key covering all
@@ -345,7 +333,7 @@
     <para>
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
-      <citerefentry project='man-pages'><refentrytitle>objcopy</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-creds</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>1</manvolnum></citerefentry>

diff --git a/man/systemd-stub.xml b/man/systemd-stub.xml
index fcb0c24ce8074173180a9e0fd4df2493bcacd2ea..c2301687806ef4d2c190234fd30f095619dc1348 100644 (file)
--- a/man/systemd-stub.xml
+++ b/man/systemd-stub.xml
@@ -382,45 +382,8 @@
   <refsect1>
     <title>Assembling Kernel Images</title>
 
-    <para>In order to assemble an UEFI PE kernel image from various components as described above, use an
-    <citerefentry project='man-pages'><refentrytitle>objcopy</refentrytitle><manvolnum>1</manvolnum></citerefentry> command line
-    like this:</para>
-
-    <programlisting>objcopy \
-    --add-section .osrel=os-release --change-section-vma .osrel=0x20000 \
-    --add-section .cmdline=cmdline.txt --change-section-vma .cmdline=0x30000 \
-    --add-section .dtb=devicetree.dtb --change-section-vma .dtb=0x40000 \
-    --add-section .splash=splash.bmp --change-section-vma .splash=0x100000 \
-    --add-section .linux=vmlinux --change-section-vma .linux=0x2000000 \
-    --add-section .initrd=initrd.cpio --change-section-vma .initrd=0x3000000 \
-    /usr/lib/systemd/boot/efi/linuxx64.efi.stub \
-    foo-unsigned.efi</programlisting>
-
-    <para>Note that these PE section offsets are example values and a properly assembled image must not
-    contain any overlapping sections (this includes already existing sections inside the stub before
-    assembly) or boot may fail.</para>
-
-    <para>This generates one PE executable file <filename>foo-unsigned.efi</filename> from the six individual
-    files for OS release information, kernel command line, boot splash image, kernel image, main initrd and
-    UEFI boot stub.</para>
-
-    <para>To then sign the resulting image for UEFI SecureBoot use an
-    <citerefentry project='archlinux'><refentrytitle>sbsign</refentrytitle><manvolnum>1</manvolnum></citerefentry> command like
-    the following:</para>
-
-    <programlisting>sbsign \
-    --key mykey.pem \
-    --cert mykey.crt \
-    --output foo.efi \
-    foo-unsigned.efi</programlisting>
-
-    <para>This expects a pair of X.509 private key and certificate as parameters and then signs the UEFI PE
-    executable we generated above for UEFI SecureBoot and generates a signed UEFI PE executable as
-    result.</para>
-
-    <para>See
-    <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
-    an example involving the <literal>.pcrsig</literal> and <literal>.pcrpkey</literal> sections.</para>
+    <para>In order to assemble a bootable Unified Kernel Image from various components as described above, use
+    <citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
   </refsect1>
 
   <refsect1>
@@ -432,8 +395,7 @@
       <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink>,
       <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>,
-      <citerefentry project='man-pages'><refentrytitle>objcopy</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry project='archlinux'><refentrytitle>sbsign</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     </para>
   </refsect1>