Virtual Disk Development Kit Release Notes

Release Date: 20 AUG 2019 | ESXi build 14351029, VDDK build 14389676
For vSphere 6.7 Update 3 | Last document update 02 DEC 2019
Check for additions and updates to these release notes.

Contents

About the Virtual Disk Development Kit

The Virtual Disk Development Kit (VDDK) 6.7.3 is an update to support vSphere 6.7 Update 3 and to resolve issues discovered in previous releases. VDDK 6.7 added support for ESXi 6.7 and vCenter Server 6.7, and was tested for backward compatibility against vSphere 6.0 and 6.5.

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 VMware {Code}.

The VMware policy concerning backward and forward compatibility is for VDDK to support N-2 and N+1 releases. In other words, VDDK 6.7 and all its update releases support vSphere 6.0, 6.5 (except for new features), and the next major release.

Changes and New Features

In addition to operating systems previously tested and supported for proxy backup, listed below, RHEL 7.6 was added for this release.

  • Windows Server 2016, including versions 1709 and 1803
  • Windows Server 2012 and 2012 R2
  • Windows Server 2008 R2
  • Red Hat Enterprise Linux RHEL 6.7, 6.8, 6.9, 7.2, 7.3, and 7.6
  • CentOS 7.4
  • SUSE Linux Enterprise Server SLES 11 SP4, 12 SP1, 12 SP4, and 15

For new features in VDDK 6.7, see the Virtual Disk Development Kit 6.7 Release Notes. For VixMntapi enhancements, see the Virtual Disk Development Kit 6.7.1 Release Notes.

Compatibility Notices

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

Recently Resolved Issues

The VDDK 6.7.3 release resolves the following issues.

  • Program failure after asynchronous NBD errors.

    In VDDK 6.7 and its first two update releases, VDDK may crash due to I/O retry after an NBD asynchronous I/O (AIO) error occurs. If a backup application ignores errors and continues reading or writing, it will result in an NBD network-connect error and subsequent program crash. This issue has been fixed in VDDK 6.7.3.

  • Curl program upgraded.

    The Curl program was upgraded from an older version to version 7.64.1 because of a known security vulnerability.

  • Open SSL library upgraded.

    The Open SSL library openssl was upgraded from version 1.0.2r to version 1.0.2s because of a known security vulnerability.

  • Large files took a long time to open with SAN mode backup.

    Backup customers complained that very large files took longer to open in SAN mode than in other backup modes. A patch was implemented to fetch block mapping information at start of file, then proceed to fetch more information as I/O proceeds. That patch is included in this release.

  • Failure to HotAdd disks with multiple PVSCSI controllers.

    When there were two paravirtual SCSI controllers on a Linux backup proxy, virtual disks could not be HotAdded due to device conflicts. This has been fixed in this release.

  • Backup snapshots fail after CBT runs out of memory.

    In saturated conditions with Windows backup, change block tracking (CBT) could run out of memory, causing snapshots taken before backup to fail. Various patches were made to fix CBT and are included in this release.

  • SAN mode backups fail with data not 4K aligned.

    VixDisklib threads could time out or crash during SAN backup when opening disks. This happens when disk size is not a 4K multiple. In this release, a counter has been added to stop fetching the block map when total bytes do not increase after five retries. This prevents crashing, but disks should be block aligned for successful backup.

Known Issues and Workarounds

These are unresolved issues known at this time.

  • Errata in VDDK documentation regarding CEIP phone home.

    In the VDDK 6.7 programming guide, section “Phone Home Support” on page 48 is inaccurate. This should be the replacement text:
    The Customer Experience Improvement Program (CEIP) helps VMware understand what products and versions have been installed on a system. This information is collected to assist and streamline problem determination and resolution. Whether this information gets sent to VMware is a customer choice (on-premise) with CEIP opt-in and opt-out, or as part of their Terms of Service. VMware will collect only the product name and version information for improved problem resolution. No other partner-specific information will be collected. VMware asks that vendors add these lines to the VDDK configuration file for identification. Double quotes are mandatory if ProductName or ProductVersion have spaces. 

    vixDiskLib.phoneHome.EnablePhoneHome = 1
vixDiskLib.phoneHome.ProductName = "vendorName or ApplicationName"
vixDiskLib.phoneHome.ProductVersion = "versionNumber"

  • 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 when feasible. Partners with cloud-based customers should make upgrade to post M5 and VDDK 6.7.2 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.

  • Forward compatiblity issue with hardware version 17 on vSphere.Next.

    When using HotAdd transport to save a VM of virtual hardware version (VHV) 17 with Changed Block Tracking (CBT) enabled, backup will fail if virtual disk size is > 256GB, because large disks in vSphere.Next require change tracking (CTK) version 2.0, not supported by vSphere 6.7. The VM's log file indicates that ReconfigureVM failed, and the UI shows “Unknown change tracking version” status. To summarize, this happens under these conditions: (1) the backed up VM is VHV 17 or higher, (2) saved disk dize is > 256GB, and (3) its CBT was (re)initialized on a post-6.7.x ESXi host. A workaround is for users to disable CBT for the target VM to avoid CTK, but this is not recommended because then full backups will ensue. The solution is to vMotion the proxy VM to ESXi.Next or greater, which supports CTK version 2.0.

  • Multiple SCSI controllers on a Linux backup proxy.

    When a Linux backup proxy VM contains multiple SCSI controllers, HotAdd transport might not able to recognize all disks correctly. See KB 67757 Best practice for Linux proxy VM configuration in HotAdd transport for discussion and workarounds.