mirror of https://github.com/vatesfr/xen-orchestra.git synced 2026-10-12 02:24:05 +00:00

Files

T

Florent BEAUCHAMP 3bf50c38ee fix(vmware-explorer): fixes omnibus (#10363 )

This branch is a reliability overhaul of the ESXi/vSphere source side of V2V, plus a scope reduction of the package. The SOAP plumbing is rewritten:

    VimClient wraps @vates/node-vsphere-soap in a promise API with one emitter per call (no more cross-talk between concurrent calls, no listener leak) and a pTimeout;
    vim25 faults are now parsed (_parseFault.mjs) so callers get a real fault type instead of task execution failed;
    the library no longer throws from async callbacks (which killed xo-server) and its beforeExit logout hook is per-client instead of removeAllListeners.
    Request specs are built in explicit schema order (soap/specs.mjs) with xsi:type, and property values are normalized (soap/normalize.mjs) so search() and the new #retrieveProperty share one shape.
    search() now paginates, cancels the retrieval and destroys the container view.
    Datastore HTTP downloads get session-cookie reuse, retry with jittered backoff, a headers-only timeout, and range-honouring validation.
    Task waiting polls with backoff and per-operation timeouts (6 h for snapshot consolidation).
    nbdkit servers are memoized by a key that includes the export options, the readiness wait races the process death instead of sleeping 2 s
    the password file is 0600 and unlinked
    the thumbprint is read over TLS in-process instead of two openssl spawns.
    The old VHD-over-datastore readers (VhdEsxi*, Datastore*, openDeltaVmdkAsVhd) are deleted, hence the majo, rleaving the vddk/NBD path with a COWD grain-directory parser as data-map fallback.
    ~1.7k lines of unit tests are added.

2026-09-11 17:36:38 +02:00

5.7 KiB

Raw Blame History

@xen-orchestra/vmware-explorer

Reads the VMs and the disks of an ESXi host or a vCenter

Install

Installation of the npm package:

npm install --save @xen-orchestra/vmware-explorer

Usage

Reads the inventory, the metadata and the disks of an ESXi host or a vCenter, over vim25 SOAP and the /folder HTTP endpoint, and exports the content of a disk through an nbdkit server.

Errors

Every error raised by this package carries a code, so that a caller can branch on a failure without matching its message. There are three families.

Faults of the host are passed through verbatim, as the vim25 fault type: FileLocked, InvalidPowerState, ManagedObjectNotFound, NotAuthenticated, InvalidDeviceSpec… These are the codes to branch on whenever the host itself refused an operation, and they are documented in the vim25 API reference. A task which failed without the host naming a fault type reports TASK_FAILED instead.

Failures of the transport keep the code of the error underneath: ECONNREFUSED, ECONNRESET, EHOSTUNREACH, ENOTFOUND, ETIMEDOUT, ENOENT when a binary is missing, and the UND_ERR_* codes of undici.

Failures of this package use the codes below.

code	meaning
`BAD_VIM25_SPEC`	A vim25 spec was built with an element the schema does not declare. This one is a bug of this package, not a problem of the host.
`BAD_VMX_PATH`	The `files.vmPathName` of a VM is not `[datastore] dir/vm.vmx`. Carries `vmId`.
`DATACENTER_NOT_FOUND`	No datacenter holds the named datastore, and a file cannot be downloaded without one. Carries `dataStore` and the `dataStores` which are known.
`DATASTORE_NOT_FOUND`	An absolute disk reference of a vmx or a vmsd is on no known datastore. Carries `filePath` and `dataStoreUrls`.
`ESXI_SESSION_EXPIRED`	The session of the HTTP endpoint was refused (401 or 403), which happens on an import lasting hours. Retried after authenticating again.
`NBDKIT_EXITED`	The `nbdkit` server exited before it started listening, e.g. on a wrong thumbprint or a missing vddk library. Its logs are named in the message.
`NBDKIT_NOT_LISTENING`	The `nbdkit` server is running, but never started listening on its port.
`NO_DATA_MAP`	The allocated ranges of a disk could not be read: an unreadable vmdk descriptor, or a delta in a format which is not supported. The disk has to be transferred in full instead of as a delta.
`NO_PROPERTY`	The host returned no value for the property which was read, e.g. because the object is gone.
`NO_TASK`	A `*_Task` method answered without a task to wait for.
`RANGE_IGNORED`	The host answered something else than the byte range which was requested. Reading it would use the wrong offset, or as much memory as the file is big.
`TASK_FAILED`	A task ended in error, and the host named no fault type for it.
`TASK_TIMEOUT`	A task did not complete within its deadline. It keeps running on the host, so it is not retried: starting a second one would not make the first go away.

ESXI_SESSION_EXPIRED and the transport failures are transient, and are retried inside the package — while downloading from a datastore, and while polling a task. Every other code is reported to the caller on the first occurrence.

Contributions

Contributions are very welcomed, either on the documentation or on the code.

You may:

report any issue you've encountered;
fork and create a pull request.

5.7 KiB Raw Blame History