esx-hcl-check is a command-line tool designed for vSphere and VMware Cloud Foundation (VCF) administrators. It connects to a vCenter server, extracts the exact hardware inventory of your ESXi hosts, and automatically verifies those components against the Broadcom VMware Compatibility Guide API and the offline vSAN database.
The tool natively handles complex extraction tasks such as parsing binary CPUID instruction sets, identifying PCI bus architectures to distinguish between standard HBAs and NVMe drives, and extracting BIOS, firmware, and driver versions directly from the hypervisor — all through the vSphere API, without ever running esxcli on a host. It reports a per-component verdict (TRUE, FALSE, N/A, ERROR, or SKIPPED) for the system chassis, processors, I/O devices, and vSAN disks, collects hosts in parallel, and returns a findings-based exit code so it can gate upgrades directly in CI/CD. It can also run fully air-gapped.
Check out the releases to find the latest binaries for your system. Release binaries are built with the SLSA3 Go builder and ship with signed build provenance — see Verifying Release Binaries.
To compile this code from source, you will need:
- Go (Golang): Version 1.18 or higher is recommended.
- Network Access: To download the required
govmomiSDK dependencies.
Build Instructions:
-
Clone the repository to your local machine. Dependencies are pinned in the committed
go.mod/go.sumand fetched automatically on first build. -
Build the executable:
go build -o esx-hcl-check .To stamp a version into the binary (reported by -version), pass it via -ldflags:
go build -ldflags "-X main.version=v0.4.0 -X main.commit=$(git rev-parse --short HEAD) -X main.date=$(date -u +%Y-%m-%dT%H:%M:%SZ)" -o esx-hcl-check .Official release binaries are stamped automatically. A plain go build reports version dev.
Every release binary is built by the SLSA3 Go builder and published alongside a signed provenance attestation (<binary>.intoto.jsonl) that proves it was built from this repository, at the released tag, by the trusted builder — not tampered with in transit or produced on someone's laptop.
To verify a download, install slsa-verifier and run:
slsa-verifier verify-artifact \
esx-hcl-check-linux-amd64 \
--provenance-path esx-hcl-check-linux-amd64.intoto.jsonl \
--source-uri github.com/dominikzorgnotti/esx-hcl-check \
--source-tag v0.6.0A PASSED: SLSA verification passed result confirms the binary's origin and integrity.
esx-hcl-check uses the same environmental connection variables as the standard govc CLI tool. You must set these variables in your terminal environment before running the tool.
Linux / macOS:
export GOVC_URL="vcsa.yourdomain.com"
export GOVC_USERNAME="administrator@vsphere.local"
export GOVC_PASSWORD="YourSecurePassword!"
export GOVC_INSECURE=1Windows (PowerShell):
$env:GOVC_URL="vcsa.yourdomain.com"
$env:GOVC_USERNAME="administrator@vsphere.local"
$env:GOVC_PASSWORD="YourSecurePassword!"
$env:GOVC_INSECURE="1"Once your variables are set, run the tool with the mandatory release parameter:
./esx-hcl-check -release="ESXi 9.1"By default (GOVC_INSECURE unset or 0, and -k not passed) the vCenter certificate is verified against your host's system root CA store. Enabling insecure mode (GOVC_INSECURE=1 or -k) disables verification entirely — the connection then trusts any certificate and is vulnerable to man-in-the-middle interception, so use it only for trusted, self-signed lab environments.
For everything short of disabling verification, the same govc TLS settings are honored. Each has an environment variable and, where govc provides one, an equivalent command-line flag; the flag overrides the environment variable:
| Variable | Flag | Purpose |
|---|---|---|
GOVC_TLS_CA_CERTS |
-tls-ca-certs |
Path(s) to PEM CA bundle(s) to trust instead of the system roots. Separate multiple paths with the OS path-list separator (: on Linux/macOS, ; on Windows). |
GOVC_TLS_KNOWN_HOSTS |
-tls-known-hosts |
Path to a known_hosts-style file of host thumbprint entries, used as a fallback when normal chain verification fails (thumbprint pinning). |
GOVC_TLS_HANDSHAKE_TIMEOUT |
(none) | Go duration string (e.g. 10s) bounding the TLS handshake. |
A missing/invalid CA bundle or an unparseable timeout is a hard error rather than a silent fallback to weaker verification. When insecure mode is on, the CA-bundle and known-hosts settings have no effect (verification is off) and the tool warns you.
esx-hcl-check has two collection modes. Run esx-hcl-check -h or esx-hcl-check rvtools -h for the same grouping on the command line — the subcommand's help hides the flags that do not apply to it.
esx-hcl-check -release "ESXi 9.1" [flags] # scan vCenter (default)
esx-hcl-check rvtools -source <path> -release "ESXi 9.1" [flags] # check an RVTools export
See Checking from an RVTools export for what this mode can and cannot verify.
| Flag | Description | Default |
|---|---|---|
-source |
[REQUIRED] Path to the RVTools export: a directory holding the CSV-per-tab export or the .xlsx workbook, or a direct *vHost*.csv / .xlsx file. |
None |
Not used by the rvtools subcommand, which reads an export instead of connecting.
| Flag | Description | Default |
|---|---|---|
-u |
vCenter/ESX URL. Overrides the GOVC_URL variable. |
$GOVC_URL |
-k |
Skip verification of the server certificate (insecure). Overrides the GOVC_INSECURE variable. |
$GOVC_INSECURE |
-tls-ca-certs |
PEM CA bundle(s) to trust instead of system roots. Overrides the GOVC_TLS_CA_CERTS variable. |
$GOVC_TLS_CA_CERTS |
-tls-known-hosts |
TLS known-hosts thumbprint file. Overrides the GOVC_TLS_KNOWN_HOSTS variable. |
$GOVC_TLS_KNOWN_HOSTS |
-dc |
Target a specific Datacenter. Overrides the GOVC_DATACENTER variable. | "" |
-cluster |
Target a specific Cluster. Overrides the GOVC_CLUSTER variable. | "" |
-workers |
How many hosts to collect from at once. 1 runs fully sequentially (one host at a time); higher values collect that many hosts in parallel. Valid range is 1–8 (hard maximum 8): values above 8 are capped, and values below 1 are rejected. Use 1 in constrained or rate-sensitive environments. |
4 |
Apply to both modes.
| Flag | Description | Default |
|---|---|---|
-release |
[REQUIRED] The target ESXi release version to validate compatibility against (e.g., "ESXi 9.1", "ESXi 8.0 U3"). | None |
-offline |
Run without internet access. Skips all Broadcom Compatibility Guide API checks (affected components are marked SKIPPED) and verifies only against the local vSAN HCL database. See Offline / Air-Gapped Operation. |
false |
-vsanhcl |
Path to the local vSAN HCL offline JSON database. Automatically downloaded if missing or outdated. | vsan-offline-hcl.json |
-exclude |
Path to the JSON file containing rules to drop specific devices from the scan. | exclude.json |
-vsan |
Extracts vSAN SSDs and NVMe drives and checks them against the vSAN HCL database. | false |
-nohcl |
Skips the Broadcom HCL validation phase entirely. Useful to just extract the vSphere hardware payload. | false |
Apply to both modes.
| Flag | Description | Default |
|---|---|---|
-json |
Outputs the final HCL evaluation results as a JSON payload instead of a text table. | false |
-csv |
Outputs the results as CSV (one row per device) to stdout, with the same detail as -json. Redirect with > report.csv. Takes precedence over -json. |
false |
-details |
Includes raw hardware identifiers (VID, DID, SVID, SSID) in the output. Auto-enables -json (unless -csv is set, giving a detailed CSV). |
false |
-map |
Lists each network card and storage adapter individually with its ESX device name (vmnicN / vmhbaN) and link state (UP/DOWN). See Mapping adapters to ESX device names. Shapes -json/-csv output; defaults to -json if neither is given; incompatible with -unique. |
false |
-unique |
Aggregates and deduplicates all hardware findings globally across all scanned hosts. | false |
-unsupported |
Filters the output to ONLY show hardware components that are NOT certified. | false |
-mismatch |
Filters the output to ONLY show certified hardware that has an unsupported Firmware or Driver installed. | false |
-quiet |
Suppresses the Issues section that lists devices for which firmware/driver information could not be retrieved. | false |
-stats |
Emits run statistics: inventory counts (datacenters, clusters, hosts, IO cards, storage devices) and query timings (vCenter, Broadcom HCL, vSAN DB). In JSON this adds a top-level stats object; in text, a Statistics section. |
false |
-vspherejson |
Path to save the raw collected hardware inventory as JSON. If empty, a file is written to the OS temp directory. | "" (temp dir) |
| Flag | Description | Default |
|---|---|---|
-debugpci |
Bypasses I/O filters and dumps all unknown PCI devices into the raw JSON file for troubleshooting. | false |
-version |
Prints the version, commit, and build date, then exits. | false |
1. Find non-certified components globally across your environment:
./esx-hcl-check -release="ESXi 9.1" -unique -unsupported
2. Find certified hardware running the WRONG firmware or driver:
./esx-hcl-check -release="ESXi 8.0 U3" -mismatch
3. Export a complete, deduplicated, detailed JSON payload for CI/CD or reporting (includes supported driver/FW lists):
./esx-hcl-check -release="ESXi 9.1" -unique -json -details -vsan
4. Export a spreadsheet for Excel / asset management:
./esx-hcl-check -release="ESXi 9.1" -unique -vsan -details -csv > hcl-report.csv
5. Gate an upgrade in CI/CD (the exit code drives the pipeline):
./esx-hcl-check -release="ESXi 9.1" -unique -json > report.json
case $? in
0) echo "All certified — proceed with the upgrade." ;;
1) echo "Uncertified hardware found — block." ; exit 1 ;;
2) echo "Result undetermined (skipped host, lookup error, or -offline) — needs review." ; exit 1 ;;
esacSome environments only permit tools the customer already runs. For those, esx-hcl-check can take its inventory from an RVTools export instead of connecting to vCenter:
./esx-hcl-check rvtools -source ./rvtools-export -release "ESXi 9.1" -json-source accepts a directory holding either the CSV-per-tab export or the single .xlsx workbook, or a direct path to a *vHost*.csv / .xlsx file. Both export formats are read with the standard library — no spreadsheet dependency is added to the build.
All the usual output and filter flags (-json, -csv, -unique, -details, -unsupported, -quiet, -stats) work exactly as in a vCenter scan; the subcommand replaces only the collection phase. Running esx-hcl-check without a subcommand is unchanged and still scans vCenter.
RVTools reports the same host identity fields the tool normally reads from the vSphere API, so the server model check is exact. It does not carry the data the other checks need:
| Check | From RVTools | Result |
|---|---|---|
| System / chassis | vHost Model |
✅ real TRUE / FALSE verdict |
| CPU | no CPUID in the export | SKIPPED |
| NICs, storage adapters | no PCI IDs (the PCI column is the bus address, not the device ID) |
not reported |
| Firmware / driver certification | no firmware, no driver versions | N/A |
Nothing undeterminable is ever reported as FALSE — those checks are SKIPPED, so an RVTools run always exits 2 ("could not be fully determined"), never 0. Treat it as a server-model pre-check, not as a complete HCL verdict; a full check needs a vCenter scan.
The server-model verdict is release-specific, not a blanket answer. The same HP ProLiant DL380 Gen9 export resolves as:
| Target release | Verdict |
|---|---|
ESXi 7.0 U3 |
TRUE |
ESXi 8.0 U3 |
FALSE |
ESXi 9.1 |
FALSE |
which matches the hardware's real support window (Gen9 was dropped with vSphere 8.0), while a ProLiant DL380 Gen10 from the same environment resolves TRUE for ESXi 9.1.
The CPU cannot be verified from any RVTools export: the Broadcom CPU guide is indexed by CPUID, and a model-name lookup returns no rows even for a certified processor. Reporting
SKIPPEDis therefore the honest answer, not a limitation of the parser.
esx-hcl-check relies on two Broadcom internet endpoints — the Compatibility Guide API and the vSAN offline HCL database. Before the HCL phase runs, the tool probes both (unless -nohcl or -offline is set). If either is unreachable, it aborts early with a clear message naming the failed endpoint(s) and three ways forward:
- Verify the host has internet access to
broadcom.com - Configure a proxy via the
HTTPS_PROXY/HTTP_PROXY/NO_PROXYenvironment variables (these are honored automatically; note that a TLS-intercepting proxy typically surfaces as a certificate error instead) - Re-run with
-offline
-offline runs a partial verification without any internet access:
- All Broadcom Compatibility Guide API checks are skipped. Components that can only be verified via that API — the system chassis, the CPU, and any I/O device not found locally — are reported as
SKIPPED. - I/O controllers, NICs, and vSAN SSDs that are present in the local vSAN offline HCL database still receive a real
TRUE/FALSEverdict. - The vSAN database is not auto-downloaded. Place it on disk beforehand at the default path (
vsan-offline-hcl.json) or point to it with-vsanhcl <path>. If it is missing, the tool tells you to download it fromhttps://vvs.broadcom.com/service/vsan/all.json.
Because an offline run cannot fully determine certification, it exits with code 2 (see below).
The process exit code reflects the scan findings, so esx-hcl-check can be used directly as a pre-upgrade gate in CI/CD without parsing its output:
| Code | Meaning |
|---|---|
0 |
Every scanned component is certified (or not applicable). |
1 |
At least one component is definitively not certified. |
2 |
The result could not be fully determined — a host or cluster was skipped (disconnected, in maintenance, or a permissions/API error), an HCL lookup failed, a check was skipped (SKIPPED, e.g. under -offline), or a fatal run error occurred (connection, inventory, or file write). A 2 takes precedence over a 1. |
Only report data is written to stdout — the text table, or the JSON payload with -json. All diagnostics (progress messages, warnings, and errors) go to stderr. This means you can safely pipe or redirect the report (> report.json) without diagnostics contaminating it.
Pass -stats to measure a run. It reports how much inventory was collected and how long each external dependency took — useful for sizing large environments and for seeing the effect of -workers.
With -json, a stats object is added at the top level, alongside results and issues:
{
"results": [ ... ],
"issues": [ ... ],
"stats": {
"datacenters": 1,
"clusters": 4,
"hosts": 15,
"io_cards": 100,
"storage_devices": 30,
"vcenter_query_ms": 1234,
"broadcom_hcl_query_ms": 5678,
"vsan_db_query_ms": 234
}
}Without -json, the same figures are printed as a Statistics section (Inventory + Runtime). The broadcom_hcl_query_ms timing counts only live calls, so with cross-host de-duplication it reflects the true network cost rather than the number of devices.
Hosts that cannot be scanned are no longer silently dropped. Each appears in the output with a skip_reason (e.g. host not connected (state: disconnected), property-collector-error: ..., or could not enumerate hosts: ...), and the JSON also carries a source field identifying the originating vCenter.
By default, identical adapters on a host are collapsed into a single result with a number_of_instances count — you see what hardware is present, not which port it is. Pass -map (together with -json or -csv) to expand every network card and storage adapter into one row per physical adapter, each annotated with:
esx_device_name— the ESX-assigned adapter name (e.g.vmnic0for a NIC,vmhba1for a storage HBA).link_state—UPorDOWN. For NICs it reflects the physical link. For storage adapters it is reported only where a link concept applies — fabric/target-attached HBAs (FC/iSCSI) that reportonline/offline; internal RAID/SAS controllers have no link, solink_stateis omitted for them rather than showing a misleadingDOWN.
Because each adapter is printed individually, number_of_instances is dropped for those rows (other device classes — CPU, system, GPU, vSAN disks — are unaffected and keep it). Both fields come from the vSphere API (config.network.pnic and config.storageDevice.hostBusAdapter) — no esxcli.
-map only affects the machine-readable formats. If you pass -map without -json or -csv, it defaults to -json (like -details) so the fields are actually emitted. It is the opposite of -unique (which aggregates across hosts), so the two cannot be combined.
./esx-hcl-check -release="ESXi 9.1" -json -map{
"device": "QLogic 57810 10 Gigabit Ethernet Adapter",
"device_type": "io card (network)",
"current_firmware": "Storm: 7.13.20.0 MFW: 7.16.13",
"current_driver_version": "1.4.51.0",
"driver_name": "qfle3",
"hw_certified": "TRUE",
"driver_certified": "N/A",
"firmware_certified": "N/A",
"esx_device_name": "vmnic0",
"link_state": "UP",
"hcl": "https://compatibilityguide.broadcom.com/search?..."
}esx-hcl-check runs in three phases: it collects a hardware inventory from vCenter, verifies each component against Broadcom's HCL data, then reports the result. A deliberate design constraint shapes the whole tool:
It never runs
esxclior any command on the hosts. Everything is read through the vSphere API (govmomi) using your existing vCenter credentials. This keeps the tool safe to run against production and requires no host-level access — at the cost of a few extraction limits noted below.
Hosts are queried in parallel (bounded by -workers) via the vCenter property collector. For each host the tool extracts the system make/model and BIOS, decodes the processor's CPUID from the raw CPU feature bits, and enumerates every PCI device — classifying it as a NIC, Fibre Channel / RAID controller, GPU, or NVMe device — plus vSAN SSD/NVMe disks (-vsan).
Where it gets firmware and driver versions without esxcli:
- NICs — firmware, driver, and driver version come directly from the physical-NIC properties.
- NVMe controllers — firmware from the NVMe topology; driver name from the PCIe HBA; driver version from vSphere 9.1+ (see below).
- Fibre Channel / RAID HBAs — these fields are not modeled by the vSphere API on releases before 9.1. On vSphere 9.1 and later the tool retrieves them through a targeted SOAP call. On older releases they are unavailable, and the affected devices are listed in the Issues section with the reason — rather than guessing or shelling out to
esxcli. - NVMe vendor tokenization — vSphere often reports the vendor of a direct-attached NVMe drive generically as "NVMe" and folds the real vendor (Dell, Samsung, …) into the model string. The tool tokenizes the model to recover it for matching.
Broadcom does not expose deep firmware/driver matrices through its live API for unauthenticated queries, so the tool uses two data sources and prefers the richer one:
-
The vSAN Offline Database (local, authoritative for firmware/driver). Storage controllers and vSAN SSD/NVMe devices are first matched here — by exact hex identifiers (VID, DID, SVID, SSID) for controllers/NVMe, or by vendor + model tokens for disks. A match yields not just a certified baseline but the arrays of certified driver and firmware versions, which the tool cross-references against what is actually installed. This is what powers the
driver_certified/firmware_certifiedcolumns, thesupported_drivers/supported_firmwareslists (-details), and the-mismatchfilter. Driver versions are matched by prefix so vendor build suffixes don't cause false mismatches. -
The live Broadcom Compatibility Guide API (fallback, baseline only). Anything not covered by the offline DB — the system chassis, the CPU, and all NICs and other I/O devices — is checked against the live API. Each device class is matched against its own guide: I/O devices by PCI ID (
program=io), the system and CPU by model/CPUID, and GPUs against the dedicated vSphere third-party GPU guide (program=sptg). The GPU guide is fetched once and each GPU is matched by exact VID:DID — the reliable join key, since vSphere device names carry form-factor noise (e.g.NVIDIA H100 NVL PCIe 94GBvs the guide'sNVIDIA H100 NVL) and short model tokens collide across siblings (L4vsL40S). This confirms whether the hardware baseline is certified (TRUE/FALSE) but cannot certify an exact firmware/driver combination, so those columns reportN/A. Live calls are protected by timeouts and bounded retry/backoff, and identical hardware seen across many hosts is queried once and reused (cross-host de-duplication) to avoid hammering the endpoint.
The vSAN Offline Database (vsan-offline-hcl.json) is downloaded automatically, refreshed when older than 24 hours, and written atomically with an integrity check so an interrupted or truncated download can never corrupt the cache. Relocate it with -vsanhcl, or run fully air-gapped with -offline (see Offline / Air-Gapped Operation).
Out of scope — vSAN RDMA NIC HCL. The offline database's NIC category is Broadcom's vSAN RDMA/RoCE NIC list, which is separate from — and more restrictive than — the general I/O device HCL. Matching general NICs against it produced false negatives (an adapter certified for the current release appearing as supported only up to an old one). The tool therefore does not use the vSAN RDMA NIC list: NIC compatibility is verified against the general I/O device HCL via the live API. Consequences: NIC verdicts require internet (under
-offlinea NIC is reportedSKIPPED), and this tool does not assess a NIC's suitability for vSAN RDMA/RoCE.
Every result carries three verdicts — hw_certified, driver_certified, and firmware_certified — each one of:
| Value | Meaning |
|---|---|
TRUE |
Certified for the target release. |
FALSE |
Checked and not certified. |
N/A |
Not applicable or not determinable from the available data (e.g. a firmware verdict for a device the offline DB has no matrix for, or any driver/firmware column when only the live API baseline was available). |
ERROR |
A live Broadcom API lookup failed (network or parse error). Kept distinct from FALSE so a transient outage is never mistaken for "not certified". |
SKIPPED |
The check was not performed — e.g. an API-only check under -offline, or a CPU whose CPUID the host did not report (the Broadcom CPU guide is indexed by CPUID, so certification cannot be determined from the model name). |
In large environments, you may want to ignore non-critical components (like integrated AHCI controllers or USB bridges) to prevent them from cluttering your reports. You can achieve this by creating an exclude.json file in your working directory.
This is also the intended way to handle embedded management / BMC display adapters — HPE iLO VGA, the Matrox G200 found on many server baseboards, and similar. These are enumerated as PCI display devices, so the tool classifies them as GPUs and checks them against the vSphere third-party GPU guide, where they are (correctly) not listed — surfacing them as FALSE. They are not discrete accelerators and are not meant to be certified there, so exclude them rather than treating the FALSE as a finding. The shipped exclude.json already lists iLO5 VGA as an example; add the exact device name (or PCI ID) your hosts report for other management VGA adapters.
You can filter devices using three different methods:
- names: An exact string match of the device name.
- regex_names: A Regular Expression applied to the device name.
- ids: Specific hexadecimal hardware identifiers (VID, DID, SVID, SSID).
Example exclude.json Payload:
{
"names": [
"Lewisburg SATA AHCI Controller",
"VMware NVMe Controller",
"iLO5 VGA"
],
"regex_names": [
"Lewisburg.*",
"(?i)^intel.*usb.*"
],
"ids": [
{
"vid": "8086",
"did": "a1d2"
},
{
"vid": "15b3",
"ssid": "0091"
}
]
}