Virtual Disk Development Kit Release Notes

VDDK 7.0.2 | 9 March 2021 | ESXi build 17630552, VDDK build 17696664
For vSphere 7.0 Update 2 and VMC | Last document update 5 March 2021
Check frequently for additions and updates to these release notes.

Contents

About the Virtual Disk Development Kit

The Virtual Disk Development Kit (VDDK) 7.0.2 is an update to support vSphere 7.0 U2 and resolve some reported issues. VDDK 7.0.2 supports ESXi 7.0, vCenter Server 7.0, and VMware Cloud (VMC). Previous 7.0 releases were tested for backward compatibility against vSphere 6.5 and 6.7.

The VMware policy concerning backward and forward compatibility is for VDDK to support N-2 and N+1 releases. In other words, VDDK 7.0 and all its update releases will support vSphere 6.5, 6.7 (except for new features), and the next major 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 landing page on code.vmware.com.

Changes and New Features

VDDK 7.0.2 offers the following enhancements:

  • Phone home (CEIP) enhancements.
    Metrics now include backup data, disk performance data, VDDK API usage, and VDDK configuration with options. Customers can choose to avoid CEIP (customer experience improvement program) by disabling it in the vSphere Client.
  • HotAdd performance improvement.
    By setting a more realistic timeout when waiting for a file open/close lock, performance of highly concurrent HotAdd backup was improved.

For new features in the previous VDDK version, see the VDDK 7.0 Release Notes and VDDK 7.0 U1 Release Notes.

Compatibility Notices

Missing from documentation (until 7.0.1) was this caveat about multithreading: QueryAllocatedBlocks should be called in the same thread as open and close disk, not from read and write worker threads.

vVol and vSAN datastores do not support SAN mode transport. As of VDDK 6.7, SAN transport is explicitly rejected for vSAN and vVols.

As of 6.7.3 and in vSphere 7.0, the VDDK library marks parentHandle internally to prevent closure and ensure cleanup. In earlier releases it was an error to close parentHandle after VixDiskLib_Attach succeeds. See the VDDK 6.7.1 Release Notes for coding advice.

VDDK 7.0.2 supports the same operating systems for proxy backup as 7.0:

  • Windows Server 2019
  • Windows Server 2016, including versions 1709 and 1803
  • Windows Server 2012 and 2012 R2
  • Red Hat Enterprise Linux RHEL 7.7 and 8.0
  • CentOS 7.7
  • SUSE Linux Enterprise Server SLES 12 SP5 and 15 SP1
The following table shows recommended VDDK versions for various VMC milestones.

    VMC MilestoneCompatible VDDK Versions
    M86.5.2, 6.5.2 EP1, 6.5.3, 6.5.4, 6.7.x, 7.0.x
    M96.5.2, 6.5.2 EP1, 6.5.3, 6.5.4, 6.7.x, 7.0.x
    M106.7.x, 7.0.x
    M116.7.x, 7.0.x

Recently Resolved Issues

This VDDK release resolves the following issues.

  • Disk manager performance improvement.

    The vdiskmanager program on Linux required Open SSL libraries to be /usr/lib/vmware and nowhere else, otherwise performance slowed. Performance was improved by looking for them in DEFAULT_LIBDIRECTORY.

  • Slow initial sync in disaster recovery.

    The upgrade to SRM 8.3 and vSphere Replication caused initial sync of fail-over and fail-back to slow down considerably. This was caused by a change in the kernel module for CBT (changed block tracking). The fix has been applied in various ESXi patches and 7.0 U2.

  • Reading data from snapshot causes crash sporadically.

    When an NBD connection failure occurred (HTTP response code 503) VixDiskLib_Open crashed when trying to read a snapshot. To help avoid this issue, VDDK error handling has been made more robust.

  • Unable to repair VMDK using disk manager.

    When customers used vdiskmanager in VMware Fusion or Workstation to repair a VMDK, an error message appeared in the log file saying “Failed to initialize PhoneHome library.” This message did not cause failure to repair, but has been eliminated.

  • Invalid connect parameters when vmxSpec is null or empty.

    When the AllocateConnectParams function is called and vmxSpec is null or empty string, cleanup of tmpDir failed with the error “Invalid spec type.” This was fixed by checking elsewhere for null or empty vmxSpec.

  • Cleanup function crash if connection parameter not set.

    Before VDDK 6.7, passing Null vmxSpec was a way to clean up from multiple VM backups after a crash. In VDDK 6.7 and 7.0, the VixDiskLib_Cleanup function required its first parameter VixDiskLibConnectParams->vmxSpec to be set correctly. If vmxSpec was Null, applications crashed when calling the cleanup function. In this, libraries changed to permit the Null parameter.

  • Open SSL library upgraded.

    The Open SSL library openssl was upgraded in VDDK 7.0.2 to version 1.0.2x because of known security vulnerabilities.

Known Issues and Workarounds

These are unresolved issues known at this time.

  • Clean-up function not working with default tmpDirectory.

    With a default temporary directory, the folder name can change from backup to backup, if the backup job is a new OS process, so the VixDiskLib_Cleanup function might not clean up everything left behind. As a workaround, programs should set tmpDirectory in the configuration file.

  • VDDK 6.7 did not support Windows Server 2019 as a backup proxy.

    When using Windows Server 2019 as a HotAdd backup proxy with vSphere 6.x, every target VM gets flagged for reboot after backup. The user can ignore this message, as a reboot is not required. and subsequent HotAdd backups will continue to work. This issue was fixed in the VDDK 7.0 release by opening the disk itself instead of the disk adapter.

  • HotAdd transport mode limitations for vSAN datastores.

    If the target VM is on a vSAN datastore and the backup proxy on a non-vSAN datastore, HotAdd transport is not supported. VMware may add support in a future release. A workaround is to vMotion the backup proxy to a vSAN datastore.

  • Errata in VDDK documentation regarding CEIP phone home.

    In the VDDK 6.7 programming guide, section “Phone Home Support” on page 48 was inaccurate. In vSphere 7.0, CEIP is customer controlled. The EnablePhoneHome=1 setting in the VDDK configuration file has no effect. However, backup software should set vendor details as recommended below, otherwise vendor name and version will appear as “Unknown” in VMware analytics. Legal characters: 26 letters, digits, underscore (_), minus (-), period (.), and space. Double quotes are mandatory if setting strings contain spaces. DatabaseDir stores phone home data in a separate folder. 

    vixDiskLib.phoneHome.ProductName = "vendorName or ApplicationName"
vixDiskLib.phoneHome.ProductVersion = "versionNumber"
vixDiskLib.phoneHome.DatabaseDir = "folderName"

  • vSphere 6.7 HTTP File Service not backward compatible until 6.7 U2.

    This is related to “Disk open fails in HotAdd mode if name contains special characters” in 6.7.2. Backup partners with on-prem customers running VDDK 6.7.0 or VDDK 6.7.1 can recommend the NoNfcSession=0 setting to work around the problem, and urge an upgrade to VDDK 6.7.2 or 7.0 when feasible. Partners with cloud-based customers should make upgrade to post M5 and VDDK 7.0 mandatory, because NoNfcSession=1 must be set for security reasons. Partners using the Http_Access API in their own programs should code a fix to support multiple vCenter versions with adaptive single and double decoding. This issue will be permanent for partners supporting vSphere 6.7, 6.7 U1, and M5.

 

Copyright © 2021 VMware, Inc. All rights reserved.