How vphone-cli Handles APFS Boot Snapshot Modification for CFW Installation

vphone-cli modifies APFS boot snapshots by renaming the com.apple.os.update-* snapshot to a disabled prefix using offline block-level editing, causing the iOS kernel to fall back to the live volume without mounting the filesystem.

The Lakr233/vphone-cli project enables custom firmware (CFW) installation on virtual iPhones by manipulating APFS boot snapshots before the VM starts. This technique performs APFS boot snapshot modification entirely on the host side, flipping the boot source to allow CFW execution while maintaining filesystem integrity.

The Challenge of APFS Boot Snapshots in Virtualized iOS

iOS utilizes sealed system volumes and APFS snapshots to ensure boot security. When the kernel boots, it searches for a snapshot named com.apple.os.update-* followed by a 64-character hexadecimal hash. If found, it boots from that sealed snapshot; otherwise, it falls back to the live volume. For CFW installation, this behavior must be reversed without accessing the running VM.

Traditional approaches require tools like snaputil inside the guest OS. However, vphone-cli implements APFS boot snapshot modification offline by directly manipulating the raw disk image blocks, avoiding any filesystem mount or kernel syscalls.

Offline Snapshot Renaming Architecture

The modification pipeline consists of a host-side shell script that invokes a specialized Python utility to rewrite APFS metadata blocks before the VM boots.

Host-Side Trigger in cfw_install_host.sh

After attaching the VM's Disk.img as a raw block device, scripts/cfw_install_host.sh launches the rename tool:

# scripts/cfw_install_host.sh

"$PY" "$PROJ/tools/apfs_snap_rename.py" "$IMG"

This call occurs while the disk image is offline, ensuring no filesystem drivers are active during the modification.

Block-Level Processing in apfs_snap_rename.py

The tools/apfs_snap_rename.py utility performs four critical operations on the raw image:

1. Pattern Detection The script scans the image for the byte sequence com.apple.os.update- followed by a 64-character hex hash—the standard APFS update snapshot identifier.

2. Fletcher-64 Checksum Verification For each match, the tool extracts the containing 4 KB block and validates the APFS metadata using the Fletcher-64 checksum algorithm. As implemented in lines 24‑31 of apfs_snap_rename.py, only blocks passing this verification are considered genuine APFS metadata, preventing accidental modification of strings embedded in Mach-O binaries or other data.

3. Prefix Replacement The matched prefix is replaced with orig-fs.disabled.rn- (or a user-supplied --new-prefix argument). Because the replacement string maintains identical length to the original, the B-tree node ordering remains unchanged, preserving filesystem structure.

4. Checksum Recalculation After modification, the cksum function (lines 23‑31) recomputes the Fletcher-64 checksum, and the new value is written back to the block at lines 84‑86.

# Conceptual flow from apfs_snap_rename.py

# Lines 24-31: Verify checksum

# Lines 84-86: Write new checksum after rename

Preserving APFS Metadata Integrity

The safety of this APFS boot snapshot modification relies on strict constraints:

• Equal-Length Replacement: The default prefix orig-fs.disabled.rn- is exactly the same length as com.apple.os.update-<hash>, ensuring B-tree block pointers and node ordering remain valid.
• Checksum Validation: Only blocks with valid Fletcher-64 checksums are modified, guaranteeing that no unrelated data corruption occurs.
• Raw Block Operation: By operating on 4 KB blocks rather than mounted filesystem structures, the tool avoids cache coherency issues and driver-level constraints.

Practical Implementation Examples

Performing a Dry Run

Preview changes without modifying the image using the --dry-run flag:

# Preview the rename operation with a custom prefix

$ tools/apfs_snap_rename.py Disk.img --dry-run --new-prefix "myboot.snap-"

Integrating into Build Scripts

Automate the APFS boot snapshot modification in custom installation pipelines:

#!/usr/bin/env zsh
IMG="/path/to/your/VM/Disk.img"
PY=$(command -v python3)
PROJ="/path/to/vphone-cli"

# Rename the APFS boot snapshot before VM start

"$PY" "$PROJ/tools/apfs_snap_rename.py" "$IMG"

Summary

• vphone-cli performs APFS boot snapshot modification entirely offline through scripts/cfw_install_host.sh invoking tools/apfs_snap_rename.py.
• The rename tool locates com.apple.os.update-* snapshots by pattern matching and validates targets using Fletcher-64 checksums on 4 KB blocks.
• Replacing the prefix with an equal-length string (orig-fs.disabled.rn- by default) preserves B-tree integrity while disabling the sealed snapshot boot.
• The iOS kernel subsequently boots from the live volume, enabling CFW installation without internal VM tooling.
• Additional repository references include sources/VPhoneCore/VPhoneResources.swift (Swift-side URL provision) and documentation in AGENTS.md.

Frequently Asked Questions

Does vphone-cli mount the APFS volume to modify boot snapshots?

No. The tool operates entirely on raw image blocks without mounting the filesystem or invoking kernel-level syscalls. It reads the Disk.img file directly, scans for APFS metadata patterns, and rewrites specific 4 KB blocks after checksum verification.

How does the APFS boot snapshot modification ensure data integrity?

The apfs_snap_rename.py script verifies the Fletcher-64 checksum of every candidate block (lines 24‑31) before modification and recalculates the checksum after renaming (lines 84‑86). Additionally, because the new prefix matches the original length exactly, the B-tree structure and block ordering remain intact, preventing filesystem corruption.

What prefix replaces the original snapshot name?

By default, the tool replaces com.apple.os.update- with orig-fs.disabled.rn-. Users can specify a custom prefix using the --new-prefix argument, provided it maintains the same character length as the original snapshot name to preserve metadata alignment.

Where is the rename utility located in the vphone-cli repository?

The core utility resides at tools/apfs_snap_rename.py. The host-side orchestration script is located at scripts/cfw_install_host.sh, while sources/VPhoneCore/VPhoneResources.swift provides the Swift-side resource URL. Documentation regarding the tool's role in the CFW pipeline appears in AGENTS.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}