VDDK 1.2.1 Release Notes

Released 17 Nov 2010   |   Build Number 323406
Last document update 19 Oct 2012.


About the 1.2.1 Virtual Disk Development Kit

The Virtual Disk Development Kit (VDDK) 1.2.1 is a bug fix release to VDDK 1.2.

VDDK 1.2 added support for ESX/ESXi 4.1 and vCenter Server 4.1, application-level VSS quiescing on Windows Server 2008 (R2), and was tested with Windows 7 virtual machines, in addition to previously tested Windows XP, Windows Server, and Linux systems. VDDK 1.2 and 1.2.1 support the following VMware platform products:

  • ESX/ESXi versions: 4.1, 4.0, and 3.5
  • vCenter Server versions: 4.1 and 4.0 managing ESX/ESXi 3.5 and later
  • VirtualCenter version: 2.5 managing ESX/ESXi 3.5

These release notes provide information about issues that were identified or resolved since VDDK 1.2. For information on VDDK including general information about the development kit, how to obtain and install the software, redistributing it, and issues that were identified or resolved in previous releases, see the VDDK 1.2 Release Notes.

VMware Consolidated Backup (VCB) has a knowledge base article (link here) showing the support matrix for storage multipathing. VMware does not provide a similar support matrix for VDDK. Customers should seek this information from their backup software vendors.

Compatibility Notice for Partners

VDDK 1.2.1 does not support vSphere 5.
ESXi 5.0 includes VMFS-5, an updated file system with larger volumes to hold big virtual machines. In SAN transport mode, libraries check VMFS headers for an acceptable version number match. Older VDDK libraries do not recognize VMFS-5, so SAN transport may fail on VMFS-5 partitions. VMware recommends recompiling software with VDDK 5.0 to support vSphere 5.

The VDDK 1.1 FAQ stated that VDDK licensing requires paid vSphere platform products, not free ESXi standalone. Although VDDK 1.1 and 1.1.1 included advanced transports, this licensing was not enforced until the VDDK 1.2 and 1.2.1 releases, when a license check was inserted for advanced transports.

In February 2011, RHEL 5.6 was qualified for use with VDDK 1.2.1.

The following table summarizes platform compatibility of recent VDDK releases.

CompatibilityESX 3.5ESX 4.0ESX 4.1Caveats and Changes
VDDK 1.1.1YesYesYesVSS application level quiescing not supported for Windows 2008 VMs on ESX 4.1 hosts.
No HotAdd support when proxy server is on ESX 4.1 host.
VDDK 1.2.1YesYesYesAs of VDDK 1.2 the vmcryptolib.dll library is no longer required by VDDK libraries.

While all versions of vSphere allow the at-sign (@) in datastore names, the VixDiskLib API is unable to open VMDK files inside those datastores. You might want to modify your backup code to throw an error in such a case. The customer workaround is to avoid datastore names with the at-sign (@) when using VDDK.

Recently Resolved Issues

This release of the VDDK resolves the following issues:

  • Solution for write-protected SAN on Windows Server 2008 proxy.

    When using SAN transport or HotAdd mode on a Windows Server 2008 proxy, make sure to set the Windows SAN policy to onlineAll, otherwise writes produce the error message “media is write protected.”

  • More-complete cleanup after Windows disk mount

    If programs called VixMntapi_OpenDisks() and subsequently called VixMntapi_MountVolume() and VixMntapi_GetVolumeInfo(), log files such as vixmntapi0.LOGn were created but never deleted under the Administrator's local settings folder in Temp\vmware-Administrator-*. This did not occur if opening with VixMntapi_OpenDiskSet(). The problem was fixed in the VDDK 1.2 release by deleting temporary files created by Windows while mounting registry hives, and by shutting down the mount server after dismounting the last volume.

  • Can now simultaneously mount cloned disks on Windows

    When VixMntapi_MountVolume() tried to simultaneously mount two disks with same disk signature, the mount failed with error 12, VIX_E_FILE_ALREADY_EXISTS, “cannot create a file when that file already exists.” This occurred only on Windows when mounting disks from two VMs if one was cloned from the other, or both were cloned from an original VM. The issue was fixed by checking similarity of UUID and getting another if needed.

  • Password no longer error-logged in clear text

    When an VDDK error occurred, such as failure to connect or open a disk, the error was logged along with the user name and password in cleartext. This issue was fixed by sanitizing the password to read “xxx” instead.

  • Advanced transport modes available again in ESX 3.5

    VDDK 1.2.1 again supports advanced transports, such as SAN mode, with VirtualCenter 2.5 and ESX/ESXi 3.5. VDDK 1.2 had a regression where it did not support advanced transport modes in VC 2.5 and ESX 3.5.

  • No more time-outs for NBD operations in ESX 3.5

    The 3 minute timeout instituted in VDDK 1.2 has been eliminated. Although the underlying performance problem was fixed in VI 3.5 U3 and vSphere 4.0 U1, the downside is that NBD operations might hang in earlier releases. You can still set a custom timeout by editing the configuration file.

  • Most of the messages now pass through the Log function

    In previous VDDK releases, some error messages were sent only to the console (stderr) instead of going through the Log function. So the log file did not record all messages, missing those sent to stderr only. The default Log function sends messages to the console and writes them to the log file. Now if programmers define a custom Log function to replace the default one, most messages will pass through their function.

Known Issues and Workarounds

The following known issues pertain to this VDDK release. Most of these issues are holdovers from the VDDK 1.2 release.

  • Changed Block Tracking could return full thin-provisioned disk.

    On very large thin-provisioned virtual disks (> 200GB) the first QueryChangedDiskAreas call could return the entire disk, rather than only the in-use areas of thin-provisioned disk. This results in excessively large backup data.

  • HotAdd code should ignore independent disks, which are unsuitable for backup

    The HotAdd transport should not be used to back up virtual machines with a VMDK configured as “independent“ (not capable of snapshots). Any attempt to use HotAdd in this circumstance causes an error that results in none of the VMDKs being HotAdded, even ones capable of snapshots.

  • HotAdd limitation when VMFS block sizes are mismatched

    HotAdd cannot be used if the VMFS block size of the datastore containing the virtual machine folder for the target virtual machine does not match the VMFS block size of the datastore containing the proxy virtual machine. For example, if you back up virtual disk on a datastore with 1MB blocks, the proxy must also be on a datastore with 1MB blocks.

  • Do not use HotAdd mode to back up the backup proxy

    After using HotAdd transport mode to back up the virtual machine that serves as the backup proxy, the backup completes successfully, but during cleanup, regular virtual disk is mistakenly removed along with HotAdded disk. This will be fixed in the next release. If you mistakenly use HotAdd mode, you will have to run the vSphere Client, select the proxy VM, edit settings, and re-add the “Hard Disk” VMDK file from storage.

  • Possible confusion about VDDK version number

    The VDDK version number remains “2.1” for this release. In the log files, you can distinguish the 1.2.1 release by looking at the build number following the version number.

  • VDDK and VADP do not support IP version 6

    The 1.2 release of VDDK has not been tested with VADP and the new IPv6 features of vSphere 4.

  • Backing up thick disk requires the maximum disk size to be available

    When backing up a thick disk, the proxy virtual machine datastore must have at least as much space available as the maximum configured disk size for the virtual machine to be backed up.

  • Read/Write operations might fail with SAN transport mode in Windows Server 2008 Proxy

    Attempts to read or write to a volume after it was opened using VixDiskLib_Open() sometimes does not work as expected when running on a Windows Server 2008 proxy using SAN transport mode. To address this issue you can manually clear the read-only attribute.

  • Advanced accelerated transport modes require XML library

    Attempts to use advanced accelerated transport modes might fail if the XML library expat is not installed in the guest operating system. VDDK 1.1 used version 1.95.7 for Windows 32-bit, 1.95.8 for Linux and Windows 64-bit. VDDK 1.2 and 1.2.1 use version 1.95.8 for Windows 32-bit as well. To resolve this issue, install the appropriate libexpat version. If binary compatibility is present, you can use a higher version.

  • With SAN transport mode, cannot write to redo logs, only to base disk

    When programs write to remote disk that was opened in SAN transport mode, they can write to the base disk, but they cannot write to a snapshot (redo log). Opening and writing to a snapshot is supported for hosted disk.

  • VDDK sample code -single option is not supported remotely

    The vixdisklibsample.cpp file should be modified to remove the -single option, which cannot open the specified remote disk as a single link, instead opening the entire chain. VDDK does not support -single for remote disks that have child disks.

  • Multiple sequential connections over SAN results in WrongThreadException

    Attempts to use SAN advanced transport mode to establish multiple sequential connections may fail, resulting in a WrongThreadException. For example, a first thread might be created that connects to a disk, reads from the disk, closes the disks, and then disconnects. Then if a subsequent thread attempts to open the same disk, a failure may occur. To avoid this issue, use NBDSSL advanced transport mode when establishing multiple sequential connections.

  • Cleanup of HotAdd disks can affect changed block tracking.

    During backup or restore, disks may be HotAdded, and subsequently removed after task completion. This cleanup might remove the change tracking (ctk) file, so that changed block tracking (CBT) could fail. This issue should resolve itself automatically. If it does not, the workaround is to power cycle the virtual machine.

  • Mounting HotAdded disks may fail and not be cleaned up

    In some cases, an attempt to mount a HotAdded disk fails. In such cases, directories can be created but are not removed by the standard cleanup process. To resolve this issue, manually remove the disks from the proxy virtual machine and delete the \tmp\vmware directory created in the current user's Documents and Settings directory, typically found at C:\Documents and Settings\username\Local Settings\Temp\vmware-username\. The next time a snapshot is created or deleted for the virtual machine, redo logs will get cleaned up.

  • HotAdd and SAN transports fail with some Linux distributions

    Attempts to use advanced transports fail on Ubuntu 7.10, SLES 11, and Fedora Core 8. HotAdd and SAN advanced transports work as expected with RHEL up to version 5.6. For better Linux support, developers can upgrade to VDDK 5.0, which is backward compatible.

  • SAN mode on Linux might report stale data

    When performing SAN reads from a proxy machine, the Linux OS may cache the reads. If the proxy tries again to read the same data block and the SAN disk data block is still in the cache, the Linux OS might satisfy the read from the cache instead of reading it again from the disk. To avoid this issue, you could clear the cache between backups, for example with the following command if the Linux kernel supports it:
    echo 1 > /proc/sys/vm/drop_caches

  • VixDiskLib should check SAN accessibility on disk open

    Programs that open a local VMDK in SAN mode might be able to read (if the disk is empty) but writing to virtual disk fails. Checking accessibility on open is a feature enhancement request. Even when a program calls VixDiskLib_ConnectEx() with NULL parameter to accept the default transport mode, SAN is selected as the preferred mode, if SAN storage is available from the ESX/ESXi host. Then if the program opens a VMDK on local storage, upcoming writes will fail. In this case, the program should explicitly pass nbd or nbdssl as the preferred transport mode.


Copyright © 2010 VMware, Inc. All rights reserved.