错误码
许可闸门的 403 错误码、激活接口的返回、status.json 里的 reason，以及安装和 Kerberos 层面常见的错误原文。
本页面向排查 IDMatrix 错误信息的管理员。IDMatrix 自身产生的错误只有三处：许可闸门、许可激活接口、受管主机数插件。其余都是 FreeIPA 和 Kerberos 的原生错误，这里只列排障时常见的。
许可闸门（JSON-RPC 403）
管理台和 ipa 命令行的每个写请求先经过闸门。被拒时返回 HTTP 403，响应体是标准 IPA 错误格式：
{"error": {"code": 4301, "name": "LicenseModuleLocked", "message": "许可证未授权此功能,操作被拒绝: dnszone_add"}, "result": null, "id": 0}| 错误码 | 含义 | 处理 |
|---|---|---|
4300 LicenseReadOnly | 许可无效（未激活、过期、指纹不符、吊销），所有写操作被拒 | 查看 status.json 的 reason，激活或重签 |
4301 LicenseModuleLocked | 许可有效，但 message 里的方法属于未授权模块 | 查看 mods；需要该模块则升档 |
只有写操作会被拒：方法名含 add、mod、del、remove、enable、disable、set、reset、stage、unstage、activate、deactivate、rename、import、revoke、retract、request、rebuild、run、approve、reject、restore。find 和 show 永远放行。batch 里任一子命令被拒，整个 batch 被拒。
FreeIPA 自身的服务主体（host/、ldap/、HTTP/ 等）不经过闸门。ipa-client-install 以 admin 身份执行，经过闸门，但 host_add 和 host_mod 不属于任何模块。两条规则都是 1.0.2 起。
闸门拒绝时不写 httpd 日志。grep LicenseModuleLocked /var/log/httpd/error_log 永远为 0。
许可激活接口
POST https://<FQDN>/ipa/modern-ui/license/install，body 是 .lic 原文。返回 {"ok": true, "status": {...}} 或 {"ok": false, "reason": "..."}。失败时现有许可不变。
| 错误码 | 含义 | 处理 |
|---|---|---|
许可证文件为空或过大 | body 为空，或超过 64 KB | 多为 curl --data-binary @<路径> 路径不对，读到空文件。使用绝对路径 |
许可证文件不是有效文本 | 不是 UTF-8 | 上传原始 .lic，不要转码 |
Offline license is bound to a different host | 指纹不符 | 换机、重装、克隆后重签 |
RSA-PSS signature verification failed | 签名不对 | 文件被修改过，或不是 Reallysec 签发。由发证方重发 |
License has expired | 已到期 | 续期重签 |
Unsupported license_type. Please request an updated license. | 许可格式比产品旧 | 重签 |
| 其他解析类错误 | 文件损坏，或拿到的不是离线 .lic | 重新下载；确认发证方给的是离线许可而不是在线 token |
status.json
/var/lib/idmatrix-license/status.json 由每日 timer 和每次激活写入。关键字段：
| 字段 | 含义 | 处理 |
|---|---|---|
valid | true 或 false，闸门的只读判据 | false 时看 reason |
degraded | true 表示许可有问题 | 看 reason |
reason | no license file at /var/lib/idmatrix-license/license.lic 是出厂态；License has expired；Offline license is bound to a different host；revoked or offline-grace expired 是在线模式被吊销或超过宽限期；IDMATRIX_LICENSE_TOKEN unset for online mode 是设了 SERVER 没设 TOKEN | 按原因激活、续期、重签或补齐环境变量 |
mods | 已授权模块数组，闸门的模块判据，导航按它隐藏 | 无 |
max_managed_hosts、current_hosts | 上限与当前数 | 接近上限时清理主机或扩容 |
expiry、days_left | 到期日与剩余天数，30 以内显示黄色横幅 | 到期前续期 |
fingerprint | 本机指纹，发证使用 | 无 |
license_id | LIC- 开头，与 Reallysec 对账使用 | 无 |
受管主机数
ipa host-add 超过上限时：
ipa: ERROR: 已达授权受管主机数上限 (100 台)。如需新增主机,请联系您的授权服务商。该错误由服务端插件产生，不经过闸门，因此是普通 ExecutionError 而不是 403。ipa host-find --sizelimit=0 | tail -1 查看当前数量。删除不用的主机对象可以腾出名额。
安装
日志在 /var/log/ipaserver-install.log 和 /var/log/ipareplica-install.log。
| 错误信息 | 含义 | 处理 |
|---|---|---|
Unable to resolve host name、hostname resolves to localhost | IPA_HOSTNAME 解析不通，或解析到 127.0.0.1 或 ::1 | 修正 DNS 或 /etc/hosts |
DNS server <IP> ... not responding | IPA_FORWARDERS 不可达 | 改成可达的转发器 |
DNS server <IP> does not support DNSSEC | 上游不签 DNSSEC，安装程序自动关闭校验 | 无，可忽略 |
IPA server is already configured on this system | 上次没有卸载干净 | ipa-server-install --uninstall -U |
FileNotFoundError: /etc/httpd/conf.d/ssl.conf | 缺 mod_ssl | dnf install mod_ssl |
ipa-getkeytab ... Failed to add key to the keytab（exit 11） | /var/lib/ipa/gssproxy/ 目录不存在，系统被清理过 | rpm -Va --nofiledigest | grep ^missing，dnf reinstall 对应的包 |
FileNotFoundError: /var/log/pki/pki-ca-spawn.*.log | /var/log/pki 不存在，原因同上 | 同上 |
certmonger request is in state 'CA_UNREACHABLE' | replica 安装时第一台的许可缺证书签发模块（1.0.2 前） | 升级或重签 |
Replica DNS records could not be added on master: Insufficient access | 安装中途的 ACI 时序，replica 自己的 DNS 阶段会补记录 | 安装后核对 DNS 记录 |
Replication topology in suffix 'domain' is disconnected | 卸载 replica 时的拓扑检查 | 加 --ignore-topology-disconnect |
Kerberos 与目录
| 错误信息 | 含义 | 处理 |
|---|---|---|
Clock skew too great、KRB5KDC_ERR_SKEW | 时差超过 5 分钟 | 对时 |
Cannot contact any KDC for realm | 客户端找不到 KDC：DNS SRV 不通，或 KDC 没有启动 | 客户端执行 dig +short _kerberos._tcp.<域> SRV；服务端 ipactl status |
Server not found in Kerberos database | 服务主体不存在，通常是主机名不匹配 | 核对主机名与服务主体 |
Keytab contains no suitable keys for <principal> | 用错 keytab，或 keytab 里的主体是别的主机 | 在目标主机重新执行 ipa-getkeytab |
ldap_bind: Invalid credentials (49) 且 DS 日志 gss_accept_sec_context | 服务端解不开票据：新主机缺 crypto-policies，KDC 签发了 camellia 票据 | 见添加第二台 |
ldap_bind: Server is unwilling to perform (53) Unauthenticated binds are not allowed | 空口令绑定被拒，属正常防护 | 无 |
Error (4) ... Unable to parse the response to the startReplication extended operation | 复制协议解码失败，通常伴随僵尸 RUV | cleanallruv |
Didn't connect to LDAP on startup: 110、while fetching master key K/M | KDC 在目录服务启动之前启动 | ipactl restart |
WERR_CONNECTION_REFUSED | trust-add 使用了双向信任 | 改单向，不加 --two-way |