Deploy (Model B)
What the playbook does on the target, where things 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.
What the playbook does
deploy-ipaserver.yml has four stages. All are idempotent; a rerun only fixes the difference.
| Stage | Action | Lands in |
|---|---|---|
| Offline RPM repo | Pushes the bundled rpms/ to the target and registers it as a local yum repo (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 login | 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, embedded public key, 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/ | gate_wsgi.py (request gate), license_gate.py (classifier), phonehome.py (validator), public.pem (embedded public key), rstlic/ SDK |
/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 | WSGIScriptAlias /ipa repointed from /usr/share/ipa/wsgi.py to /opt/idmatrix-license/gate_wsgi.py; 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} |
To roll back the licence layer, point the WSGIScriptAlias line in ipa.conf back at /usr/share/ipa/wsgi.py and systemctl reload httpd. FreeIPA itself is untouched.
Verify
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 = 02:30 tomorrow
sudo systemctl start idmatrix-backup.service && ls /var/lib/ipa/backup/ # run one now, see 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, either WSGIScriptAlias in ipa.conf was not repointed 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.
When the install fails
ipa-server-install is not atomic. A mid-way failure leaves half a directory instance and half a 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 / ::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; rpm -q mod_ssl, the bundled repo has it |
setting up httpd keytab / 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 |
Handover checklist
Give the customer:
- Console URL,
adminpassword, Directory Manager password, into their password manager - The complete
docs/set from the bundle COPYINGandidmatrix-source.tar.gz. The console is a GPLv3 derivative of freeipa-webui; the corresponding source must ship with it- 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
Confirm before installing - delivery form, host size, hostname and DNS, time sync, ports to open, and the control node.
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.