xen-orchestra/@xen-orchestra/vmware-explorer/vectura/README.md

Vectura

Vectura reads VMware virtual disks over the NFC protocol. It is one Linux binary with two commands:

• vectura serve logs in to an ESXi host, opens one virtual disk and serves it read-only as an NBD export on its own standard input and output. The program that spawned it reads any range of the disk, in any order, and ends the session when it is done.
• vectura fingerprint prints the certificate thumbprints a host presents on its management and data ports, so an operator can pin them before any credential is sent.

Vectura targets ESXi 7.x and 8.x hosts, reached directly or through a vCenter; with a vCenter, the disk is read from the ESXi host its ticket names. An ESXi 6.x host is refused at the data port's greeting. Certificate verification can be pinned or pointed at a CA bundle but never skipped, and the password is read from VECTURA_PASSWORD only.

Install

The binary, vectura, ships in this directory with @xen-orchestra/vmware-explorer, and xo-server runs it from there. It runs on Debian 12, Ubuntu 22.04 or newer (amd64) and needs nothing but glibc. To use it by hand, copy it to a directory in PATH:

sudo install vectura /usr/local/bin/

To build from source, install the build-essential package (the TLS library compiles C) and let rustup pick the pinned toolchain from rust-toolchain.toml:

cargo build --release --locked

Try it

vectura fingerprint --host esxi.example
read -rs VECTURA_PASSWORD && export VECTURA_PASSWORD
vectura serve --host esxi.example --user root --vm-id 3 \
  --disk '[datastore1] vm/vm.vmdk' \
  --thumbprint sha256:<the 443 sha256 line printed above>

After the last command, standard output is an NBD stream and standard error is the only place a message for a person appears. An NBD client that can talk to a child process over its pipes, such as libnbd's connect_command, reads the disk from there. The tutorial below walks through it.

Documentation

Tutorial, for the first run:

• Read your first disk

How-to guides, one task each:

• Pin a host certificate
• Copy a disk to a raw image
• Drive Vectura from a program
• Tune depth and compression
• Troubleshoot a session

Reference, the facts:

• Command line
• The NBD export
• The transcript
• Host requirements and limits

Explanation, the reasoning:

• How a disk is read
• The security model
• Scope and design choices

Development and release

.github/workflows/vectura.yml runs cargo fmt, cargo clippy, the tests, cargo deny, the coverage floor and the binary build on every push that touches this directory. The pre-commit hook runs cargo fmt --check when a .rs file is staged.

A change to vectura needs its own line in the packages list of CHANGELOG.unreleased.md:

- vectura patch

scripts/gen-deps-list.js then lists ./scripts/bump-pkg vectura <type>, followed by a release of @xen-orchestra/vmware-explorer, which bundles the binary. bump-pkg runs scripts/release.sh: it bumps the version in Cargo.toml and Cargo.lock, rebuilds the binary in place of the previous one and commits both as feat(vectura): <version>. tests/bundled_binary.rs fails when the binary and Cargo.toml disagree, or when the binary lost its executable bit.

The build links against glibc 2.34 through zig, whatever the glibc of the machine, so the binary runs on Debian 12 and Ubuntu 22.04. It needs zig (0.16.0 tested) and:

cargo install --locked [email protected]