Re-enrolling and uninstalling FreeIPA clients

Re-enrolling and uninstalling FreeIPA clients: when teams need it

Teams need to re-enroll or uninstall a FreeIPA client when a host moves to a different realm or FreeIPA server, when it is rebuilt under the same name, or when it is retired. In each case the host still carries state from its previous enrollment, and that state does not disappear on its own. A clean exit or a deliberate re-enrollment means removing or replacing that state in a known order, not simply reinstalling packages. A FreeIPA client holds several pieces of identity material. The host entry in the directory is the server-side record that Kerberos principals, host-based access control and DNS records point to. The host keytab, usually at /etc/krb5.keytab, holds the long-term keys the machine uses to authenticate. SSSD keeps a local cache of users, groups and credentials so that logins keep working when the server is slow or unreachable. Certificates issued for the host and its services, and any DNS records the client registered, sit on top of that. FreeIPA is built from 389 Directory Server, MIT Kerberos, the Dogtag certificate system and SSSD on clients, so a leftover in any one of those layers can make the others disagree. A stale keytab paired with a new host entry, or a cached realm that no longer matches the server, produces authentication errors that look unrelated to the original change. Before starting, confirm which of these artifacts the host owns in your environment, and who has the rights to remove the server-side host entry, its certificates and its DNS records. FreeIPA is licensed under GPL-3.0-or-later and has no paid edition, so the procedures come from the project's own tools and documentation, and the work of planning and verifying them falls to your team or a partner. Check the exact client commands and options against the version of FreeIPA and of your distribution that you run before any production host is touched.

Which path fits: move, rebuild or retire a host

Use this path when the host stays in service but must authenticate against a different FreeIPA server or a different realm. The machine keeps its role and usually its name, but its identity context changes. Treat the change as an uninstall of the existing enrollment followed by a fresh enrollment, and check the workloads that depend on Kerberos and SSSD before you start.

Order of operations: Confirm the target server or realm resolves and is reachable from the host, uninstall the current client enrollment, then enroll against the new server with explicit server and realm values.
Server-side records: On the old deployment, remove the host entry and its service principals once the host no longer uses them. If the realm changes, old principals have no meaning in the new realm, so plan to create new service principals and keytabs there.
What the host loses: Kerberos tickets and cached SSSD identity data stop working until enrollment completes. Services that authenticate with keytabs will fail until they receive new ones.
Policies to rebuild: Host-based access control rules, sudo rules and host group memberships do not follow the host automatically. Check whether they exist on the new side and recreate or migrate them.
Recovery access: Keep a local administrative account available throughout the change so you can reach the host if enrollment fails.

Before scheduling the change, compare the old and new deployments to see which policies, DNS entries and service principals already exist on the target side.

How to uninstall the FreeIPA client cleanly

This sequence removes a Linux host from FreeIPA in an order that keeps the server's records consistent with the machine, so the host leaves the realm without stale principals, certificates or local login paths behind. Each step ends with a check you can record before moving on.

Inventory and back up local state
The administrator who owns the host records what it depends on before anything is removed: services that use Kerberos or SSSD, SSH authorized keys sourced from FreeIPA, sudo and access rules that were working, and any host certificates the host itself uses. Copy the relevant configuration under /etc/sssd, /etc/krb5.conf, /etc/ipa and the keytab to a location outside the host, then confirm that the copies open and are readable. Keep these copies only as long as your change record requires, and store them under the same access controls as other identity material. Done when the inventory lists every service that will lose Kerberos or SSSD logins and each service has a named owner who has agreed to the cut-over.
Stop services that depend on FreeIPA logins
Before the host loses its identity, stop or reconfigure services that authenticate users or machines through Kerberos or SSSD, such as application servers, file shares and scheduled jobs that use a keytab. The administrator confirms that no process still holds an open Kerberos ticket it needs and that local administrator access is available through a documented fallback account. Check that klist shows no tickets needed by running jobs and that systemctl reports the dependent units as inactive or moved. Done when a second administrator can reach the host through the fallback path and the dependent services are either stopped or pointed elsewhere.
Remove the host and its principals on the server
When the host is being retired, an administrator with FreeIPA admin rights runs the host deletion from a healthy IPA server, which removes the host entry and its service principals and host certificates. Run ipa host-show for the fully qualified host name first to record which services, certificates and host groups are attached, then delete with ipa host-del. Only do this for a host that will not re-enroll under the same name, because a later enrollment with that name will need a new keytab. Done when ipa host-show returns not found and ipa service-find lists no services for that host.
Run the client uninstall with ipa-client-install
On the host, run ipa-client-install --uninstall as root from a session that stays open until the verification steps pass. The tool restores the system files it changed during enrollment and removes the client configuration it created, so review its output for any file it reports as not restored. If the host was enrolled with options that changed NSS, PAM or NTP settings, confirm those settings afterward rather than assuming they were reverted. Done when the command exits without error and the log it writes lists each file it restored or removed.
Verify that keytab, cache and Kerberos files are gone
Confirm that /etc/krb5.keytab is absent, that /var/lib/sss/db and /var/lib/sss/mc no longer hold the realm's cache, and that /etc/krb5.conf and the CA trust files added during enrollment have been removed or restored to their pre-enrollment content. Run kinit against a test account in the old realm and expect it to fail, and run getent passwd for a FreeIPA user and expect no result. Remove any leftover directories under /etc/ipa that the uninstall did not touch. Done when each path has been checked, and the results are recorded in the change ticket.
Confirm the host no longer resolves FreeIPA logins
Test the logins that used to work from a separate machine and on the host itself. Attempt an SSH login with a FreeIPA user, confirm that the account is refused, and confirm that the local fallback account still works and is the only way in. Check that id for a former FreeIPA user returns no entry and that sudo -l no longer shows rules from the realm. Ask the directory team to confirm that no HBAC or sudo rule still names the host, and that monitoring no longer expects it to report. Done when the login tests behave as expected and the remaining IPA references are documented or removed.

Cleanup options and when each fits

This table compares the main ways to retire or rebuild a FreeIPA client, from full host deletion to manual file cleanup. Read each row against the situation you are in: a decommission, a same-name rebuild, or a move to another realm. The main takeaway is that the host object, its certificates and its keytab are separate things, and removing the wrong one can leave stale trust behind or break a live service.

Option	What it removes	When it fits	Main risk
Delete the host object with its certificates	Host entry in IdM, its keytab entries, service principals and host certificates issued to it	Permanent decommission where the machine will never return under this name	Services on other hosts that still reference the host principal or certificate may fail until updated
Keep the host entry for a same-name rebuild	Nothing in IdM; local client config and keytab are removed on the machine only	Reinstalling the same host and reusing its name, group memberships and DNS record	Old host certificates and keytab material may still be valid until revoked or replaced
Force or unenroll the client tool	Local SSSD and Kerberos client state, usually without touching server-side objects	Machine is offline or IdM is unreachable and you need to clear local state quickly	Server still shows the host as enrolled, so the orphaned entry can be mistaken for a live machine
Manually delete keytabs and certificate files	Local keytab and certificate files on disk only	Recovery when the client tool fails partway and leftover files block re-enrollment	Deleting the wrong file, or a file still used by a running service, causes outages and hides the real state
Move the host to a new server or realm	Client trust to the old realm, while the host entry may be recreated in the new one	Migration where the target realm or server is different from the one the host was enrolled in	Mixing old and new realm configuration on one host can leave two sets of tickets and DNS records in conflict
Revoke host certificates before deletion	Certificates issued to the host, recorded as revoked in the CA	Host compromise, or a decommission that needs proof the certificates no longer work	Revocation is permanent and affects every service using that certificate, so confirm replacements first

Rebuilding a host with the same name without breaking trust

A reimaged host that keeps its old FreeIPA host entry will often fail enrollment, because the server still holds a host object, DNS records and a host keytab tied to the previous installation. The new client cannot take over an identity that is still active, so the first step is to decide whether the old entry is removed or deliberately reused. Before you run ipa-client-install again, list what the server still knows about the name with ipa host-show and check for the host's service principals with ipa service-find, since an old host/ principal and any HTTP/ or other service principals on the same name can conflict with the new install.

Remove in a fixed order so nothing is left pointing at a dead key. Start with the services and their certificates, then the host entry, then the DNS records that the old install created (A, AAAA and any SSHFP records). Deleting the host object with ipa host-del also removes its service principals and host-based access control links in most cases, but confirm this in your own version and check that no HBAC or sudo rule still names the host as a member. On the client side, the new system must not reuse the old /etc/krb5.keytab or SSSD cache from the image. Clear those before enrolling, and only reuse a host entry when you have a written reason, because a reused entry keeps the old key version history and can hide a compromised image.

Certificates issued to the old host need an explicit decision. Dogtag tracks each certificate by serial number, and a host certificate that still exists on the server may renew or may be trusted by services you did not expect. If the old machine may have been exposed, revoke its certificates through the CA and confirm the revocation appears on the CRL. If the image was simply retired, let the certificates expire under your CA policy and remove the host's certificate and service entries so no automated renewal tries to reissue them. Confirm with your CA owner which path your policy requires before you rebuild the host.

Security risks of leftover keytabs and certificates

A host that leaves FreeIPA without cleanup keeps working credentials, trust records and identity traces after the machine is gone. The cards below cover the risks that show up most often when a client is re-enrolled, rebuilt or uninstalled, and what to check for each one.

Retained keytab readable by others

The host keytab at /etc/krb5.keytab holds long-term Kerberos keys for the host principal. Anyone who can read that file while the host is still in service, or after the disk leaves your control, can act as that host to the KDC. Check file ownership and permissions before decommissioning, remove the keytab during uninstall, and confirm the old principal no longer has valid keys on the server.

Certificates valid after decommissioning

Host and service certificates issued by the integrated Dogtag CA stay valid until they expire unless someone revokes them. A decommissioned host can still present a certificate that services trust. Before reusing a host name, list the certificates tied to that host, revoke those that should no longer be trusted, and confirm the revocation reached the CRL your services check.

Orphaned DNS records on reused addresses

If a host record and its A or AAAA records remain after the machine is removed, the name resolves to an address that a new machine may now hold. Services that authenticate by name can then reach the wrong system, and Kerberos service principals may point at the wrong host. Remove the host and its DNS entries together, and check reverse zones for stale PTR records.

Cached credentials left in SSSD

SSSD keeps cached credentials and directory data under /var/lib/sss/db/ so that users can log in while the server is unreachable. Those caches can hold password hashes and group data for users who no longer belong on the host. Clear the SSSD database as part of uninstall, and confirm that no cached material survives on images, snapshots or retired disks.

Audit gaps when a name is reused

Logs and audit records that identify a host only by name cannot tell the old machine from the new one. Investigations into past access can then attribute activity to the wrong system, and a rebuilt host may inherit a trust history it did not earn. Record the host's enrollment date and any new host identifier before rebuilding, and keep the decommissioned host's logs with a clear label.

Unpatched servers during cleanup

Cleanup work touches the LDAP and Kerberos services that hold these credentials. FreeIPA 4.13.4 fixed two CVEs, including LDAP access control flaws that could let unauthenticated clients obtain credentials. Confirm your servers run the 4.13.4 security release or later before you remove keytabs and revoke certificates, so that cleanup does not run on a server that is still exposed.

Questions teams ask before re-enrolling or uninstalling FreeIPA clients

How much effort does a FreeIPA client cleanup take?

The effort depends on how many hosts are involved and how much each one is tied to the rest of the estate. A cleanup is mostly careful, repeatable work per host: removing the client, clearing the keytab and cached state, and confirming the host is gone from the server. The variables that move the effort most are the host count, how many host certificates were issued through the Dogtag CA and need revoking, how tightly DNS records and reverse zones depend on the old host name, and how mature your automation is. Ask any provider to break the estimate down by those four drivers before you accept a number.

Can our own team re-enroll or uninstall FreeIPA clients without a partner?

Yes, many teams do this in-house, especially for a small number of hosts with simple DNS and no pending certificate work. The work is well suited to an internal team when it has a host inventory, server administrator access, a tested runbook and someone who has rebuilt a host before. A partner is more useful when the host count is large, certificates or DNS records are entangled with other services, or the team has no one who can safely run a test host through the full sequence. A partner can also write the runbook and train your staff, which keeps the knowledge in-house after the engagement.

What does the cleanup need from our team?

The work needs a few specific inputs before it starts:

Administrator access to the FreeIPA servers, with a named person who can approve changes to the directory.
An inventory of every host to be re-enrolled, uninstalled or rebuilt, including its current FQDN, owner and services that depend on it.
Change windows agreed with the owners of those services, plus a rollback point for each host.
A list of host certificates and service principals tied to those hosts, so they can be revoked or reissued.

Without these, the work stalls on discovery rather than on the technical steps.

How is the cost structured in a fixed-scope quote?

Most engagements are fixed-scope, so the quote follows a written statement of what is in and out. The cost components are usually discovery and inventory, a test run on representative hosts, the production run with validation, and handover documentation. Most of this is one-time work. Ongoing items, such as later re-enrollments or support, are typically separate retainers. Ask for the quote to list the host count and host types it covers, the number of certificates and DNS changes in scope, which change windows are included, and what happens if discovery finds more hosts than expected. DeployOpen does not publish a price list, so the quote comes from the written scope.

What happens if a host is not cleaned up properly?

A host left with stale state can cause a few predictable problems. The old host principal and keytab may still exist in the directory, so a rebuilt machine with the same name can fail enrollment or collide with the old entry. Host certificates may remain valid and trusted for services that should no longer accept them. DNS records may point to a machine that no longer answers, and SSSD may keep cached configuration that confuses logins. Ask your provider how they verify each host after cleanup, for example by checking the server-side host entry, the local keytab and the state of SSSD on the client.

Does DeployOpen issue an audit report or certification for the cleanup?

No. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports, attestations or certifications. Independent auditors and certification bodies perform those assessments. For a cleanup, DeployOpen can provide records such as the host inventory, the revocation and removal log, and verification results, which your auditor may review. Confirm with your auditor in advance which evidence they expect, because the format and scope of acceptable records are their decision.

Will a cleanup change the security posture of the remaining estate?

A well-run cleanup should reduce exposure, because it removes stale credentials and certificates that no longer have a valid owner. It does not change the security of hosts that are not touched. Before the work starts, confirm which keytabs and certificates will be revoked, and check that no active service depends on them. Also confirm how revocation is recorded, since the Dogtag CA maintains certificate revocation and that record is part of your audit trail.

Official FreeIPA sources for client cleanup and backups

Before you re-enroll, rebuild or uninstall a host, read the FreeIPA About page to confirm which components your client work touches. FreeIPA combines 389 Directory Server, MIT Kerberos, the Dogtag certificate system and SSSD on clients, so a clean removal has to account for Kerberos keytabs, SSSD cache and configuration, and any certificates that the host requested. The FreeIPA About page gives the component overview that your runbook should match against the state of each host you plan to touch.

Next, read the backup and restore documentation before you remove any host object or change a server in the same change window. The FreeIPA backup guidance covers full and online data-only backups through ipa-backup and ipa-restore, and it warns that restoring an outdated backup into an active replica topology can break replication. Host removal and re-enrollment are changes to live directory data, so confirm that a current backup exists and that you know which server holds it. The FreeIPA backup and restore documentation is the page to check for those steps.

Confirm the exact command options, cleanup behavior and supported version for your release against the official pages before you run anything in production. Ask your team to record the FreeIPA version on each server and client, because the official sources describe behavior by release. Where the documentation does not answer a question about your environment, such as how a specific distribution handles leftover SSSD files, test on a non-production host first and treat the result as the basis for your runbook.

How DeployOpen scopes and delivers host re-enrollment and cleanup

DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, including FreeIPA client re-enrollment and uninstall work. We start from a written scope that names the hosts, the source and target realms, and the cleanup steps each host needs, so the work can be checked before any machine is touched.

How we scope

We inventory the hosts, their current realm, server targets and SSSD state before agreeing the work.
The written scope lists which hosts are re-enrolled, rebuilt or uninstalled, and in what order.
We agree who holds the admin credentials, how one-time passwords are issued, and where change records are kept.

How we build

We prepare a tested runbook for each host type, covering keytab removal, certificate cleanup and SSSD reset.
We run the procedure on representative test hosts first and record the results against the agreed checks.
We script repeatable steps where the estate allows, and keep manual steps in the runbook with clear owners.

How we hand over

You receive the runbooks, the host list with final state, and the verification results for each host.
Documentation records what was removed from each host and which server entries were deleted or recreated.
Your team walks through the rollback steps and the checks used to confirm a clean enrollment or uninstall.

How we support

Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.
Ongoing support for future re-enrollments and client upgrades is available as a retainer.
Confirm with us which follow-up checks, such as login and certificate tests, are included in the written scope.

Re-enrolling and uninstalling FreeIPA clients