Virtual Disk Development Kit Release Notes

Contents

• About the Virtual Disk Development Kit
• Changes and New Features
• Compatibility Notices
• Recently Resolved Issues
• Known Issues and Workarounds

About the Virtual Disk Development Kit

The Virtual Disk Development Kit (VDDK) 7.0.3.1 is an bug-fix update to support vSphere 7.0 U3 patch P04 and resolve some reported issues.

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 developer.vmware.com.

Changes and New Features

VDDK 7.0.3.1 offers the following:

• New: Two additional operating systems will be supported as backup proxy VMs for HotAdd and other transports: Red Hat Enterprise Linux (RHEL) 8.1 and 8.2.
• Bug fixes as below.

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

Compatibility Notices

New: Best practice for restore with pre-existing snapshot. When a backed-up VM had snapshots, disaster recovery software can restore a fresh VM with its pre-existing snapshots in place. However for partial file recovery, or to recover a VM back to a point in time, it is difficult to determine how to restore a VM that has an existing snapshot. Should parts of the snapshot be restored to a previous state (if applicable), or only the VM by ignoring the snapshot? Certain backup-restore applications do not handle this situation well; snapshot contention causes a GenericVmConfigFault. One good solution is for customers to delete any pre-existing snapshots before recovery, especially if not needed. This is mandatory for SAN transport recovery, anyway. Restore applications could refuse to recover a VM until any pre-existing snapshot is deleted. If not, a customer work-around is to recover the VM to a different location, avoiding the issue, then retain the recovered VM and delete the VM with pre-existing snapshot.

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. Since VDDK 6.7, SAN transport is explicitly rejected for vSAN and vVols.

Recently Resolved Issues

The VDDK 7.0.3 release resolves the following issues.

• Open SSL library and XML library upgraded.

  New: The Open SSL library openssl was upgraded to version 1.0.2za, and the XML streaming library libexpat to version 2.4.4.

• NBDSSL failed to open encrypted FCD with IPv6 enabled.

  New: In secure NBD (NBDSSL) transport mode, encrypted First Class Disk (FCD) could not be opened if IPv6 was enabled on the network. This regression discovered in VDDK 7.0.2 is fixed in this release.

Known Issues and Workarounds

These are unresolved issues known at this time.

• On VMC with NFS, Storage vMotion may conflict with backup.

  New: During backup a VM's disks are locked against removal. If Storage vMotion is requested against that VM, VM disks remain afterwards, and must be removed manually. The longer backup takes, the higher the likelihood of this occurring. Customers should avoid Storage vMotion during the backup window, but if not, they can find VMDKs not associated with VM or FCD, and remove them.

• Linked clone problems with HotAdd backup on vVol datastores.

  New: If backup software creates a linked clone target VM from a linked clone VM on a vVol datastore, then performs a backup using HotAdd transport, the proxy VM might become invalid when opening a disk on that target VM. This is a regression from VDDK 7.0.2 to 7.0.3. One alternative is to create the linked clone target VM from a full-clone source VM, rather than from a linked clone VM. Another alternative is to choose a transport mode other than HotAdd.

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