Fix FreeIPA ID range conflicts with ipa-idrange-fix

How to fix FreeIPA ID range problems with ipa-idrange-fix

You have users or groups whose UID or GID falls outside the ID range assigned to your FreeIPA domain or trust. This often shows up after a migration from another directory, or after an Active Directory trust is set up and the IDs in use no longer match the range FreeIPA allocated. The ipa-idrange-fix tool was introduced in FreeIPA 4.13, according to the FreeIPA 4.13.0 release notes, so older servers will not have it. This section explains when your team is likely to need the tool and what the rest of the page covers: the symptoms that point to an ID range problem, the checks to run before changing anything, and the steps for repairing affected accounts and preventing conflicts in later migrations and trust setups.

The supplied documentation does not define the tool's command syntax, options or the exact changes it makes to existing objects. Before you run it, read the man page installed with your FreeIPA version and the 4.13 release notes, and confirm each option against them. Do not assume a flag behaves the way a similarly named tool does. Confirm, too, whether the tool writes changes immediately or supports a preview, and whether it touches file ownership on enrolled clients, since a changed UID or GID can leave files owned by numbers rather than names. Record the current ID ranges and the affected object list first, so you can compare the state before and after.

Treat the repair as a change to a production identity system. Schedule it in a window, confirm you have a current backup as described in the backup and restore section, and run it on a server where replication health is known to be good. If your deployment has replicas, check that the change will replicate cleanly before you rely on it. After the run, verify the affected users and groups with the standard lookup commands on a few enrolled clients, and confirm that ID mapping for any trusted Active Directory users still resolves as expected. Keep the output and the commands you ran as part of your change record.

Which repair path fits which range problem

This table compares in-place repair with ipa-idrange-fix, a fresh migration into a new deployment, and an ID view or trust-side change for AD users. Read each row against your own range layout, then confirm each option's behavior on your FreeIPA version before choosing.

Path	When it fits	What it changes	What stays manual	Main risk
In-place repair with ipa-idrange-fix	Users or groups in the existing domain fall outside the configured ID range, and the deployment itself is sound	Reassigns IDs for objects that sit outside the configured range, as the tool is designed to do in 4.13 and later	Confirming the affected objects, checking file ownership on enrolled hosts, and reviewing sudo or HBAC rules that reference IDs	Ownership of files on clients may no longer match after IDs change, so plan a check of affected paths
Fresh migration with ipa migrate-ds or ipa-migrate	The current deployment has range errors that are hard to untangle, or you are moving to a new FreeIPA server or domain anyway	Copies users, groups and policy objects into a new deployment with newly planned ranges	Sudo and HBAC rules may need manual migration through LDIF, and Kerberos attributes are regenerated rather than copied	Clients enrolled in the old realm must be re-pointed, and objects that do not migrate cleanly can be missed
ID view or trust-side change for AD users	The problem is with Active Directory users reaching Linux hosts, and the AD side owns the identity data	Adds an override or mapping layer so AD identities present consistent UIDs and GIDs on Linux	Maintaining view overrides per host group, and aligning AD-side attributes with the chosen ID scheme	Overlapping ID ranges or a DNS domain overlap with the AD forest can break trust, so confirm the trust design first
Change nothing and document exceptions	Only a few objects are affected and no client file ownership depends on their IDs	No changes to the directory, only a recorded list of exceptions	Ongoing tracking of new objects so the gap does not grow	Silent drift as new users are created outside the intended range

Repair sequence for out-of-range IDs

This sequence takes an out-of-range FreeIPA ID problem from diagnosis to verified repair, with a backup taken first and a defined point to roll back. Each step ends with a check you can record before moving on.

Record current ID ranges and affected objects
The identity administrator lists every configured ID range on the deployment, noting each range's domain, base ID and size, and then lists the users and groups whose UID or GID falls outside those ranges. Export the lists to a change record so you can compare them after the repair. Also note which clients depend on these IDs for file ownership, sudo or HBAC decisions. The step is complete when the change record holds the range inventory, the object list and the owning team's sign-off on the scope.
Take a full backup before any change
The platform team runs a full backup on the server that holds the authoritative data, following the backup procedure for the installed version. The FreeIPA backup documentation warns that restoring an outdated backup into a live replica topology can break replication, so this backup is your reference point, not a substitute for a current copy. Store it off the server and record its location and checksum. The step is complete when a restore test or file listing confirms the backup is readable.
Rehearse the repair on a non-production copy
Restore the backup into an isolated environment that matches the production topology as closely as you can, including the number of replicas and the presence of any AD trust. Run the planned changes there first and note every warning, prompt and object that moves. Confirm that enrolled test clients resolve the expected UIDs and GIDs afterwards. The step is complete when the rehearsal log shows no unexpected object changes and the team agrees the production plan matches what happened in the copy.
Run ipa-idrange-fix from the installed version's man page
Read the ipa-idrange-fix man page on the exact FreeIPA version in production, since options and behavior can differ between 4.x releases. The administrator runs the tool from the server that the change record names, following the documented options for the range being corrected, and captures the full output. Do not run it on several servers at once unless the documentation says to. The step is complete when the tool exits without errors and its output lists the objects it changed, matching the rehearsal.
Verify IDs on sample enrolled clients
Pick a representative set of enrolled Linux clients, including at least one that holds files owned by a repaired user or group. On each one, confirm with the standard identity lookup commands that the repaired users and groups now report the expected IDs, and check that file ownership on a test directory still matches. Compare results with the object list from the first step. The step is complete when every sampled client shows the expected IDs and no ownership mismatches remain.
Check replication status on every server
Run the replication status checks on every FreeIPA server in the topology, confirming that each agreement is current and that the repaired entries appear with matching values on each replica. Record the output for each server and investigate any replication error before you close the change. Because the repair writes to directory data, a server that lags or rejects updates needs attention now, not later. The step is complete when all servers report healthy replication and the repaired entries match across them.
Decide whether to keep or roll back
Set a rollback decision point before the change window opens, and apply it using the checks from the previous steps. Roll back if a sampled client shows wrong IDs, if file ownership breaks in a way the owning team cannot correct, or if replication errors persist. Rolling back means restoring from the verified backup under the vendor procedure, with the full replica re-initialization steps your version requires, and confirming replication again. Keep the change open until the decision is written in the change record with the evidence attached.

How the fix differs after a migration, an AD trust or a restore

After a migration from another LDAP directory or from another FreeIPA deployment, users and groups arrive carrying UID and GID values from the source system. If those values fall outside the ID ranges configured on the target, or overlap a range already in use, the entries will not match what the new domain expects. The migration paths also carry different data. The LDAP path excludes Kerberos attributes that FreeIPA regenerates, and sudo and HBAC rules need manual migration through LDIF.

Source ID values: List the UID and GID numbers in the source directory and compare them with the range on the target domain.
Regenerated Kerberos attributes: Confirm that migrated users have new Kerberos attributes, because the migration how-to says these are regenerated rather than copied.
Manual rule migration: Check that sudo and HBAC rules were moved by hand through LDIF, since they do not arrive with the users and groups.
Trust-era ranges: If the source deployment used AD trust ranges, confirm they are not carried into a range that now overlaps.
Client caches: Clear SSSD caches on test clients before judging results, so stale IDs do not look like conflicts.

Before running any repair, confirm the source ID values, the target ranges and the tool behavior for the FreeIPA version you run.

Preventing range conflicts after migrations and AD trusts

Most ID range conflicts are avoidable if ranges are planned before anything is migrated or trusted. Before moving users from another LDAP directory or another FreeIPA deployment, write down the ID range each deployment, each trust and each ID view uses, and confirm that no two of them can allocate the same UID or GID to different identities. Record these values in your change documentation so the next person adding a trust or a migration can check them without reconstructing the history. Confirm the IPA domain's DNS name against the AD forest before you create the trust: the FreeIPA Trusts page requires that the IPA domain use a DNS domain that does not overlap with any domain in the AD forest. Treat that check as a gate, because an overlap is far harder to unwind after users and hosts have enrolled.

Deployment layout affects how much room you have to correct a mistake. The FreeIPA deployment recommendations call for at least two to three replicas in each datacenter, no more than four replication agreements per replica, and dedicated servers without other applications. A topology built that way gives you replicas to test a range change against and to fall back on, while a single or poorly connected server estate leaves you with no safe place to rehearse. Ask who owns each replica, which servers hold the CA and DNS roles, and how long a change window must stay open while replication converges across sites. Those answers determine whether a range change can be staged site by site or must happen in one disruptive window.

Any ID range change should go through change control and be rehearsed on a copy of the deployment first. Take a current backup, restore it into an isolated environment, and run the change there, then verify that existing users keep the UIDs and GIDs their files and processes depend on. Restoring an outdated backup into an active replica topology can break replication, so keep the test copy fully separate from production. Your change record should name the approver, the rollback path and the verification checks, including login and file ownership tests on enrolled clients. Confirm with your own team which steps the tooling performs and which need manual handling before you schedule the window.

Security and operational risks during an ID range repair

An ID range repair changes the numeric identities behind files, processes and directory entries, so the risks reach beyond the FreeIPA server. The cards below cover what changes on clients, which caches and replicas can disagree, and which records must be protected and approved before the work starts.

File ownership on clients

When a user or group ID changes, files that were written under the old numeric UID or GID keep those numbers and may stop matching the account. Identify which hosts and shared filesystems hold data owned by users in the affected range, and decide whether ownership is corrected with a recursive change or left for the owner to review. Confirm that no process relies on hard-coded numeric IDs before the change window opens.

Kerberos and SSSD caches

Clients keep cached identity data through SSSD, and Kerberos tickets carry the principal name rather than the numeric ID, so a repair can leave clients resolving users inconsistently until caches expire or are cleared. Plan which hosts must be cleared, in what order, and how a user with an active session will be affected. Verify login and id output on a sample of enrolled hosts after each step.

Replication consistency across servers

FreeIPA runs as a multi-master directory, so an ID range change made on one server must reach every replica before the next step. Check replication status on all servers before starting and after each change, and confirm that no replica is offline or out of date. Restoring an outdated backup into an active topology can break replication, so do not treat a backup as a fallback for a half-applied change without a tested plan.

Backups and audit trails during the change

Take a full backup of every FreeIPA server before the repair and record the exact state of the ID ranges. Audit logs for the change are part of the evidence an auditor will ask for, so confirm where API and LDAP-side records are stored and that they are copied off the server during the window. Confirm who can read backups, since they contain credential and policy material.

Service accounts and non-human identities

Service accounts, system accounts and automation that authenticate with fixed IDs can break silently when their numeric IDs move. Inventory these accounts, their owners and the hosts that depend on them before the change, and decide whether each needs to be excluded, retested or updated. Check any ansible roles, cron jobs and mount configurations that reference numeric IDs.

Change control and a named approver

Record the change as a written plan with a scope, a rollback decision point and one named approver who can stop the work. Require sign-off from the owners of affected systems and from the security team that reviews access, and keep the approval with the change record. Your change process should define what counts as a failed check that triggers a stop, so the decision is not made under pressure during the window.

Common questions about ID range repair

What drives the cost of a FreeIPA ID range repair?

The cost depends mainly on how many users, groups and hosts sit outside the configured ID ranges, how many systems depend on their UIDs and GIDs, and how many sources they came from. Each source adds analysis: LDAP directories, earlier FreeIPA deployments, Active Directory trusts and local files all leave different ownership patterns. Clients also pay for access to the affected servers and clients, change planning, a rehearsal in a test copy, and verification after the change. Ask a quote to list each of these as a separate line, state which items are one-time, and say what you need from your own team. Recurring costs are usually limited to monitoring and any later support retainer.

How long does an ID range repair take?

Duration varies with the number of affected objects, the number of file ownerships and client systems that reference old IDs, and how many change windows your environment allows. Repairs on a small, single-domain deployment are generally shorter than repairs spanning migrated directories and AD trust mappings, because each source needs its own check. Approval cycles, freeze periods and the time needed to rehearse the change in a test copy often take longer than the tool run itself. Ask any provider for a written timeline that separates analysis, rehearsal, the production change and post-change checks, and confirm which steps depend on your team.

What does the work need from our team?

Expect to provide administrative access to the FreeIPA servers, a current, verified backup taken with the project's backup tooling, read access to the systems that own files and processes, and a list of change windows. A test copy of the deployment is important because it lets the team run the repair, compare results and roll back without touching production. Your team should also name an owner for application and file ownership questions, since those decisions cannot be made from the directory alone. Confirm with your provider which of these they require before work starts.

Can our own team repair ID ranges without a partner?

Yes, if you have engineers who understand FreeIPA ID ranges, the ipa-idrange-fix tool and the replication topology, and if you can rehearse the change safely. Teams that have run earlier migrations or AD trusts usually find the analysis manageable. A partner is most useful when the environment is large, when several sources have overlapping ranges, when file or process ownership needs careful mapping, or when the team has no spare capacity for a test copy and a change window. Read the tool's documentation for the release you run before deciding, and treat unfamiliar behavior as a reason to test again.

How does repairing ID ranges differ from re-migrating data?

Repair keeps the existing FreeIPA deployment and corrects the users and groups whose IDs fall outside the configured ranges, so the work centers on the directory and the systems that already use those IDs. Re-migration moves users, groups, policies and other objects into a new or different deployment, which means new replication, new certificates and new client enrollments in many cases. The FreeIPA to FreeIPA migration design covers moving objects between two deployments, and that path carries far more change and testing. Choose repair when the problem is confined to IDs, and treat migration as a separate project with its own scope.

What should we check before and after a repair?

Before the change, verify that backups restore cleanly in a test copy, that replication is healthy on every server, and that you know which hosts, file systems and services depend on the affected IDs. After the change, confirm that affected users resolve to their expected IDs on sample clients, that file ownership still matches, and that logins, sudo and access rules behave as before. Record the results so the team can prove what changed. Ask your provider to document each check and the rollback steps, and confirm how the checks will be run across all replicas.

Does a repair need a compliance or security review?

Often yes, because changes to identity data affect who can access systems and which records show that access. Changing UIDs and GIDs can alter file permissions, audit trails and the link between a person and their activity, so your security or compliance team may need to approve the plan and review the evidence. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports or certifications, and independent auditors make those determinations. Confirm with your assessor which records they expect to see before the change.

Limits to confirm in your environment

The ipa-idrange-fix tool changes identity data that Linux clients, sudo rules and file ownership depend on, so the repair is only as safe as the assumptions behind it. The cards below cover the version, platform, trust, backup and prior-change questions to answer before anyone runs a command on a production server.

Exact tool behavior in your version

The tool was introduced in FreeIPA 4.13, so confirm its exact syntax, options and dry-run behavior in your installed release rather than relying on examples from other versions. Check the help output on a test server and read the release notes for any later fixes. Ask whether the tool reports planned changes before it modifies anything, and whether it can be limited to one range or one domain. Record the answers in the change ticket.

Server version relative to 4.13

Find out whether every server in the topology runs 4.13 or later, because a repair that is valid on a newer server may not be available on an older one. Mixed versions across replicas can produce different views of the same ranges during a change. Confirm the security release level as well, since the 4.13.4 release fixed two CVEs in authentication and LDAP access control. Plan the upgrade order before the repair if any server is behind.

Client platforms and distributions

List the Linux distributions, SSSD versions and non-Linux clients that resolve UIDs and GIDs from FreeIPA. Files owned by a renumbered ID are often on hosts you do not manage directly, such as file servers, backup agents and build runners. Confirm how each client caches identities and whether a cache clear or SSSD restart is needed after the change. Make a list of hosts that must be checked after the repair.

AD trusts in scope

Decide whether any cross-forest trust with Active Directory is part of the repair, because ID mapping for trusted users follows different rules from POSIX users in the IPA domain. Confirm the trust type, the ID ranges it uses and whether ID views apply to the affected hosts. The IPA domain must not overlap with any AD domain name, and that rule should be rechecked before any range is changed. Treat trusted users as a separate scope with its own sign-off.

Backup storage and restore testing

Confirm where ipa-backup archives are stored, who can read them, and whether a restore has been tested on a separate host within the last change cycle. The backup documentation warns that restoring an outdated backup into an active replica topology can break replication, so a backup is only useful if it matches the current state. Check that the backup was taken on a server with the right role and after the last identity change. Write down the restore steps your team would follow if the repair goes wrong.

Prior attempts and changed data

Ask whether anyone has already run a range fix, a manual LDAP edit or a migration script against these ranges, and whether the results were recorded. A partial repair can leave some users renumbered and others not, which makes file ownership and group membership harder to reason about. Compare the current UIDs and GIDs with the last known inventory before starting. If the data has already changed, treat the repair as a recovery task with its own verification steps.

How DeployOpen scopes and delivers an ID range repair

DeployOpen treats an ID range repair as a planned change to a live identity system, starting from a written scope that names the affected users, groups and hosts. The work runs inside your own infrastructure, with testing, documentation and handover agreed before the first change is made.

How we scope

Inventory every IPA server, ID range and trust, and record which users and groups fall outside the configured ranges
Agree in writing which systems, hosts and ID views are in scope and which are excluded
Confirm the replication topology and backup state so the repair plan accounts for every server

How we build

Run the repair first against a copy of your directory to confirm the effect on file ownership and SSSD caches
Make changes in a documented sequence with a verified backup taken before any server is modified
Test logins, sudo, HBAC and Samba file access on representative clients after each change set

How we hand over

Deliver a written record of each range change, the affected objects and the commands used
Document how to check for out-of-range IDs, including the steps to run after future migrations or trust changes
Walk your administrators through the procedure and agree who owns each follow-up task

How we support

Fixed-scope engagements close when the agreed deliverables are accepted, with any further work quoted separately
Ongoing support, upgrades and continuous testing are available as a retainer for FreeIPA estates that change often
Confirm with your team which range checks belong in routine monitoring and who receives the alerts

Fixing FreeIPA ID range problems with ipa-idrange-fix