Upgrade and backup

Model B only. The Model A container appliance has no data-preserving upgrade: replacing the image means deleting volumes, which wipes the identity store. Production runs Model B.

Upgrade

IDMatrix releases (features, localisation, gating, bug fixes) all fall into the first three rows and never touch FreeIPA itself.

Before upgrading

sudo ipa-backup                                                       # full; stops dirsrv ~30 s, maintenance window
sudo tar czf /root/license-state-preupgrade.tgz -C /var/lib idmatrix-license   # licence state is outside ipa-backup
rpm -q ipa-server; ls -la /opt/idmatrix/dist/index.html               # note versions for rollback

Keep the previous bundle.

Recommended: rerun the playbook

Take the new bundle, keep the old customer.env, point IDM_WEBUI_DIST_SRC and IDM_LIC_SRC at the new bundle, rerun:

cd <new bundle> && ./deploy/render-inventory.sh
ansible-playbook -i deploy/inventory.generated.yml deploy-ipaserver.yml

The ipaserver role skips when IPA is already installed; overwritten console and licence files trigger their own restarts.

Manual: console only

Build output carries content hashes; empty the directory first or old and new files pile up:

cd /opt/idmatrix/dist && find . -mindepth 1 -delete
tar xzf /tmp/dist-<new version>.tar.gz -C /opt/idmatrix/dist

Static files only; no service restart, Ctrl+F5 in the browser.

Manual: licence layer only

sudo install -m 0755 -o root -g root <new>/license_gate.py <new>/gate_wsgi.py /opt/idmatrix-license/
sudo rm -rf /opt/idmatrix-license/__pycache__
python3 /opt/idmatrix-license/license_gate.py       # must print self-test: PASS
sudo systemctl restart httpd

Three checks afterwards: curl -sk -o /dev/null -w '%{http_code}\n' https://<FQDN>/ipa/modern-ui/ returns 200; ipa user-show admin works; valid in status.json is unchanged. Then attempt a write in an unlicensed module and confirm it is refused. A broken gate lets things through; it does not error.

Not upgraded in place: FreeIPA itself

Not tied to IDMatrix releases. Air-gapped sites have no yum repo and a cross-version upgrade needs a full dependency closure; major versions run ipa-server-upgrade with schema migration that is hard to roll back; restore requires the same version, so upgrading IPA strands older backups. For security advisories, contact Reallysec for a dedicated plan; do not dnf update ipa-server on your own.

Rollback

Backup

Two things to back up: the IPA identity store (users, groups, hosts, policies, certificates, CA, DNS) and the licence state (/var/lib/idmatrix-license/).

Two kinds

Output lands in /var/lib/ipa/backup/ipa-full-<timestamp> or ipa-data-<timestamp>. Nothing leaves the host on its own; copy it off and keep at least two generations.

Daily automatic backup

The playbook installs /usr/local/sbin/idmatrix-backup.sh and idmatrix-backup.timer, producing two artefacts at 02:30 daily in about 5 seconds without stopping services:

Anything older than 14 days is pruned (idm_backup_keep_days). Sites with their own backup system set idm_setup_backup=false at install. Inspect with systemctl list-timers idmatrix-backup.timer and journalctl -u idmatrix-backup.service; run one now with systemctl start idmatrix-backup.service.

With multi-master

Back up each IPA server. Restore a full backup on one server only, then re-initialise the others from it (ipa-replica-manage re-initialize --from <restored server>); otherwise the data conflicts.

Restore

Restore overwrites the identity store; services are down for about 45 seconds during ipa-restore. Use a maintenance window.

Requirements: same IPA version, same hostname / realm / domain. A full restore normally goes onto a freshly installed IPA server.

sudo cp -a /offsite/ipa-full-<timestamp> /var/lib/ipa/backup/
sudo ipa-restore /var/lib/ipa/backup/ipa-full-<timestamp>
# only when restoring to the same machine
sudo tar xzf license-state.tgz -C /var/lib
sudo systemctl restart httpd

Afterwards: ipactl status all RUNNING; kinit admin && ipa user-find --sizelimit=1; ipa trust-show <AD domain> where a trust exists; License Activation page shows valid.

Two lines of normal output, not faults: Could not open file for writing: /etc/httpd/conf.d/nss.conf (this version uses mod_ssl; the file never exists) and the note about re-initialising replicas (irrelevant on a single server; handle multi-master as above).

The target machine decides whether the licence survives

DR sequence: install the same IPA version on the new host (same hostname / realm) → ipa-restore → identity store back → reissue the licence for the new fingerprint → with a trust, verify ipa trust-show and id <AD user>@<AD domain>.

Measured on a 4 GB / 2 vCPU single server: full backup 30 seconds, full restore 45 seconds; afterwards all 11 services up, objects created after the backup rolled back, AD trust intact, console returning 200.