From f61ae49b3b6a5f41d7e725e5267573cb8407f6f5 Mon Sep 17 00:00:00 2001 From: mgbilby <21131327+mgbilby@users.noreply.github.com> Date: Sat, 21 Nov 2026 22:45:48 +0000 Subject: [PATCH 1/2] Support Linux LUKS partition type in the installer OS templates can now request a LUKS root partition with "type": "luks". diskutil has no friendly LUKS content name, so the alias is translated to the Linux LUKS type GUID when the partition is created, and the post-creation selection check normalizes LUKS roots however diskutil reports them (raw GUID or Linux LUKS). Selection still fails closed if the new partition cannot be uniquely identified. --- src/diskutil.py | 15 ++++++++++++--- tests/test_partition_selection.py | 21 +++++++++++++++++++++ 2 files changed, 33 insertions(+), 3 deletions(-) diff --git a/src/diskutil.py b/src/diskutil.py index a22eab5..54ca43c 100644 --- a/src/diskutil.py +++ b/src/diskutil.py @@ -248,19 +248,28 @@ def addPartition(self, after, fs, label, size): disk = after.rsplit("s", 1)[0] before = {p.uuid for p in self.get_partitions(disk) if not p.free} - self.action("addPartition", after, fs, label, size, verbose=True) + requested_type = "Apple_APFS" if fs.lower() == "apfs" else fs.strip("%") + linux_luks_uuid = "CA7D7CCB-63ED-4C53-861C-1742536059CC" + add_type = f"%{linux_luks_uuid}%" if requested_type.lower() == "luks" else fs + self.action("addPartition", after, add_type, label, size, verbose=True) self.get_list() parts = self.get_partitions(disk) # macOS may insert Apple_Boot helpers between Linux partitions. # Identify the newly created partition by UUID and requested type. - requested_type = "Apple_APFS" if fs.lower() == "apfs" else fs.strip("%") # diskutil accepts %Linux% but reports Content as Linux Filesystem. # Normalize this alias without weakening the UUID/type uniqueness check. + # LUKS roots carry the Linux LUKS type GUID; diskutil may report it + # either as the GUID itself or as Linux LUKS. + def canonical_type(value): value = value.lower() - return "linux filesystem" if value == "linux" else value + if value == "linux": + return "linux filesystem" + if value in ("luks", "linux luks", linux_luks_uuid.lower()): + return linux_luks_uuid.lower() + return value candidates = [p for p in parts if not p.free and p.uuid not in before and canonical_type(p.type) == canonical_type(requested_type)] diff --git a/tests/test_partition_selection.py b/tests/test_partition_selection.py index 0f6f978..9d7de0e 100644 --- a/tests/test_partition_selection.py +++ b/tests/test_partition_selection.py @@ -46,3 +46,24 @@ def test_missing_or_ambiguous_candidates_fail_closed(self): with self.assertRaisesRegex(Exception, 'Could not uniquely identify'): disk.addPartition('disk0s4', '%Linux%', '%noformat%', 1073741824) disk.get_partition_info.assert_not_called() + + def test_luks_alias_uses_guid_and_matches_reported_guid(self): + wanted = partition('disk0s6', 'CA7D7CCB-63ED-4C53-861C-1742536059CC', 'new-luks') + disk = self.setup_disk([partition('disk0s5', 'Apple_Boot', 'helper'), wanted]) + self.assertIs(disk.addPartition('disk0s4', '%luks%', '%noformat%', 1073741824), wanted) + disk.action.assert_called_once_with('addPartition', 'disk0s4', + '%CA7D7CCB-63ED-4C53-861C-1742536059CC%', + '%noformat%', '1073741824', verbose=True) + + def test_luks_alias_matches_linux_luks_content(self): + wanted = partition('disk0s5', 'Linux LUKS', 'new-luks') + disk = self.setup_disk([wanted]) + self.assertIs(disk.addPartition('disk0s4', '%luks%', 'name', 1073741824), wanted) + + def test_luks_missing_or_plain_linux_fails_closed(self): + for added in [[], [partition('disk0s5', 'Linux Filesystem', 'plain-root')]]: + with self.subTest(added=added): + disk = self.setup_disk(added) + with self.assertRaisesRegex(Exception, 'Could not uniquely identify'): + disk.addPartition('disk0s4', '%luks%', '%noformat%', 1073741824) + disk.get_partition_info.assert_not_called() From 198ba468b6e5f3226424e55193a3ae88da1ea6c2 Mon Sep 17 00:00:00 2001 From: mgbilby <21131327+mgbilby@users.noreply.github.com> Date: Sat, 21 Nov 2026 22:45:48 +0000 Subject: [PATCH 2/2] Add Apple Silicon repartition and LUKS encryption runbook Reference walkthrough covering the fixed Apple firmware partitions, reclaiming macOS containers from Linux, physical partition relocation with preserved GPT slot numbers and UUIDs, LUKS2+btrfs encryption for data volumes and for migrating an existing install without reinstall, keyfile-based second devices, discard handling, verification and rollback patterns, and the installer integration approach for OS templates with LUKS roots. --- docs/apple-silicon-repartition-encryption.md | 300 +++++++++++++++++++ 1 file changed, 300 insertions(+) create mode 100644 docs/apple-silicon-repartition-encryption.md diff --git a/docs/apple-silicon-repartition-encryption.md b/docs/apple-silicon-repartition-encryption.md new file mode 100644 index 0000000..a87a418 --- /dev/null +++ b/docs/apple-silicon-repartition-encryption.md @@ -0,0 +1,300 @@ +# Apple Silicon: repartitioning and Linux partition encryption (fc44 runbook) + +Distilled from a validated end-to-end migration on an Apple Silicon +Mac mini (M4-class) running Gravity Linux release 44 (Fedora 44 +based): dual-boot reclaim to single-boot, LUKS2-encrypted root and +data, with the boot chain kept intact at every stage. Intended as reference for installer +integration (`--encrypt`, guided repartition) and as a CLI walkthrough +for users doing it manually. + +## Apple Silicon disk facts that constrain everything + +- The internal disk uses GPT with several Apple-firmware partitions + that must never be modified, deleted, or have their numbers/UUIDs + changed casually: + - `Apple_APFS_ISC` (type `AF0B`, ~500M) — iBoot system container. + - `Apple_APFS_Recovery` (type `AF0C`, ~5G) — recoveryOS/1TR: boot + picker's Options, Disk Utility, `bless`, `bputil`, `kmutil`, + macOS reinstall, DFU revive. It stays functional even if macOS + is deleted. + - The Linux boot chain's APFS stub container (type `AF0A`, ~2-3G) + created by the installer — holds the personalized boot object + iBoot loads. Deleting it makes the system unbootable until the + 1TR re-registration (`bless` + `kmutil configure-boot`) is redone. +- Machines cannot boot from external media; the boot picker only + enumerates internal containers. A "Linux partition" for the rootfs + is a normal GPT entry, but boot always starts from the APFS stub. +- GPT partition numbers are table slots, not physical positions. A + partition can be relocated to a different physical offset while + keeping its number, PARTUUID, and type code — this keeps all boot + references (`(hd0,gpt5)` in GRUB, BLS paths) valid. +- macOS identifiers (`disk0sN`) and Linux ones (`nvme0n1pN`) do not + correspond; sizes and type codes are the reliable identifiers. +- APFS containers on Linux are read-only via apfs-fuse; FileVault + volumes are unreadable by design (keys in the Secure Enclave + escrow). Encryption questions on the Linux side are therefore + solved with LUKS, not with anything APFS. + +## Repartition + +Always start from a full layout listing and match partitions by size +and type, never by order: + +```bash +lsblk -o NAME,SIZE,FSTYPE,LABEL /dev/nvme0n1 +sudo sgdisk -p /dev/nvme0n1 +``` + +### Shrinking macOS to make room (from macOS) + +```bash +diskutil list +diskutil apfs resizeContainer disk0s2 175g +diskutil addPartition disk0s2 APFS development 20g +``` + +`resizeContainer` takes the container's NEW total size. Container +names (`disk3`) and slice identifiers (`disk0s2`) do not align; re-run +`diskutil list` between commands. + +### Deleting the macOS container from Linux (post-migration reclaim) + +```bash +sudo dnf install gdisk +sudo sgdisk --delete=2 /dev/nvme0n1 +sudo sgdisk --largest-new=2 --typecode=2:8300 /dev/nvme0n1 +sudo partprobe /dev/nvme0n1 +sudo wipefs -a /dev/nvme0n1p2 +sudo dd if=/dev/zero of=/dev/nvme0n1p2 bs=1M count=16 status=none +sudo partprobe /dev/nvme0n1 +``` + +`--largest-new` fills the biggest free gap. The zero-wipe clears stale +APFS signatures (APFS keeps superblock copies at several offsets). + +### Relocating partitions to consolidate free space + +When freed space is not adjacent (typical case: the old root sits +between `/boot` and Recovery), partitions can be moved instead of +leaving stranded space: + +1. Save the GPT and capture identity GUIDs: + +```bash +sudo sgdisk --backup=/root/gpt-backup.bin /dev/nvme0n1 +for n in 2 3 4 5; do sudo sgdisk -i $n /dev/nvme0n1; done +``` + +2. Copy partition contents while unmounted: + +```bash +sudo umount /boot/efi /boot +sudo dd if=/dev/nvme0n1p3 of=/root/p3.img bs=1M status=none +sudo dd if=/dev/nvme0n1p4 of=/root/p4.img bs=1M status=none +sudo dd if=/dev/nvme0n1p5 of=/root/p5.img bs=1M status=none +``` + +3. Delete and recreate entries at new offsets with the SAME slot + numbers, PARTUUIDs, and type codes (compute start/end from + `sgdisk -p` output; new lengths must equal original lengths): + +```bash +sudo sgdisk --delete=3 --delete=4 --delete=5 /dev/nvme0n1 +sudo sgdisk --new=3:: --typecode=3:af0a --partition-guid=3:$UUID3 /dev/nvme0n1 +sudo sgdisk --new=4:: --typecode=4:ef00 --partition-guid=4:$UUID4 /dev/nvme0n1 +sudo sgdisk --new=5:: --partition-guid=5:$UUID5 /dev/nvme0n1 +sudo partprobe /dev/nvme0n1 +sudo dd if=/root/p3.img of=/dev/nvme0n1p3 bs=1M status=none +sudo dd if=/root/p4.img of=/dev/nvme0n1p4 bs=1M status=none +sudo dd if=/root/p5.img of=/dev/nvme0n1p5 bs=1M status=none +sudo partprobe /dev/nvme0n1 +sudo fsck -f /dev/nvme0n1p5 +``` + +Growing a partition is the same pattern: `--delete` then `--new` +with a bigger end, same start, same GUID. + +## Encryption: LUKS2 + btrfs + +Boot chain constraint: the APFS stub, EFI, and `/boot` stay +unencrypted (required — GRUB and the stub run before any unlock). +Encrypt root and data only. + +### New data partition + +```bash +sudo cryptsetup luksFormat --type luks2 /dev/nvme0n1pN +sudo cryptsetup open /dev/nvme0n1pN name +sudo mkfs.btrfs -L name /dev/mapper/name +sudo mkdir /data && sudo mount /dev/mapper/name /data +echo "name UUID=$(sudo blkid -s UUID -o value /dev/nvme0n1pN) none luks,discard" | sudo tee -a /etc/crypttab +echo "/dev/mapper/name /data btrfs defaults,nofail 0 2" | sudo tee -a /etc/fstab +sudo dracut --force --regenerate-all +``` + +`luks,discard` in crypttab makes fstrim/discard work through dm-crypt; +without it `fstrim` fails with "the discard operation is not +supported". Enable on an already-open mapper without reboot: + +```bash +sudo cryptsetup refresh --allow-discards name +``` + +Forgotten LUKS passphrases are unrecoverable — no escrow exists. + +### Migrating an existing install into encryption (no reinstall) + +An existing filesystem cannot be wrapped in place; copy it into a new +LUKS container and boot both until the encrypted one is proven: + +```bash +sudo cryptsetup luksFormat --type luks2 /dev/nvme0n1pX +sudo cryptsetup open /dev/nvme0n1pX gravity +sudo mkfs.btrfs -L gravity /dev/mapper/gravity +sudo mount -o subvol=root /dev/mapper/gravity /mnt/newroot +sudo mount -o subvol=home /dev/mapper/gravity /mnt/newroot/home +sudo rsync -aHAXx / /mnt/newroot/ --exclude=proc --exclude=sys --exclude=dev --exclude=run --exclude=mnt --exclude=tmp --exclude=boot --exclude=home +sudo rsync -aHAXx /home/ /mnt/newroot/home/ +``` + +The copy needs replacement mountpoints that rsync excluded: + +```bash +sudo mkdir -p /mnt/newroot/{dev,proc,sys,run,tmp,var/tmp} +``` + +Chroot, re-point fstab at the mapper, and regenerate an initramfs with +LUKS support into a NEW filename (never overwrite the working one): + +```bash +for d in dev proc sys run; do sudo mount --bind /$d /mnt/newroot/$d; done +sudo mount /dev/nvme0n1p5 /mnt/newroot/boot +sudo mount /dev/nvme0n1p4 /mnt/newroot/boot/efi +sudo chroot /mnt/newroot +LUKS_UUID=$(blkid -s UUID -o value /dev/nvme0n1pX) +sed -i "s|$(awk '$2==\"/\" {print $1}' /etc/fstab)|/dev/mapper/gravity|g" /etc/fstab +grep -q '^gravity ' /etc/crypttab || echo "gravity UUID=$LUKS_UUID none luks,discard" >> /etc/crypttab +KVER=$(basename /boot/vmlinuz-$(uname -r) | sed 's/vmlinuz-//') +dracut --force /boot/initramfs-$KVER-luks.img $KVER +``` + +Add a BLS entry copied from the working one, pointing at the LUKS +initramfs and root: + +```bash +SRC=$(grep -l "vmlinuz-$KVER" /boot/loader/entries/*.conf | head -1) +cp "$SRC" /boot/loader/entries/gravity-luks.conf +sed -i "s|^title \(.*\)|title \1 (LUKS)|" /boot/loader/entries/gravity-luks.conf +sed -i "s|^initrd .*|initrd /initramfs-$KVER-luks.img|" /boot/loader/entries/gravity-luks.conf +sed -i "s|root=UUID=[^ ]*|root=/dev/mapper/gravity|" /boot/loader/entries/gravity-luks.conf +sed -i "s|\(options .*\)|\1 rd.luks.uuid=$LUKS_UUID|" /boot/loader/entries/gravity-luks.conf +``` + +Boot-selection notes validated on fc44 images: BLS entries sort by their +`version` field (newest first); a `version` suffix bump makes an entry +both the top of the menu and the fallback default. `grubby --set-default` +does not accept a BLS conf path; select defaults via +`grub2-editenv /boot/grub2/grubenv set saved_entry=`. +Menu auto-hiding is driven by `menu_auto_hide` in the grubenv; +`grub2-editenv ... unset menu_auto_hide` plus `GRUB_TIMEOUT_STYLE=menu` +in `/etc/default/grub` shows the menu. + +### Deleting the old root and absorbing non-adjacent space + +Two options for the freed gap: + +a) Second encrypted device appended to the same btrfs (no geometry + work; single-fs semantics): + +```bash +sudo cryptsetup luksFormat --type luks2 /dev/nvme0n1p6 +sudo dd if=/dev/urandom of=/etc/luks-second.key bs=4096 count=1 status=none +sudo chmod 600 /etc/luks-second.key +sudo cryptsetup luksAddKey /dev/nvme0n1p6 /etc/luks-second.key +sudo cryptsetup open --key-file /etc/luks-second.key /dev/nvme0n1p6 second +sudo btrfs device add /dev/mapper/second / +echo "second UUID=$(sudo blkid -s UUID -o value /dev/nvme0n1p6) /etc/luks-second.key luks" | sudo tee -a /etc/crypttab +sudo dracut --force --regenerate-all +``` + +A keyfile on the encrypted root avoids a second passphrase at boot. + +b) Physical relocation of the small boot-chain partitions (see above) + to make the freed space contiguous, then grow: + +```bash +sudo sgdisk --delete=2 /dev/nvme0n1 +sudo sgdisk --new=2:: --partition-guid=2:$UUID2 /dev/nvme0n1 +sudo partprobe /dev/nvme0n1 +sudo cryptsetup resize gravity +sudo btrfs filesystem resize max / +sudo fstrim -v / +``` + +Stale plaintext from the old partition in the absorbed region is +discarded via `fstrim` through the encrypted mapping (blkdiscard fails +with EBUSY on a mounted mapper). + +## Fedora 44 (Anaconda) reference behavior + +Fedora 44's own installer is a useful reference despite being GUI-based: + +- It offers a single high-level choice ("Encrypt my data" on the + storage screen); everything below /boot and /boot/efi gets + encrypted. One template-level toggle, not per-partition granularity. +- The default layout keeps the EFI System Partition and /boot + unencrypted and wraps the btrfs root in LUKS2; the Web UI actively + blocks an encrypted /boot without a workaround, matching the + Apple Silicon constraint that the stub, ESP, and /boot stay + plaintext for the boot chain. +- Defaults applied at install time: LUKS2, aes-xts-plain64, 512-bit + key, Argon2id key derivation. Build-side encrypted root images + should match these. +- Automation is first-class: kickstart `autopart --encrypted + --passphrase --luks-version=luks2` covers unattended installs. A + text-mode gap in Anaconda (no interactive encryption option) was + long-standing; CLI flows should treat the encrypted variant as a + first-class choice, not an expert-only path. +- Interactive installs use passphrases only; keyfiles come later from + the running system, which matches the post-install migration flow + in this document. + +## Verification patterns + +```bash +cat /proc/cmdline +df -h / +sudo btrfs filesystem show / +sudo cryptsetup status gravity +sudo fstrim -v / +``` + +Rollback at every stage: the old boot entry and root remain untouched +until the encrypted path is proven over several reboots; the GPT +backup restores with `sgdisk --load=`; content backups +(`dd` images) restore by re-copying. + +## Installer integration notes (fc44) + +The CLI installer runs on macOS and installs prebuilt partition images +raw onto `diskutil`-created partitions, so it cannot run cryptsetup at +install time. The two clean integrations are: + +- Build side: ship an OS template whose Root partition uses type + `luks` and a prebuilt root image containing the LUKS container, the + btrfs filesystem, and bootloader entries already carrying the + image's `rd.luks.uuid`. The installer writes the image raw as it + does today; no crypto tooling is needed on macOS. +- Installer side (this change): accept `"type": "luks"` in OS + templates and create the root partition with the Linux LUKS type + GUID so the partition table describes the encrypted container. + +For systems already installed without encryption, the post-install +migration procedure above covers converting to LUKS from the running +Linux system. + +`luks,discard` should remain the recommendation for generated +crypttab lines (silent fstrim failures are a common first-day +surprise otherwise); document that a keyfile under `/etc` protects a +migrated data volume only when the root filesystem is itself +encrypted.