5.7 KiB
@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.