pewrap(1)

💅 pewrap(1) — the group chat version 💅

okay so bestie, you've opened the manual page for pewrap, a General Commands Manual situation, and honestly? it's giving "tool for building stubble images." iconic. let's get into it 🫶

---

✨ NAME ✨

pewrap — the tool for building stubble images. that's it, that's the name, no notes 💖

---

🎀 SYNOPSIS 🎀

pewrap <-s|--stub> <-o|--output> [-l|--linux] [-i|--initrd]
[-c|--cmdline] [--sbat] [--hwids] [--dtbauto] [--post-process-for-ukify]
[-h|--help] [-V|--version]

like, look at her. -s and -o are the mandatory besties, everything else is optional but lowkey always invited ✨

---

🦋 DESCRIPTION 🦋

pewrap takes a pre-built stub binary and smushes it together with additional binaries — think the Linux kernel, initrd, device trees — plus SBAT data and HWIDs, and out comes a stubble image. slay.

the way it works is: you hand it a stub PE binary, and it adds brand-new sections onto it containing all the payloads you specified. this is what makes it possible to create stubble images that UEFI firmware can load with every necessary component already embedded inside. one file, everything in it, main character energy 👑

---

💅 OPTIONS 💅

• -s, --stub <FILE> — path to the input stub PE image.

bestie this one is required. the stub PE has to be a valid UEFI executable, because it's literally the base that the output image gets built on. every single section from the stub gets preserved in the output, and the new sections get appended after them. nothing gets deleted, we don't do that here 💖

• -o, --output <FILE> — path to the output stubble image.

this is where your little creation lands. the resulting stubble image contains all the sections from the stub plus any extra sections the other arguments told it to add. and the section offsets and headers? automatically recalculated, so the PE format stays valid. she does the math so you don't have to 🧚

• -l, --linux <FILE> — path to the linux kernel image to add.

this embeds the kernel image into a .linux section for boot loading. important: the kernel must be a PE binary. for Linux kernels that typically means a PE-wrapped bzImage or something similar that's suitable for UEFI loading. no PE, no entry, sorry bestie 😭

• -i, --initrd <FILE> — path to the initrd image to add.

this drops the initial ramdisk into a .initrd section for boot loading. the bootloader loads the initrd into memory before the kernel starts, which gives you an early userspace environment and drivers. it's the little pre-game before the main event 🎀

• -c, --cmdline <STRING> — the kernel command line to add.

embeds that command line string into a .cmdline section. this is where your boot parameters and configuration options live — the stuff passed to the kernel at boot time, like the root device, console settings, and kernel features. basically the kernel's to-do list 📝

• --sbat <FILE> — add a .sbat section with SBAT data from the given file.

SBAT stands for UEFI Secure Boot Advanced Targeting and this is the metadata for revocation support. this section carries versioning information that UEFI Secure Boot uses to enable fine-grained revocation of vulnerable bootloader components — without having to revoke an entire certificate. she's precise, she's targeted, we love her ✨

• --hwids <DIR> — HWIDs directory to scan for JSON files.

scans the directory recursively for HWID JSON files and generates a .hwids section full of CHID-to-compatible mappings. those mappings get used for automatic device tree selection based on hardware identification (SMBIOS/EDID). translation: one single stubble image can support multiple hardware platforms. versatile queen 👑

• --dtbauto <FILE> — device tree blobs to add for automatic loading.

each DTB gets embedded in its own separate .dtbauto section for automatic loading based on hardware detection. want more than one? just repeat the argument as many times as you want, bestie, we don't gatekeep. at boot time the stubble image uses those HWID mappings to pick the right DTB for whatever hardware it's actually running on 🔥

• --post-process-for-ukify — post-process a lace-stubble PE binary for systemd-ukify compatibility.

okay so here's the lore: systemd-ukify works with lace-stubble, but unlike pewrap, it does not have the ability to relayout the raw layout of a PE image. consequence? the maximum number of sections it can handle is limited to however many fit before the original SizeOfHeaders value. 💀

pewrap, on the other hand, can relayout the raw layout of the image. that gives it the power to add as many sections as can fit before the VirtualAddress of the first section. periodt.

so this option tells pewrap to relayout the image by setting SizeOfHeaders to as large as possible — maximizing the number of sections systemd-ukify can add later on.

and there's more: it also sets the PE major version to 1, which ukify also requires. without that, it will never indicate support for LoadFile2. so yeah, required. no cap.

• -h, --help — print help. (pro tip: add -h to see a summary version 🎀)
• -V, --version — print version.

---

⭐ VERSION ⭐

v0.1.0

she's baby, she's new, she's already this good 💜

---

and that's the whole page, bestie. this was pewrap 0.1.0, living in the General Commands Manual section, and if you made it all the way down here you're literally a Unix legend. go build a stubble image, you've got this 🌸🦋💖