VDDK 5.5.1 Release Notes

Release date: 11 MAR 2014 | Builds: ESXi 1623387, VDDK 1601882
For vSphere 5.5 U1. Last document update: 8 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.1 released with vSphere 5.5 U1 is a bug-fix update to VDDK 5.5.

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).

Additionally RHEL 6.4 proxy OS has been qualified with VDDK 5.5 and VDDK 5.5.1, so VDDK 5.5 and 5.5.1 support the following operating systems to perform proxy backup:

  • Windows Server 2003 R2
  • Windows Server 2008
  • Windows Server 2008 R2
  • Windows Server 2012
  • Red Hat Enterprise Linux RHEL 5.9, 6.2, 6.3, and 6.4.
  • SUSE Linux Enterprise Server SLES 10.4, 11.1, and 11.2.

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.1 Release Notes.

Recently Resolved Issues

The VDDK 5.5.1 release resolves the following issues.

  • Error message for insufficient Datacenter role was misleading.

    VDDK 5.1.x and VDDK 5.5 require the backup administrator to have permissions for the vCenter role, instead of just the Datacenter role. If the user has restricted permissions of a lesser role, the misleading message “not licensed to use this function” would appear. This has been the case since VDDK 5.1. It is fixed in this update by logging the message “Licenses could not be retrieved for supplied user credentials” instead.

  • Prepare-for-access call fails when using SSPI authentication.

    When using SSPI credentials for authentication, functions VixDiskLib_PrepareForAccess and VixDiskLib_EndAccess failed, returning error code 3. This was possibly a regression in VDDK 5.5, although the efficacy of SSPI was not fully tested in previous releases. The issue is fixed in this release.

  • Restoring and relocating a VM on Virtual SAN.

    You can back up virtual machines hosted on a Virtual SAN (VSAN) datastore, and you can restore to a VSAN datastore when overwriting the virtual disks. However you could not restore a VM to a different place on Virtual SAN. The error “mkdir not enabled, failing mkdir request” appeared. The issue is fixed in the 5.5 U1 release.

  • Sample program compiles for 32-bit instead of 64-bit.

    On Windows, the VixDiskLib sample program compiles as a 32-bit binary. In this release, the vcproj and sln files were changed to compile the sample program as a 64-bit binary.

  • Some log messages appear on system console, not in log file.

    On Windows, some log messages from VixDiskLib were thrown to the system console, rather than going to the designated log file. This has been fixed by diverting these messages to the designated callback function for logging.

  • Assert failure causes 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. This was fixed by checking for null lock token and cleaning up lock files if necessary.

  • Always reboot after uninstalling VDDK on a Windows proxy.

    Attempts to install or uninstall the Windows vstor2 driver using the provided scripts might be unsuccessful without rebooting. When uninstalling VDDK from a Windows proxy, you should reboot afterwards. If you do no, it may prove impossible to (re)install the vstor2 driver until the proxy is rebooted.

  • Threads still running after VixDiskLib_Exit call.

    When the VDDK plugin was loaded, several threads were started that could not be shut down until the calling application exited. For instance on Windows Server 2008, VDDK libraries left threads running after the VixDiskLib_Exit call. Still-running threads were from the vCenter vmacore library and could not be unloaded until the application finished. The leftover threads should be harmless, but in some cases the calling application could terminate unexpectedly. Even with the fix in this release, threads will continue to run as before. This fix addresses only the logging attempts that caused problems, not thread termination, due to extensive code changes required for termination.

  • VixMntapi now works better with GPT partitions.

    The VDDK 5.0 Release Notes said that the VixMntapi library did not support GPT. After a root cause analysis, VMware determined that the problem was partition ordering, with the shadow copy partition appearing first although it was index numbered later. So VixMntapi was modified to put the shadow copy partition in its expected order. This change enables file-level restore on Windows Server 2012.

  • Backup of >2TB disks could fail silently with HotAdd transport.

    When using HotAdd transport, backing up disks larger than 2TB could fail silently on Windows virtual machines. The issue occurred when disk.enableUUID was set True in the virtual machine. VDDK abruptly halted backup and wrongly returned success status. This has been fixed in the VDDK 5.5.1 release. See KB 2068424.

  • Advanced transport requires more memory on SLES 11.1.

    On a SLES 11.1 proxy using SAN or HotAdd transport, you need to increase the maximum locked memory, memory size, and virtual memory. Do this by specifying unlimited for the ulimit -l, -m, and -v options. RHEL has higher default limits than SUSE Linux, or no limits.

  • Error 87 with Windows 2012 NTFS.

    NTFS virtual disk from Windows Server 2012 might produce “Error 87” when a backup proxy mounts the disk read-only on earlier versions of Windows Server. The VDDK log contains the error “Volume/NTFS filesystem is corrupt (87).” This was determined to be a Windows backward compatability issue. If customers encounter this error, one workaround is to mount these virtual disks read/write so that the system has a chance to repair them.

For VDDK issues that were resolved before the vSphere 5.5 U1 release, see the VDDK 5.5 Release Notes.

Known Issues and Workarounds

The following VDDK issues were reported after the vSphere 5.5 GA release.

  • 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.

  • End Access call crashes if hostname does not resolve.

    Calls to VixDiskLib_EndAccess crash at VixDiskLibVim_AllowVMotion+0x169 if the server name provided in connection parameters (cnxParams.serverName) does not resolve correctly as a valid hostname. A fix has been identified and will be available in a future release.

  • 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.

  • 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 license key, the VixDiskLib_Open call returns a VIX_E_DISK_NOLICENSE error, even if hosts later in the list have an appropriate edition license key. The workaround is to remove and re-add the license in question; this deletes it from the initial position, and allows backups to run. The VDDK 5.5.3 release fixes this issue.

  • Cleanup function does not remove the HotAdd disks.

    After virtual disks are HotAdded with VixDiskLib_Open, they are 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, available in a future release, is to clean up or hot-remove any HotAdd disk based on mount information when VixDiskLib_Cleanup is called.

The following VDDK issues were reported during vSphere 5.5 testing, and still apply.

  • 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.