Error codes
The licence gate's 403 codes, activation endpoint responses, reason values in status.json, and the verbatim install and Kerberos errors met in practice.
This page is for administrators looking up an IDMatrix error message. IDMatrix itself produces errors in three places: the licence gate, the activation endpoint and the managed-host plugin. Everything else is native FreeIPA or Kerberos; only the ones that matter in troubleshooting are listed.
Licence gate (JSON-RPC 403)
Every write from the console or the ipa CLI passes the gate. A refusal is HTTP 403 with a standard IPA error body:
{"error": {"code": 4301, "name": "LicenseModuleLocked", "message": "..."}, "result": null, "id": 0}| Code | Meaning | Remedy |
|---|---|---|
4300 LicenseReadOnly | Licence invalid (not activated, expired, fingerprint mismatch, revoked); all writes refused | Read reason in status.json; activate or reissue |
4301 LicenseModuleLocked | Licence valid, but the method named in message belongs to an unlicensed module | Check mods; upgrade the tier to use it |
Only writes are refused: method names containing add, mod, del, remove, enable, disable, set, reset, stage, unstage, activate, deactivate, rename, import, revoke, retract, request, rebuild, run, approve, reject or restore. find and show always pass. If any sub-command in a batch is refused, the whole batch is.
FreeIPA's own service principals (host/, ldap/, HTTP/ and so on) bypass the gate. ipa-client-install runs as admin and passes through it, but host_add and host_mod belong to no module. Both rules apply from 1.0.2.
Refusals are not logged by httpd. grep LicenseModuleLocked /var/log/httpd/error_log is always 0.
Activation endpoint
POST https://<FQDN>/ipa/modern-ui/license/install, body is the raw .lic. It returns {"ok": true, "status": {...}} or {"ok": false, "reason": "..."}. On failure the current licence is left untouched.
| Code | Meaning | Remedy |
|---|---|---|
许可证文件为空或过大 (file empty or too large) | Empty body, or over 64 KB | Usually a wrong path after curl --data-binary @, sending an empty file. Use an absolute path |
许可证文件不是有效文本 (not valid text) | Not UTF-8 | Send the raw .lic; do not transcode |
Offline license is bound to a different host | Fingerprint mismatch | Reissue after a machine change, reinstall or clone |
RSA-PSS signature verification failed | Bad signature | File altered, or not signed by Reallysec. The issuer resends |
License has expired | Expired | Renew |
Unsupported license_type. Please request an updated license. | Licence format older than the product | Reissue |
| Other parse errors | Corrupt file, or not an offline .lic | Download again; confirm the issuer sent an offline licence rather than an online token |
status.json
/var/lib/idmatrix-license/status.json is written by the daily timer and by every activation. Key fields:
| Field | Meaning | Remedy |
|---|---|---|
valid | true or false; the gate's read-only criterion | When false, read reason |
degraded | true means the licence has a problem | Read reason |
reason | no license file at /var/lib/idmatrix-license/license.lic is the factory state; License has expired; Offline license is bound to a different host; revoked or offline-grace expired is revoked in online mode or past the grace period; IDMATRIX_LICENSE_TOKEN unset for online mode is SERVER set without TOKEN | Activate, renew, reissue or complete the environment variables, per the reason |
mods | Licensed module list; the gate's module criterion, and navigation hides by it | None |
max_managed_hosts, current_hosts | Cap and current count | Near the cap, remove hosts or reissue with a higher cap |
expiry, days_left | Expiry date and days remaining; yellow banner under 30 | Renew before expiry |
fingerprint | This host's fingerprint, used for issuance | None |
license_id | Starts with LIC-; reference when contacting Reallysec | None |
Managed host cap
ipa host-add beyond the cap:
ipa: ERROR: 已达授权受管主机数上限 (100 台)。如需新增主机,请联系您的授权服务商。The message reads: managed host limit reached (100 hosts); contact your licence provider to add hosts.
The server plugin refuses it, not the gate, so it is a plain ExecutionError rather than a 403. ipa host-find --sizelimit=0 | tail -1 shows the current count. Deleting unused host objects frees capacity.
Install
Logs are in /var/log/ipaserver-install.log and /var/log/ipareplica-install.log.
| Message | Meaning | Remedy |
|---|---|---|
Unable to resolve host name, hostname resolves to localhost | IPA_HOSTNAME does not resolve, or resolves to 127.0.0.1 or ::1 | Fix DNS or /etc/hosts |
DNS server <IP> ... not responding | IPA_FORWARDERS unreachable | Point at a reachable forwarder |
DNS server <IP> does not support DNSSEC | Upstream does not sign; validation is disabled automatically | None; ignore |
IPA server is already configured on this system | Previous install not removed | ipa-server-install --uninstall -U |
FileNotFoundError: /etc/httpd/conf.d/ssl.conf | mod_ssl missing | dnf install mod_ssl |
ipa-getkeytab ... Failed to add key to the keytab (exit 11) | /var/lib/ipa/gssproxy/ does not exist; the system was cleaned by hand | rpm -Va --nofiledigest | grep ^missing, then dnf reinstall the owning packages |
FileNotFoundError: /var/log/pki/pki-ca-spawn.*.log | /var/log/pki does not exist; same cause | As above |
certmonger request is in state 'CA_UNREACHABLE' | During a replica install, the first server's licence lacked certificate issuance (before 1.0.2) | Upgrade or reissue |
Replica DNS records could not be added on master: Insufficient access | ACI timing during install; the replica's own DNS stage adds the record | Verify the DNS records afterwards |
Replication topology in suffix 'domain' is disconnected | Topology check on replica uninstall | Add --ignore-topology-disconnect |
Kerberos and directory
| Message | Meaning | Remedy |
|---|---|---|
Clock skew too great, KRB5KDC_ERR_SKEW | More than 5 minutes apart | Sync time |
Cannot contact any KDC for realm | Client cannot find a KDC: DNS SRV broken, or the KDC is down | On the client dig +short _kerberos._tcp.<domain> SRV; on the server ipactl status |
Server not found in Kerberos database | Service principal does not exist; usually a hostname mismatch | Compare the hostname with the service principal |
Keytab contains no suitable keys for <principal> | Wrong keytab, or it holds another host's principal | Rerun ipa-getkeytab on the target host |
ldap_bind: Invalid credentials (49) with gss_accept_sec_context in the DS log | The server cannot decrypt the ticket: the new host lacks crypto-policies and its KDC signed with camellia | See Adding a second server |
ldap_bind: Server is unwilling to perform (53) Unauthenticated binds are not allowed | Empty-password bind refused; correct behaviour | None |
Error (4) ... Unable to parse the response to the startReplication extended operation | Replication protocol decode failure, usually with a zombie RUV | cleanallruv |
Didn't connect to LDAP on startup: 110, while fetching master key K/M | The KDC started before the directory | ipactl restart |
WERR_CONNECTION_REFUSED | trust-add with a two-way trust | Use one-way; drop --two-way |