VMware 虚拟化编程(5) — VixDiskLib 虚拟磁盘库详解之一

目录

• 目录
• 前文列表
• VixDiskLib 虚拟磁盘库
• 虚拟磁盘数据的传输方式 Transport Methods
  • VixDiskLib_ListTransportModes 枚举支持的传输模式
  • VixDiskLib_InitEx 初始化 VixDiskLib 库
  • VixDiskLib_ConnectEx 连接到 virtual disk library
  • VixDiskLib_Disconnect 断开 VixDiskLib 的连接
  • VixDiskLib_Cleanup 断开连接之后的清理
  • VixDiskLib_Exit cleans up the library before exit
  • VixDiskLib_GetErrorText 获取错误信息
  • VixDiskLib_FreeErrorText 释放错误描述
• VMDK File 的访问认证和权限 Credentials and Privileges
• SSL 证书和安全

前文列表

VMware 虚拟化编程(1) — VMDK/VDDK/VixDiskLib/VADP 概念简析

VMware 虚拟化编程(2) — 虚拟磁盘文件类型详解

VMware 虚拟化编程(3) —VMware vSphere Web Service API 解析

VMware 虚拟化编程(4) — VDDK 安装

VixDiskLib 虚拟磁盘库

VDDK 实际上是基于 Virtual Disk API(虚拟磁盘接口) 来实现的，而 Virtual Disk API 也就是 VixDiskLib 虚拟磁盘库，是一组管理 VMDK File 的函数调用集合。

虚拟磁盘数据的传输方式 Transport Methods

VDDK 总共提供了 5 种数据传输方式，其中前 3 种为基本传输方式，后两种为高级传输方式：

• 本地文件(Local File)
• 网络块设备 NBD(Network Block Device)
• 局域网的加密 NBD(NBDSSL，NBD with encryption)
• SAN
• 热添加的 SCSI(SCSI HotAdd)

而在 VDDK 1.1 以后的版本中，都能够支持应用程序通过 SAN 或者 HotAdd 等方式来直接访问存储设备(Datastore)上的 VMDK File，而不仅限于使用 LAN 或 NBD 的传输方式来访问 VMDK File 数据，从而显着提高了 I/O 性能。

VixDiskLib_ListTransportModes 枚举支持的传输模式

函数原型：

/**
 * Get a list of transport modes known to VixDiskLib. This list is also the
 * default used if VixDiskLib_ConnectEx is called with transportModes set
 * to NULL.
 *
 * The string is a list of transport modes separated by colons. For
 * example: "file:san:hotadd:nbd". See VixDiskLib_ConnectEx for more details.
 *
 * @return Returns a string that is a list of plugins. The caller must not
 *         free the string.
 */
const char *
VixDiskLib_ListTransportModes(void);

函数调用：

printf(“Transportmethods: %s\n”, VixDiskLib_ListTransportModes());

该函数返回一个表示当前支持的传输模式列表字符串，E.G. file:san:hotadd:nbd，其中 nbd 表示 LAN 传输，nbdssl 表示 SSL 加密的 NBD 传输。san:hotadd:nbdssl:nbd 表示所有传输模式均可以使用。

VixDiskLib_InitEx 初始化 VixDiskLib 库

函数原型：

typedef void (VixDiskLibGenericLogFunc)(const char *fmt, va_list args);

/**
 * Initializes VixDiskLib.
 * @param majorVersion [in] Required major version number for client.
 * @param minorVersion [in] Required minor version number for client.
 * @param log [in] Callback for Log entries.
 * @param warn [in] Callback for warnings.
 * @param panic [in] Callback for panic.
 * @param libDir [in] Directory location where dependent libs are located.
 * @param configFile [in] Configuration file path in local encoding.
 *          configuration files are of the format
 *                name = "value"
 *          each name/value pair on a separate line. For a detailed
 *          description of allowed values, refer to the VixDiskLib
 *          documentation.
 *
 * @return VIX_OK on success, suitable VIX error code otherwise.
 */
VixError
VixDiskLib_InitEx(uint32 majorVersion,
                  uint32 minorVersion,
                  VixDiskLibGenericLogFunc *log,
                  VixDiskLibGenericLogFunc *warn,
                  VixDiskLibGenericLogFunc *panic,
                  const char* libDir,
                  const char* configFile);

函数调用：

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

函数 VixDiskLib_InitEx 用于初始化 Virtual Disk Library，与 VixDiskLib_Exit 相对，都应且仅应该在「应用程序的生命周期中」被调用一次。VixDiskLib_InitEx 函数支持使用高级传输方式。

• 形参 majorVersion, minorVersion 表示 VDDK 的发行版本的主板本号和次版本号。例如：如果我们使用的是 VDDK 6.0 Version，那么就是 majorVersion == 6; minorVersion == 0。
  
  PS：版本号由二至四个部分组成，主版本号、次版本号、内部版本号和修订号。主版本号和次版本号两个部分为必选。内部版本号和修订号两个部分为可选；格式为：主版本号.次版本号[.内部版本号[.修订号]]。

• 形参 &logFunc, &warnFunc, &panicFunc 分别为 Log、Warning、Panic 级别日志函数指针类型，若传入 NULL 实参则表示使用默认日志函数。但需要注意的是，默认日志函数式线程非安全的，如果在多线程场景下，务必需要实现自定义日志函数。

• 形参 *libDir 指定了 VDDK Lib 库的系统路径，按照上篇博文所提到的，在 Linux OS 中该路径应该为 /usr/lib/vmware-vix-disklib。

• 形参 *configFile 指定了 VDDK 配置文件的路径，通常为 /usr/etc/vddk.conf 配置文件中能够指定连接认证的方式、日志级别、传输类型、超时时间等。EXAMPLE：

# temporary directory for logs etc.
# 日志或一些 etc 文件的临时目录
tmpDirectory="/usr/local/vendorapp/var/vmware/temp"
# log level 0 to 6 for quiet ranging to verbose
# 高级传输方式(不包括NFC)的日志级别 0=Panic(failureonly)，1=Error，2=Warning，3=Audit，4=Info，5=Verbose，6=Trivia
vixDiskLib.transport.LogLevel=2
# disable caching to disk
# 当信息被重复读取或随机访问时，缓存可以提高性能。但在备份程序中，信息通常是被连续读取，缓存实际上降低了性能。所以备份程序而言一般不建议开启。
vixDiskLib.disklib.EnableCache=0
# whether to check SSL thumbprint on Linux - has no effect
# 从 Linux 连接到 VMware 虚拟机时是否检查 SSL 指纹
vixDiskLib.linuxSSL.verifyCertificates=1
# nfc.LogLevel (0 = Quiet, 1 = Error, 2 = Warning, 3 = Info, 4 = Debug)
# NFC 操作日志级别，NFC 设置应用于 NBD/NBDSSL，但不适用于 SAN 或 HotAdd。0=Quiet(minimallogging)，1=Error，2=Warning，3=Info，4=Debug
vixDiskLib.nfc.LogLevel=2
# network file copy options
# NFC 接收操作的默认值(3分钟)
vixDiskLib.nfc.AcceptTimeoutMs=180000
# NFC 请求操作的默认值(3分钟)
vixDiskLib.nfc.RequestTimeoutMs=180000
# NFC 读操作的默认值(1分钟)
vixDiskLib.nfc.ReadTimeoutsMs=60000
# NFC 写操作的默认值
vixDiskLib.nfc.WriteTimeoutsMs=600000
# NFC 文件系统操作的默认值(0，不定时等待)
vixDiskLib.nfcFssrvr.TimeoutMs=0
# NFC 文件系统写操作的默认值(没有超时)
vixDiskLib.nfcFssrvrWrite.TimeoutMs=0
# Specifiesadevicenodepath,oracommaseparatedlistof 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.
# SAN 高级传输设备黑名单
vixDiskLib.transport.san.blacklist=
# Specifiesadevicenodepath,oracommaseparatedlistof 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.
# SAN 高级传输设备白名单
vixDiskLib.transport.san.whitelist=

VixDiskLib_ConnectEx 连接到 virtual disk library

函数原型：

/**
 * Create a transport context to access disks belonging to a
 * particular snapshot of a particular virtual machine. Using this
 * transport context will enable callers to open virtual disks using
 * the most efficient data acces protocol available for managed
 * virtual machines, hence getting better I/O performance.
 *
 * If this call is used instead of VixDiskLib_Connect, the additional
 * information passed in will be used in order to optimize the I/O
 * access path, to maximize I/O throughput.
 *
 * Note: For local virtual machines/disks, this call is equivalent
 *       to VixDiskLib_Connect.
 *
 * @param connectParams [in] NULL if maniuplating local disks.
 *             For remote case this includes esx hostName and
 *             user credentials.
 * @param readOnly [in] Should be set to TRUE if no write access is needed
 *             for the disks to be accessed through this connection. In
 *             some cases, a more efficient I/O path can be used for
 *             read-only access.
 * @param snapshotRef [in] A managed object reference to the specific
 *             snapshot of the virtual machine whose disks will be
 *             accessed with this connection.  Specifying this
 *             property is only meaningful if the vmxSpec property in
 *             connectParams is set as well.
 * @param transportModes [in] An optional list of transport modes that
 *             can be used for this connection, separated by
 *             colons. If NULL is specified, VixDiskLib's default
 *             setting of "file:san:hotadd:nbd" is used. If a disk is
 *             opened through this connection, VixDiskLib will start
 *             with the first entry of the list and attempt to use
 *             this transport mode to gain access to the virtual
 *             disk. If this does not work, the next item in the list
 *             will be used until either the disk was successfully
 *             opened or the end of the list is reached.
 * @param connection [out] Returned handle to a connection.
 * @return VIX_OK if success, suitable VIX error code otherwise.
 */
VixError
VixDiskLib_ConnectEx(const VixDiskLibConnectParams *connectParams,
                     Bool readOnly,
                     const char *snapshotRef,
                     const char *transportModes,
                     VixDiskLibConnection *connection);

函数调用：

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;
    cnxParams.thumbPrint = thumbPrint;
}
VixError vixError = VixDiskLib_ConnectEx(&cnxParams, TRUE, snapshotMoref, transportModes, &connection);

在完成了 Virtual Disk Library 的初始化之后就可以调用 VixDiskLib_ConnectEx 将 Virtual Disk Library 连接到 vSphere or ESX/ESXi。其实，实际上是连接到某个具体的虚拟机。与 VixDiskLib_Disconnect 相对的，都应且仅应该在「对虚拟机所拥有的 VMDK File 操作的生命周期中」被调用。

• @param connectParams：连接参数集，包含以下子参数：
  • vmxSpec：一个 VirtualMachine moRef 虚拟机托管对象引用，E.G. moref=vm-3133。指定了连接到一个具体的虚拟机，集合参数 @param snapshotRef 就能够指定连接到一个具体的虚拟机的具体快照数据文件(VMDK)。
  • serverName, port: 是 vCenter os ESX/ESXi server 的 Ipaddress 和 Port，若 Port 设置为 NULL 时， VixDiskLib 使用默认的通信端口，通常是 443(HTTPS) 或者 902(VIX自动化)。注意，这里指的是数据传输端口，而不是 SOAP 请求的端口。
  • creds.uid.userName, creds.uid.password: 是登录账户认证信息
  • credType: 账户认证方式，支持下列认证方式：
    
    • VIXDISKLIB_CRED_UID (用户名/密码)
    • VIXDISKLIB_CRED_SESSIONID (HTTP Session ID)
    • VIXDISKLIB_CRED_TICKETID (vSphere Ticket ID)
    • VIXDISKLIB_CRED_SSPI (当前线程的认证凭据，只用于 Windows)
    • thumbPrint: vCenter or ESX/ESXi 的 SHA1 指纹信息，可以通过下述方式获取。

root@mickeyfan-dev:~# echo | openssl s_client -connect 192.168.10.105:443 |& openssl x509 -fingerprint -noout
SHA1 Fingerprint=96:20:34:47:6A:1A:15:DF:D4:BE:1D:52:A8:25:26:76:40:52:C6:BB

• @param readOnly: 为 TRUE 时，表示只读的访问 VMDK，通常效率会更高，而且之后调用 VixDiskLib_Open 也总是只读的，而无需理会其他的 openFlags 参数如何设置。若为 FALSE 表示可读写的方式访问 VMDK。

• @param snapshotRef: Snapshot moRef，与 vmxSpec 的格式不同，这里只需要给出 Snapshot moRef 的唯一值，E.G. snapshot-47。如果在参数 @param connectParams 中给定了 vmxSpec 子参数，那么该参数只能传入，Snapshot Mof。相反，还能够提供 ESXi Mof 或 vSphere Mof 来连接到 ESX/ESXi Host 和 vCenter Server。如果希望使用 SAN, HotAdd, NBDSSL 传输方式和需要访问一个开启电源的虚拟机的话，该参数也是必须的。如果访问的 VMDK File 为托管磁盘，就必须提供该实参；反之，若 VMDK File 为寄宿磁盘则可以为 NULL。

• @param transportModes: 传入一个以「:」为间隔的传输模式列表字符串，NULL 表示默认的 file:san:hotadd:nbd 传输模式。一般的，VixDiskLib 会遵循自左向右的优先级尝试使用不同的传输模式，直至成功连接或到达列表结尾为止。特别的，如果 SAN 存储可用的话，就会直接选择 SAN 传输模式、当然，你也可以仅指定一种传输模式，并且如果该模式不可用，连接也不会失败，只是在调用 VixDiskLib_Open 函数时，会自动选择使用 NDB 模式。

• @param connection: 该实参是一个指针类型，会在 VixDiskLib_ConnectEx 函数调用成功后返回，成为一个 connection 对象的句柄 handle，在 Disconnection 时会被用到。

NOTE：VixDiskLib_InitEx 和 VixDiskLib_ConnectEx 函数是 VixDiskLib_Init 和 VixDiskLib_Connect 的加强版，在版本较新的 VDDK 中才有提供，前者的组合有更加丰富的功能，建议使用。

VixDiskLib_Disconnect 断开 VixDiskLib 的连接

函数原型：

/**
 * Breaks an existing connection.
 * @param connection [in] Valid handle to a (local/remote) connection.
 * @return VIX_OK if success suitable VIX error code otherwise.
 */
VixError
VixDiskLib_Disconnect(VixDiskLibConnection connection);

函数调用：

VixDiskLib_Disconnect(connectionHandle);

调用该函数即可断开指定连接。

• @param connection：为调用 VixDiskLib_ConnectEx 之后 Return 的 VixDiskLibConnection 类型对象

VixDiskLib_Cleanup 断开连接之后的清理

函数原型：

/**
 * Perform a cleanup after an unclean shutdown of an application using
 * VixDiskLib.
 *
 * When using VixDiskLib_ConnectEx, some state might have not been cleaned
 * up if the resulting connection was not shut down cleanly. Use
 * VixDiskLib_Cleanup to remove this extra state.
 *
 * @param connection [in] Hostname and login credentials to connect to
 *       a host managing virtual machines that were accessed and need
 *       cleanup. While VixDiskLib_Cleanup can be invoked for local
 *       connections as well, it is a no-op in that case. Also, the
 *       vmxSpec property of connectParams should be set to NULL.
 * @param numCleanedUp [out] Number of virtual machines that were
 *       successfully cleaned up. -- Can be NULL.
 * @param numRemaining [out] Number of virutal machines that still
 *       require cleaning up. -- Can be NULL.
 * @return VIX_OK if all virtual machines were successfully cleaned
 *       up or if no virtual machines required cleanup. VIX error
 *       code otherwise and numRemaning can be used to check for
 *       the number of virtual machines requiring cleanup.
 */
VixError
VixDiskLib_Cleanup(const VixDiskLibConnectParams *connectParams,
                   uint32 *numCleanedUp, uint32 *numRemaining);

函数调用：

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

如果在 Disconnect 之后，虚拟机的额外状态并未正确的清除掉，调用该函数就能将这些额外的状态都清理掉。

NOTE：通过我们会在 VixDiskLib_InitEx 之前，或者 VixDiskLib_Disconnect 之后调用该函数，以清除不确定因素。但需要注意的是，在多并发或并行的场景中，调用该函数将变得非常危险。

VixDiskLib_Exit cleans up the library before exit

函数原型：

/**
 * Cleans up VixDiskLib.
 */
void
VixDiskLib_Exit(void);

函数调用：

VixDiskLib_Exit();

在程序退出之前，均需要调用 VixDiskLib_Exit 来清理 Lib 库所分配的资源。

VixDiskLib_GetErrorText 获取错误信息

函数原型：

/**
 * Returns the textual description of an error.
 * @param err [in] A VIX error code.
 * @param locale [in] Language locale - not currently supported and must be NULL.
 * @return The error message string. This should only be deallocated
 *         by VixDiskLib_FreeErrorText.
 *         Returns NULL if there is an error in retrieving text.
 */
char *
VixDiskLib_GetErrorText(VixError err, const char *locale);

函数调用：

char*msg = VixDiskLib_GetErrorText(errorCode, NULL);

调用 VixDiskLib_GetErrorText 函数，能够获取 errorCode 所代表的的错误信息描述。

VixDiskLib_FreeErrorText 释放错误描述

函数原型：

/**
 * Free the error message returned by VixDiskLib_GetErrorText.
 * @param errMsg [in] Message string returned by VixDiskLib_GetErrorText.
 *    It is OK to call this function with NULL.
 * @return None.
 */
void
VixDiskLib_FreeErrorText(char* errMsg);

函数调用：

VixDiskLib_FreeErrorText(msg);

需要注意的是，在获取了错误描述信息之后，均需要调用该函数来释放这些信息。

• @param errMsg：即为调用 VixDiskLib_GetErrorText 所获得的错误信息类型对象。

VMDK File 的访问认证和权限 Credentials and Privileges

ESX/ESXi Host 使用登陆凭据信息进行访问认证，只要凭据正确，VixDiskLib 可以访问 ESX/ESXi Host 上任意 VMDK File。而 VMware vSphere 则有专属的一组权限(Privileges)机制，需要拥有正确的权限和登陆凭据，VixDiskLib 才能访问所有由 vCenter Server 管理的 ESX/ESXi Host 上任意的 VMDK File。

• vCenter Server 中，备份应用用户在备份虚拟机数据时，必须具有以下权限：

  1. 虚拟机(VirtualMachine) > 配置(Configuration) > 跟踪磁盘修改(Disk Change Tracking)
  2. 虚拟机(VirtualMachine) > 支持(Provisioning) > 允许磁盘只读访问，并且允许虚拟机下载(VM download)
  3. 虚拟机(VirtualMachine) > 状态(State) > 创建快照和移除快照

• 备份应用中，用户必须具有以下权限：

  1. 数据存储(Datastore) > 分配空间(Allocate space)
  2. 虚拟机(VirtualMachine) > 配置(Configuration) > 添加新磁盘和移除磁盘
  3. 虚拟机(VirtualMachine) > 配置(Configuration) > 修改资源(Resource)和设置(Setting)

• 当备份涉及 vCenter Server 以及所有 ESX/ESXi Host 时，用户还需要具有以下权限：

  1. 全局(Global) > 禁用和启用方法(DisableMethods and EnableMethods)
  2. 全局(Global) > 牌照(License)
     
     所有的权限都必须应用在 vCenter Server 级别，否则将会返回类似「The host is not licensed for this feature」这样的错误。

SSL 证书和安全

在 Linux 上的 VixDiskLib 的 SSL 证书验证需要提供指纹(Thumbprints)序列，vSphere 的指纹是指从一个可信源(vCenter Server or ESX/ESXi)中获得的一个哈希值(hash)，并将该指纹传入 NFC Ticket 的 SSLVerifyParam 数据结构，若检查 Thumbprints PASS 则可以建立 SSL 连接。

在上述的 vddk.conf 配置文件中使用下述配置，则表示开启检查 SSL SHA1 Thumbprints。

vixDiskLib.linuxSSL.verifyCertificates= 1