Advanced Transport APIs

For managed disk, the first release of VDDK required network access ESXi host (LAN or NBD transport). With VDDK 1.1 programs can access virtual disks directly on a storage device, LAN-free. Direct SAN access increases I/O performance. To select the most efficient transport method, a set of APIs is available, including:

■	VixDiskLib_InitEx() – Initializes the advanced transport library. You must specify the library location. Replaces VixDiskLib_Init() in your application.

■	VixDiskLib_ListTransportModes() – Lists transport modes that the virtual disk library supports.

■	VixDiskLib_ConnectEx() – Establishes a connection using the best transport mode available, or one you select, to access a given machine’s virtual disk. Currently it does not check validity of transport type. Replaces VixDiskLib_Connect() in your application.

Initialize Virtual Disk API

VixDiskLib_InitEx() replaces VixDiskLib_Init() to initialize new releases of the library. Parameters are similar, except you should specify an actual libDir, and the configFile parameter is new. For multithreaded programming, you should write your own logFunc, because the default logging function is not thread-safe. VixDiskLib loads many libraries (DLLs or shared objects) at start time using the Path or LD_LIBRARY_PATH environment. At run time, libDir specifies were to load advanced transport modes, whitelist, and blacklist. On Windows, *libDir could be C:\Program Files\VMware\VMware Virtual Disk Development Kit. On Linux, *libDir could be /usr/lib/vmware-vix-disklib.

VixError vixErr = VixDiskLib_InitEx(majorVersion, minorVersion, &logFunc, &warnFunc, &panicFunc, *libDir, *configFile);

Logged messages appear by default in a temporary folder or log directory, for VDDK and for many other VMware products. See Location of Log Files.

The currently supported entries in the configFile are listed below. The correct way to specify a configuration is name=value. See Example: Sample InitEx configuration file for a sample configuration file.

■	tmpDirectory = "<TempDirectoryForLogging>"

■	vixDiskLib.transport.LogLevel – Overrides default logging for vixDiskLib advanced transport functions, not including NFC (see nfc.LogLevel below). The default value is 3, indicating audit. Each level includes all of the messages generated by lower numbered levels. Here are the levels:

■	0 = Panic (failure only)

■

1 = Error

■	2 = Warning

■

3 = Audit

■

4 = Info

■	5 = Verbose

■	6 = Trivia

■

vixDiskLib.transport.san.blacklist – Specifies a device node path, or a comma separated list of device node paths, that VDDK uses as a list of LUNs on which not to attempt VMFS file system discovery. This has the effect of making fewer device nodes available to SAN transport, and avoids I/O on specific device node paths. The special string all indicates that VDDK should use only the device node paths specified by vixDiskLib.transport.san.whitelist.

■

vixDiskLib.transport.san.whitelist – Specifies a device node path, or a comma separated list of device node paths, that VDDK uses as a list of LUNs on which to attempt VMFS file system discovery. This has the effect of making more device nodes available to SAN transport, encouraging I/O on specific device node paths. Backup applications may create a special device node and whitelist this device node for use in addition to those found by VDDK’s device node scanner. Backup applications can also blacklist specific devices found by VDDK’s device node scanner to prevent use by SAN transport. Combining whitelist and blacklist, applications can establish a preferred device policy for backup I/O.

■

vixDiskLib.disklib.EnableCache – Caching by vixDiskLib is off (0) by default. Setting 1 turns it on. Caching increases performance when information is read repeatedly, or accessed randomly. In backup applications, information is usually accessed sequentially, and caching can actually reduce performance. Moreover with caching, backup applications risk getting stale information if a disk sector is rewritten (by another application) before the cache is refreshed.

■	vixDiskLib.linuxSSL.verifyCertificates – Whether to check SSL certificates and thumbprints when connecting to a virtual machine. The only possible value is 1 for On, which is the default.

The following NFC related options override the default numbers provided to the various NFC functions. The NFC timeouts shown in Example: Sample InitEx configuration file correspond to default values on ESXi 5.x hosts.

■	vixDiskLib.nfc.AcceptTimeoutMs – Overrides default value (3 minutes) for NFC accept operations.

■	vixDiskLib.nfc.RequestTimeoutMs – Overrides default value (3 minutes) for NFC request operations.

■	vixDiskLib.nfc.ReadTimeoutMs – Overrides default value (one minute) for NFC read operations.

■	vixDiskLib.nfc.WriteTimeoutMs – Overrides default value (ten minutes) for NFC write operations.

■

vixDiskLib.nfcFssrvr.TimeoutMs – Overrides the default value (default is 0, indefinite waiting) for NFC file system operations. If you specify a value, then a timeout occurs if the file system is idle for the indicated period of time. The hazard of using the default value is that in the rare case of a catastrophic communications failure, the file system will remain locked.

■	vixDiskLib.nfcFssrvrWrite.TimeoutMs – Overrides the default value (default is no timeout) for NFC file system write operations. The timeout is specified in milliseconds. If you specify a value, it will time out when a write operation fails to complete in the specified time interval.

■	vixDiskLib.nfc.LogLevel – Overrides the default logging level for NFC operations. The default value is 1, indicating error messages only. The meaning of values is listed here. Each level includes all of the messages generated by lower numbered levels. This is the final NFC setting.

■	0 = Quiet (minimal logging)

■

1 = Error

■	2 = Warning

■

3 = Info

■

4 = Debug

Example: Sample InitEx configuration file

# temporary directory for logs etc.

tmpDirectory="/usr/local/vendorapp/var/vmware/temp"

# log level 0 to 6 for quiet ranging to verbose

vixDiskLib.transport.LogLevel=2

# disable caching to disk

vixDiskLib.disklib.EnableCache=0

# whether to check SSL thumbprint on Linux - has no effect

vixDiskLib.linuxSSL.verifyCertificates=1

# network file copy options

vixDiskLib.nfc.AcceptTimeoutMs=180000

vixDiskLib.nfc.RequestTimeoutMs=180000

vixDiskLib.nfc.ReadTimeoutsMs=60000

vixDiskLib.nfc.WriteTimeoutsMs=600000

vixDiskLib.nfcFssrvr.TimeoutMs=0

vixDiskLib.nfcFssrvrWrite.TimeoutMs=0

# nfc.LogLevel (0 = Quiet, 1 = Error, 2 = Warning, 3 = Info, 4 = Debug)

vixDiskLib.nfc.LogLevel=2

 

Timeout values are stored in a 32-bit field, so the maximum timeout you may specify is 2G (2,147,483,648). Timeouts are specified in milliseconds and apply to each disk handle. NFC settings apply to NBD/NBDSSL but not to SAN or HotAdd.

Location of Log Files

On Linux, log messages appear under /var/log by default. On Windows, they appear in a temporary folder, whose location can change from time to time. Early Windows systems used C:\Windows\Temp. Windows XP and Server 2003 use C:\Documents and Settings\<user>\Local Settings\Temp\vmware-<user>. Vista, Windows 7, and Server 2008 use C:\Users\<user>AppData\Local\Temp\vmware-<user>.

On all versions of Windows the user’s TEMP environment setting overrides the default Temp folder location. Temporary is something of a misnomer because files are never deleted from the Temp folder, unless the user or an application deletes them. If the TEMP or Windows default Temp folder is not found, VDDK (and other VMware software) have a fallback to <localAppDir>\Temp.

Alternatively, your software can set a custom temporary directory, as shown in Example: Sample InitEx configuration file.

List Available Transport Methods

The VixDiskLib_ListTransportModes() function returns the currently supported transport methods as a colon-separated string value, currently “file:san:hotadd:nbd” where nbd indicates LAN transport. When available, SSL encrypted NBD transport is shown as nbdssl.

printf("Transport methods: %s\n", VixDiskLib_ListTransportModes());

The default transport priority over the network is san:hotadd:nbdssl:nbd assuming all are available.

The advanced transport license for VDDK includes all transport types.

Connect to VMware vSphere

VixDiskLib_ConnectEx() connects the library to managed disk on a remote ESXi host or through VMware vCenter Server. For hosted disk on the local system, it works the same as VixDiskLib_Connect(). VixDiskLib_ConnectEx() takes three additional parameters:

■	Boolean indicating TRUE for read-only access, often faster, or FALSE for read/write access. If connecting read-only, later calls to VixDiskLib_Open() are always read-only regardless of the openFlags setting.

■

Managed object reference (MoRef) of the snapshot to access using this connection. This is required for most transport methods (SAN, HotAdd, NBDSSL) and to access a powered-on virtual machine. You must also specify the associated vmxSpec property in connectParams. When connecting directly to an ESXi host, provide the ESXi MoRef. When connecting through vCenter Server, pass the vSphere MoRef, which differs from the ESXi one.

■	Preferred transport method, or NULL to accept the defaults. If you specify any advanced transport mode as the only method, and that method is not available, the VixDiskLib_ConnectEx() call does not fail, but the subsequent VixDiskLib_Open() call will fall back to NBD mode.

VixDiskLibConnectParams cnxParams = {0};

if (appGlobals.isRemote) {

cnxParams.vmName = vmxSpec;

cnxParams.serverName = hostName;

cnxParams.credType = VIXDISKLIB_CRED_UID;

cnxParams.creds.uid.userName = userName;

cnxParams.creds.uid.password = password;

cnxParams.port = port;

}

VixError vixError = VixDiskLib_ConnectEx(&cnxParams, TRUE, "snapshot-47", NULL, &connection);

Even when a program calls VixDiskLib_ConnectEx() with NULL parameter to accept the default transport mode, SAN is selected as the preferred mode, if SAN storage is available from the ESXi host. Then if the program opens a virtual disk on local storage, subsequent writes will fail. In this case, the program should explicitly pass nbd or nbdssl as the preferred transport mode.

In the connection parameters cnxParams, the vmxSpec managed object reference would be different on an ESXi host than on the vCenter Server:

vmxSpec = "moid=23498";

vmxSpec = "moid=898273";

The port is where vCenter Server listens for API queries. Specifying null allows the library to select the port, usually 443 (HTTPS). By default VADP uses the same port for virtual machine operations as other SOAP-based Web Services. By default VDDK uses port 902 (VIX automation) for NBD and NBDSSL data transport.

Get Selected Transport Method

The VixDiskLib_GetTransportMode() function returns the transport method selected for diskHandle.

printf("Selected transport method: %s\n", VixDiskLib_GetTransportMode(diskHandle));

Prepare For Access and End Access

The VixDiskLib_PrepareForAccess() function notifies a vCenter-managed host that a virtual machine’s disks are being opened, probably for backup, so the host should postpone virtual machine operations that might interfere with virtual disk access. Call this function before creating a snapshot on a virtual machine. Internally, this function disables the vSphere API method RelocateVM_Task.

vixError = VixDiskLib_PrepareForAccess(&cnxParams, "vmName");

The connection parameters must indicate one virtual machine only. When opening a managed disk, provide valid credentials for the vCenter Server that manages the ESXi host with the disk. The second parameter is currently just for identity tracking purposes, and is limited to 50 characters. It could be the virtual machine name or the name of your application.

If you run VixDiskLib_PrepareForAccess() directly on an ESXi host, the system throws an error saying “VDDK: HostAgent is not a vCenter, cannot disable svmotion.”

Every VixDiskLib_PrepareForAccess() call should have a matching VixDiskLib_EndAccess() call.

The VixDiskLib_EndAccess() function notifies the host that a virtual machine’s disks have been closed, so operations that rely on the virtual disks to be closed, such as vMotion, can now be allowed. Call this function after closing all the virtual disks, and after deleting the virtual machine snapshot. Normally this function is called after previously calling VixDiskLib_PrepareForAccess, but you can call it to clean up after a crash. Internally, this function re-enables the vSphere API method RelocateVM_Task.

vixError = VixDiskLib_EndAccess(&cnxParams, "vmName");

Here is a code snippet showing use of PrepareForAccess in a backup program that waits up to 10 minutes for Storage vMotion to finish. Regular vMotion would finish much faster than that.

/* New sample code accounts for VMODL_TYPE_VIM_FAULT_METHOD_ALREADY_DISABLED_FAULT */

if (appGlobals.vmxSpec != NULL) {

for (int i = 0; i < 10; i++) {

vixError = VixDiskLib_PrepareForAccess(&cnxParams, "Sample");

if (vixError == VIX_OK) {

break;

}

else {

Sleep(60000);

}

}

}

SAN Mode on Linux Uses Direct Mode

With SAN transport on Linux, read and write operations are performed in “direct” mode (O_DIRECT), meaning that no read or write buffering is done. Direct mode prevents other processes from accessing the latest data, and avoids loss of information if the process dies before committing its write buffers. In direct mode, the most time efficient performance can be achieved if applications follow these guidelines when performing reads and writes:

■	The offset into the SAN where the operation is performed should be an even multiple of page size, 4096.

■	The buffer used for data transfer should be aligned on a page boundary.

■	The transfer length should be an even multiple of the page size.

Clean Up After Disconnect

If virtual machine state was not cleaned up correctly after connection shut down, VixDiskLib_Cleanup() removes extra state for each virtual machine. Its three parameters specify connection, and pass back the number of virtual machines cleaned up, and the number remaining to be cleaned up.

int numCleanedUp, numRemaining;

VixError vixError = VixDiskLib_Cleanup(&cnxParams, &numCleanedUp, &numRemaining);