Virtual Disk Development Kit 1.2 Release Notes

Released 12 JUL 2010   |   Build 230216

Last document update 17 SEP 2013.


About the 1.2 Virtual Disk Development Kit

The Virtual Disk Development Kit (VDDK) 1.2 is an update to the VDDK 1.1.1. VDDK 1.2 adds support for ESX/ESXi 4.1 and vCenter Server 4.1. It has been tested with Windows 7 virtual machines, in addition to previously tested Windows XP, Windows Server, and Linux systems. Application-level VSS quiescing is now available for Windows Server 2008 and Windows Server 2008 R2 virtual machines.

These release notes provide information about issues that have been identified or resolved since VDDK 1.1.1. For information on VDDK including general information about the development kit, how to obtain and install the software, issues that were identified or resolved in previous releases, see Virtual Disk Development Kit 1.1.1 Release Notes.

VDDK 1.2 works with the following VMware platform products:

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

Redistributing the Software

Partners can obtain a license to redistribute VMware binaries for support of their VDDK applications. On Linux virtual machines that do not have VDDK installed, you can install vmware-vix-disklib executables and libraries from the bin{32,64}, lib{32,64}, and plugins{32,64} directories. To enable VDDK-based binaries on Windows virtual machines that do not have VDDK installed, take the following steps:

  1. Install the Microsoft Visual C++ (MSVC) redistributable, possibly as a merge module. The latest MSVC runtime works as side-by-side component, so manually copying it might not work on Vista. See the Microsoft Web site for x86 processors or x64 processors.
  2. Install VMware executables and DLLs from the \bin, \lib, and \plugins folders of the VDDK, and the vstor2-mntapi10.sys driver (see below for location).
  3. Install your application, compiled in a manner similar to the vixDiskLibSample.exe program.

Resolved Issues

This release of the VDDK resolves the following issues:

  • Connections possible to vCenter Server on ports other than 443

    In this release (and 1.1.1) VDDK supports connecting to vCenter Server using ports other than 443.

  • Writing to disk using NBDSSL transport mode now supported

    Restoring snapshots required read/write mode, so NBDSSL could not be used to restore snapshots. NBDSSL is now supported for operations including restoring snapshots.

  • Timeout caused NBD operations to fail

    If a disk is opened in NBD or NBDSSL mode and no disk activity occurs for 3 minutes, the server will time out and disk operations will fail. VixDiskLib may fail to release resources, so subsequent cleanup attempts by VixDiskLib_Cleanup() could crash due to null pointers. The underlying problem was fixed in VI 3.5 U3, vSphere 4.0 U1, and vSphere 4.1. For earlier releases, a workaround is to provide a configuration file with the VixDiskLib_InitEx() call specifying a longer time-out:
    vixDiskLib.nfcFssrvr.TimeoutMs = "<timeoutInMilliseconds>"

  • Hot Add supported for proxy virtual machines with SAS adapters

    In previous releases, Hot Add could fail if the proxy virtual machine lacked IDE CD-ROM device, or had an IDE disk attached at IDE 0:0 and IDE 1:0. These configurations are now supported.

  • Hot Adding disks with invalid configurations produced residual nonfunctioning disks

    When Hot Add mode is enabled, VixDiskLib_Open started the process of Hot Adding the disks to the proxy virtual machine even when the disk's block size was not supported on the datastore of the proxy virtual machine. Such attempts resulted in the Hot Add failing to complete and leaving residual nonfunctioning disks. This issue has been resolved. Before Hot Adding a disk, checks are completed to ensure the process will produce a valid outcome.

  • Attempts to reconnect to vCenter Server failed

    If the connection to vCenter Server was lost while a backup was being completed, there were problems reconnecting. This problem occurred because the connection object from the lost connection persisted, but could no longer be used. If the connection is lost, the connection object is now managed so as to permit reconnection.

  • Some special characters were not properly handled

    Passwords that included < or & were not handled as expected. These characters can now be used as expected.

  • Mounting VMDK files using the VixDiskLib library created memory leaks

    When VixDiskLib was used to mount VMDK files, large shared objects were loaded and unloaded, resulting in memory leaks. VixDiskLib has been modified, eliminating the steps that resulted in the leaks.

  • Read/Write operations work with Hot Add transport in Windows Server 2008 Proxy

    Reading or writing to a volume after it was opened using VixDiskLib_Open() sometimes did not work as expected when running on a Windows Server 2008 proxy using Hot Add transport mode. Reading and writing to such volumes now performs as expected. This issue still exists for SAN transport mode. To resolve this issue in SAN transport mode, set the disks online and set the SAN transport mode policy to OnlineAll. To make disks writable, clear the readonly flag. This flag can be cleared in a variety of ways. In Windows Server 2008, you could use the diskpart utility to clear the flag.

  • Location of Windows system driver vstor2-mntapi10 has changed

    In VDDK 1.1.1 the virtual disk kernel mode driver vstor2-mntapi10.sys was installed in the VDDK \bin folder with various DLLs. In VDDK 1.2 the vstor2-mntapi10-shared.sys driver is installed in the Windows\system32\drivers folder.

  • With 4.0 change block tracking, UUID was not reinitialized after failure

    On ESX/ESXi 4.0, if a VM had change block tracking (CBT) enabled, and VM operations ceased or its snapshot was reverted, then the QueryChangedDiskAreas API call returned invalid extent error, and the disk UUID was not reinitialized. Several conditions can cause VM operations to cease: VM crash with unclean shutdown, and ESX/ESXi reboot or crash with the VM powered-on. The workaround on 4.0 is to disable and re-enable change tracking after a crash, because there may have been changes to the disk that are not reflected in the change tracking information. The VM unclean shutdown problem is fixed in ESX/ESXi 4.0 Update 1 and in ESX/ESXi 4.1. The snapshot problem is fixed in ESX/ESXi 4.1 only.

Known Issues and Workarounds

The following known issues were discovered through rigorous testing. This list of issues pertains to this VDDK release only.

  • 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 may manually clear the read-only attribute.

  • Advanced accelerated transport modes not available without XML

    Attempts to use advanced accelerated transport modes plugins might fail if the XML library libexpat version 1.95.7 is not installed with VDDK. To resolve this issue, install the library.

  • Advanced transport modes not available in ESX 3.5

    VDDK 1.2 does not support advanced transports with VirtualCenter 2.5 or ESX/ESXi 3.5.

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

  • Opening multiple connections in sequential threads with SAN transport fails

    If a connection to a SAN is establish and then ended, connection attempts by subsequent threads may fail. There is no workaround for this issue.

  • VixMntapi_MountVolume could fail with file-already-exists error

    If VixMntapi_MountVolume tries to simultaneously mount two disks with same disk signature, the mount might fail with error 12, VIX_E_FILE_ALREADY_EXISTS, “cannot create a file when that file already exists.” This can happen when mounting disks from two VMs if one was cloned from the other, or both were cloned from an original VM. Windows does not run VMs if disks have the same signature, so this problem occurs only with clones. Windows generates Event ID 58, and a message like this may appear: “The disk signature of disk 2 is equal to the disk signature of disk 1.” The workaround: serialize backup operations for these VMs so they are never backed up simultaneously, or change the disk signature of any cloned VMs to be unique. The following procedure was tested with a Windows Server 2003 VM:

    1. Back up the disk to be modified, because misuse of dd could cause data loss.
    2. Power on the cloned VM.
    3. Add a disk to the VM, initialize it, and format it. This disk has a new signature.
    4. Shutdown the guest and power off the VM.
    5. On the VM's host, as root or superuser, cd to the VM directory.
    6. Identify the flat files for new disk, and the disk to be fixed. Then run the following command, which copies disk data, thereby changing the old disk signature to the new disk signature.
      dd if=new-flat.vmdk of=old-flat.vmdk bs=4 count=1 skip=110 seek=110 conv=notrunc
    7. Use vCenter Server to remove the new disk, which now has a conflicting signature.

  • VixMntAPI_MountVolume does not always perform as expected

    Some drivers fail to load due to driver name changes not being reflected through the product. As a result of this error, VixMntAPT_MountVolume() fails. This has consequences for two use cases:

    • Mounting a local volume is successful, but attempts to create new files on the VMDK fail.
    • Mounting a remote volume fails with the error Disk in use. The disk is not in use, but the mount fails.

    These issues occur because the vixMntapi library fails to load when compiling code using vixMntapi. To resolve this issue, add the following path to your makefile:

    • For 64-bit environments: /usr/lib/vmware-vixdisklib/lib64
    • For 32-bit environments: /usr/lib/vmware-vixdisklib/lib32
  • Cleanup of Hot Added backup disks can affect change tracking files

    When a backup is conducted, disks may be Hot Added. After the backup completes, Hot Added disks are removed and a cleanup operation is conducted. This cleanup may remove the change tracking (ctk) file. This issue may resolve itself automatically, though if it does not, it can be resolved by powering the virtual machine off and then powering it back on again.

  • Mounting Hot Added disks may fail and not be cleaned up

    In some cases, an attempt to mount a Hot Added 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.

  • Cleanup of Hot Added virtual machine triggers ctk file removal

    Hot add cleanup sometimes causes the ctk files to be removed. Changed block tracking subsequently fails until the virtual machine is powered up again.

  • Some error messages are sent to stdout

    Error messages may be sent to the console and not to other output destinations such as logs. This might make it difficult to troubleshoot issues.

  • Hot Add advanced transport fails with some Linux distributions

    Attempts to use Hot Add advanced transport fail on Ubuntu 7.10 and SUSE 10. Hot Add advanced transport works as expected with RHEL.

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