VMware

Copyright © 2009 VMware, Inc. All rights reserved.

Virtual Disk Development Kit 1.1.1 Release Notes

Released 19 NOV 2009   |   Build 207031

Last document update 6 OCT 2010.


This document contains the following sections:

About the 1.1.1 Virtual Disk Development Kit

The Virtual Disk Development Kit (VDDK) 1.1.1 is an update to VDDK 1.1. These release notes provide information about issues that have been identified or resolved since VDDK 1.1. For information about issues that were identified or resolved in previous releases, see the VDDK 1.1 Release Notes.

VDDK 1.1.1 works with the following VMware platform products:

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

In September 2010, VDDK 1.1.1 was certified on vSphere 4.1. However ESX 4.1 hosts (with the latest VMware Tools installed) use application level quiescing for Windows Server 2008 virtual machines. VDDK 1.1.1 lacks support for application level quiescing, so it is unable to back up those virtual machines.

Installing the Virtual Disk Development Kit

To install the software, follow the same procedure as in the Virtual Disk API Programming Guide.

Installing on Windows

  1. Download the installer VMware-vix-disklib*.exe from the VMware Web site to your desktop.
  2. Double-click the new desktop icon.
  3. Click Next, read and accept the license terms, click Next twice, click Install, and Finish.

Installing on Linux

  1. Download the compressed archive VMware-vix-disklib.*.tar.gz from the VMware Web site. You have a choice of 32-bit or 64-bit support.
  2. Type this command to unpack the archive, creating a new directory:
    tar xvzf VMware-vix-disklib.*.tar.gz
  3. Change to that directory and run the installation script as root:
    cd vmware-vix-disklib-distrib
    sudo ./vmware-install.pl
  4. Read the license terms and type “yes” to accept them.
  5. Software components install in /usr unless you specify otherwise.

Redistributing the Software

Partners can obtain a license to redistribute VMware binaries for support of their VDDK applications. To enable VDDK-based binaries on Windows guest 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.
  3. Install your application, compiled in a manner similar to the vixDiskLibSample.exe program.

Resolved Issues

This release of the VDDK resolves following issues since the VDDK 1.1 release:

  • Backups and Restores Involving SAN Transport Mode Destinations Do Not Complete As Expected

    Under certain conditions, backup and restore operations using SAN transport mode storage encountered errors. These operations now complete properly.

  • Writing to Empty Thin Disks Fail Over SAN Transport Mode Fails

    Thin disks that have no content at all could not be written to over SAN transport mode. This condition has been addressed so writes to empty disks of SAN transport mode succeeds.

  • Backups Attempting to Use Unlicensed Hot Add Creates Errors

    ESX Servers backing up virtual machines using hot add must have a hotplug license. Backups using hot add were attempted, even if no license was available. These attempts produced errors. This behavior has been modified so if hot add is not licensed, no attempt is made to use the feature, other backup means are invoked, and no error occurs.

  • Cloned Disks Created For Hot Add Backups Not Handled As Expected

    During backup operations, hot add clones of disks may be created. At the end of the backup, the redo log should be consolidated with the base disk, but sometimes this did not happen. This issue has been addressed so hot added clones are now merged with the base disk after the backup completes.

  • Connections Using Alternate Ports Not Supported

    By default, connections to vCenter Server use port 443. If vCenter Server is configured to use an alternate port, VDDK continued to attempt to connect using the default port. This caused resulted in authentication failures. Alternate vCenter Server port configurations are now supported.

  • Windows 64-bit Drivers Not Signed

    The Windows 64-bit drivers were not signed, making it impossible to complete the Windows certification process for solutions created with the VDDK. The driver is now signed, eliminating this issue.

  • SAN Transport Mode Does Not Perform Optimally

    SAN transport mode did not perform at full potential speeds. SAN transport mode performance has been improved to expected levels.

  • Hot Add Advanced Transport Cannot Mount Large Files

    Attempts to use the hot add advanced transport mechanism to mount VMDK files that were 1 TB or larger failed. This issue has been resolved, so large files are now be mounted successfully.

Known Issues and Workarounds

  • VDDK and VADP do not support IP version 6

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

When run against vSphere 4.1, VDDK 1.1.1 has the following issues:

  • Windows Server 2008 backup fails due to application level quiescing

    Windows Server 2008 virtual machines with the latest VMware Tools installed use application level quiescing for backup on ESX 4.1 hosts, so VDDK 1.1.1 is unable to back them up. This issue has two workarounds. The first is to power off Windows Server 2008 using the vSphere Client, select Settings > Options > General > Configuration Parameters, set disk.EnableUUID to False, save settings, and power on the virtual machine. The second workaround is to create a file in the guest at C:\ProgramData\VMware\VMware Tools\tools.conf with the following contents:

    [vmbackup]
    vss.disableAppQuiescing = true
    	
  • Hot Add problem if proxy virtual machine hosted on ESX/ESXi 4.1

    When using hot add transport mode, VDDK 1.1.1 is unable to open disks of virtual machines when the proxy virtual machine resides on an ESX/ESXi 4.1 host. The workaround is to designate a proxy virtual machine hosted on ESX/ESXi 4.0 or earlier. This issue is fixed in VDDK 1.2.

This release of the VDDK has the following known issues:

  • Virtual Machines With Changed Block Tracking Enabled Cannot Be Restored Over SAN Transport Mode

    When changed block tracking (CBT) is enabled on a virtual disk, it is not possible to restore virtual machines using SAN transport mode. To avoid this issue, disable CBT for the duration of the restore.

  • Restores to Thin Provisioned Disks Using SAN Transport Mode May Fail

    By default, VMFS uses one MB blocks, but it is possible to create disks that include some fraction of a VMFS block. When using SAN transport mode to restore to a thin disk, you can only restore up to the portion of the disk that is a factor of 1 MB. For example, consider a scenario where the source disk or backup size is 512.5 MB. To restore, you can either:

    • Create a disk that is 513MB and restore the entire backup with SAN transport mode.
    • Restore 512MB of the disk with SAN transport mode, then restore the final 0.5 MB with NBD or NBDSSL transport mode.
  • Read/Write Operations May Fail From Windows Server 2008 Proxy When Using Hot Add or SAN Transport Mode

    Reading or writing to a volume after it is opened using VixDiskLib_Open() may not work as expected when running on a Windows Server 2008 proxy using hot add or SAN transport mode. To make disks accessible in such cases, set the disks online and set the SAN transport mode policy to OnlineAll. To make disks writeable, 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.

  • Backups and Restores Created Using Hot Add On a Windows Proxy May Contain Inconsistent Signatures

    When a backup of a disk is created on a Windows proxy using the hot add transport, the first sector of the backup may not match the original. To avoid this issue for backups:

    1. Read the first sector of the disk using NBD transport mode.
    2. Read the remaining disk using hot add mode.

    To avoid this issue for restores:

    1. Write the entire disk using hot add mode.
    2. Close the disk and the corresponding connection handle.
    3. Open a new connection handle.
    4. Open the disk using NBD transport mode to write the first sector.
  • Hot Add Not Supported For Proxy Virtual Machines With SAS Adapters

    Using a virtual machines with an SAS adapter as the proxy virtual machine is not a supported configuration.

  • Hot Add May Fail With Certain Proxy Virtual Machine Configurations

    Hot add may fail if the proxy virtual machine has one of the following configurations:

    • The proxy virtual machine does not have any IDE CD-ROM device.
    • The proxy virtual machine on ESX 4.0 has an IDE disk attached at IDE 0:0 and IDE 1:0.

    To avoid this issue, do not use these configurations.

  • Under Particular Conditions queryChangedDiskAreas and getChangeID fail

    The queryChangedDiskAreas and getChangeID methods rely on support from the vSphere platform to examine file data in a read-only mode. The underlying platform cannot gather the requested data if the following conditions are true:

    • The query is regarding a virtual machine that is powered off
    • Information about the versions of the virtual machine being compared are on different ESX hosts
    • Information about the snapshot being compared is accessed using SCSI hot add transport mode
  • VixMntapi_MountVolume could fail with file-already-exists error

    If VixMntapi_MountVolume tries to mount two disks with same disk signature at the same time, 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 different VMs if the VMs were cloned from one original VM. The workaround: serialize backup operations for these VMs to avoid simultaneous backup, or change the disk signature of any cloned VMs to be unique, as outlined in the VDDK 1.2 Release Notes.