FAQ

Find the cause by symptom, grouped by install, login, AD trust, licence, clients and replication. Most problems are DNS or time.

Three commands locate most problems:

sudo ipactl status                                  # which service is down
chronyc tracking                                    # clock offset
getent hosts $(hostname -f); dig +short -x <own IP>  # forward and reverse resolution

Install

Symptom	Cause	Fix
`ipa-server-install` says the hostname is unresolvable or loopback	`IPA_HOSTNAME` has no forward / reverse record, or `/etc/hosts` puts it on the `127.0.0.1` / `::1` line	Fix DNS or `/etc/hosts` to the real IP; remove `myhostname` from `nsswitch.conf`
Fails at DNS forwarder validation	`IPA_FORWARDERS` unreachable, or `IPA_AUTO_FORWARDERS=true` picked a dead address from `resolv.conf`	Pick one of the three layouts in the quick start
Time-related task `FAILED`	Bare metal with `IPA_NO_NTP=true` and no external time source	`IPA_NO_NTP=false`
`setup_dns` sub-options rejected	DNS sub-options passed with `IPA_SETUP_DNS=false`	Use the bundled `render-inventory.sh`; it neutralises them
Collection version mismatch	Control node ansible-core differs from the packaging version	Use the bundled `collections/`, run `ansible-galaxy collection install -r requirements.yml` inside it
ansible ping fails	ssh user lacks `NOPASSWD` sudo, or wrong key	Test with `ansible -i deploy/inventory.generated.yml all -m ping`
Rerun hangs in `ipa-server-install`	Previous attempt not cleaned	`ipa-server-install --uninstall -U` first; see Deploy
`configuring mod_ssl` says `ssl.conf` is missing	`mod_ssl` not installed	`dnf install mod_ssl`; the bundled repo has it
httpd keytab or pkispawn complains a directory is missing	Target not clean; `/var/lib/ipa/gssproxy`, `/var/log/pki` etc. were deleted	`rpm -Va --nofiledigest \| grep ^missing`, `dnf reinstall` the owners
Check 5 (write before activation) is not refused	Licence gate inactive	`WSGIScriptAlias /ipa` in `/etc/httpd/conf.d/ipa.conf` must point at `/opt/idmatrix-license/gate_wsgi.py`; `status.json` must be readable

Symptom	Cause	Fix
Browser distrusts the certificate	Factory certificate from the built-in IPA CA	Expected. Import `/etc/ipa/ca.crt` into the browser trust store, or replace with a customer CA certificate
`ERR_CERT_AUTHORITY_INVALID`, cannot proceed	IP address in the URL	Use the FQDN
Console unreachable	443 blocked or in use	`ss -lntp \| grep :443`; open in firewalld
`kinit admin` reports `Clock skew too great`	More than 5 minutes off	Sync time
Every write returns 403 after login	Not activated, or module not licensed	Check `valid` and `mods` in `status.json`
A navigation group is missing	Module not in the licence	Same; not a cache issue
Classic UI works, new console is blank	`dist/` not deployed or wrong path	`index.html` under `IDM_WEBUI_DIST_DST`; `/ipa/modern-ui` alias in `ipa.conf`

AD trust

Symptom	Cause	Fix
`trust-add` cannot find the AD domain	No forward zone	`ipa dnsforwardzone-add <AD domain> --forwarder <AD DNS> --skip-overlap-check`
`WERR_CONNECTION_REFUSED`	Two-way trust	One-way: `--range-type=ipa-ad-trust`, no `--two-way`
`KRB5KDC_ERR_SKEW`	More than 5 minutes off the DC	Same NTP source
Trust exists, `id <AD user>@<AD domain>` returns nothing	sssd has not fetched, or winbind is down	`ipactl status` for smb / winbind; `sss_cache -E`
AD user resolves, ssh refused	No HBAC rule allows it	`ipa hbactest --user <AD user>@<AD domain> --host <host> --service sshd`
No Trusts page	Licence lacks the AD trust module	Enterprise tier

More under AD trust prerequisites.

Licence

Symptom	Cause	Fix
Red banner "Not activated"	Factory state, no `.lic` uploaded	Copy the fingerprint on the activation page, upload the `.lic`
"Not authorised on this server"	Fingerprint mismatch: new machine, reinstall, clone, changed `machine-id`	Reissue for the new fingerprint
Upload returns `许可证文件为空或过大` (file empty or too large)	Wrong path after `curl --data-binary @`	Use an absolute path
`status.json` shows `degraded: true`	See `reason`: expired, over host cap, revoked, fingerprint mismatch	Act on the reason
`ipa host-add` fails	Managed host cap reached	`ipa host-find --sizelimit=0 \| tail -1` for the count; reissue with a higher cap
`LicenseModuleLocked` never in httpd logs	The gate does not log refusals	Read `status.json` only
Edited `idmatrix-license.service` env has no effect	Missing `daemon-reload` and `systemctl start`	The timer runs once a day

Clients

Symptom	Cause	Fix
`ipa-client-install` reports `Failed to upload host SSH public keys`	Before 1.0.2 the licence gate counted host keys under the ssh-keys module	Upgrade to 1.0.2; for hosts already enrolled, `ipa host-mod <FQDN> --sshpubkey="$(cat /etc/ssh/ssh_host_ed25519_key.pub)"`
Client logins slow or time out	sssd cannot find the KDC; DNS SRV not resolving	On the client: `dig +short _kerberos._tcp.<domain> SRV`
No home directory on first login	mkhomedir not enabled on the client	`authselect enable-feature with-mkhomedir`, start oddjobd
sudo rules not applied	sssd cache	`sss_cache -E`; `sudo -l` shows what was fetched

Replication (multi-master)

Symptom	Cause	Fix
`Invalid credentials (49)`, DS log shows `gss_accept_sec_context`	New host lacks `/etc/krb5.conf.d/crypto-policies`; its KDC signs camellia tickets	See Adding a second server
`topologysegment` is `both` but `user-add` does not replicate	Zombie replica id in the RUV	`dsconf ... cleanallruv --replica-id <id>`
Replica install fails with `CA_UNREACHABLE`	First server's licence lacked certificate issuance (before 1.0.2)	Upgrade or reissue

Still stuck

Collect these before contacting Reallysec:

sudo ipactl status
cat /var/lib/idmatrix-license/status.json
sudo ipa-healthcheck --failures-only
sudo tail -100 /var/log/ipaserver-install.log        # install problems
sudo tail -100 /var/log/dirsrv/slapd-<REALM>/errors  # replication problems