Document that host-switch isn't needed for shared-storage vMotion

[doccaz]

Summary

Investigated the "Host-switch AIO messages" (NFC_AIO_SWITCH_HOST_*) backlog item. The binary's own strings (SWITCHHOST_VADP, a PreSwitchHost callback string carrying a full new-host descriptor) show this is VDDK's mechanism for keeping an NFC/backup session alive across a live vMotion. Testing it needed a second ESXi host in the cluster with shared storage.

Three findings, fully closing the question:

1. Compute-only vMotion (shared NFS datastore) while an SSL-hook-captured native-VDDK NFC read session stayed open — completely unaffected.
2. Combined storage+compute vMotion — a disk on host-local VMFS the target host had no path to at all, relocated to shared storage and the compute moved to that host, in one RelocateVM_Task. Still completely unaffected, including reads issued after the migration fully completed. Both times the wire capture shows a single TCP fd for the entire session, no reconnect, no NFC_AIO_SWITCH_HOST_* traffic.
3. No public API surface for the mechanism at all — grepped every header in the VDDK 8.0.3 SDK for SwitchHost/Callback and found only the documented, unrelated completion/progress/logging callbacks. There is no public registration function for PreSwitchHost anywhere. Whatever this mechanism does, it's wired into VMware's own internal/first-party tooling (VADP), not reachable through any API a third-party client — or OpenVixDiskLib — actually links against. This closes the investigation without needing to test the remaining scenario (the connected host itself becoming unavailable) by disrupting a real lab host — there's no code path by which a normal client could ever need to implement this regardless.

• docs/host_switch.md — the investigation and evidence (both vMotion tests plus the API-surface finding)
• docs/host_switch_lab_setup.md — the 2-host/shared-storage lab build (reused an existing NFS server already running in the underlying cluster rather than standing up new storage)
• docs/reverse_engineering_procedure.md / README.md updated

Also found, and corrected mid-PR: an earlier commit on this branch mischaracterized a real finding as NFS-specific — that opening a running VM's disk over NFC needs a snapshot. It doesn't matter which datastore type; confirmed by powering on SLES16 (an ordinary long-lived VMFS-backed lab VM) and reproducing the identical failure. This project's own lab pytest fixture never powers on its temp VM, so every prior capture in this whole project had been reading a powered-off VM's disk without that being a deliberate choice.

Test plan

• Compute-only vMotion with an active NFC session — zero effect
• Combined storage+compute vMotion with an active NFC session — zero effect, verified via wire capture (single fd, no reconnect)
• Confirmed the "needs a snapshot when powered on" finding is general, not NFS-specific, against a second VM on VMFS
• Confirmed no public VDDK SDK API exists for the host-switch callback mechanism (all three headers checked)

Note on PR sequencing

Stacked on top of the unmerged direct-ESXi/GetInfo/QueryAllocatedBlocks/CBT work (PRs #3–#6), same as #7 and #8 — this branch's history includes their combined commit, so the diff shown here will shrink to just the three new commits (a84a0ae, 133457e, bf99794) once those merge. Docs-only, no code changes, no overlap with the other PRs.

[petrutlucian94]

This document contains some potentially useful information but I'm not sure if we should document the vCenter / vMotion deployment procedure here, especially referencing scripts that aren't included in the repo.

[doccaz]

Good point, thanks. I trimmed docs/host_switch_lab_setup.md down to the generic requirements for a 2-host vMotion lab: shared datastore, second host in the same cluster, vMotion enabled on a VMkernel adapter, and the RelocateVM_Task check. I removed the environment-specific parts (how the NFS server and the nested host were provisioned) and every reference to scripts that aren't in the repo.

Those references pointed at a local .lab/ directory that we never committed. It holds the scripts I used for the encryption and host-switch investigations:

• Lab setup: vc_setup.py and move_host_to_cluster.py (add a host to vCenter and move it into a cluster), mount_nfs_datastore.py (mount the same NFS export on both hosts), esx_capacity.py and esx_netinfo.py (host RAM and network checks), and a VCSA deploy config template.
• Encryption: nkp_setup.py (creates a Native Key Provider over REST), create_encrypted_vm.py, encrypt_with_vtpm.py, encrypt_disk.py, check_disk_encryption.py, and relocate_encrypted_vm_cross_host.py (cold-relocates an encrypted VM to a host that has never held its key).
• Host-switch tests: trigger_vmotion.py and trigger_storage_vmotion.py trigger a live or storage vMotion while vddk_loop_read_trace.py holds an NFC read session open under an SSL hook. Both tests were negative: one TCP fd for the whole session, and no NFC_AIO_SWITCH_HOST_* traffic.
• Tracing: sslhook.c and vddk_open_crypto_trace.py (VDDK tracing through an SSL hook), and ovdl_crypto_readwrite.py (a read/write test on an encrypted disk).

They currently have hard-coded assumptions about my lab and would need sanitizing first. Would you like me to add any of them to the repo? If not, the docs stand on their own now.

[petrutlucian94]

Thanks for cleaning up the the docs. I'd keep it simple for now so that we can merge it more easily.