Upgrade and backup

Which layers upgrade in place, the upgrade and rollback steps, what the daily backup produces, when to take a full backup, and the difference between restoring to the same machine and a new one.

This page is for administrators maintaining an IDMatrix server and applies to 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

Layer	In place	How
Console (`dist/`)	Yes	Replace the directory, no restart
Licence layer	Yes	Rerun the playbook
Configuration and playbook	Yes	Rerun the playbook; idempotent
FreeIPA itself (`ipa-server` RPM)	No	See below
OS major version	No	Reinstall and restore, as a project

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

Before upgrading

Take a full backup. ipa-backup stops dirsrv for about 30 seconds; use a maintenance window.
Back up the licence state separately; ipa-backup does not include it.
Record the current versions for rollback.
Keep the previous bundle.

sudo ipa-backup
sudo tar czf /root/license-state-preupgrade.tgz -C /var/lib idmatrix-license
rpm -q ipa-server; ls -la /opt/idmatrix/dist/index.html

Recommended: rerun the playbook

Keep the old customer.env, point IDM_WEBUI_DIST_SRC and IDM_LIC_SRC at the new bundle, and 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. The licence layer upgrades through the playbook only; replacing individual files by hand is not supported.

Manual: console only

Build output carries content hashes. Empty the directory before unpacking, 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

The console is static files only: no service restart, Ctrl+F5 in the browser.

Post-upgrade checks

Check	Expected
`curl -sk -o /dev/null -w '%{http_code}\n' https://<FQDN>/ipa/modern-ui/`	`200`
`ipa user-show admin`	Returns normally
`valid` in `/var/lib/idmatrix-license/status.json`	Unchanged from before the upgrade
A write in an unlicensed module	`403`

The last check is mandatory. A broken gate lets requests through; it does not error.

FreeIPA itself is not upgraded in place

FreeIPA is 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 run dnf update ipa-server.

Rollback

Upgraded	Rollback
Console	Empty `dist/`, unpack the previous version
Licence layer	Rerun the playbook from the previous bundle
Data damage	`ipa-restore <pre-upgrade full backup>`, then restore `license-state-preupgrade.tgz`

Backup

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

Backups contain the CA private key and directory data. Encrypt them once off the host and restrict access.

Two kinds

Command	Scope	Service impact	Use
`ipa-backup`	Full: data, CA, certificates, configuration	Stops dirsrv for about 30 s	Disaster recovery; weekly, and before trust setup, bulk policy changes and upgrades
`ipa-backup --data --online`	LDAP data only	None	Daily; preconfigured at install

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. It produces two artefacts at 02:30 daily in about 5 seconds without stopping services:

Artefact	Path
Data backup	`/var/lib/ipa/backup/ipa-data-<timestamp>/`
Licence state	`/var/lib/ipa/backup/license-state-<timestamp>.tgz`

Anything older than 14 days is pruned (idm_backup_keep_days). Sites with their own backup system set idm_setup_backup=false at install.

Action	Command
Show the next run	`systemctl list-timers idmatrix-backup.timer`
Show the log	`journalctl -u idmatrix-backup.service`
Run one now	`systemctl start idmatrix-backup.service`

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, same realm, same 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

Checks afterwards:

Check	Expected
`ipactl status`	All RUNNING
`kinit admin && ipa user-find --sizelimit=1`	Returns normally
`ipa trust-show <AD domain>` (where a trust exists)	Returns normally
License Activation page	Status valid

Two lines of output are normal, 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

Restore to	`machine-id`	Licence
Same host (reinstall, rollback)	Unchanged	Still valid; restore `/var/lib/idmatrix-license` with it
New host, new hardware (DR rebuild)	Changed	Invalid. Take the new fingerprint, Reallysec reissues, upload on the License Activation page

DR sequence:

Install the same IPA version on the new host with the same hostname and realm.
Run ipa-restore.
Reissue the licence for the new fingerprint and upload it.
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.

On this page