@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 a vectura 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. | | NBD_SERVER_EXITED | The vectura server exited, e.g. on a wrong thumbprint or a disk the host refuses to open. Raised by NbdStdioClient, which carries the tail of its stderr on the error. | | 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. | | NO_CHANGE_ID | Asked for changed block, but change block was not tracked when snapshotted |

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.

License

ISC © Vates SAS