Skip to content

Add Changed Block Tracking (CBT) support - #6

Open
doccaz wants to merge 2 commits into
cloudbase:masterfrom
doccaz:pr4-cbt
Open

doccaz wants to merge 2 commits into
cloudbase:masterfrom
doccaz:pr4-cbt

Conversation

@doccaz

@doccaz doccaz commented Sep 19, 2026

Copy link
Copy Markdown

Summary

CBT turned out to need no NFC reverse engineering at all: VirtualMachine.QueryChangedDiskAreas — the actual changed-byte-range query real backup tools use, distinct from VDDK's own VixDiskLib_QueryAllocatedBlocks (a different, disk-internal allocated-block bitmap) — is public VIM API with no VDDK/NFC involvement whatsoever.

Adds thin wrappers:

  • enable_change_tracking — sets changeTrackingEnabled via ReconfigVM_Task
  • disk_change_id — reads a disk's current changeId off its backing, once CBT is active and a snapshot exists
  • query_changed_disk_areas — the actual changed-range query, converted to plain dataclasses

Also documents real-world characteristics found through live testing that aren't obvious from the API docs:

  • A wildcard changeId="*" query (the initial-full-backup path) reports only allocated regions on a thin-provisioned disk, not the full sparse virtual capacity.
  • A single large contiguous write comes back as one extent regardless of size; only the number of discontiguous changed regions drives how large the extent list gets — the real scaling risk for CBT on a busy disk is fragmented random I/O, not big sequential writes.

Full workflow and lab evidence: docs/cbt.md.

Test plan

  • New unit tests (ValueError paths, VIM call argument/result conversion, mocked — no lab needed): pytest tests/unit/test_nfc_auth.py
  • New integration test exercising the full cycle: enable CBT, snapshot, write a known sector, snapshot, query, verify the write falls inside the reported extent
  • Validated against a live standalone ESXi 8.0.3 host

Note on PR sequencing

Last of 4 focused PRs splitting up the original combined PR #2 (now closed). Zero code overlap with the other three (direct-ESXi fix, GetInfo+DDB_GET, QueryAllocatedBlocks) — pure VIM API, no NFC touched at all. Can merge independently in any order. (The integration test's write step uses the existing NFC write path, so it was validated live by temporarily stacking on the direct-ESXi fix locally, since our test lab is a bare ESXi host that needs that fix to connect at all — the CBT code itself has no such dependency.)

🤖 Generated with Claude Code

CBT turned out to need no NFC reverse engineering at all:
VirtualMachine.QueryChangedDiskAreas -- the actual changed-byte-range
query real backup tools use, distinct from VDDK's own
VixDiskLib_QueryAllocatedBlocks (a different, disk-internal
allocated-block bitmap) -- is public VIM API with no VDDK/NFC
involvement whatsoever.

Adds thin wrappers: enable_change_tracking (sets
changeTrackingEnabled via ReconfigVM_Task), disk_change_id (reads a
disk's current changeId off its backing, once CBT is active and a
snapshot exists), and query_changed_disk_areas (the actual changed-
range query, converted to plain dataclasses).

Also documents real-world characteristics found through live testing,
not obvious from the API docs:
- A wildcard changeId="*" query (the initial-full-backup path) reports
  only *allocated* regions on a thin-provisioned disk, not the full
  sparse virtual capacity.
- A single large contiguous write comes back as one extent regardless
  of size; only the number of *discontiguous* changed regions drives
  how large the extent list gets -- the real scaling risk for CBT on
  a busy disk is fragmented random I/O, not big sequential writes.

Adds unit tests (ValueError paths, VIM call argument/result
conversion, mocked -- no lab needed) and an integration test exercising
the full cycle: enable CBT, snapshot, write a known sector, snapshot,
query, verify the write falls inside the reported extent. Validated
against a live standalone ESXi 8.0.3 host. Full workflow and lab
evidence: docs/cbt.md.
@petrutlucian94

Copy link
Copy Markdown
Member

I was a bit surprised when I saw this PR since it's already covered by the public QueryChangedDiskAreas method.

I'm not against having this small wrapper in OpenVixDiskLib though, especially since it was marked as a missing feature / TODO.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants