ddns(Dynamic Domain Name System) 版本信息 项目 内容 组件版本 1.140.0 首发版本 0.0.1(2022-11-21) 文档作者 openUBMC 社区 最后更新 2026-10-19
1. 组件概述 1.1 组件简介 ddns 组件是 openUBMC 中的动态域名系统(Dynamic Domain Name System)客户端组件,以独立 skynet 服务形式部署运行(D-Bus 服务名 bmc.kepler.ddns,systemd 服务单元 ddns.service)。组件实现的 DNS 报文构造/解析与套接字收发动态库,对外提供 DNS 配置管理、resolv.conf 维护与 DNS 资源记录动态更新能力。
1.2 解决什么问题 在 BMC 主机 IP、域名或 VLAN 发生变化时,自动向 DNS 服务器更新 A/AAAA/PTR 资源记录,使用户能够通过域名实时正确地访问 BMC,无需人工干预。 统一管理 BMC 侧的 DNS 客户端配置(主/备/第三 DNS 服务器、DNS 地址来源模式、DHCPv4/v6 自动获取开关、绑定 IP 协议版本等),并通过 resolv.conf 为 BMC 系统内所有需要进行域名解析的进程提供解析能力。 提供 IPMI 与资源协作接口(MDB)两种北向配置通道,并支持配置导入/导出与装备定制化,便于对接运维平台与产线装备流程。 1.3 核心功能 核心功能一:DNS 客户端配置管理。维护主/备/第三 DNS 服务器地址、DHCPv4/DHCPv6 自动获取 DNS 开关、DNS 地址来源(Static/IPv4/IPv6)、绑定 IP 协议版本(ServerIpVersion)等属性,并持久化到数据库表 t_ddns_config。 核心功能二:resolv.conf 配置文件维护。根据 DNS 配置(含 options timeout/attempts、search 域名、nameserver 列表)生成 /data/etc/resolv.conf,文件权限 640;并在 DHCP 自动获取模式下从 resolv.conf.dhclient / resolv.conf.dhclient6 同步配置。 核心功能三:DNS 资源记录动态更新。通过 feature_basic 特性门控启用,按租约周期或属性变更触发,向 DNS 服务器发送 SOA 查询、A/AAAA/PTR 查询与动态更新报文,更新 BMC 主机对应的 A/AAAA/PTR 记录。 核心功能四:配置导入导出与装备定制化。通过 mdb_config_manage 注册 import/export/verify 回调,支持标准配置与装备定制化两种场景的导入、导出和校验。 核心功能五:IPMI 命令支持。提供设置 DNS 服务器、设置 DHCP DNS 来源、设置绑定 IP 协议、查询/设置 DNS 记录更新信息等 OEM IPMI 命令。 1.4 关键术语表(可选) 术语 解释 DDNS Dynamic Domain Name System,IP/域名变化时自动更新 DNS 记录的机制 RR Resource Record,DNS 资源记录,本组件涉及 A、AAAA、A6、PTR、SOA 等类型 DNSAddressOrigin DNS 服务器地址来源模式,取值为 Static(手动)/ IPv4(DHCPv4 自动)/ IPv6(DHCPv6 自动) ServerIpVersion DNS 绑定的 IP 协议版本,取值为 IPv4 或 IPv6 LeaseTimeSeconds DDNS 记录更新租约时间(秒),默认 180,取值范围 180~86400 feature_basic 组件构建期特性门控,决定是否启用 DNS 资源记录动态更新特性,默认 false
1.5 外部交互边界图 2. API 使用说明与示例 2.1 SetPrimaryNameServer 功能说明 设置主 DNS 服务器地址(PrimaryNameServer)。校验 IP 合法性后同步到内存、资源树与数据库,并刷新 resolv.conf;若启用动态更新特性,会触发 DNS 资源记录更新标志。
属性 内容 接口名 bmc.kepler.Managers.EthernetInterfaces.DNS.SetPrimaryNameServer 废弃状态 正常可用 替代接口
参数说明 参数名 方向 类型 描述 取值范围 IpAddr 输入 String 主 DNS 服务器 IP 地址,允许清空 合法 IPv4/IPv6 字符串或空字符串
返回值与异常 返回值 含义 触发条件 处理建议 0 (E_OK) 成功 IP 合法且更新成功 无 0x00000002 (E_INVALID_IP) 失败 IP 既不是合法 IPv4 也不是合法 IPv6 检查输入 IP 格式 异常 InvalidValue 失败 IP 校验未通过时通过 error 抛出 检查输入 IP 格式
应用场景 Redfish/Web/CLI 等北向接口设置 BMC 主 DNS 服务器地址时,最终通过资源协作接口 SetPrimaryNameServer 落盘。
限制条件 调用者需具备 BasicSetting 写权限。 IP 与当前值相同时直接返回 0,不触发后续刷新动作。 调试示例 命令行调试 bash busctl --user call bmc.kepler.ddns /bmc/kepler/Managers/1/EthernetInterfaces/DNS bmc.kepler.Managers.EthernetInterfaces.DNS SetPrimaryNameServer s "192.168.1.1" 2.2 SetBackupNameServer 功能说明 设置备用 DNS 服务器地址(BackupNameServer)。处理逻辑与 SetPrimaryNameServer 一致,对应数据库字段 BackupNameServer 与 resolv.conf 中第二个 nameserver。
属性 内容 接口名 bmc.kepler.Managers.EthernetInterfaces.DNS.SetBackupNameServer 废弃状态 正常可用 替代接口
参数说明 参数名 方向 类型 描述 取值范围 IpAddr 输入 String 备用 DNS 服务器 IP 地址,允许清空 合法 IPv4/IPv6 字符串或空字符串
返回值与异常 返回值 含义 触发条件 处理建议 0 (E_OK) 成功 IP 合法且更新成功 无 0x00000002 (E_INVALID_IP) 失败 IP 不合法 检查输入 IP 格式
应用场景 北向接口设置 BMC 第二 DNS 服务器地址。
限制条件 调试示例 命令行调试 bash busctl --user call bmc.kepler.ddns /bmc/kepler/Managers/1/EthernetInterfaces/DNS bmc.kepler.Managers.EthernetInterfaces.DNS SetBackupNameServer s "192.168.1.2" 2.3 SetTertiaryNameServer 功能说明 设置第三 DNS 服务器地址(TertiaryNameServer)。处理逻辑同 SetPrimaryNameServer,对应数据库字段 TertiaryNameServer 与 resolv.conf 中第三个 nameserver。
属性 内容 接口名 bmc.kepler.Managers.EthernetInterfaces.DNS.SetTertiaryNameServer 废弃状态 正常可用 替代接口
参数说明 参数名 方向 类型 描述 取值范围 IpAddr 输入 String 第三 DNS 服务器 IP 地址,允许清空 合法 IPv4/IPv6 字符串或空字符串
返回值与异常 返回值 含义 触发条件 处理建议 0 (E_OK) 成功 IP 合法且更新成功 无 0x00000002 (E_INVALID_IP) 失败 IP 不合法 检查输入 IP 格式
应用场景 北向接口设置 BMC 第三 DNS 服务器地址。
限制条件 调试示例 命令行调试 bash busctl --user call bmc.kepler.ddns /bmc/kepler/Managers/1/EthernetInterfaces/DNS bmc.kepler.Managers.EthernetInterfaces.DNS SetTertiaryNameServer s "192.168.1.3" 2.4 SetDHCPUseDNSServers 功能说明 设置 DHCPv4 或 DHCPv6 自动获取 DNS 服务器开关。根据 DHCPVersion 选择目标属性(DHCPv4UseDNSServers / DHCPv6UseDNSServers),按 State 转换为布尔值后同步到内存、资源树与数据库。
属性 内容 接口名 bmc.kepler.Managers.EthernetInterfaces.DNS.SetDHCPUseDNSServers 废弃状态 正常可用 替代接口
参数说明 参数名 方向 类型 描述 取值范围 DHCPVersion 输入 U16 选择目标属性,0 表示 DHCPv4UseDNSServers,1 表示 DHCPv6UseDNSServers 0 / 1 State 输入 U8 使能开关,1 为打开,0 为关闭 0 / 1
注:proto/types/messages.proto 中 DHCPVersion 声明为 uint8,但 bingo gen 生成的 gen/class/model.lua 与 gen/ddns/json_types/DNS.lua 实际按 uint16 校验,busctl 签名应为 qy(U16+U8)。
返回值与异常 返回值 含义 触发条件 处理建议 0 (E_OK) 成功 参数合法且更新成功 无 0x00000005 (E_PARAM_OUT_OF_RANGE) 失败 DHCPVersion 非 0/1 检查 DHCPVersion 取值 异常 InvalidValue 失败 State 非 0/1 检查 State 取值
应用场景 通过北向接口使能/去使能从 DHCPv4 或 DHCPv6 自动获取 DNS 服务器地址。
限制条件 调试示例 命令行调试 bash
busctl --user call bmc.kepler.ddns /bmc/kepler/Managers/1/EthernetInterfaces/DNS bmc.kepler.Managers.EthernetInterfaces.DNS SetDHCPUseDNSServers qy 0 1 2.5 SetDNSAddressOrigin 功能说明 设置 DNS 服务器地址来源模式(DNSAddressOrigin)。组件会按 Origin 联动设置 DHCPv4UseDNSServers / DHCPv6UseDNSServers,并在非 Static 模式下更新 ServerIpVersion;当 Origin 为 IPv4/IPv6 时,会校验对应网络是否处于 DHCP 模式。
属性 内容 接口名 bmc.kepler.Managers.EthernetInterfaces.DNS.SetDNSAddressOrigin 废弃状态 正常可用 替代接口
参数说明 参数名 方向 类型 描述 取值范围 Origin 输入 String DNS 服务器来源 "Static" / "IPv4" / "IPv6"
返回值与异常 返回值 含义 触发条件 处理建议 0 (E_OK) 成功 Origin 合法且更新成功 无 0x00000001 (E_INTERNAL_ERR) 失败 同步 DHCPv4/DHCPv6/ServerIpVersion 失败 查看组件 error 日志定位失败步骤 异常 StaticIPMode 失败 Origin 为 IPv4/IPv6 但对应网络非 DHCP 模式 先将对应网络切换为 DHCP 模式 异常 InvalidValue 失败 Origin 非 Static/IPv4/IPv6 检查 Origin 取值
应用场景 Redfish 设置 Oem.Huawei.DNSAddressOrigin 或 IPMI SetDHCPDnsServers 时,最终调用此方法切换 DNS 服务器获取方式。
限制条件 调用者需具备 BasicSetting 写权限。 切换到 IPv4 模式要求 IPv4 网络已处于 DHCP;切换到 IPv6 模式要求 IPv6 网络已处于 DHCPv6。 调试示例 命令行调试 bash busctl --user call bmc.kepler.ddns /bmc/kepler/Managers/1/EthernetInterfaces/DNS bmc.kepler.Managers.EthernetInterfaces.DNS SetDNSAddressOrigin s "Static" 2.6 SetDnsServer(IPMI 命令) 功能说明 通过 OEM IPMI 命令设置主 DNS 服务器地址。将 IPMI 报文中的 IpAddress(4 字节 IPv4 / 16 字节 IPv6 / 0 字节清空)字符串化后调用 set_primary_nameserver 落盘。
属性 内容 接口名 IPMI netfn 0x30 cmd 0x93 SubCmd 0x05 ParameterSelector 0x04 废弃状态 正常可用 替代接口
参数说明 参数名 方向 类型 描述 取值范围 ManufactureId 输入 U32(3B) 厂商 ID 0x0007db SubCmd 输入 U8 子命令 0x05 ParameterSelector 输入 U8 参数选择器 0x04 Reserved 输入 U8(7b) 保留字段 0 Cascade 输入 U8(1b) 级联标志 0/1 Offset 输入 U8 偏移量 0 Length 输入 U8 IpAddress 长度 0 / 4 / 16 IpAddress 输入 String IP 地址原始字节 长度等于 Length CompletionCode 输出 U8 完成码 0x00 成功 / 0x02 命令非法 / 0x03 设置失败 ManufactureId 输出 U32(3B) 厂商 ID 回显 0x0007db
返回值与异常 返回值 含义 触发条件 处理建议 0x00 成功 ManufactureId、Length 校验通过且 set_primary_nameserver 成功 无 0x02 命令非法 ManufactureId 不匹配或 Length 非 0/4/16 检查厂商 ID 与 Length 0x03 设置失败 set_primary_nameserver 抛出异常 查看 error 日志 异常 IPMIInvalidFieldRequest 失败 ManufactureId 不匹配 检查厂商 ID 异常 IPMIOutOfRange 失败 Length 与 IpAddress 实际长度不一致 检查报文长度
应用场景 通过 IPMI 命令通道配置主 DNS 服务器,常见于带外管理工具脚本化配置 BMC。
限制条件 权限:role Operator,privilege BasicSetting。 系统锁定策略:Forbidden(系统锁定时禁止执行)。 调试示例 命令行调试 bash ipmitool -I lanplus -H < bmc_i p > -U < use r > -P < pas s > raw 0x30 0x93 0xdb 0x07 0x00 0x05 0x04 0x00 0x00 0x04 0xC0 0xA8 0x01 0x01 2.7 SetDnsServer1 / SetDnsServer2(IPMI 命令) 功能说明 SetDnsServer1 设置备用 DNS 服务器(ParameterSelector=0x07,对应 BackupNameServer);SetDnsServer2 设置第三 DNS 服务器(ParameterSelector=0x1B,对应 TertiaryNameServer)。其余字段、返回码、限制条件与 SetDnsServer 一致。
属性 内容 接口名 IPMI netfn 0x30 cmd 0x93 SubCmd 0x05 ParameterSelector 0x07(SetDnsServer1) / 0x1B(SetDnsServer2) 废弃状态 正常可用 替代接口
参数说明、返回值与异常、限制条件、调试示例请参见 2.6 节 SetDnsServer,差异仅在于 ParameterSelector 取值与目标属性。
2.8 SetDHCPDnsServers(IPMI 命令) 功能说明 通过 OEM IPMI 命令设置 DNS 服务器获取方式。Data=0 表示 Static 模式;Data=1 表示使用当前 ServerIpVersion 对应的自动模式(DHCPv4 或 DHCPv6)。
属性 内容 接口名 IPMI netfn 0x30 cmd 0x93 SubCmd 0x05 ParameterSelector 0x0F 废弃状态 正常可用 替代接口
参数说明 参数名 方向 类型 描述 取值范围 Data 输入 U8 DNS 来源选择 0=Static,1=自动(按 ServerIpVersion) 其他字段 输入 - 与 SetDnsServer 相同(ManufactureId/SubCmd/ParameterSelector=0x0F/Reserved/Cascade/Offset/Length=1) 见 ipmi.json CompletionCode 输出 U8 完成码 0x00 / 0x02 / 0x03
返回值与异常 返回值 含义 触发条件 处理建议 0x00 成功 Data 合法且 set_dns_addr_origin 成功 无 0x02 命令非法 Data 非 0/1 检查 Data 取值 0x03 设置失败 set_dns_addr_origin 抛出异常(如网络非 DHCP) 查看日志,确认网络模式
应用场景 通过 IPMI 命令切换 DNS 服务器获取方式。
限制条件 权限:role Operator,privilege BasicSetting;系统锁定策略 Forbidden。 Data=1 时需对应网络已为 DHCP,否则 set_dns_addr_origin 抛出 StaticIPMode 异常。 2.9 SetDnsBindIpProtocol(IPMI 命令) 功能说明 通过 OEM IPMI 命令设置 DNS 绑定的 IP 协议版本。Data1=0 表示 IPv4,Data1=1 表示 IPv6。若当前为 DHCP 自动模式则联动调用 set_dns_addr_origin,否则仅更新 ServerIpVersion。
属性 内容 接口名 IPMI netfn 0x30 cmd 0x93 SubCmd 0x05 ParameterSelector 0x10 废弃状态 正常可用 替代接口
参数说明 参数名 方向 类型 描述 取值范围 Data1 输入 U8 绑定 IP 协议 0=IPv4,1=IPv6 其他字段 输入 - 与 SetDnsServer 相同(ParameterSelector=0x10) 见 ipmi.json CompletionCode 输出 U8 完成码 0x00 / 0x02 / 0x03
返回值与异常 返回值 含义 触发条件 处理建议 0x00 成功 Data1 合法且更新成功 无 0x02 命令非法 Data1 非 0/1 检查 Data1 取值 0x03 设置失败 set_dns_addr_origin 或 update_serveripversion_use_dns_data 抛出异常 查看日志
限制条件 权限:role Operator,privilege BasicSetting;系统锁定策略 Forbidden。 2.10 GetDnsRecordUpdateInfo(IPMI 命令) 功能说明 查询 DNS 资源记录动态更新的使能状态与租约时间。仅当 feature_basic 特性启用(即 update_detection 模块可用)时注册。
属性 内容 接口名 IPMI netfn 0x30 cmd 0x93 SubCmd 0x5b Selector 0x004c 废弃状态 正常可用 替代接口
参数说明 参数名 方向 类型 描述 取值范围 ManufactureId 输入 U32(3B) 厂商 ID 0x0007db SubCmd 输入 U8 子命令 0x5b Selector 输入 U16 选择器 0x004c Length 输入 U16 长度 0x0000 CompletionCode 输出 U8 完成码 0x00 / 0x80(InvalidFieldRequest) UpdateEnable 输出 U8 动态更新使能 0/1 LeaseTime 输出 String(4B) 租约时间(小端 4 字节) 180~86400
返回值与异常 返回值 含义 触发条件 处理建议 0x00 成功 ManufactureId 校验通过 无 0x80 (InvalidFieldRequest) 失败 ManufactureId 不匹配 检查厂商 ID
限制条件 权限:role Operator,privilege ReadOnly。 仅 feature_basic=true 构建版本可用。 2.11 SetDnsRecordUpdateInfo(IPMI 命令) 功能说明 设置 DNS 资源记录动态更新使能与租约时间。UpdateEnable=0 表示关闭(LeaseTime 必须为空),UpdateEnable=1 表示使能(LeaseTime 可为空或 4 字节小端整数,范围 180~86400)。
属性 内容 接口名 IPMI netfn 0x30 cmd 0x93 SubCmd 0x5a Selector 0x004c 废弃状态 正常可用 替代接口
参数说明 参数名 方向 类型 描述 取值范围 UpdateEnable 输入 U8 动态更新使能 0 / 1 LeaseTime 输入 String 租约时间(小端 4 字节)或空 空或 4 字节,范围 180~86400 Length 输入 U16 LeaseTime 长度 + 1 与 LeaseTime 长度一致 CompletionCode 输出 U8 完成码 见下表
返回值与异常 返回值 含义 触发条件 处理建议 0x00 成功 参数合法且落盘成功 无 0x80 (InvalidFieldRequest) 失败 ManufactureId 不匹配 检查厂商 ID 0x09 (ParmOutOfRange) 失败 UpdateEnable 非 0/1 或 LeaseTime 超出 180~86400 检查参数取值 0x07 (ReqDataLenInvalid) 失败 LeaseTime 长度非 0/4 或 Length 不匹配 检查报文长度 0xFF (UnspecifiedError) 失败 数据库保存失败 查看日志
应用场景 通过 IPMI 命令开启/关闭 DDNS 动态更新,或调整租约周期。
限制条件 权限:role Operator,privilege BasicSetting;系统锁定策略 Forbidden。 仅 feature_basic=true 构建版本可用。 3. 组件扩展案例 3.1 扩展能力概述 ddns 组件提供以下扩展能力:
构建期特性门控:通过 conan 选项 feature_basic 控制是否启用 DNS 资源记录动态更新特性。当前 conanfile.py 在 feature_basic=True 时会从 package 中删除 update_detection.lua(运行期 pcall(require, 'update_detection') 失败,动态更新与相关 IPMI 命令不注册),与 mds/service.json 中"feature_basic 决定是否支持动态更新 DNS 资源记录特性"的语义描述方向相反,使用前请以 conanfile.py 实际逻辑为准(详见本文档证据篇)。 装备定制化:组件注册了 customize_import / customize_export / customize_verify 回调,支持装备产线通过定制化配置文件批量下发 DNS 配置(含主/备/第三 DNS、DNS 来源模式、动态更新使能与周期)。 配置导入导出:通过 mdb_config_manage 注册标准 import/export/verify 回调,对接 openUBMC 配置导入导出引擎,支持按 Import 字段控制单属性是否导入。 资源树属性订阅:组件按 service.json 中 required 声明订阅 bmc_network 组件的域名、主机名、IPv4/IPv6 地址、VLAN 等属性变化,可作为新增网口组类型的扩展点。 3.2 扩展点说明 mds/service.json 的 options.feature_basic:构建期特性门控,默认 false。当前 conanfile.py 实际逻辑为:feature_basic=True 时在 package 阶段删除 update_detection.lua,运行期 pcall(require, 'update_detection') 失败,相关 IPMI 命令(GetDnsRecordUpdateInfo/SetDnsRecordUpdateInfo)不注册;feature_basic=False 时保留 update_detection.lua。该行为与 mds/service.json 中"feature_basic 决定是否支持动态更新 DNS 资源记录特性"的描述方向相反,使用前请以 conanfile.py 实际逻辑为准。mds/service.json 的 required 数组:声明组件需要订阅的外部资源树接口与属性。新增对其他网络属性的依赖时,可在此处添加 path/interface/properties 配置,并在 ddns_config.lua 的 register_listen_cb 中注册对应的 On*PropertiesChanged 回调。customization/customization.py:构建期装备定制化脚本入口,post_rootfs 钩子用于在 rootfs 中创建 /etc/resolv.conf -> /data/etc/resolv.conf 的软链。mds/model.json 的 methods 与 properties:扩展新的资源协作方法或属性时,在此声明并使用 bingo gen 重新生成代码,再在 ddns_app.lua 的 register_methods 中实现。3.3 二次开发指导 步骤一 在 mds/model.json 的 bmc.kepler.Managers.EthernetInterfaces.DNS.methods 下声明新的方法(含 privilege 配置),并在 mds/service.json 的 dependencies 中补充所需的 conan 依赖。
步骤二 执行 bingo gen 重新生成 gen/ddns/service.lua 等代码,使新的 ImplDNSDNS<MethodName> 接口可用;在 src/lualib/ddns_app.lua 的 register_methods 函数中注册方法实现,并将业务逻辑下沉到 ddns_config.lua 的对应方法中。
示例代码 lua -- src/lualib/ddns_app.lua
function cddns_client : register_methods ()
-- ... 已有方法注册 ...
dns_service : ImplDNSDNSSetNewOption ( function (obj, ctx, Value)
return self : SetNewOption (obj, ctx, Value)
end )
end
function cddns_client : SetNewOption (obj, ctx, Value)
local ret = self . ddns_config : set_new_option (Value)
if ret ~= err_code. E_OK then
log : operation ( ctx : get_initiator (), 'ddns' , 'Set new option failed' )
else
log : operation ( ctx : get_initiator (), 'ddns' , 'Set new option to (%s) successfully' , Value)
end
return ret
end 验证方法 执行 bingo build 构建组件并部署到 BMC。 通过 busctl --user introspect bmc.kepler.ddns /bmc/kepler/Managers/1/EthernetInterfaces/DNS 查看新方法是否暴露。 调用新方法并查看 /var/log/framework/ddns.log 中的 operation 日志与数据库 t_ddns_config 是否更新。 预期结果:方法调用返回 0,日志中记录成功操作,数据库字段更新。 注意事项 新增方法必须在 mds/model.json 中声明 privilege,否则资源树权限校验会拒绝调用。 修改 mds/service.json 的 required 后需确认 bmc_network 等被依赖组件已暴露对应接口与属性,否则组件启动时依赖检查失败。 feature_basic 关闭时,任何引用 update_detection 模块的代码路径都必须通过 pcall(require, 'update_detection') 保护,避免运行期 require 失败导致服务异常。涉及 resolv.conf 写入的操作必须使用 utils.file.open_s 安全接口,并通过 utils_core.chmod_s 设置 640 权限。 4. 日志说明 4.1 一键日志收集 执行系统一键日志收集功能时,会自动收集本组件的以下日志文件:
文件路径 内容说明 /var/log/framework/ddns.log ddns 组件运行期日志,包含启动、配置变更、IPMI 操作、动态更新、错误等信息(由 dist/config.cfg 中 logger 配置)
4.2 关键日志信息 日志片段 日志级别 含义解读 建议处理动作 ddns service startINFO ddns 服务启动 无 ddns service exitINFO ddns 服务退出 若非主动重启,检查是否被 systemd 拉起 DNS config database is corruptedERROR 数据库 t_ddns_config 查询不到记录,使用默认值初始化 检查 persistence 组件与数据库状态 Open resolv.conf failedERROR 打开 /data/etc/resolv.conf 失败 检查文件是否存在、权限是否为 640、属主是否为 secbox Generate DNS config file failedERROR 生成 resolv.conf 失败 查看 error 日志上下文定位 open_s / write 失败原因 Invalid IPv4 or IPv6 addressERROR 设置 DNS 服务器时 IP 校验失败 检查调用方传入的 IP 格式 Invalid manufacturer id: 0x%xERROR IPMI 命令 ManufactureId 不等于 0x0007db 检查 IPMI 报文厂商 ID Set primary DNS server to (%s) successfullyOPERATION 主 DNS 服务器设置成功 无 Set DNS service mode to (%s) failedOPERATION DNS 地址来源模式设置失败 结合 error 日志确认是否网络非 DHCP 模式 property has changed, need to update dns resource recordeINFO 监听到属性变更,触发 DNS 记录更新 无 DDNS client lease over %dDEBUG 租约到期,触发 DNS 记录更新 无 Set dns auto update success. update enable: %u, lease time: %u secondsNOTICE DNS 自动更新使能与租约时间设置成功 无
5. 问题定界指南 5.1 典型问题定界 现象描述 是否为本组件问题 判断依据 关键证据收集方法 BMC 无法通过域名解析 是 ddns 负责 resolv.conf 生成与 DNS 服务器配置,resolv.conf 损坏或 DNS 服务器配置错误均会导致解析失败 查看 /data/etc/resolv.conf 内容与权限;查看 /var/log/framework/ddns.log 中 Generate DNS config file failed 等错误 DNS 资源记录未自动更新 是 动态更新由 update_detection 模块负责,未更新可能是 feature_basic 关闭、UpdateEnable=false、租约未到期或 DNS 服务器不可达 通过 IPMI GetDnsRecordUpdateInfo 查询使能状态;查看日志中 property has changed / DDNS client lease over / socket_connect fail Redfish 设置 DNSAddressOrigin 返回失败 是 set_dns_addr_origin 在网络非 DHCP 模式时会抛出 StaticIPMode 异常 查看日志 Set DNS service mode to (%s) failed;确认 IPv4/IPv6 网络 IpMode 是否为 DHCP/DHCPv6 IPMI 设置 DNS 服务器返回 0x02 是 ManufactureId 不匹配或 Length 非 0/4/16 查看日志 Invalid manufacturer id 或 data len is invalid;核对 IPMI 报文 BMC IP 变化后域名解析仍指向旧 IP 否(DNS 服务器侧) ddns 已发送更新报文但 DNS 服务器未生效 抓取 BMC 到 DNS 服务器的 UDP 53 报文;查看 DNS 服务器侧记录 组件启动失败 是 systemd ddns.service 拉起失败,通常为依赖未就绪或配置错误 systemctl status ddns.service;查看日志 ddns service start 是否出现;检查依赖服务 dbus/framework/persistence/bmc_core
5.2 错误码速查表 组件内部错误码定义在 src/lualib/error.lua:
错误码 含义 可能原因 排查建议 0x00000000 (E_OK) 成功 - - 0x00000001 (E_INTERNAL_ERR) 内部错误 资源树对象获取失败、属性同步失败、DHCP 状态同步失败 查看 error 日志上下文 0x00000002 (E_INVALID_IP) IP 地址非法 输入既非合法 IPv4 也非合法 IPv6 检查 IP 格式 0x00000003 (E_NIL_PARAMETER) 参数为空 nameserver 或 value 为 nil 检查调用方是否传 nil 0x00000004 (E_OPEN_FILE_FAILED) 打开文件失败 resolv.conf 不存在或无权限 检查文件与权限 0x00000005 (E_PARAM_OUT_OF_RANGE) 参数越界 DHCPVersion、State、Origin 等参数取值非法 检查参数取值 0x00000006 (E_SOCKET_ERR) 套接字错误 socket 连接/发送/接收失败、worker 超时 检查 DNS 服务器可达性与网络
IPMI 完成码:
错误码 含义 可能原因 排查建议 0x00 (COMP_CODE_SUCCESS) 成功 - - 0x02 (COMP_CODE_INVALID_CMD) 命令非法 ManufactureId 不匹配、Data/Data1/Length 取值非法 核对报文厂商 ID 与参数 0x03 (COMP_CODE_SET_FAILED) 设置失败 底层 set_*_nameserver / set_dns_addr_origin 抛出异常 查看 ddns.log error 日志 0x07 (ReqDataLenInvalid) 请求长度非法 LeaseTime 长度非 0/4 或 Length 不匹配 核对 SetDnsRecordUpdateInfo 报文长度 0x09 (ParmOutOfRange) 参数越界 UpdateEnable 非 0/1 或 LeaseTime 超出 180~86400 核对参数取值 0x80 (InvalidFieldRequest) 字段非法 ManufactureId 不匹配 核对厂商 ID 0xFF (UnspecifiedError) 未指定错误 数据库 save 失败 查看 persistence 状态与日志
5.3 调试方法 开启调试日志 ddns 组件日志级别由 dist/config.cfg 与 libmc 框架配置控制。如需开启 DEBUG 级别日志:
修改 /opt/bmc/apps/ddns/config.cfg 或对应 libmc 配置中的日志级别为 DEBUG。 重启 ddns 服务:systemctl restart ddns.service。 查看日志:tail -f /var/log/framework/ddns.log。 复现问题方法 前置条件设置:BMC 已正常启动,ddns.service 处于 active 状态;已配置可达的 DNS 服务器。 操作步骤: 通过 Redfish 或 IPMI 修改 DNS 服务器地址 / DNSAddressOrigin / VLAN / 主机 IP 等属性。 或等待租约时间(默认 180s)到达。 预期现象:/var/log/framework/ddns.log 中出现 property has changed, need to update dns resource recorde 或 DDNS client lease over,随后向 DNS 服务器发送 SOA/查询/更新报文;DNS 服务器侧 BMC 对应的 A/AAAA/PTR 记录被刷新。 6. 常见问题解答 Q1:BMC 重启后 DNS 配置丢失 问题描述:BMC 重启后 /data/etc/resolv.conf 内容为空或被重置。 一句话答案:ddns 服务启动时会根据数据库 t_ddns_config 中的持久化配置重新生成 resolv.conf,正常情况下不会丢失。 根因说明:若数据库查询不到记录(日志出现 DNS config database is corrupted),组件会使用默认空值初始化并生成 resolv.conf;或 persistence 组件异常导致数据库未恢复。 解决方案:通过 Redfish/IPMI 重新设置 DNS 服务器地址;排查 persistence 组件状态。 规避方案:在装备阶段通过定制化配置预置 DNS 配置。 适用版本:全部版本。 Q2:设置了 DNSAddressOrigin 为 IPv4 但返回失败 问题描述:调用 SetDNSAddressOrigin("IPv4") 报错,操作日志记录 Set DNS service mode to (IPv4) failed。 一句话答案:当前 IPv4 网络未处于 DHCP 模式,组件拒绝切换。 根因说明:set_dns_addr_origin 在 Origin 为 IPv4 时会校验 acc_mdb.func.get_ip4_mode() == 'DHCP',否则抛出 StaticIPMode 异常。 解决方案:先将 BMC IPv4 网络切换为 DHCP 模式,再设置 DNSAddressOrigin 为 IPv4。 规避方案:使用 Static 模式手动配置 DNS 服务器。 适用版本:1.30.5 及以后。 Q3:IPMI SetDnsRecordUpdateInfo 命令不存在 问题描述:通过 IPMI 调用 SetDnsRecordUpdateInfo 时返回命令不支持。 一句话答案:当前构建版本在 package 阶段删除了 update_detection.lua,动态更新相关 IPMI 命令未注册。 根因说明:conanfile.py 当前逻辑为 feature_basic=True 时在 package 阶段删除 update_detection.lua(默认 feature_basic=False 时保留该文件)。被删除后运行期 pcall(require, 'update_detection') 失败,ddns_ipmi 中 if ok_update_detection then 分支不执行,GetDnsRecordUpdateInfo/SetDnsRecordUpdateInfo 不注册。该行为与 mds/service.json 中特性描述方向相反,使用前请以 conanfile.py 实际逻辑为准。 解决方案:使用 feature_basic=False(默认值)重新构建并部署组件以保留 update_detection.lua;如确实需要按 feature_basic=True 启用,请先与维护者确认 conanfile.py 的裁剪逻辑是否符合预期。 规避方案:如不需要动态更新 DNS 记录,可忽略此命令。 适用版本:1.130.2 及以后。 Q4:DNS 资源记录更新不生效 问题描述:BMC IP 变化后,DNS 服务器侧 A/AAAA 记录未更新。 一句话答案:可能是 UpdateEnable=false、租约未到期、DNS 服务器不可达或域名/主机名为空。 根因说明:update_detection 任务仅在 UpdateEnable=true 且(租约到期或属性变更标志为 true)时触发更新;handle_rr_packet 在 domain_is_invalid 时直接返回;socket 连接/发送失败会记录 socket_connect fail。 解决方案:通过 IPMI GetDnsRecordUpdateInfo 确认使能状态;查看日志确认触发条件与 socket 错误;确认 DNS 服务器可达且域名/主机名已配置。 规避方案:手动在 DNS 服务器上更新记录。 适用版本:1.0.0 及以后(feature_basic 启用时)。 Q5:resolv.conf 权限或属主异常 问题描述:/data/etc/resolv.conf 权限非 640 或属主非 secbox,导致其他进程无法读取或安全扫描告警。 一句话答案:ddns 生成 resolv.conf 时强制设置 640 权限,属主由启动脚本 S16DdnstInit.sh 设置为 secbox。 根因说明:resolv_conf_mgmt.generate_resolv_conf 写入后调用 utils_core.chmod_s 设置 640;S16DdnstInit.sh 在启动时 chown secbox:secbox 该文件。 解决方案:若权限异常,重启 ddns 服务触发重新生成;若属主异常,确认 S16DdnstInit.sh 已执行。 规避方案:手动 chmod 640 /data/etc/resolv.conf && chown secbox:secbox /data/etc/resolv.conf。 适用版本:1.60.5 及以后。 附录 附录A 参考资料 openUBMC 资源协作接口(MDB)开发指南 openUBMC bingo 工具使用指南 附录B 修订记录 版本 日期 修订人 修订内容 v1.0 2026-10-19 openUBMC 社区 初始版本创建,按组件文档模板重写