代码仓
中
更新时间: 2026/11/14
在AtomGit上查看源码

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 关键术语表(可选) ​

术语解释
DDNSDynamic Domain Name System,IP/域名变化时自动更新 DNS 记录的机制
RRResource Record,DNS 资源记录,本组件涉及 A、AAAA、A6、PTR、SOA 等类型
DNSAddressOriginDNS 服务器地址来源模式,取值为 Static(手动)/ IPv4(DHCPv4 自动)/ IPv6(DHCPv6 自动)
ServerIpVersionDNS 绑定的 IP 协议版本,取值为 IPv4 或 IPv6
LeaseTimeSecondsDDNS 记录更新租约时间(秒),默认 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 服务器地址。

限制条件 ​

  • 调用者需具备 BasicSetting 写权限。

调试示例 ​

命令行调试 ​
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 服务器地址。

限制条件 ​

  • 调用者需具备 BasicSetting 写权限。

调试示例 ​

命令行调试 ​
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 表示 DHCPv6UseDNSServers0 / 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 服务器地址。

限制条件 ​

  • 调用者需具备 BasicSetting 写权限。

调试示例 ​

命令行调试 ​
bash
# 使能 DHCPv4 自动获取 DNS(busctl 签名 qy:U16 DHCPVersion + U8 State)
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输入StringDNS 服务器来源"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)厂商 ID0x0007db
SubCmd输入U8子命令0x05
ParameterSelector输入U8参数选择器0x04
Reserved输入U8(7b)保留字段0
Cascade输入U8(1b)级联标志0/1
Offset输入U8偏移量0
Length输入U8IpAddress 长度0 / 4 / 16
IpAddress输入StringIP 地址原始字节长度等于 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_ip> -U <user> -P <pass> 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输入U8DNS 来源选择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)厂商 ID0x0007db
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输入U16LeaseTime 长度 + 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

验证方法 ​

  1. 执行 bingo build 构建组件并部署到 BMC。
  2. 通过 busctl --user introspect bmc.kepler.ddns /bmc/kepler/Managers/1/EthernetInterfaces/DNS 查看新方法是否暴露。
  3. 调用新方法并查看 /var/log/framework/ddns.log 中的 operation 日志与数据库 t_ddns_config 是否更新。
  4. 预期结果:方法调用返回 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.logddns 组件运行期日志,包含启动、配置变更、IPMI 操作、动态更新、错误等信息(由 dist/config.cfg 中 logger 配置)

4.2 关键日志信息 ​

日志片段日志级别含义解读建议处理动作
ddns service startINFOddns 服务启动无
ddns service exitINFOddns 服务退出若非主动重启,检查是否被 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%xERRORIPMI 命令 ManufactureId 不等于 0x0007db检查 IPMI 报文厂商 ID
Set primary DNS server to (%s) successfullyOPERATION主 DNS 服务器设置成功无
Set DNS service mode to (%s) failedOPERATIONDNS 地址来源模式设置失败结合 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 secondsNOTICEDNS 自动更新使能与租约时间设置成功无

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 级别日志:

  1. 修改 /opt/bmc/apps/ddns/config.cfg 或对应 libmc 配置中的日志级别为 DEBUG。
  2. 重启 ddns 服务:systemctl restart ddns.service。
  3. 查看日志:tail -f /var/log/framework/ddns.log。

复现问题方法 ​

  1. 前置条件设置:BMC 已正常启动,ddns.service 处于 active 状态;已配置可达的 DNS 服务器。
  2. 操作步骤:
    • 通过 Redfish 或 IPMI 修改 DNS 服务器地址 / DNSAddressOrigin / VLAN / 主机 IP 等属性。
    • 或等待租约时间(默认 180s)到达。
  3. 预期现象:/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.02026-10-19openUBMC 社区初始版本创建,按组件文档模板重写