Error codes
The licence gate's 403 codes, activation endpoint responses, reason values in status.json, and the verbatim install and Kerberos errors you will meet.
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 | name | Meaning | Fix |
|---|---|---|---|
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 / restore. find / show always pass. If any sub-command in a batch is refused, the whole batch is.
FreeIPA's own service principals (host/, ldap/, HTTP/…) bypass the gate. ipa-client-install runs as admin and passes through it, but host_add / host_mod belong to no module. Both 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. Returns {"ok": true, "status": {...}} or {"ok": false, "reason": "..."}. On failure the current licence is left untouched.
| reason | Meaning | Fix |
|---|---|---|
许可证文件为空或过大 (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 |
Offline license is missing its host binding (bound_fingerprint) | Not an offline licence | An online token was sent, or the file is corrupt |
RSA-PSS signature verification failed | Bad signature | File altered, or not signed by Reallysec |
License has expired | Expired | Renew |
Unsupported license_type. Please request an updated license. | Licence format older than the product | Reissue |
token must be 'base64.base64' / payload is not valid JSON | Corrupt file | Download again |
status.json
/var/lib/idmatrix-license/status.json, written by the daily timer and by every activation. Key fields:
| Field | Value |
|---|---|
valid | true / false. The gate's read-only criterion |
degraded | When true, read reason |
reason | no license file at /var/lib/idmatrix-license/license.lic: factory state; License has expired; Offline license is bound to a different host; revoked or offline-grace expired: revoked in online mode or past the grace period; IDMATRIX_LICENSE_TOKEN unset for online mode: SERVER set without TOKEN |
mods | Licensed module list. The gate's module criterion; navigation hides by it |
max_managed_hosts / current_hosts | Cap and current count |
expiry / days_left | Expiry date and days remaining; yellow banner under 30 |
fingerprint | This host's fingerprint, used for issuance |
license_id | Starts with LIC-; reference when contacting Reallysec |
Managed host cap
ipa host-add beyond the cap:
ipa: ERROR: 已达授权受管主机数上限 (100 台)。如需新增主机,请联系您的授权服务商。(“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
/var/log/ipaserver-install.log and /var/log/ipareplica-install.log.
| Text | Meaning |
|---|---|
Unable to resolve host name / hostname resolves to localhost | IPA_HOSTNAME does not resolve, or resolves to 127.0.0.1 / ::1 |
DNS server <IP> ... not responding | IPA_FORWARDERS unreachable |
DNS server <IP> does not support DNSSEC | Upstream does not sign; validation is disabled automatically, 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 |
ipa-getkeytab ... Failed to add key to the keytab (exit 11) | /var/lib/ipa/gssproxy/ does not exist; the system was cleaned by hand |
FileNotFoundError: /var/log/pki/pki-ca-spawn.*.log | /var/log/pki does not exist; same cause |
certmonger request is in state 'CA_UNREACHABLE' | During a replica install, the first server's licence lacked certificate issuance (before 1.0.2) |
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 afterwards |
Replication topology in suffix 'domain' is disconnected | Topology check on replica uninstall; add --ignore-topology-disconnect |
Kerberos and directory
| Text | Meaning |
|---|---|
Clock skew too great / KRB5KDC_ERR_SKEW | More than 5 minutes apart |
Cannot contact any KDC for realm | Client cannot find a KDC: DNS SRV broken, or the KDC is down |
Server not found in Kerberos database | Service principal does not exist; usually a hostname mismatch |
Keytab contains no suitable keys for <principal> | Wrong keytab, or it holds another host's principal |
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 |
ldap_bind: Server is unwilling to perform (53) Unauthenticated binds are not allowed | Empty-password bind refused; correct behaviour |
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 |