XML Hook

概览

XML Hook：一种脚本程序，用于在云主机XML文件中灵活插入或修改参数，从而实现定制化配置并扩展云主机功能。

如图 1所示：

功能优势

ZStack Cloud XML Hook功能具有以下优势：

灵活性
- XML Hook以单独的脚本文件形式管理和维护，将临时或个性化配置需求与程序核心逻辑代码分离，云主机绑定/解绑XML Hook，即可实现配置动态调整和灵活扩展，无需手动修改代码。
- XML Hook可长期保存、重复使用，一个XML Hook可同时绑定到多台云主机，有效提高大规模场景运维效率。
可扩展性
通过定义并使用XML Hook，用户可按实际需求灵活修改云主机XML参数，实现部分无法通过界面操作直接完成的配置，有效扩展云主机能力，满足个性化场景需求，例如：修改QEMU自定义参数、关闭vNIC TSO等。XML Hook为用户现场、第三方软硬件测试与应用提供了更便捷的适配途径。

注意事项

使用XML Hook需熟悉云主机配置和XML编写规则，如XML Hook中包含语法错误或导致云主机配置错误，云主机将无法启动。
如需对已绑定XML Hook的云主机需进行QEMU/Libvirt升级，请提前确认预期QEMU/Libvirt是否兼容该XML Hook，避免升级后因不兼容导致云主机启动/重启失败。

清单

属性

名字	描述	起始支持版本
uuid	资源UUID，唯一标识该资源	5.2.0
description	资源的详细描述	5.2.0
name	资源名称	5.2.0
hookScript	XML Hook脚本内容	5.2.0
libvirtVersion	Libvirt版本	5.2.0
type	类型	5.2.0
createDate	请参见资源结构	5.2.0
lastOpDate	请参见资源结构	5.2.0
tagUuid	标签UUID列表	5.2.0
userTags	用户标签，请参见创建用户标签(CreateUserTag)	5.2.0
systemTags	系统标签，请参见创建系统标签(CreateSystemTag)	5.2.0
groupBy		5.2.0

示例

{
    "inventories": [
        {
            "createDate": "Aug 29, 2024 2:08:10 PM",
            "hookScript": "ZGVm",
            "lastOpDate": "Aug 29, 2024 2:08:10 PM",
            "name": "test",
            "type": "Customization",
            "uuid": "38cb92040eb747e7835b7c50a803a9ed"
        }
    ],
    "success": true
}

操作 (Operations)

创建用户自定义XML Hook（CreateVmUserDefinedXmlHookScript）

用户可以使用CreateVmUserDefinedXmlHookScript创建XML Hook。例如：

CreateVmUserDefinedXmlHookScript name=hook hookScript=base64

参数（Parameters）

名字	描述	可选的	起始支持版本
name	资源名称		5.2.0
description	资源的详细描述	是	5.2.0
hookScript	XML Hook脚本内容		5.2.0
resourceUuid	资源UUID	是	5.2.0
tagUuids	标签UUID列表	是	5.2.0
userTags	用户标签，请参见创建用户标签(CreateUserTag)	是	5.2.0
systemTags	系统标签，请参见创建系统标签(CreateSystemTag)	是	5.2.0
timeout		是

彻底删除用户自定义XML Hook（ExpungeVmUserDefinedXmlHookScript）

用户可以使用ExpungeVmUserDefinedXmlHookScript彻底删除XML Hook。例如：

ExpungeVmUserDefinedXmlHookScript uuid=99df64f50f5b34c6be5a7339d676aeb6

参数（Parameters）

名字	描述	可选的	起始支持版本
uuid	资源的UUID，唯一标示该资源		5.2.0
userTags	用户标签，请参见创建用户标签(CreateUserTag)	是	5.2.0
systemTags	系统标签，请参见创建系统标签(CreateSystemTag)	是	5.2.0
timeout		是

查询用户自定义XML Hook（QueryVmUserDefinedXmlHookScript）

用户可以使用QueryVmUserDefinedXmlHookScript查询XML Hook。例如：

QueryVmUserDefinedXmlHookScript uuid=99df64f50f5b34c6be5a7339d676aeb6

原生域查询（Primitive Fields of Query）

请参见XML Hook Inventory

更新用户自定义XML Hook（UpdateVmUserDefinedXmlHookScript）

用户可以使用UpdateVmUserDefinedXmlHookScript更新XML Hook。例如：

UpdateVmUserDefinedXmlHookScript uuid=99df64f50f5b34c6be5a7339d676aeb6 name=example

参数（Parameters）

名字	描述	可选的	可选的参数值	起始支持版本
uuid	资源的UUID，唯一标示该资源			5.2.0
name	资源名称	是		5.2.0
description	资源的详细描述	是		5.2.0
hookScript	XML Hook脚本内容	是		5.2.0
userTags	用户标签，请参见创建用户标签(CreateUserTag)	是		5.2.0
systemTags	系统标签，请参见创建系统标签(CreateSystemTag)	是		5.2.0
startupStrategy	启动策略		Reboot None	5.2.0
timeout		是

挂载用户自定义XML Hook到云主机（AttachUserDefinedXmlHookScriptToVm）

用户可以使用AttachUserDefinedXmlHookScriptToVm挂载XML Hook到云主机。例如：

AttachUserDefinedXmlHookScriptToVm vmInstanceUuid=6baaffd8cb123dcc954b6242835267b9 xmlHookUuid=73300c2b203e3e43bc4b0dec7c3b0f21 startupStrategy=None

参数（Parameters）

名字	描述	可选的	可选的参数值	起始支持版本
vmInstanceUuid	云主机UUID			5.2.0
xmlHookUuid	XML Hook UUID			5.2.0
startupStrategy	启动策略	是	Reboot None	5.2.0
userTags	用户标签，请参见创建用户标签(CreateUserTag)	是		5.2.0
systemTags	系统标签，请参见创建系统标签(CreateSystemTag)	是		5.2.0
timeout		是

从云主机卸载用户自定义XML Hook（DetachUserDefinedXmlHookScriptFromVm）

用户可以使用DetachUserDefinedXmlHookScriptFromVm从云主机卸载XML Hook。例如：

DetachUserDefinedXmlHookScriptFromVm vmInstanceUuid=6baaffd8cb123dcc954b6242835267b9 startupStrategy=None deleteMode=Permissive

参数（Parameters）

名字	描述	可选的	可选的参数值	起始支持版本
vmInstanceUuid	云主机UUID			5.2.0
startupStrategy	启动策略	是	Reboot None	5.2.0
deleteMode	删除模式	是	Permissive Enforcing，Permissive	5.2.0
userTags	用户标签，请参见创建用户标签(CreateUserTag)	是		5.2.0
systemTags	系统标签，请参见创建系统标签(CreateSystemTag)	是		5.2.0
timeout		是