The FreeIPA Master Class - Part 9

The FreeIPA Master Class - Part 9

Published March 17, 2025, 5:28 a.m. by dwest

Troubleshooting FreeIPA

Throughout this series we’ve covered how to install, configure, and operate FreeIPA as a full identity management platform for Linux environments. When everything works, FreeIPA provides seamless authentication, centralized identity management, Kerberos single sign-on, and fine-grained access control. However, in real environments things eventually break.

FreeIPA is built on several complex systems working together:

  • LDAP (389 Directory Server)
  • Kerberos
  • DNS
  • Certificate Authority
  • Replication topology
  • SSSD clients

When something goes wrong, it can take a lot of investigation to determine which component is responsible. This article documents real-world troubleshooting scenarios that commonly appear in FreeIPA environments.

Some of these problems occur due to:

  • Failed upgrades
  • Replica removal issues
  • Replication conflicts
  • LDAP schema mismatches
  • Missing ID ranges
  • Directory corruption

Many of the examples below come from real operational environments and demonstrate how to diagnose and repair these issues.

First Things to Check

Most FreeIPA troubleshooting begins with the same steps. Before diving into deeper troubleshooting, check these common areas.

  1. Check FreeIPA service status 

    ipactl status

  2. Restart all services if necessary. I occasionally do this even when services are working correctly. It can help reinitialize processes that might be stuck, but not detected yet 

    ipactl restart

  3. Check FreeIPA logs. There is a wealth of information in them and will often hold the key to your issue. While there are dozens of related logs to FreeIPA, the important logs include:

    • /var/log/ipaserver-install.log
    • /var/log/ipaclient-install.log
    • /var/log/httpd/error_log
    • /var/log/dirsrv/slapd-EXAMPLE-COM/errors
    Note
    ‘EXAMPLE-COM’ will be your actual domain name

  4. For Kerberos issues, review the following

    • /var/log/krb5kdc.log

These logs often contain the first clues about what went wrong.

Replication Problems

FreeIPA relies heavily on replication between servers. When replication breaks, you may see symptoms such as:

  • Replica installation failures
  • User accounts not appearing on all servers
  • Inconsistent configuration
  • Errors removing replicas

Several types of replication conflicts can occur.

Cleaning Replication Conflicts

When a replica is removed from a cluster, FreeIPA attempts to clean up all related records across the network. If something interrupts that process, orphaned records may remain in the LDAP directory. These leftover records can prevent new replicas from being added.

  1. Search for replication conflicts 

    ldapsearch -h localhost -D "cn=directory manager" -W -x \
-b "cn=<hostname>.example.com,cn=masters,cn=ipa,cn=etc,dc=example,dc=com" \
'(&(nsds5replconflict=*)(objectclass=ldapsubentry))' | grep cn

  2. Remove any conflicting entries you find. For each conflict found use the following to remove them. 

    ldapdelete -h localhost -D "cn=directory manager" -W -r -x \
cn=<hostname>.example.com+nsuniqueid=<ID>,cn=masters,cn=ipa,cn=etc,dc=example,dc=com

  3. Repeat this process until all conflict entries are removed.

Naming Conflicts

Naming conflicts occur when the same DN exists on multiple servers due to replication errors. This often prevents replica removal with errors like:

not allowed on non-leaf entry
Identify naming conflicts

To resolve this kind of conflict, do the following:

  1. Query each IPA master for a list of replication conflicts 

    dsconf -D "cn=Directory Manager" ldap://<ipa_master>.example.com repl-conflict list   dc=example,dc=com

  2. Extract the DN values. You will use this to reference the conflict you are removing 

    dsconf -D "cn=Directory Manager" ldap://<ipa_master>.example.com repl-conflict list   dc=example,dc=com | grep 'dn: '

  3. Remove the conflicting entry 

    dsconf -D "cn=Directory Manager" ldap://<ipa_master>.example.com repl-conflict delete '<DN>'
    Example 
    dsconf -D "cn=Directory Manager" ldap://ipa1.example.com repl-conflict delete \
cn=ipa1.example.com-to-ipa2.example.com+nsuniqueid=bb35ce84-77be11ec-99d2,cn=domain,cn=topology,cn=ipa,cn=etc,dc=example,dc=com

The key element is the nsuniqueid, which FreeIPA adds during conflicts.

Replica Update Vectors (RUV)

Replication topology is tracked using Replica Update Vectors (RUVs). If a replica is removed incorrectly, orphaned RUV entries may remain. This can cause errors when adding a new replica since it things the agreement already exists.

Replication agreement already exists

You will need to remove these orphaned records before you can re-add the replica into FreeIPA.

  1. List existing RUVs. Take note of the RUV ID for any RUV’s that should not exist. 

    ipa-replica-manage list-ruv

  2. Remove a specific RUV by referencing the RUV ID 

    ipa-replica-manage clean-ruv <RUV_ID>

  3. Remove all dangling RUVs. This is useful if you have a lot of RUV’s that need to be removed at once. 

    ipa-replica-manage clean-dangling-ruv

  4. It will take some time for the RUV’s to get cleaned up and the changes replicated across the network. You can monitor progress by running the following: 

    ipa-replica-manage list-clean-ruv

  5. It is possible that process for cleaning the RUV’s might get stuck. You can abort the process if necessary: 

    ipa-replica-manage abort-clean-ruv <RUV_ID>

⚠️ Warning
Cleaning RUV entries affects the entire cluster and should be done carefully.

Restoring Preserved Users

Over years of FreeIPA upgrades and directory migrations, you might start to find entries with legacy values or relations. One change made over the years is that a users default group became more tightly bound to the account. Older accounts might have left that group active in the directory when the account was disabled and preserved. This might have left that group disassociated in the directory. When restoring a preserved user, the following error may appear in the GUI:

Server is unwilling to perform: Managed Entry Plugin rejected modrdn operation

While that error is not specifically helpful, if you check the directory logs, you might find the following message:

Unable to add managed entry "cn=username,cn=groups,cn=accounts"
Already exists

This happens when the user’s private group was not removed during the preservation process. When IPA tries to restore the user, it attempts to recreate a group that already exists and fails. So the fix is to delete the group. However, before you can do that, you have to disassociate it from the account.

  1. Verify the group 

    ipa group-show username --all --raw
    Example output: 
    dn: cn=username,cn=groups,cn=accounts,dc=example,dc=com
mepManagedBy: uid=username,cn=users,cn=accounts,dc=example,dc=com

  2. Remove the managed entry attributes. This protects the group from accidental deletion since it is supposed to be tightly associated with the account. 

    ldapmodify -Y GSSAPI <<EOF
dn: cn=username,cn=groups,cn=accounts,dc=example,dc=com
changetype: modify
delete: objectclass
objectclass: mepManagedEntry
-
delete: mepManagedBy
EOF

  3. Delete the group 

    ipa group-del username

After removing the group, the preserved user can be restored normally.

IPA Upgrade Failures

Sometimes after upgrading FreeIPA packages, services fail to start with an error like:

IPA version error: data are in newer version than IPA

Example:

IPA version error:
data version '4.9.8-7'
IPA version '4.9.8-2'

This indicates that the LDAP schema upgrade was incomplete. This usually happens when the upgrade aborts in the middle due to an error. The first thing you should try is forcing the upgrade again.

ipa-server-upgrade --skip-version-check

Adding the --skip-version-check flag will allow it to continue when the versions mismatch.

If successful, you should see: 

The IPA services were upgraded
The ipa-server-upgrade command was successful

If it fails, then it should provide you with a clue as to where to look next.

Missing DNA Range on a Master

Another common issue occurs when creating users or groups and fails when attempting to assign new posix ID’s.

Operations error:
Allocation of a new value for range cn=posix ids failed

This happens when a server loses its DNA (Distributed Numeric Assignment) range, due to various troubleshooting procedures that might require removing and re-adding the replica to the cluster. The DNA plugin is what automatically assigns UID/GID numbers. However, if a server loses its range, it cannot create new users.

To resolve this, you will first need to determine what the current DNA range is on each IPA replica so you do not accidentally try to overlap them.

ipa-replica-manage dnarange-show

If any of the FreeIPA replicas displays “No range set”, then you will need to assign one manually. This is normally done by taking a range from an existing replica and then dividing it in half and then equally distributing it with the new one. Since we are doing this manually, you have a little more freedom with how you do it, so just pick a range that makes sense.

  1. Check the domain ID range. The is the range across all replicas in the domain, so you will need to make sure your range is within it. 

    ipa idrange-find
    Example: 
    Range name: EXAMPLE.COM_id_range
First Posix ID of the range: 1473200000
Number of IDs in the range: 200000

Full range:

1473200000 – 1473400000

  2. Divide the range among servers. You might have to reallocate ranges on existing replicas to make this work, but in an ideal situation, you should try to make it look like the following example: 

    ipa1.example.com: 1473200000-1473200999
ipa2.example.com: 1473201000-1473201999
ipa3.example.com: 1473202000-1473202999

  3. Assign the ranges to their respective replicas 

    ipa-replica-manage dnarange-set ipa1.example.com 1473200000-1473200999

  4. Verify again: 

    ipa-replica-manage dnarange-show

After assigning ranges, user creation should work again.

General Troubleshooting Tips

When diagnosing FreeIPA issues, follow a layered approach.

  1. Check DNS. Many FreeIPA failures are caused by DNS, so that should be the first place you look. 

    dig ipa.example.com

  2. Check Kerberos. Authentication problems often originate here. 

    kinit admin
klist

  3. Verify the replication agreements 

    ipa topologysegment-find

  4. Check the system time. Kerberos requires synchronized clocks. If it drifts too far, then all tickets will fail to authenticate 

    timedatectl status

  5. Verify certificates 

    ipa-certupdate

Final Thoughts

FreeIPA is an extremely powerful identity management platform, but it also involves multiple moving parts working together:

  • LDAP directory services
  • Kerberos authentication
  • Certificate infrastructure
  • DNS integration
  • Multi-master replication

Because of this complexity, troubleshooting sometimes requires digging through logs, understanding replication topology, and repairing LDAP entries manually. The key to success with FreeIPA is understanding how these components interact. Once you learn how to diagnose issues across the stack, maintaining a FreeIPA deployment becomes far less intimidating.

The End of the Series

This concludes The FreeIPA Master Class.

Throughout this series we covered:

  1. Introduction to Directory Services
  2. Directory Binding and Clients
  3. Managing Users and Groups
  4. Kerberos Authentication Deep Dive
  5. Host-Based Access Control and Sudo Policies
  6. Managing Certificates and Services
  7. Replication and High Availability
  8. Active Directory Integration
  9. Troubleshooting FreeIPA

By now you should have a complete understanding of how FreeIPA works and how to operate it in real-world environments. FreeIPA remains one of the most powerful open-source identity platforms available for Linux infrastructure. And hopefully this guide helps you spend less time banging your head against the keyboard when something inevitably goes wrong.

Share this post

Similar posts

The FreeIPA Master Class - Part 8

The FreeIPA Master Class - Part 7

The FreeIPA Master Class - Part 6

The FreeIPA Master Class - Part 5

0 comments

There are no comments.

Add a new comment

Search
Categories
Popular Posts