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

> Discover how vphone-cli modifies APFS boot snapshots for CFW installation. Learn about its offline block-level editing and kernel fallback mechanism for seamless updates.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: how-to-guide
- Published: 2026-09-05

---

**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`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/cfw_install_host.sh) launches the rename tool:

```zsh

# 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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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.

```python

# 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:

```bash

# 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:

```zsh
#!/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`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/cfw_install_host.sh) invoking [`tools/apfs_snap_rename.py`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/sources/VPhoneCore/VPhoneResources.swift) (Swift-side URL provision) and documentation in [`AGENTS.md`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/tools/apfs_snap_rename.py). The host-side orchestration script is located at [`scripts/cfw_install_host.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/cfw_install_host.sh), while [`sources/VPhoneCore/VPhoneResources.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/VPhoneCore/VPhoneResources.swift) provides the Swift-side resource URL. Documentation regarding the tool's role in the CFW pipeline appears in [`AGENTS.md`](https://github.com/Lakr233/vphone-cli/blob/main/AGENTS.md).