bmc_time ​

版本信息 ​

1. 组件概述 ​

1.1 组件简介 ​

bmc_time 是 openUBMC 中负责 BMC 时间管理的组件，提供系统时间管理、NTP 时间同步、时区/夏令时管理、RTC 时间维护以及 NTP 身份认证组密钥管理等能力。它通过北向资源协作接口接收 Web/CLI/Redfish/IPMI 的时间相关命令，统一调度系统时间、RTC（SMC 芯片）和 NTP（ntpd 客户端）三者之间的时间同步关系。

bmc_time 组件在系统中的定位：

• 统一的时间管理中枢，屏蔽不同硬件平台 RTC 芯片寄存器与 NTP 实现的差异；
• 保证 BMC 系统时间、RTC 时间、NTP 服务器时间的一致性；
• 通过持久化保证掉电后时间不丢失，通过时间跳变检测与同步结果上报提升可观测性。

1.2 解决什么问题 ​

• 时间一致性：统一管理系统时间、RTC、NTP 三种时间源，避免时间源之间互相覆盖；
• 掉电保持：将时间持久化保存，BMC 重启后从持久化数据或 RTC 恢复时间；
• 自动校时：通过 NTP 客户端周期同步服务器时间，支持静态/DHCP 两种服务器获取模式；
• 时区正确性：支持城市时区与 UTC 偏移两种配置方式，支持夏令时开关；
• 安全校时：支持 NTP 身份认证组密钥导入，并在主备板之间同步，防止非法时间服务器篡改；
• 配置迁移：支持 NTP、时区等敏感配置的周期导出/变更导出/导入，便于批量部署。

1.3 核心功能 ​

• 系统时间管理：设置/查询系统时间，时间跳变检测（TimeHoppingThreshold），同步状态上报；
• RTC 时间维护：从 RTC 周期同步系统时间，支持 SMC 芯片读写偏移/长度/格式定制，NTP 同步失败可切换 RTC；
• NTP 时间同步：支持首选/备选/扩展服务器、轮询间隔配置、静态与 DHCP（IPv4/IPv6）模式；
• 时区与夏令时管理：城市时区（如 Asia/Shanghai）与 UTC 偏移（如 +08:00）双模式，DST 开关；
• NTP 身份认证：NTP 组密钥导入（同步/异步）、组密钥状态上报、主备板组密钥同步（DataSync）；
• 敏感配置导入导出：NTP/时区等配置的周期导出、变更导出与导入；
• IPMI 支持：SEL 时间、SDR 仓库时间、NTP OEM 命令；
• 持久化：时间戳、时区、NTP 等配置掉电保存。

1.4 关键术语表 ​

1.5 外部交互边界图 ​

2. API 使用说明与示例 ​

2.1 SetDateTime 设置系统时间 ​

NAME                                TYPE      SIGNATURE             RESULT/VALUE           FLAGS
.SetDateTime                        method    a{ss}a{ss}            -                      -

功能说明 ​

设置 BMC 系统时间，支持同时设置日期时间与时区/偏移。北向设置时间的命令最终都汇聚到该接口。

参数说明 ​

返回值与异常 ​

该方法无返回值，执行结果通过 D-Bus 异常（Error）上报：调用成功时无返回内容；执行失败时抛出如下异常。

应用场景 ​

• Web/CLI/Redfish 手动设置系统时间；
• IPMI SetSelTime / SetSDRRepoTime 命令的内部实现通道。

限制条件 ​

• 需要 BasicSetting 及以上权限；
• 设置时间将同步更新 RTC 时间；
• 时间参数须通过时间戳格式校验，非法日期时间会返回失败。

调试示例 ​

busctl --user call bmc.kepler.bmc_time /bmc/kepler/Managers/Time_Bmc_010101 \
    bmc.kepler.Managers.Time SetDateTime a{ss}a{ss} \
    0 3 TimeZone 'UTC+08:00' TimeStamp '1786154400' DSTEnable 'false'

2.2 SetRtcTime 设置 RTC 时间 ​

NAME                             TYPE          SIGNATURE             RESULT/VALUE           FLAGS
.SetRtcTime                      method     a{ss}t                   -                      -

功能说明 ​

通过时间戳直接设置 RTC 芯片时间，并同步更新系统时间。

参数说明 ​

返回值与异常 ​

该方法无返回值，执行结果通过 D-Bus 异常（Error）上报：调用成功时无返回内容；执行失败时抛出如下异常。

应用场景 ​

• 主板与备板 RTC 时间同步；
• 备板升主板后同步 RTC 时间。

限制条件 ​

• 需要 BasicSetting 及以上权限；
• RTC 读写依赖 CSR 中 CpuBrdRtc 引用的 BlockIO 配置。

调试示例 ​

busctl --user call bmc.kepler.bmc_time /bmc/kepler/Managers/Time_Bmc_010101 \
    bmc.kepler.Managers.Time SetRtcTime a{ss}t 0 1769940000

2.3 SetPollingInterval 设置 NTP 轮询间隔 ​

NAME                                TYPE      SIGNATURE             RESULT/VALUE           FLAGS
.SetPollingInterval                 method    a{ss}yy               -                      -

功能说明 ​

设置 NTP 最小/最大轮询间隔，控制 BMC 向 NTP 服务器请求时间的频率。

参数说明 ​

返回值与异常 ​

该方法无返回值，执行结果通过 D-Bus 异常（Error）上报：调用成功时无返回内容；执行失败时抛出如下异常。

说明：MinPoll/MaxPoll 传 0xFF 表示使用默认值（MinPoll=6、MaxPoll=10），不视为非法参数。

应用场景 ​

• 通过 Web/CLI 调整 NTP 同步频率。

限制条件 ​

• 需要 BasicSetting 及以上权限；
• 默认 MinPoll=6（64 秒）、MaxPoll=10（1024 秒）。

调试示例 ​

busctl --user call bmc.kepler.bmc_time /bmc/kepler/Managers/Time_Bmc_010101 \
    bmc.kepler.Managers.Ntp SetPollingInterval a{ss}yy 0 6 10

2.4 SetNtpExtraServers 设置扩展 NTP 服务器 ​

NAME                                TYPE      SIGNATURE             RESULT/VALUE           FLAGS
.SetNtpExtraServers                 method    a{ss}yas              -                      -

功能说明 ​

批量设置扩展 NTP 服务器列表，用于在首选/备选服务器之外补充更多时间源。

参数说明 ​

返回值与异常 ​

该方法无返回值，执行结果通过 D-Bus 异常（Error）上报：调用成功时无返回内容；执行失败时抛出如下异常。

应用场景 ​

• 配置多个 NTP 服务器以提升同步可靠性。

限制条件 ​

• 需要 BasicSetting 及以上权限。

调试示例 ​

busctl --user call bmc.kepler.bmc_time /bmc/kepler/Managers/Time_Bmc_010101 \
    bmc.kepler.Managers.Ntp SetNtpExtraServers a{ss}yas 0 3 1 192.168.1.10

2.5 ImportGroupKey 导入 NTP 组密钥 ​

NAME                                TYPE      SIGNATURE             RESULT/VALUE           FLAGS
.ImportGroupKey                     method    a{ss}s                -                      -

功能说明 ​

通过文件路径导入 NTP 身份认证组密钥，用于校验 NTP 服务器身份，防止非法服务器篡改时间。

参数说明 ​

返回值与异常 ​

该方法无返回值，导入结果通过 D-Bus 错误机制上报：无论成功或失败，都会返回一个结果错误对象，调用方需根据结果对象判断导入结果。

应用场景 ​

• 使能 NTP 身份认证前导入组密钥。

限制条件 ​

• 需要 BasicSetting 及以上权限；
• 导入后组密钥文件写入受保护目录，需具备相应权限。

调试示例 ​

busctl --user call bmc.kepler.bmc_time /bmc/kepler/Managers/Time_Bmc_010101 \
    bmc.kepler.Managers.Ntp.Auth ImportGroupKey a{ss}s 0 /data/trust/ntp/group.key

2.6 ImportGroupKeyWithContent 通过内容导入 NTP 组密钥 ​

NAME                                TYPE      SIGNATURE             RESULT/VALUE           FLAGS
.ImportGroupKeyWithContent          method    a{ss}s                -                      -

功能说明 ​

直接以密钥文本内容导入 NTP 组密钥，无需事先上传文件。

参数说明 ​

返回值与异常 ​

该方法无返回值，导入结果通过 D-Bus 错误机制上报：无论成功或失败，都会返回一个结果错误对象，调用方需根据结果对象判断导入结果。

说明：跨板同步（skip_auto_export）场景下该方法返回 (状态, 是否变更) 二元组，非跨板场景无返回值。

应用场景 ​

• Web/CLI 直接粘贴密钥内容导入，免去文件上传流程。

限制条件 ​

• 需要 BasicSetting 及以上权限。

调试示例 ​

busctl --user call bmc.kepler.bmc_time /bmc/kepler/Managers/Time_Bmc_010101 \
    bmc.kepler.Managers.Ntp.Auth ImportGroupKeyWithContent a{ss}s 0 "1 MD5 d41d8cd98f00b204e9800998ecf8427e"

2.7 ImportGroupKeyAsync 异步导入 NTP 组密钥 ​

NAME                                TYPE      SIGNATURE             RESULT/VALUE           FLAGS
.ImportGroupKeyAsync                method    a{ss}s                u                      -

功能说明 ​

异步导入 NTP 组密钥，适用于大文件或需跨板同步的场景，导入任务通过 TaskService 跟踪进度。

参数说明 ​

返回值与异常 ​

该方法返回导入任务 ID（u32）。任务创建成功后立即返回 TaskId，任务执行结果需通过 TaskService 查询；任务创建失败时抛出如下异常。

应用场景 ​

• 大密钥文件导入，避免同步调用阻塞；
• 主备板组密钥同步场景。

限制条件 ​

• 需要 BasicSetting 及以上权限。

调试示例 ​

busctl --user call bmc.kepler.bmc_time /bmc/kepler/Managers/Time_Bmc_010101 \
    bmc.kepler.Managers.Ntp.Auth ImportGroupKeyAsync a{ss}s 0 /data/trust/ntp/group.key

2.8 SetDestination 敏感配置导入导出 ​

NAME                                TYPE      SIGNATURE             RESULT/VALUE           FLAGS
.SetDestination                     method    a{ss}ssss             -                      -

功能说明 ​

对 NTP、时区等敏感配置提供导入、周期导出、变更导出能力，支持跨板/批量部署时同步配置。

参数说明 ​

返回值与异常 ​

该方法无返回值，不抛出 D-Bus 异常。设置目标成功后写入 DestinationService/DestinationPath/DestinationInterface/DestinationMethod 属性；目标对象或接口不存在时返回 -1，但因接口无返回类型，调用方无感知，建议通过读取上述属性确认配置结果。

应用场景 ​

• 主备板 NTP 组密钥/时区配置自动同步；
• 批量部署时统一导入时间配置。

限制条件 ​

• 需要 BasicSetting 及以上权限；
• PeriodSec 取值范围 5-86400 秒。

调试示例 ​

busctl --user call bmc.kepler.bmc_time /bmc/kepler/Managers/Time_Bmc_010101 \
    bmc.kepler.Managers.SensitiveConfigurations SetDestination a{ss}ssss \
    0 bmc.kepler.bmc_time /bmc/kepler/Managers/Time_Bmc_010101 bmc.kepler.Managers.Ntp.Auth Import

3. 组件扩展案例 ​

3.1 扩展能力概述 ​

bmc_time 组件支持以下扩展能力：

• CSR 配置定制：通过 CSR 配置 RTC 芯片读写偏移（Offset/WriteOffset）、读取长度（Size）、年差值（YearOffset）、读取格式（EffOffset）等，无需改代码适配不同 SMC RTC 芯片；
• 时间同步策略可配：TimeHoppingThreshold 时间跳变门限、TimeSynchronizationPolicy 同步失败告警策略、NotRecordSel 是否记录 SEL、SwitchRtcOnNtp 是否在 NTP 失败时切换 RTC；
• 敏感配置导出目标可配：通过 SetDestination 配置导出目标服务/路径/接口/方法，支持周期导出与变更导出。

3.2 扩展点说明 ​

3.3 二次开发指导 ​

步骤一：配置 CSR 适配 RTC 芯片 ​

为 Time 对象配置 CpuBrdRtc 引用的 BlockIO 通道及 Offset/WriteOffset/Size/YearOffset/EffOffset 参数。

步骤二：配置时间同步策略 ​

配置 NotRecordSel、SwitchRtcOnNtp 等属性。

示例代码 ​

"Time_Bmc": {
    "Id": "${Slot}",
    "CpuBrdRtc": "#/CpldChip_1",
    "IsValid": true,
    "RtcSupported": true,
    "Offset": 64,
    "Size": 8,
    "YearOffset": 0,
    "EffOffset": 0,
    "NotRecordSel": true
}

"TimeSynchronization_0": {
    "SwitchRtcOnNtp": true
}

验证方法 ​

1. 编译并部署组件；
2. 通过 busctl 调用时间接口；
3. 观察 DateTime 属性、RTC 时间与日志是否符合预期。

注意事项 ​

• 修改 CSR 属性后需重启组件生效；
• RTC 芯片参数需与硬件手册一致，避免读写越界；
• 时间跳变门限不宜过小，避免正常校时被误判为跳变。

4. 日志说明 ​

4.1 一键日志收集 ​

执行系统一键日志收集功能时，会自动收集 bmc_time 组件的运行日志：

4.2 关键日志信息 ​

5. 问题定界指南 ​

5.1 典型问题定界 ​

5.2 错误码速查表 ​

5.3 调试方法 ​

开启调试日志 ​

通过调整日志级别（notice/info/debug）可查看时间设置与 NTP 同步的详细流程。

复现问题方法 ​

1. 前置条件设置：配置 NTP 服务器或 RTC 芯片 CSR；
2. 操作步骤：通过 busctl 或 IPMI 调用时间接口；
3. 预期现象：DateTime/时间戳按预期变化，日志无 ERROR。

6. 常见问题解答 ​

Q1：NTP 时间不同步如何处理？ ​

• 问题描述：BMC 时间与 NTP 服务器时间不一致
• 一句话答案：检查 NTP 使能、服务器可达性与轮询间隔配置
• 根因说明：NTP 未开启、服务器不可达、或同步失败连续计数导致暂停
• 解决方案：确认 Enabled=true、服务器地址正确且网络可达，必要时调整 MinPoll/MaxPoll
• 规避方案：无
• 适用版本：所有版本
• 相关文档链接：无

Q2：设置系统时间后重启又跳回旧时间？ ​

• 问题描述：手动设置时间后重启 BMC，时间恢复为旧值
• 一句话答案：持久化或 RTC 同步异常导致时间未保存
• 根因说明：时间戳持久化失败，或 RTC 芯片读写异常
• 解决方案：检查持久化日志与 RTC 芯片链路，必要时重新设置并确认 DateTime 属性
• 规避方案：无
• 适用版本：所有版本
• 相关文档链接：无

Q3：时区/夏令时设置不生效？ ​

• 问题描述：修改 TimeZoneName 或 DSTEnabled 后本地时间显示不正确
• 一句话答案：检查时区名合法性与时区链接文件生效情况
• 根因说明：时区名非法、时区链接文件未更新或 DST 配置与地区不匹配
• 解决方案：使用合法时区名（如 Asia/Shanghai）或 ±HH:MM 偏移，确认 DSTEnabled 正确
• 规避方案：无
• 适用版本：所有版本
• 相关文档链接：无

Q4：RTC 时间与系统时间不一致？ ​

• 问题描述：RTC 时间与 BMC 系统时间存在偏差
• 一句话答案：检查 RTC 芯片读写参数与同步策略
• 根因说明：CSR 中 Offset/Size 等参数与芯片不符，或 NTP/RTC 切换策略未按预期执行
• 解决方案：核对 CSR 芯片参数，确认 SwitchRtcOnNtp 等策略配置
• 规避方案：无
• 适用版本：所有版本
• 相关文档链接：无长度

Q5：NTP 组密钥导入失败？ ​

• 问题描述：导入 NTP 组密钥返回失败
• 一句话答案：检查文件路径、密钥格式与目录权限
• 根因说明：文件不存在、密钥格式非法或目标目录权限不足
• 解决方案：确认文件路径正确、密钥格式合法，必要时改用 ImportGroupKeyWithContent
• 规避方案：无
• 适用版本：所有版本
• 相关文档链接：无

附录 ​

附录A 参考资料 ​

• 时间管理问题手册
• 时间同步机制及相关标识说明
• RTC时间同步报错问题分析

附录B 修订记录 ​