VMware

Virtual Disk Development Kit 1.1 Release Notes

Released 21 May 2009   |   Build 163495

Last document update 12 August 2009.


Contents

About the 1.1 Virtual Disk Development Kit

The Virtual Disk Development Kit (VDDK) 1.1 includes the following new features:

  • Advanced transport for SAN and HotAdd.
    VixDiskLib can now copy sectors of virtual disk data directly through the SAN, or using SCSI HotAdd disk. For documentation, see Appendix A of the Virtual Disk API Programming Guide.
  • Vix Mount API for Windows and Linux.
    VixMntapi is a new set of library routines to mount virtual disks. On Linux, Vix Mount supports local and LAN transport modes only. On Windows, Vix Mount also supports SAN and HotAdd advanced transports. For documentation, see Appendix B of the Virtual Disk API Programming Guide.
  • Internationalization support.
    All library routines now support Unicode UTF-8 file paths and strings, although error messages are still in English only.
  • Windows 64-bit Libraries.
    The Windows installer has 64-bit libraries packaged in a ZIP file. See below for unpacking instructions.
  • SSPI support on Windows.
    Security Support Provider Interface (SSPI) improves security by enabling Windows applications using VixDiskLib, or the DiskMount utility, to authenticate users into VMware vCenter while eliminating the need to store passwords in the application.

VDDK and VADP do not support IP version 6.
The 1.1 release of VDDK has not been tested with VADP and the new IPv6 features of vSphere 4.

VDDK 1.1 is backward compatible with VDDK 1.0 and continues to support ESX 3.0.2, ESX/ESXi 3.5, and VirtualCenter 2.5. When those older platforms do not support new 1.1 features, library functions return an Unsupported or Not_Supported error code. In particular:

  • Some of the new Flexible Transport modes require ESX/ESXi 4.
  • Changed Block Tracking (with QueryChangedDiskAreas) requires VMware vSphere 4.
  • Snapshot and Changed Block Tracking should work with virtual compatibility RDMs. Physical compatibility (pass-through) RDMs are not supported however, because they completely bypass the ESX storage stack.
  • VDDK 1.1 supports SCSI HotAdd transport with VirtualCenter 2.5, using the same helper VM. The usual datastore and privilege requirements apply. However when connecting through vCenter Server 4, the helper VM is not needed, and clone privilege is not required. The host running the proxy VM requires access to the datastore of the backed-up VMs, but the hosts of the backed-up VMs do not need access to the proxy VM datastore.

Obtaining the Distribution

To obtain this VDDK 1.1 distribution, proceed to VMware product download area.

It is packaged as an EXE installable for Windows, or a tar.gz archive for Linux, and was tested on the following systems:

  • Windows, both 32-bit x86 and 64-bit x86-64
    • Windows XP SP2
    • Windows 2003 Server SP2
    • Windows Vista
    • Windows 2008 Server SP1
  • Linux, separate packages for 32-bit x86 and 64-bit x86-64
    • Red Hat Enterprise Linux (RHEL) 5
    • SUSE Enterprise Server 10 SP1
    • Ubuntu Desktop 7.10
    • Fedora Core 8

If you are a VMware TAP select or higher partner, you can request a license to redistribute the VDDK and bundle it with your application so that end-users do not have to install the VDDK separately.

  1. Contact your VMware TAP alliance manager to obtain and complete a redistribution agreement.
  2. This release is not prepackaged into merge modules, so you must decide which VDDK binaries you need and package them yourself.
  3. On Windows, the VSTOR2 kernel module is required for your applications to access mount functionality (VixMntapi). This is a software-only driver and is not complicated to install. Both 32-bit and 64-bit drivers are in the package.
  4. On Linux, the Fuse kernel module and shared object (libfuse.so) are prerequisites.
  5. The remaining binaries can simply be copied. They do not require Windows registry support.

Installing the Software

To install the software, follow the same procedure as in chapter 2 of the Virtual Disk API Programming Guide.

Installing on Windows

  1. Download the installer VMware-vix-disklib*.exe from the VMware FTP site to your desktop.
  2. Double-click the new desktop icon.
  3. Click Next, read and accept the license terms, click Next twice, click Install, and Finish.

Unpacking Windows 64-bit Libraries

  1. Install VDDK on Windows as above.
  2. Find vddk64.zip in the install directory, which is C:\Program Files\VMware\VMware Virtual Disk Development Kit\bin by default.
  3. Unzip this into a location of your choice, taking care not to overwrite any existing files. Do not select the above bin directory as the extraction target!
  4. You should see bin, lib and plugins directories. You can build your VixDiskLib and VixMntapi code against these. Be sure to add the bin directory to the Path when you run your binary. A 64-bit version of the vmware-mount utility is not provided.

Installing on Linux

  1. Download the compressed archive VMware-vix-disklib.*.tar.gz from the VMware FTP site to disk.
    You have a choice of 32-bit or 64-bit support.
  2. Type this command to unpack the archive, creating a new directory:
    tar xvzf VMware-vix-disklib.*.tar.gz
  3. Change to that directory and run the installation script as root:
    cd vmware-vix-disklib-distrib
    sudo ./vmware-install.pl
  4. Read the license terms and type yes to accept them.
  5. Software components install in /usr unless you specify otherwise.

Redistributing the Software

Partners can obtain a license to redistribute VMware binaries for support of their VDDK applications. To enable VDDK-based binaries on Windows guest virtual machines that do not have VDDK installed, take the following steps:

  1. Install the Microsoft Visual C++ (MSVC) redistributable, possibly as a merge module. The latest MSVC runtime works as side-by-side component, so manually copying it might not work on Vista. See the Microsoft Web site for x86 processors or x64 processors.
  2. Install VMware executables and DLLs from the \bin, \lib, and \plugins folders of the VDDK.
  3. Install your application, compiled in a manner similar to the vixDiskLibSample.exe program.

Resolved Issues

This release of the VDDK resolves the following issues since first partner release:

  • The VixMntapi library has been implemented on both Windows and partially on Linux.
  • Instead of using path to VMX or inventory path, programs should now open virtual disk using the MoRef of its virtual machine. For advanced transport, this is the best method.
  • In VDDK 1.1 Beta releases, VixDiskLib_Open() required the virtual disk to be associated with a virtual machine. VDDK 1.0 did not impose this restriction when connecting directly to an ESX host. Although the restriction has been lifted in 1.1 RC, VMware recommends against doing this. The virtual disk could be a parent, and writing to it would corrupt its children.
  • To mount registry hives, Windows needs write access to a volume, so VixMntapi read-only mode was enhanced to copy the registry to a temporary directory where it is writable.
  • When doing a remote clone with VixDiskLib_Clone() over network NBD transport, the specified creation parameters are no longer ignored.
  • (Before RC) Flexible transport is functional after VixDiskLib_ConnectEx().
  • QueryChangedDiskAreas() in the vSphere API now can ignore unallocated sectors.
  • VixDiskLib_Clone() now works when connecting to a remote ESX server.

VMware-Mount Utility

  • This utility can now mount virtual disks with non-ASCII characters in their path name.

Known Issues

This release of the VDDK has the following known issues:

Disk Mount Library

  • On Linux, use of VixMntapi disk mount with advanced transports (SAN, HotAdd) is not supported. A workaround, though not a good one, is to substitute NBDSSL or NBD transport.
  • The VixMntapi_GetOsInfo() function returns no information for Linux.
  • SSPI authentication is done when acquiring an open disk handle, before calling VixMntapi.
  • VDDK does not support connecting to vCenter Servers using ports other than 443.

Virtual Disk Library

  • The VixDiskLib_Open() and VixDiskLib_Close() functions are not multithread safe. Disk handles are not bound to a thread and could be used across threads. A symptom of this problem when using advanced transport is that an out-of-thread VixDiskLib_Open() falls back to NBD when you requested SAN transport. The best solution is to call VixDiskLib_Open() and VixDiskLib_Close() on one thread, and serialize all open calls. I/O can be concurrent if the disk handle is owned by one thread. Another solution is to use a mutex (mutual exclusion lock) across threads.
  • The default logging function is not multithread safe. To use VixDiskLib_InitEx() in a multithreading environment, you should specify a custom log function that is thread safe.
  • The vSphere SDK client loader employs an XML parser that loads Unicode libraries which cannot be unloaded and reloaded. To avoid reloading, you should call VixDiskLib_InitEx() only once at the beginning of your program, and VixDiskLib_Exit() once at the end of your program.
  • Writing to disk using NBDSSL transport mode is not supported. Restoring snapshots requires read/write mode, so NBDSSL cannot be used to restore snapshots. A workaround is to specify NBD mode instead.
  • HotAdd advanced transport cannot mount large (1 TB) VMDK files.
  • HotAdd and SAN transport fail, falling back to NBD transport, when a backed-up virtual machine has independent disks. An independent disk is one not affected by snapshots. For storage that you want to back up quickly, do not set independent mode.
  • With HotAdd transport, full backup of a virtual machine fails when multiple disks have the same name, as they could if on different datastores.
  • HotAdd advanced transport fails on Ubuntu 7.10 and SUSE 10, but works on RHEL.
  • SAN library routines include support for striped, mirrored, and spanned disks, but not RAID 5.

VMware-VdiskManager Utility

  • If you rename a VMDK file with the -n option, then try to rename it back again, you see the error message “Failed to analyze snapshot chain” and the second rename fails.
  • This utility does not accept comma as the decimal separator in European locales.

Notes on VMX Spec

The purpose of a vmxSpec is to identify a virtual machine. As of the VDDK 1.1 RC release, the preferred way to specify vmxSpec is as follows:

moref=<moid_of_VM>

This constitutes an API change, but was necessary for advanced transport functionality.


Copyright © 2009 VMware, Inc. All rights reserved.