Deploy (Model B)
What the playbook does on the target, where files land, how to verify, how to clean up a failed run, and the handover checklist.
The step-by-step is in the quick start. This page covers what happens behind the playbook, for troubleshooting and repeat deliveries.
Playbook stages
deploy-ipaserver.yml has five stages. All are idempotent; a rerun only fixes the difference.
| Stage | Action | Location |
|---|---|---|
| Offline RPM repo | Pushes the bundled rpms/ to the target and registers it as a local yum repo with signature checking on | /opt/idmatrix-rpms/, /etc/yum.repos.d/idmatrix-offline.repo |
| FreeIPA server | The ipaserver role from freeipa.ansible_freeipa: packages, ipa-server-install (directory, KDC, CA, DNS, adtrust); enables oddjob-mkhomedir so home directories are created on first sign-in | Standard FreeIPA paths |
| Console | Pushes dist/ to the target and adds the /ipa/modern-ui alias to /etc/httpd/conf.d/ipa.conf | IDM_WEBUI_DIST_DST, default /opt/idmatrix/dist |
| Licence layer | Validator, status endpoint, request gate, host-limit plugin, daily check timer; then runs one check immediately | /opt/idmatrix-license/, /var/lib/idmatrix-license/status.json |
| Daily backup | Backup script and idmatrix-backup.timer, online data backup at 02:30 daily | /var/lib/ipa/backup/ |
How the three licence components divide the work: Licence.
What is added to the target
| Path | Content |
|---|---|
/opt/idmatrix-license/ | The licence layer |
/var/lib/idmatrix-license/ | license.lic (after activation), status.json (current licence state; the console banner and the gate both read it) |
/etc/httpd/conf.d/ipa.conf | The /ipa WSGI entry repointed to the licence layer's request gate; the /ipa/modern-ui alias |
/etc/httpd/conf.d/idmatrix-license.conf | Three endpoints: status, fingerprint request, licence upload |
| FreeIPA plugin directory | idmatrix_hostlimit.py, the server-side managed-host cap |
/etc/systemd/system/ | idmatrix-license.{service,timer}, idmatrix-backup.{service,timer} |
Verification
All six must pass:
sudo ipactl status # 1. all 11 services RUNNING
curl -sk -o /dev/null -w '%{http_code}\n' https://<FQDN>/ipa/modern-ui/ # 2. 200 or 301
sudo systemctl list-timers idmatrix-backup.timer # 3. NEXT is 02:30 tomorrow
sudo systemctl start idmatrix-backup.service && ls /var/lib/ipa/backup/ # run one now, confirm the output
cat /var/lib/idmatrix-license/status.json # 4. valid:false is expected before activation
echo '<admin password>' | kinit admin && ipa pwpolicy-mod --minlength=9 # 5. expect Forbidden
chronyc sources # 6. time in syncCheck 5 proves the licence gate exists. Refusing writes before activation is by design; if the write succeeds, the licence layer did not take over the /ipa entry, or status.json is unreadable and the gate failed open. A broken gate reports nothing.
The 11 services: Directory Service, krb5kdc, kadmin, named, httpd, ipa-custodia, pki-tomcatd, ipa-otpd, ipa-dnskeysyncd, smb, winbind. IPA_SETUP_DNS=false drops named and ipa-dnskeysyncd; IPA_SETUP_ADTRUST=false drops smb and winbind.
Cleaning up a failed install
ipa-server-install is not atomic. A mid-way failure leaves an incomplete directory instance and KDC. Do not rerun the playbook as is; clean the target first:
sudo ipa-server-install --uninstall -U
ls -d /etc/dirsrv/slapd-* /etc/pki/pki-tomcat /etc/ipa/default.conf 2>&1 # all should be No such file
sudo getcert list | grep -c MONITORING # should be 0Remove leftovers by hand: dsctl slapd-<REALM> remove --do-it, rm -rf /etc/pki/pki-tomcat, getcert stop-tracking -i <id>. ipa-client-install --uninstall restores /etc/nsswitch.conf from its pre-install backup; if the hosts: line was edited before install (removing myhostname), edit it again after uninstall.
Common failure points, in order of appearance:
| Fails at | Cause |
|---|---|
| Hostname check | hostname -f differs from IPA_HOSTNAME; FQDN resolves to 127.0.0.1 or ::1 |
| DNS forwarder check | IPA_FORWARDERS unreachable, or IPA_AUTO_FORWARDERS=true picked a dead address from resolv.conf |
| Time | More than 5 minutes off the NTP source or DC |
configuring mod_ssl | mod_ssl missing on the target. Check with rpm -q mod_ssl; the bundled repo has it |
setting up httpd keytab, or pkispawn cannot create its log | The target is not a clean system; directories such as /var/lib/ipa/gssproxy or /var/log/pki were deleted. Run rpm -Va --nofiledigest | grep ^missing and dnf reinstall the owning packages |
Handover checklist
Give the customer:
| Item | Notes |
|---|---|
Console URL, admin password, Directory Manager password | Into their password manager |
The complete docs/ set from the bundle | |
COPYING and idmatrix-source.tar.gz | The console is a GPLv3 derivative of freeipa-webui; the corresponding source must ship with it |
| Backup notes | Backups land in /var/lib/ipa/backup/; off-host copies are the customer's responsibility |
Do not give: customer.env (clear-text passwords), the control node's ssh private key, vendor-internal documents.
Requirements and network
Delivery form, host size, hostname and DNS, time sync, ports to open and the control node, to confirm before installing.
Configuration
customer.env, variable by variable. Model A's .env and Model B's customer.env share one variable set; only the connection method and a few container settings differ.