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

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 below for a sample configuration file.

tmpDirectory =

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

– 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 the example (below

LogLevel

) 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. Similar to TCP keep-alive interval. See NFC Session Limits and Timeouts.

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

Here is a 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 and NBDSSL, but not to SAN or HotAdd.

Advanced Transport APIs

Content feedback and comments

VMware vSphere SDKs and Tools 6.7

Initialize Virtual Disk API