For managed disk, the first release of VDDK required network access ESX/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_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.
|
Replacing VixDiskLib_Init(),
VixDiskLib_InitEx() initializes new releases of the library, Parameters are similar, except you should specify an actual
libDir, and the new
configFile parameter. For multithreaded programming, you should write your own
logFunc, because the default logging function is not thread-safe. On Windows,
*libDir could be C
:\Program Files\VMware\VMware Virtual Disk Development Kit. On Linux,
*libDir is probably
/usr/lib/vmware-vix-disklib.
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.
|
■
|
vixDiskLib.transport.LogLevel – Overrides the default logging for vixDiskLib transport functions (not including NFC). The default value is 6. The range is 0 to 6, where 6 is most verbose and 0 is quiet.
|
The following NFC related options override the default numbers provided to the various NFC functions. Timeout values are stored in a 32-bit field, so the maximum timeout you may specify is 2G (2,147,483,648).
|
■
|
vixDiskLib.nfc.AcceptTimeoutMs – Overrides the default value (default is no timeout, or 0) for accept operations. This timeout is specifed in milliseconds. Applies to NBD/NBDSSL ibkt not SAN or HotAdd
|
|
■
|
vixDiskLib.nfc.RequestTimeoutMs – Overrides the default value (default is no timeout, or 0) for NFC request operations. This timeout is specifed in milliseconds.
|
|
■
|
vixDiskLib.nfc.ReadTimeoutMs – Overrides the default value (default is no timeout, or 0) for NFC read operations. This timeout is specifed in milliseconds.
|
|
■
|
vixDiskLib.nfc.WriteTimeoutMs – Overrides the default value (default is no timeout, or 0) for NFC write operations. This timeout is specifed in milliseconds.
|
|
■
|
vixDiskLib.nfcFssrvr.TimeoutMs – Overrides the default value (default is 0, indefinite waiting) for NFC file system operations. This timeout is specifed in milliseconds. 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 a rare case of 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 specifed 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 below. Each level includes all of the messages generated by (lower numbered) levels above. This is the final NFC setting.
|
LogLevel and the six NFC timeout settings affect only NBD/NBDSSL. They do not affect SAN and HotAdd transport. The NFC timeouts are applied to each disk handle.
|
■
|
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.
|
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.
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.
The default transport priority over the network is san:hotadd:nbdssl:nbd assuming all are available.
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:
VixDiskLib_ConnectEx() connects the library to managed disk on a remote ESX/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 with 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 ESX/ESXi host, provide the ESX/ESXi MoRef. When connecting through vCenter Server, pass the vSphere MoRef, which differs.
|
|
■
|
Preferred transport method, or NULL to accept defaults. If you specify SAN as the only transport, and SAN is not available, VixDiskLib_ConnectEx() does not fail, but the first VixDiskLib_Open() call will fail.
|
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 ESX/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 ESX/ESXi host than on the vCenter Server:
The port should be the one on which vCenter Server listens for API queries. Specifying a null port allows the library to select the default communications port. It is likely to be 443 (HTTPS) or maybe 902 (VIX automation). This is the port for data copying, not the port for SOAP requests.
The VixDiskLib_GetTransportMode() function returns the transport method selected for
diskHandle.
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.
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 tracking purposes, and 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 VirtualCenter, 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.
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.
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.