Virtual Disk Development Kit Release Notes

Release Date: 16 OCT 2018 | ESXi GA build, VDDK 6.7.1 Build 10362358
For vSphere 6.7 Update 1. Last document update 31 OCT 2018
Check for additions and updates to these release notes.

Contents

About the Virtual Disk Development Kit

The Virtual Disk Development Kit (VDDK) 6.7.1 is an update to support vSphere 6.7 Update 1 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

The VixMntapi library on Linux systems now supports:

  • Advanced transports modes: HotAdd, SAN, and NBD/NBDSSL.
  • Read-only mounting of VMDK files.
  • Diagnostic logging as set by vixMntapi.cfg.LogLevel in the VDDK configuration file. Levels are the same as for vixDiskLib.transport – Panic, Error, Warning, Audit, Info, Verbose, Trivia. The output file named vixMntapi.log appears in the same directory as other log files. Not available for Windows.

In addition to those previously qualified for use as a backup proxy, the following operating systems were tested with VDDK 6.7.1:

  • Red Hat Enterprise Linux RHEL 6.9
  • CentOS 7.4
  • SUSE Linux Enterprise Server SLES 15
  • Windows Server 2016 version 1803

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

Compatibility Notices

In earlier releases it was an error to close parentHandle after VixDiskLib_Attach succeeds. The VDDK library now marks parentHandle internally to prevent closure and ensure cleanup. Proper calling sequences are as follows:

  1. First open a disk for attach with this call:
    VixDiskLib_Open(remoteConnection, virtualDiskPath, flags, &parentHandle);
  2. Create a local connection using: VixDiskLib_Connect(NULL, &localConnection);
  3. With the backed-up disk (referred to as parent disk) still open, make this call, creating the child disk with a unique name: VixDiskLib_CreateChild(parentHandle, "C:\tmp.vmdk", VIXDISKLIB_DISK_MONOLITHIC_SPARSE, NULL, NULL);
  4. Open tmp.vmdk (referred to as the redo log): VixDiskLib_Open(localConnection, "C:\tmp.vmdk", VIXDISKLIB_FLAG_OPEN_SINGLE_LINK, &redoHandle);
  5. Attach the redo log to its parent disk with: VixDiskLib_Attach(parentHandle, redoHandle);

If VixDiskLib_Attach fails, now the system automatically cleans up the local file handle.

  1. To end, close the redo log. Whether to close the parent disk handle is release dependent:
    VixDiskLib_Close(redoHandle);
    if (VIXDISKLIB_VERSION_MAJOR > 7) {
       VixDiskLib_Close(parentHandle); // to avoid memory leaks
    }
  2. Unlink the redo log from the parent disk.

Recently Resolved Issues

The VDDK 6.7.1 release resolves the following issues.

  • XML library upgraded.

    We XML library libxml2 was upgraded from version 2.9.6 to version 2.9.8 because of a known security vulnerability.

  • Open SSL library upgraded.

    The Open SSL library openssl was upgraded from an earlier version to version 1.0.2p because of a known security vulnerability.

  • NBD transport in VDDK 6.7 is slow when running against vSphere 6.5.

    When data protection software is compiled with VDDK 6.7 libraries, NBD/NBDSSL mode backup and restore is significantly slower than before on vSphere 6.5 or 6.0. This was caused by dropping the OPEN_BUFFERED flag when it became the default in VDDK 6.7. This backward compatibility issue is fixed in the VDDK 6.7.1 release. When performance is important, VMware recommends use of NBD Asynchronous I/O, calling VixDiskLib_WriteAsync and VixDiskLib_Wait.

  • With HotAdd transport VDDK could hang after many NFC connections.

    For programs compiled with VDDK 6.7 or 6.7 EP1 libraries, VDDK may eventually hang in VixDiskLib_Open when building server connections to ESXi. After the log entry “NBD_ClientOpen: attempting to create connection” VDDK hangs. The cause is that after HotAdd mode retrieves the disk signature, it fails to close the NFC connection, so many NFC server threads continue running and prevent new NFC connections. This regression is fixed in the VDDK 6.7.1 release.

  • HotAdd backup of VM template crashed if NoNfcSession was enabled.

    In VDDK 6.5.1 and later when it became available to avoid creating an NFC session for backup in cloud environments where local connections are disallowed, if vixDiskLib.transport.hotadd.NoNfcSession=1 was set in the proxy's VDDK configuration file, HotAdd mode crashed due to null pointer access of an attribute in the VM template object.

  • VixMntapi on Linux did not work with advanced transport mode.

    VDDK partners use VixDiskLib for block-oriented image backup and restore, while they use VixMntapi for file-oriented backup and restore. The Windows implementation of VixMntapi has supported advanced transports for many releases, but the Linux implementation of VixMntapi did not – it supported only NBD mode. In the VDDK 6.7.1 release, VixMntapi supports HotAdd or SAN transport and NBD/NBDSSL on Linux, so it can be used in VMC environments for file-oriented backup and restore of Linux VMs.

  • VDDK hangs during restore when directly connecting to ESXi hosts.

    When doing restore with direct ESXi connections, VDDK may hang intermittently. The cause is that NfcServer on ESXi enters the wrong state, waiting for new messages that never arrive. The fix for NfcServer was to avoid waiting when no data remains. To resolve this issue, customers must upgrade ESXi hosts to 6.7 U1 or later.

  • VixMntapi on Linux could not open files as read-only.

    In previous releases, opening files read-only was not supported by VixMntapi. When read-only mode is requested at open time, the file is opened read/write. In this release, VixMntapi actually opens files as read-only on Linux VMs.

  • HotAdd proxy failed with Windows Server backups.

    If there was SATA controller in the Windows backup proxy, HotAdd mode did not work. The cause was that VDDK did not rescan SATA controllers after HotAdding, so if there existed multiple SATA controllers or ACHI controllers, VDDK sometimes used the wrong controller ID and could not find the HotAdded disk. Disk open failed, resulting in “HotAdd ManagerLoop caught an exception” and “Error 13 (You do not have access rights to this file)” messages. The workaround was to remove the SATA controller from the Windows backup proxy. The issue is fixed in this release so the workaround is no longer needed. See KB 2151091.

Known Issues and Workarounds

There are no known unresolved issues at this time.