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 below 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 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.