Virtual Disk Development Kit Release Notes

Release date: 10 AUG 2017 | Build number: VDDK 6195444
VDDK 6.5.2 for VMware Cloud GA | Last document update: 22 MAR 2018
Check frequently for additions and updates to these release notes.

Contents

About the Virtual Disk Development Kit

The Virtual Disk Development Kit (VDDK) 6.5.2 is an update to resolve issues related to deployment of VMware Cloud. VDDK 6.5.2 is forward compatible with the next vSphere release.

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 the software, programming details, and redistribution, see the VDDK page on the VMware {code} website.

VDDK 6.5.2 supports the same set of operating systems to perform proxy backup as VDDK 6.5.1.

Changes and New Features

This release contains bug fixes but no new features.

  • Fixes for HotAdd transport
  • Windows Disk Signature Collision Problem.
  • Disk Online Problem
  • Hotadd restore

Compatibility Notices

This VDDK release is forward compatible with vSAN 6.6 and vSAN 6.6.1.

ESXi hosts and especially vCenter Server should be upgraded in conjunction with VDDK libraries.

Windows Disk Signature Collision Problem. If the backup proxy has an online disk with the same signature as a target VM disk (the virtual disk being backed up or restored), there will be a disk signature collision when the target VM's disk is HotAdded on the proxy. The target VMs disk will show status “Offline (the disk is offline because it has signature collision with another disk that is online)” in Disk Manager. The disk signature collision causes two data bytes (index 0x1bc and 0x1bd) in the first sector data of the target VMs disk to be silently changed, leading to inconsistencies during backup or restore.
To avoid this problem, VMware strongly recommends that backup software not use the same disk for proxy VM and target VM, especially not from the same VM template. If this is unavoidable, software can use NBD(SSL) transport to backup or restore the first sector.

Disk Online Problem. The Virtual Disk Programming Guide used to recommend SAN policy OnlineAll for Windows 2008 and later (this recommendation was removed for the VDDK 6.5.1 release). Disk online may cause signature collision problems and restore problems. So with HotAdd transport, VMware suggests customers set SAN policy to OfflineShared or OfflineAll in Windows 2008 R2 and later. This places the disk offline to prevent signature collision and restore problems. As of VDDK 6.5.2 and vSphere 2017 releases, disk is forcibly set to offline, and if this setting cannot be made, the HotAdd transport may fail.

Unbuffered HotAdd Restore. VMware recommends that programmers set the VDDK flag VIXDISKLIB_FLAG_OPEN_UNBUFFERED when opening virtual disks before performing a restore with HotAdd transport. In vSphere 2017 releases and later, programmers must allocate a data buffer that is sector size aligned when setting this flag. Sector size may be 512 bytes or a larger multiple. Sector size alignment is recommended for older VDDK releases as well.

Recently Resolved Issues

The VDDK 6.5.2 release resolves the following issues:

  • VDDK may crash during PrepareForAccess.

    VDDK could crash when calling VixDiskLib_PrepareForAccess with the “vmodl_vim_fault_method_already_disabled” error. This was a regression because the NULL fault was not considered. A fix has been found and appears in VDDK 6.5.2 and later.

  • Log file entries related to blacklist were missing in VDDK 6.5.

    Log file entries (at the verbose and trivial levels) related to device blacklisting were missing in VDDK 6.5 as compared to VDDK 6.0. These log entries have been restored in this release.

  • Write failure when restoring virtual disk with HotAdd transport.

    Unbuffered support was removed from asynchronous I/O (AIO) manager after vSphere 6.5. This removal results in a data write failure if the virtual disk was opened with flag VIXDISKLIB_FLAG_OPEN_UNBUFFERED when memory buffer boundaries are not sector size aligned (512-byte and multiples thereof). See the compatibility notice saying sector alignment is mandatory as of 2017.

  • Virtual disks must be offline for HotAdd restore.

    Starting with vSphere 2017 releases, virtual disk is forcibly set offline for restore. So HotAdd restores fail if disk is online after HotAdding, even if Automount is disabled. Documentation previously recommended setting SAN policy to OnlineAll, but this recommendation has been reversed.

  • Disk signature collision should be avoided for HotAdd backup and restore.

    If the same virtual disk is mounted by the proxy VM and target VM, a disk signature collision causes Windows to rewrite two bytes in the first block of the target VM's virtual disk. See above for recommendations to avoid this issue, and the NBD(SSL) workaround.

  • NFC connection can be skipped for HotAdd backups now.

    In VMware Cloud environments (SDDC as a Service), only HotAdd transport mode is allowed. This avoids the need for a direct connection between the backup proxy and ESXi hosts, which is seldom permitted by the security topology of VMware Cloud. In previous VDDK releases, an NFC connection was always made during HotAdd transport. To support backups with VMware Cloud, this NFC connection is optional in this release. When a backup proxy in VMware Cloud lacks direct access to ESXi hosts, set vixDiskLib.transport.hotadd.NoNfcSession=1 in the proxy's VDDK configuration file. Backup partners should also check the return code of VixDiskLib_PrepareForAccess, and if it is VIX_E_HOST_USER_PERMISSIONS (3014), ignore the error and continue. With VMware Cloud, VDDK does not yet support backup and restore of First Class Disk.

Known Issues and Workarounds

This issue was reported against VDDK 6.5.2 and 6.5.2 EP1.

  • HotAdd fails with encrypted proxy and encrypted virtual disk.

    When backing up an encrypted VM in HotAdd mode, if the proxy is also encrypted, adding encrypted virtual disk to the proxy succeeds, however opening encrypted disk fails. This issue occurs only if vixDiskLib.transport.hotadd.NoNFCSession=1 is set in the proxy's VDDK configuration file, It is a regression from previous VDDK 6.5.x releases, and will be fixed in VDDK 6.5.3.

For issues in the VDDK 6.5 and 6.5.1 releases, see the VDDK 6.5 Release Notes and the VDDK 6.5.1 Release Notes.