feat: rebuild ESP as a 4096-byte-sector FAT during 4Kn conversion

A verbatim partition copy carries the EFI System Partition's FAT across
unchanged, so its boot sector still declares bytes/sector=512. On a 4Kn
target that FAT can't be mounted: the Linux vfat driver requires the FAT's
logical sector size to match the device's logical block size. In our
deployment this is where the Ironic Python Agent fails -- it cannot mount
the ESP to install the bootloader. (UEFI firmware would reject it later for
the same reason.) The filesystem can't be fixed by patching the BPB byte
alone, because a FAT's whole geometry (FAT table size, cluster addressing,
reserved/region layout) is expressed in units of the logical sector size.

Detect the ESP by its GPT type GUID and, instead of copying it verbatim,
rebuild its filesystem at 4096-byte sectors with its files preserved:

  - extract the source ESP's files with mcopy
  - format a same-sized image at 4096-byte sectors with mformat
    (-S 5, FAT32, label preserved; -T total-sectors is required, otherwise
    mformat sizes the FS by dividing the file by 512 and overshoots 8x)
  - verify the result with minfo (sector size + total sectors)
  - copy the files back and write it into the destination ESP region

All other partitions still copy verbatim: ext4 and the raw BIOS-boot area
are sector-size-agnostic. mtools is now required, but only when the image
contains an ESP (sfdisk + dd still suffice for ESP-less raw images).

Author: skrobul

scripts/convert_image_to_4k.py

@@ -6,13 +6,19 @@
 re-encoded as qcow2 on output (the temporaries are removed afterwards).
 
 The conversion preserves the byte offset and size of every partition, so the
-filesystems inside copy across unchanged -- only the partition table is rebuilt
-for 4096-byte logical sectors. The raw path uses no loop devices and no root.
+filesystems inside copy across unchanged. The partition table is rebuilt for
+4096-byte logical sectors, and the EFI System Partition's FAT is rebuilt at
+4096-byte sectors too (its files preserved) -- a verbatim 512-sector FAT records
+bytes/sector=512 in its BPB, which a 4Kn device can't mount (the Linux vfat
+driver requires the FAT's sector size to match the device's logical block size;
+UEFI firmware likewise won't read it). ext4 and the raw BIOS-boot partition are
+sector-size-agnostic and copy verbatim. No loop devices, no root.
 
 Usage:
     convert.py <source.img> <output.img>
 
 Requires: python3, sfdisk (util-linux 2.26+), dd (GNU coreutils).
+          mtools is required when the image contains an ESP (mformat/mcopy/...).
           qemu-img is additionally required only for qcow2 input.
 """
 
@@ -28,6 +34,9 @@
 RATIO = DST_SECTOR // SRC_SECTOR  # 8
 HEADROOM = 64 * 1024 * 1024  # tail room for the backup GPT + alignment
 
+# GPT type GUID of an EFI System Partition (its FAT must be rebuilt for 4Kn).
+ESP_TYPE_GUID = "C12A7328-F81F-11D2-BA4B-00A0C93EC93B"
+
 
 def die(msg):
     print(f"ERROR: {msg}", file=sys.stderr)
@@ -38,12 +47,13 @@ def info(msg):
     print(f">>> {msg}")
 
 
-def run(cmd, *, input=None, capture=False, what=None):
+def run(cmd, *, input=None, capture=False, what=None, env=None):
     """Run a command; die with context on failure. Returns stdout if captured."""
     res = subprocess.run(
         cmd,
         input=input.encode() if input is not None else None,
         stdout=subprocess.PIPE if capture else None,
+        env=env,
     )
     if res.returncode != 0:
         die(f"{what or cmd[0]} failed (exit {res.returncode})")
@@ -76,16 +86,23 @@ def transform_table(dump):
     return "\n".join(out) + "\n"
 
 
-def partition_ranges(dump):
-    """Yield (offset_bytes, size_bytes) for each partition in the source dump.
+def partitions(dump):
+    """Yield (offset_bytes, size_bytes, type_guid) for each partition in the dump.
 
     Byte offsets are identical on source and destination by construction.
     """
     for line in dump.splitlines():
         m_start = re.search(r"start=\s*(\d+)", line)
         m_size = re.search(r"size=\s*(\d+)", line)
-        if m_start and m_size:
-            yield int(m_start.group(1)) * SRC_SECTOR, int(m_size.group(1)) * SRC_SECTOR
+        if not (m_start and m_size):
+            continue
+        m_type = re.search(r"type=\s*([0-9A-Fa-f-]+)", line)
+        type_guid = m_type.group(1).upper() if m_type else ""
+        yield (
+            int(m_start.group(1)) * SRC_SECTOR,
+            int(m_size.group(1)) * SRC_SECTOR,
+            type_guid,
+        )
 
 
 # Known disk-image container formats, keyed by a magic signature at offset 0.
@@ -148,10 +165,19 @@ def convert_raw(src, dst):
         print(f"    {line}")
 
     # -- Copy partition contents ----------------------------------------------
-    # Each partition copies from its source byte range to the same destination
+    # Most partitions copy from their source byte range to the same destination
     # byte range; dd's *_bytes flags address by byte while using a large block.
+    # The ESP is special-cased: its FAT is rebuilt at 4096-byte sectors instead
+    # of copied verbatim (see rebuild_esp).
     info("Copying partition contents...")
-    for off, sz in partition_ranges(dump):
+    for off, sz, type_guid in partitions(dump):
+        if type_guid == ESP_TYPE_GUID:
+            info(
+                f"  ESP offset={off}B size={sz}B -> rebuilding FAT at "
+                f"{DST_SECTOR}-byte sectors"
+            )
+            rebuild_esp(src, dst, off, sz)
+            continue
         info(f"  offset={off}B size={sz}B")
         run(
             [
@@ -178,6 +204,168 @@ def convert_raw(src, dst):
     )
 
 
+def rebuild_esp(src, dst, off, sz):
+    """Rebuild the ESP's FAT at 4096-byte sectors, preserving its files.
+
+    A verbatim-copied ESP keeps bytes/sector=512 in its FAT BPB, which a 4Kn
+    device can't mount: the Linux vfat driver needs the FAT's sector size to
+    match the device's logical block size (this is where the Ironic deploy agent
+    fails when installing the bootloader; UEFI firmware likewise won't read it).
+    We extract the source ESP's files, format a fresh FAT with 4096-byte logical
+    sectors into a same-sized image, copy the files back, and write it into the
+    destination ESP region. Pure file ops -- no mount, no root.
+    """
+    for cmd in ("mformat", "mcopy", "minfo", "mlabel"):
+        if shutil.which(cmd) is None:
+            die(f"Missing required command: {cmd} (install mtools to rebuild the ESP)")
+
+    # MTOOLS_SKIP_CHECK relaxes mtools' geometry sanity checks, which otherwise
+    # trip on plain partition images that have no CHS geometry.
+    env = {**os.environ, "MTOOLS_SKIP_CHECK": "1"}
+    outdir = os.path.dirname(os.path.abspath(dst))
+    src_esp = _mktemp(outdir, "esp-src-", ".raw")
+    dst_esp = _mktemp(outdir, "esp-dst-", ".raw")
+    files = tempfile.mkdtemp(dir=outdir, prefix="esp-files-")
+    try:
+        # Extract the source ESP region into a standalone FAT image.
+        run(
+            [
+                "dd",
+                f"if={src}",
+                f"of={src_esp}",
+                "bs=8M",
+                "iflag=skip_bytes,count_bytes",
+                f"skip={off}",
+                f"count={sz}",
+            ],
+            what="dd (extract ESP)",
+        )
+
+        label = _fat_label(src_esp, env)
+        fat32 = _fat_is_fat32(src_esp)
+        info(
+            f"  source ESP: label={label or '(none)'} "
+            f"fat={'32' if fat32 else '12/16'}"
+        )
+
+        # Format an identically-sized image with 4096-byte logical sectors.
+        # -S 5 => 128 << 5 = 4096-byte sectors; -c 1 keeps 4096-byte clusters
+        # (matching the source's). mtools sizes the FS from the image length.
+        with open(dst_esp, "wb") as f:
+            f.truncate(sz)
+        # -T (total sectors) is required: mformat otherwise derives the count by
+        # dividing the file size by 512, ignoring -S, and overshoots 8x.
+        mfmt = [
+            "mformat",
+            "-i",
+            dst_esp,
+            "-S",
+            "5",
+            "-c",
+            "1",
+            "-H",
+            "0",
+            "-T",
+            str(sz // DST_SECTOR),
+        ]
+        if fat32:
+            mfmt.append("-F")
+        if label:
+            mfmt += ["-v", label]
+        mfmt.append("::")
+        run(mfmt, what="mformat", env=env)
+        _verify_esp_geometry(dst_esp, sz, env)
+
+        # Move the file tree across: extract from source, repopulate the new FS.
+        entries = _esp_extract(src_esp, files, env)
+        if entries:
+            run(
+                ["mcopy", "-s", "-n", "-m", "-i", dst_esp, *entries, "::/"],
+                what="mcopy (populate ESP)",
+                env=env,
+            )
+        else:
+            info("  source ESP has no files; new FAT left empty")
+
+        # Write the rebuilt filesystem into the destination ESP region.
+        run(
+            [
+                "dd",
+                f"if={dst_esp}",
+                f"of={dst}",
+                "bs=8M",
+                "conv=notrunc,fsync",
+                "oflag=seek_bytes",
+                f"seek={off}",
+            ],
+            what="dd (write rebuilt ESP)",
+        )
+    finally:
+        for path in (src_esp, dst_esp):
+            try:
+                os.remove(path)
+            except FileNotFoundError:
+                pass
+        shutil.rmtree(files, ignore_errors=True)
+
+
+def _fat_label(img, env):
+    """Read a FAT image's volume label via mlabel, or "" if it has none."""
+    out = run(["mlabel", "-i", img, "-s", "::"], capture=True, what="mlabel", env=env)
+    for line in (out or "").splitlines():
+        line = line.strip()
+        if line.startswith("Volume label is "):
+            return line[len("Volume label is ") :].split(" (")[0].strip()
+    return ""
+
+
+def _fat_is_fat32(img):
+    """Return True if the FAT image is FAT32 (per its BPB)."""
+    with open(img, "rb") as f:
+        bpb = f.read(512)
+    root_entries = int.from_bytes(bpb[17:19], "little")
+    fatsz16 = int.from_bytes(bpb[22:24], "little")
+    return root_entries == 0 and fatsz16 == 0
+
+
+def _verify_esp_geometry(img, sz, env):
+    """Confirm mformat produced a 4096-byte-sector FS spanning the whole image."""
+    out = run(["minfo", "-i", img, "::"], capture=True, what="minfo", env=env) or ""
+    m_ss = re.search(r"sector size:\s*(\d+)", out)
+    if not m_ss or int(m_ss.group(1)) != DST_SECTOR:
+        die(f"rebuilt ESP has wrong sector size; minfo said:\n{out}")
+    m_big = re.search(r"big size:\s*(\d+)", out)
+    m_small = re.search(r"small size:\s*(\d+)", out)
+    total = (
+        int(m_big.group(1))
+        if m_big and int(m_big.group(1))
+        else (int(m_small.group(1)) if m_small else 0)
+    )
+    expected = sz // DST_SECTOR
+    if total != expected:
+        die(
+            f"rebuilt ESP spans {total} sectors, expected {expected} "
+            f"(mformat did not size to the partition); minfo:\n{out}"
+        )
+
+
+def _esp_extract(img, dest_dir, env):
+    """Extract all top-level entries of a FAT image into dest_dir.
+
+    Returns the list of extracted local paths. An empty ESP yields []."""
+    res = subprocess.run(
+        ["mcopy", "-s", "-n", "-m", "-i", img, "::/*", dest_dir + "/"],
+        stderr=subprocess.PIPE,
+        env=env,
+    )
+    entries = [os.path.join(dest_dir, e) for e in sorted(os.listdir(dest_dir))]
+    if res.returncode != 0 and not entries:
+        return []  # empty ESP: the glob matched nothing
+    if res.returncode != 0:
+        die(f"mcopy (extract ESP) failed: {res.stderr.decode().strip()}")
+    return entries
+
+
 def convert_qcow2(src, dst):
     """Convert a qcow2 image: decompress to raw, rescale, re-encode as qcow2."""
     if shutil.which("qemu-img") is None:
@@ -229,16 +417,12 @@ def print_notes(dst, out_fmt):
             f"Write to the 4Kn device with:  dd if='{dst}' of=/dev/<disk> bs=8M conv=fsync"
         )
     info("")
-    info("Partition contents are copied verbatim; filesystems and boot code are not")
-    info("modified beyond rewriting the partition table. Two things to know:")
-    info(" - UEFI boot: no bootloader changes needed. The ESP is preserved and GRUB")
-    info("   finds its config/modules by partition number + path, both unchanged.")
+    info("The ESP was rebuilt as a 4096-byte-sector FAT (its files preserved); other")
     info(
-        "   But the ESP's FAT was made with 512-byte logical sectors (BPB bytes/sector"
+        "partitions were copied verbatim. UEFI boot needs no bootloader changes -- GRUB"
     )
-    info("   = 512); some 4Kn firmware refuses that. If the ESP won't mount after")
     info(
-        "   deploy, rebuild it for 4096-byte sectors (mkfs.vfat -F32 -S 4096) + restore."
+        "finds its config/modules by partition number + path, both unchanged. One note:"
     )
     info(" - Legacy BIOS boot: reinstall the bootloader. The MBR boot code is not")
     info("   carried over and GRUB's embedded core.img sector is a 512-byte LBA:")