VDDK 5.5.3 Release Notes

Release date: 9 SEP 2014 | Builds: ESXi 2068190, VDDK 1909144
For vSphere 5.5 U2. Last document update: 4 MAY 2015
Check frequently for additions and updates to these release notes.

Contents


About the Virtual Disk Development Kit

The Virtual Disk Development Kit (VDDK) 5.5.3 released with vSphere 5.5 U2 is a bug-fix update to VDDK 5.5 and 5.5.1 (5.5.2 was a security update).

VDDK is used with vSphere Storage APIs for Data Protection (VADP) to develop backup and restore software. For general information about this development kit, how to obtain and install the software, programming details, and redistribution, see the VDDK documentation landing page.

The VMware policy concerning backward and forward compatibility is for VDDK to support N-2 and N+1 releases. In other words, VDDK 5.5 and all of its update releases support vSphere 5.0, 5.1, and 6.0 (except new features).

No additional guest OS testing was done for this release. VDDK 5.5.3 supports the same operating systems for proxy backup as VDDK 5.5.1.

Compatibility Notices for Partners

Support for SEsparse disks. Virtual disk libraries can handle SEsparse disk as implemented in vSphere. SEsparse disks are used for snapshots of > 2TB disks, and for linked clones in the VMware View environment (VDI). Backup and restore of SEsparse is supported for the advanced transports (NBD, NBDSSL, HotAdd, and SAN) but not for the host-based file transport.

For older compatibility notices from the VDDK 5.5 release, see the VDDK 5.5 Release Notes.

Recently Resolved Issues

The VDDK 5.5.3 release resolves the following issues.

  • OpenSSL library updated.

    The OpenSSL library was updated to version openssl-0.9.8za to address CVE-2014-0076, CVE-2014-0224, and CVE-2014-3470. This change was made in VDDK 5.5.2 and carries forward.

  • Cleanup function did not remove the HotAdd disks.

    After virtual disks were HotAdded with VixDiskLib_Open, they were not automatically cleaned up (hot-removed) by VixDiskLib_Cleanup. After disk is HotAdded or mounted, if a backup application crashes during backup due to network failure or power outage or any other issue, the leftover HotAdded disk must be cleaned up manually. Starting the backup application after a crash and calling VixDiskLib_Cleanup thereafter will clean up the mount directory, but will not hot-remove the disk. The fix is to clean up or hot-remove any HotAdd disk based on mount information when VixDiskLib_Cleanup is called.

  • Initialization functions can hang if OpenSSL library fails to load.

    During initialization with VixDiskLib_Init and /VixDiskLib_InitEx proper loading of the OpenSSL library was not verified. Lack of an error condition resulted in failure of other VDDK functions, and in some cases could cause VDDK libraries to hang. This was fixed by checking if OpenSSL loads properly, and setting an error code if loading fails.

  • Assert failure caused exit when HotAdd cannot acquire lock.

    When a backup using HotAdd transport could not acquire a file lock, and later tried to release the non-existent lock, it logged the error message “Panic: Assert Failed: _lockToken != __null” and exited prematurely. Possibly VIX_E_FILE_ERROR also appeared. This was fixed by using method HotAddMgr::NotifyAll to trigger retry of original HotAdd backup in a different transport mode.

  • Mount volume did not retain backup and restore privileges.

    When ACLs for SeBackupPrivilege and SeRestorePrivilege were enabled or disabled before calling VixMntapi_MountVolume, the original settings were lost. The fix is to remember the settings and restore them after mount volume ends.

  • VDDK version number incremented.

    The VDDK version number is 5.5.3 for vSphere 5.5 U2. Development partners should note that the Open Source License list may have changed.

  • VMDK metadata of all HotAdd disks sometimes removed when closing handle of one disk.

    When parallel backup operations on multiple disks were done using HotAdd mode, calling VixDiskLib_Close on one of the HotAdded disks deleted the VMDK metadata files of all other HotAdded disks. As part of fix, disk handle information is passed during the hot-remove, to ensure that files pertaining only to that disk handle get removed while the rest of the metadata files remain intact.

  • Open call could fail with no-license error. Due to a flaw in license checking logic, if the first host in the list had “esxBasic” edition key, the VixDiskLib_Open call returned a VIX_E_DISK_NOLICENSE error, even if hosts later in the list had an appropriate license edition key. License checking logic has been corrected in this release.

  • Outdated PDF manuals removed from Windows VDDK.

    The 5.5 Windows VDDK package mistakenly included obsolete PDF manuals. These old PDF manuals have been removed from the 5.5.3 Windows VDDK.

  • Better security with SAN transport verbose logging.

    When the VDDK configuration file has level 5 or 6 (verbose or trivia) logging enabled, some customer-private information mistakenly appeared in the vixDiskLib log file. This happened only with SAN transport, not with other transport types. Now you can safely set the vixDiskLib.transport.LogLevel higher than 4.

For issues resolved in the VDDK 5.5.1 release, see the VDDK 5.5.1 Release Notes.

Known Issues and Workarounds

The first VDDK issue was reported recently. Remaining issues were reported during vSphere 5.5 testing, and still apply.

  • HotAdd fails with more than five concurrent backup operations.

    When a backup application uses more than five (5) concurrent processes to back up or restore virtual machines using the HotAdd transport mode, one or more of the operations may fail. Logs will contain errors such as “The directory is not empty” and “Error acquiring instance lock” then “HotAdd ManagerLoop caught an exception.” The workaround is to reduce the number of concurrent backup or restore processes to five (5) or less.

  • With >2TB local or NFS disks, create child fails with mount error.

    VixDiskLib_CreateChild creates a redo log for virtual disks, for example when backup software needs to mount a disk and perform write operations on it without committing the changes to base disk. When the base disk is larger than 2TB, vSphere creates the redo log in SEsparse format. Managed disk can handle this format, but hosted disk does not support SEsparse, so when the virtual disk is local or on an NFS partition, VixMntapi_OpenDisks fails with the VIX_E_MNTAPI_NO_MOUNTABLE_PARTITIONS error. This is expected behavior. The workaround is to power off the virtual machine and open the original base disk read-only, thus avoiding creation of a child disk.

  • Virtual machine restore may crash during socket operations.

    During virtual machine restore, crashes have been reported due to an unexpected exception thrown by the vmacore library calling the async_connect function. This could be caused by network conditions such as loopback being rejected by the firewall. A fix has been identified and will be available in a future release.

  • Rapidly opening and closing virtual disk may cause already-locked error.

    Calling VixDiskLib_Open and VixDiskLib_Close in rapid succession may throw VIX_E_FILE_ALREADY_LOCKED (error code 15). With a slight delay introduced, the error disappears. One workaround is for the program to retry VixDiskLib_Open after an already-locked error.

  • Assert failure when getting NFC ticket during multiple VM backups.

    Before opening a virtual disk, the VMware libraries log into vCenter Server and acquire an NFC ticket. When multiple backup applications run on one host, or when one backup application simultanously backs up multiple virtual machines, the VMware libraries apparently have timer-related issues. Assertion failure when getting an NFC ticket causes the application to crash. A fix (insert negligible timeouts) was tested and will be available in a future release.

  • Open call might crash after network login with NBD transport.

    It is possible for the VixDiskLib_Open call to crash in gvmomi.dll after an NFC (network file copy) login, required for NBD mode, has failed. The gvmomi library initially checks for an empty load queue, but then references the queue without rechecking. VixDiskLib_PrepareForAccess and VixDiskLib_EndAccess can also cause a crash when the load queue is empty. A fix has been identified and will be available in a future release.

  • Error code may not be set correctly before VDDK exit.

    An application calling VDDK libraries should return its own exit code, but QuickExit (part of the vmacore library) may terminate the VDDK application before it can set the proper exit code. This problem began when VDDK 5.1 was modified to call QuickExit. A fix has been identified, but it might never be applied to a VDDK 5.5 update release due to the extensive nature of required changes to the code.

  • Metadata write is not supported for HotAdd and SAN transport.

    When a program calls VixDiskLib_WriteMetadata with HotAdd or SAN transport, the function returns an error saying “The operation is not supported” and supplied metadata never gets written to virtual disk. The workaround is to close the disk from HotAdd or SAN mode, reopen the disk using NBD or NBDSSL mode, then call VixDiskLib_WriteMetadata.

  • HotAdd transport not possible with SATA virtual disks.

    ESXi 5.5 adds support for SATA disks in virtual machines created with, or upgraded to, virtual hardware version 10. However HotAdd advanced transport is not supported for SATA drives. So disk library code may reject requests for SATA disk with this error: “Cannot use [this] transport to mount virtual machines with non-SCSI disks.” This caveat does not apply to SATA disks in SCSI, iSCSI, or FC connected storage arrays.

  • Read-only mount of Windows ReFS with VixMntapi.

    On Windows Server 2012 systems with Resilient File Systems (ReFS), the VixMntapi library can mount ReFS partitions read-only, but not read/write.

  • Boot disk should be scsi0:0 for use with mount API.

    When a virtual machine's boot disk is not on scsi0:0, the VixMntApi_GetVolumeInfo function does not correctly return the inGuestMountPoints (such as drive letter C:) or the numGuestMountPoints. On a scsi0:0 disk the correct information is returned, but not otherwise. For example with a scsi0:2 boot disk, the two properties are not populated. This issue was recently reported against VDDK 5.0 and later.

  • Possible segmentation violation if running multiple backup processes.

    When many simultaneous backup processes are running, some of them might crash with a SIGSEGV after many iterations. This is due to a possible race condition in VixDiskLib, which can be reduced by calling VixDiskLib_Exit() at the end of your program.

For VDDK issues that were identified in the vSphere 5.5 release, see the VDDK 5.5 Release Notes.