Migration Tools

Migrate users and groups from an LDAP server to IPA.

This performs an LDAP query against the remote server searching for users and groups in a container. In order to migrate passwords you need to bind as a user that can read the userPassword attribute on the remote server. This is generally restricted to high-level admins such as cn=Directory Manager in 389-ds (this is the default bind user).

The default user container is ou=People.

The default group container is ou=Groups.

Users and groups that already exist on the IPA server are skipped.

Two LDAP schemas define how group members are stored: RFC2307 and RFC2307bis. RFC2307bis uses member and uniquemember to specify group members, RFC2307 uses memberUid. The default schema is RFC2307bis.

The schema compat feature allows IPA to reformat data for systems that do not support RFC2307bis. It is recommended that this feature is disabled during migration to reduce system overhead. It can be re-enabled after migration. To migrate with it enabled use the “—with-compat” option.

Migrated users do not have Kerberos credentials, they have only their LDAP password. To complete the migration process, users need to go to http://ipa.example.com/ipa/migration and authenticate using their LDAP password in order to generate their Kerberos credentials.

Migration is disabled by default. Use the command ipa config-mod to enable it:

ipa config-mod —enable-migration=TRUE

If a base DN is not provided with —basedn then IPA will use either the value of defaultNamingContext if it is set or the first value in namingContexts set in the root of the remote LDAP server.

Users are added as members to the default user group. This can be a time-intensive task so during migration this is done in a batch mode for every 100 users. As a result there will be a window in which users will be added to IPA but will not be members of the default user group.

EXAMPLES

The simplest migration, accepting all defaults:
ipa migrate-ds ldap://ds.example.com:389
Specify the user and group container. This can be used to migrate user

and group data from an IPA v1 server:
ipa migrate-ds --user-container='cn=users,cn=accounts' $
    --group-container='cn=groups,cn=accounts' $
    ldap://ds.example.com:389
Since IPA v2 server already contain predefined groups that may collide with

groups in migrated (IPA v1) server (for example admins, ipausers), users

having colliding group as their primary group may happen to belong to

an unknown group on new IPA v2 server.

Use —group-overwrite-gid option to overwrite GID of already existing groups

to prevent this issue:
ipa migrate-ds --group-overwrite-gid $
    --user-container='cn=users,cn=accounts' $
    --group-container='cn=groups,cn=accounts' $
    ldap://ds.example.com:389
Migrated users or groups may have object class and accompanied attributes

unknown to the IPA v2 server. These object classes and attributes may be

left out of the migration process:
ipa migrate-ds --user-container='cn=users,cn=accounts' $
   --group-container='cn=groups,cn=accounts' $
   --user-ignore-objectclass=radiusprofile $
   --user-ignore-attribute=radiusgroupname $
   ldap://ds.example.com:389

LOGGING

Migration will log warnings and errors to the Apache error log. This file should be evaluated post-migration to correct or investigate any issues that were discovered.

For every 100 users migrated an info-level message will be displayed to give the current progress and duration to make it possible to track the progress of migration.

If the log level is debug, either by setting debug = True in /etc/ipa/default.conf or /etc/ipa/server.conf, then an entry will be printed for each user added plus a summary when the default user group is updated.

Use Cases

1. Migrating from 389 Directory Server to IPA

Organization running standalone 389 Directory Server (formerly Red Hat Directory Server) wants to migrate 5000 users and 200 groups to FreeIPA for integrated identity management.

# Enable migration mode on IPA server
ipa config-mod --enable-migration=TRUE

# Verify migration is enabled
ipa config-show | grep "Migration mode"
# Should show: Migration mode: TRUE

# Test connection to source 389-ds server
ldapsearch -x -H ldap://old-ds.example.com:389 \
  -D "cn=Directory Manager" -W \
  -b "ou=People,dc=example,dc=com" \
  "(objectClass=person)" dn | head -20

# Perform migration
# Bind as Directory Manager to access userPassword attributes
ipa migrate-ds ldap://old-ds.example.com:389 \
  --bind-dn="cn=Directory Manager" \
  --user-container="ou=People" \
  --group-container="ou=Groups" \
  --base-dn="dc=example,dc=com" \
  --schema=RFC2307bis \
  --continue

# Output shows migration progress:
# Migrating users from ou=People,dc=example,dc=com...
# 100 users migrated (elapsed: 15s)
# 200 users migrated (elapsed: 30s)
# ...
# Migration complete: 4985 users, 198 groups (15 skipped)

# Check Apache error log for detailed migration issues
tail -100 /var/log/httpd/error_log | grep -i migrate

# Instruct users to complete migration
# Send email: "Visit https://ipa.example.com/ipa/migration to complete your account migration"

Result: 4985 users and 198 groups migrated to IPA. 15 entries skipped due to conflicts (existing users). Users must visit migration page to convert LDAP passwords to Kerberos credentials.

2. Migrating from IPA v1 to IPA v4

Legacy IPA v1 deployment needs to migrate to modern IPA v4 with new features and supported platform.

# IPA v1 uses different container DNs than default
# User container: cn=users,cn=accounts,dc=example,dc=com
# Group container: cn=groups,cn=accounts,dc=example,dc=com

# Enable migration on new IPA v4 server
ipa config-mod --enable-migration=TRUE

# Migrate from IPA v1 server with correct container paths
ipa migrate-ds ldap://old-ipa-v1.example.com:389 \
  --bind-dn="cn=Directory Manager" \
  --user-container="cn=users,cn=accounts" \
  --group-container="cn=groups,cn=accounts" \
  --base-dn="dc=example,dc=com" \
  --schema=RFC2307bis \
  --group-overwrite-gid \
  --continue

# --group-overwrite-gid is critical for IPA v1 → IPA v4
# Prevents GID conflicts for default groups (admins, ipausers)

# Verify default groups GIDs were overwritten
ipa group-show admins | grep GID
ipa group-show ipausers | grep GID

# Migrate SUDO rules separately (not handled by migrate-ds)
# Extract from old IPA v1:
ldapsearch -x -H ldap://old-ipa-v1.example.com -D "cn=Directory Manager" -W \
  -b "cn=sudorules,cn=sudo,dc=example,dc=com" \
  "(objectClass=ipaSudoRule)" > sudorules.ldif

# Import sudo rules (requires manual conversion to IPA v4 format)

Result: Users and groups migrated from IPA v1 to IPA v4. GID conflicts resolved with --group-overwrite-gid. SUDO rules require manual migration.

3. Migrating NIS Users to IPA

Organization retiring legacy NIS (Network Information Service) infrastructure wants to migrate 1200 user accounts to FreeIPA.

# NIS data must first be exported to LDAP
# On NIS server, export NIS maps to LDIF
ypcat passwd > passwd.txt
ypcat group > group.txt

# Import NIS data into temporary 389-ds instance
# (Use migration scripts or nis2ldif utility)
# Assume temporary DS at ldap://nis-migration-staging.example.com

# Verify staging DS has data
ldapsearch -x -H ldap://nis-migration-staging.example.com:389 \
  -b "ou=People,dc=example,dc=com" \
  "(uid=*)" dn | wc -l

# Enable migration on IPA
ipa config-mod --enable-migration=TRUE

# Migrate from staging LDAP server
ipa migrate-ds ldap://nis-migration-staging.example.com:389 \
  --bind-dn="cn=Directory Manager" \
  --user-container="ou=People" \
  --group-container="ou=Groups" \
  --base-dn="dc=example,dc=com" \
  --schema=RFC2307 \
  --continue

# NIS uses RFC2307 schema (memberUid for groups)

# Handle NIS netgroups separately
# FreeIPA netgroups require manual migration from NIS netgroups

# Users must set new passwords via migration page
# NIS passwords (DES crypt) cannot be directly migrated to Kerberos

Result: NIS users migrated to IPA via temporary LDAP staging server. Users must reset passwords through migration portal. Netgroups require manual recreation.

4. Selective Migration Excluding Service Accounts

Migrating user directory but need to exclude system/service accounts that should not be in IPA.

# Identify service accounts to exclude
ldapsearch -x -H ldap://old-ds.example.com:389 \
  -D "cn=Directory Manager" -W \
  -b "ou=People,dc=example,dc=com" \
  "(uid=svc_*)" dn

# Create exclusion list
cat > exclude-users.txt <<EOF
svc_jenkins
svc_nagios
svc_backup
svc_legacy
system_account
EOF

# Migrate with exclusions
ipa config-mod --enable-migration=TRUE

ipa migrate-ds ldap://old-ds.example.com:389 \
  --bind-dn="cn=Directory Manager" \
  --user-container="ou=People" \
  --group-container="ou=Groups" \
  --base-dn="dc=example,dc=com" \
  --exclude-users="svc_jenkins,svc_nagios,svc_backup,svc_legacy,system_account" \
  --exclude-groups="legacy-admins,deprecated-group" \
  --continue

# Verify excluded users were not migrated
ipa user-find svc_jenkins
# Should return: 0 users matched

Result: Human user accounts migrated to IPA while service accounts and deprecated groups excluded from migration. Clean migration without legacy cruft.

5. Migrating with Custom Object Classes and Attributes

Source LDAP server has custom schema extensions (e.g., RADIUS attributes) that are unknown to IPA and must be stripped during migration.

# Identify custom object classes in source LDAP
ldapsearch -x -H ldap://old-ds.example.com:389 \
  -D "cn=Directory Manager" -W \
  -b "ou=People,dc=example,dc=com" \
  "(objectClass=*)" objectClass | sort -u

# Output shows:
# objectClass: inetOrgPerson
# objectClass: posixAccount
# objectClass: radiusprofile ← custom class

# Identify custom attributes
ldapsearch -x -H ldap://old-ds.example.com:389 \
  -D "cn=Directory Manager" -W \
  -b "ou=People,dc=example,dc=com" \
  "(uid=testuser)" + | grep radius

# Output shows custom attributes:
# radiusGroupName: wifi-users
# radiusReplyMessage: Welcome

# Migrate ignoring custom object classes and attributes
ipa config-mod --enable-migration=TRUE

ipa migrate-ds ldap://old-ds.example.com:389 \
  --bind-dn="cn=Directory Manager" \
  --user-container="ou=People" \
  --group-container="ou=Groups" \
  --base-dn="dc=example,dc=com" \
  --user-ignore-objectclass=radiusprofile \
  --user-ignore-attribute=radiusGroupName \
  --user-ignore-attribute=radiusReplyMessage \
  --continue

# Custom schema elements stripped during migration
# Only IPA-compatible attributes preserved

Result: Users migrated to IPA without custom RADIUS schema extensions. Standard POSIX and InetOrgPerson attributes preserved. Custom attributes documented for potential manual re-implementation if needed.

6. Migrating with TLS/SSL to Secure Password Transfer

Migration involves transferring user passwords from source LDAP server. Use TLS to encrypt migration traffic.

# Download source LDAP server's CA certificate
openssl s_client -connect old-ds.example.com:636 \
  -showcerts </dev/null 2>/dev/null | \
  openssl x509 -outform PEM > /tmp/old-ds-ca.pem

# Verify certificate
openssl x509 -in /tmp/old-ds-ca.pem -text -noout | grep Issuer

# Enable migration
ipa config-mod --enable-migration=TRUE

# Migrate using LDAPS (port 636) with CA certificate
ipa migrate-ds ldaps://old-ds.example.com:636 \
  --bind-dn="cn=Directory Manager" \
  --user-container="ou=People" \
  --group-container="ou=Groups" \
  --base-dn="dc=example,dc=com" \
  --ca-cert-file=/tmp/old-ds-ca.pem \
  --continue

# Migration traffic encrypted via TLS
# Password hashes transferred securely

# Clean up CA certificate
rm /tmp/old-ds-ca.pem

Result: User passwords migrated over encrypted TLS connection, protecting sensitive password hashes during transfer. CA certificate validation ensures connecting to legitimate source LDAP server.

7. Debugging Failed Migration

Migration fails with generic errors. Administrator needs to diagnose issues using detailed logging.

# Enable debug logging on IPA server
echo "debug = True" >> /etc/ipa/server.conf

# Restart Apache to apply debug setting
systemctl restart httpd

# Attempt migration with debug logging
ipa migrate-ds ldap://old-ds.example.com:389 \
  --bind-dn="cn=Directory Manager" \
  --user-container="ou=People" \
  --group-container="ou=Groups" \
  --base-dn="dc=example,dc=com" \
  --continue

# Monitor Apache error log in real-time
tail -f /var/log/httpd/error_log | grep -i migrate

# Logs show detailed errors for each user:
# [error] Failed to migrate user uid=alice: Invalid syntax in homeDirectory
# [error] Failed to migrate user uid=bob: uidNumber already exists

# Review complete error log after migration
grep -i "migrate\|error" /var/log/httpd/error_log > migration-errors.txt

# Analyze errors and fix source data or use --user-ignore-attribute
# to skip problematic attributes

# Disable debug logging after troubleshooting
sed -i '/debug = True/d' /etc/ipa/server.conf
systemctl restart httpd

Result: Debug logging revealed specific user migration failures due to invalid homeDirectory paths and duplicate uidNumbers. Issues corrected in source LDAP before re-attempting migration.

8. Post-Migration Password Reset via Migration Portal

Users migrated from LDAP need to complete password migration to obtain Kerberos credentials.

# Verify migration portal is accessible
curl -I https://ipa.example.com/ipa/migration
# Should return 200 OK

# Check migration mode is enabled
ipa config-show | grep "Migration mode"
# Migration mode: TRUE

# Instruct users to visit migration portal
# User workflow:
# 1. Visit https://ipa.example.com/ipa/migration
# 2. Enter username and OLD LDAP password
# 3. System validates LDAP password, generates Kerberos credentials
# 4. User can now use kinit with same password

# Monitor migration portal usage
grep "migration" /var/log/httpd/access_log | grep -c "POST"
# Shows number of users who completed migration

# After all users migrated, disable migration mode
ipa config-mod --enable-migration=FALSE

# Verify migration disabled
ipa config-show | grep "Migration mode"
# Migration mode: FALSE

Result: Users completed password migration through web portal, obtaining Kerberos credentials. Migration mode disabled after all users migrated.

9. Migrating Subtree with Organizational Units

Source LDAP has nested organizational structure (multiple OUs) that needs to be flattened during migration to IPA.

# Source LDAP structure:
# dc=example,dc=com
#   ou=People
#     ou=Engineering (users here)
#     ou=Sales (users here)
#     ou=HR (users here)

# IPA doesn't support nested user OUs - all users in flat structure

# Migrate using subtree scope to search nested OUs
ipa config-mod --enable-migration=TRUE

ipa migrate-ds ldap://old-ds.example.com:389 \
  --bind-dn="cn=Directory Manager" \
  --user-container="ou=People" \
  --group-container="ou=Groups" \
  --base-dn="dc=example,dc=com" \
  --scope=subtree \
  --continue

# --scope=subtree searches all levels under ou=People
# Finds users in ou=Engineering,ou=People,dc=example,dc=com
# And users in ou=Sales,ou=People,dc=example,dc=com
# All migrated to flat cn=users,cn=accounts,dc=example,dc=com

# Preserve organizational structure using groups
ipa group-add engineering --desc="Engineering department"
ipa group-add sales --desc="Sales department"
ipa group-add hr --desc="HR department"

# Manually assign users to department groups based on original OU
# (Requires custom scripting to map original ou to IPA groups)

Result: Users from nested organizational units migrated to IPA’s flat user structure. Organizational hierarchy preserved through group memberships rather than LDAP OUs.

10. Migrating Without Default Group Assignment

Large migration (10,000+ users) where adding all users to default group causes performance issues. Disable default group assignment.

# Enable migration
ipa config-mod --enable-migration=TRUE

# Migrate without adding users to default group
ipa migrate-ds ldap://old-ds.example.com:389 \
  --bind-dn="cn=Directory Manager" \
  --user-container="ou=People" \
  --group-container="ou=Groups" \
  --base-dn="dc=example,dc=com" \
  --use-default-group=FALSE \
  --continue

# Migration completes much faster without group membership updates
# Users exist but are not in ipausers group

# Post-migration, add users to ipausers in batches
# Create batch script to add 1000 users at a time

for i in {0..9}; do
  # Get users 0-999, 1000-1999, etc.
  users=$(ipa user-find --sizelimit=1000 --pkey-only --raw | \
    grep 'uid:' | awk '{print $2}' | tail -n +$((i*1000+1)) | head -n 1000)

  # Add batch to ipausers
  ipa group-add-member ipausers --users=${users// /,}

  echo "Batch $i complete ($(date))"
  sleep 5
done

# Verify all users in ipausers
ipa group-show ipausers | grep "member users" | wc -w

Result: Migration of 10,000 users completed rapidly without default group assignment overhead. Users added to ipausers group in post-migration batches to avoid migration timeouts.

Security Considerations

Password Exposure During Migration

User passwords (hashed) are transferred from the source LDAP server to IPA during migration. If migration uses unencrypted LDAP (ldap:// on port 389), password hashes are transmitted in plaintext over the network, vulnerable to interception. An attacker capturing migration traffic can extract password hashes and perform offline cracking attacks. Always use LDAPS (ldaps:// on port 636) with --ca-cert-file to encrypt migration traffic. Verify the source LDAP server’s certificate matches the expected CA to prevent man-in-the-middle attacks. In high-security environments, perform migration over isolated networks or VPN tunnels.

Migration Mode Enables Unauthenticated Attacks

When migration mode is enabled (ipa config-mod --enable-migration=TRUE), the migration web portal at /ipa/migration becomes accessible to anonymous users. While the portal requires users to authenticate with their LDAP password, it creates an unauthenticated password validation endpoint that attackers can use for brute-force or password-spraying attacks against migrated user accounts. After migration completes, immediately disable migration mode (--enable-migration=FALSE) to remove this attack surface. Monitor /var/log/httpd/access_log for excessive POST requests to /ipa/migration during the migration window, which may indicate brute-force attempts.

Bind DN Credential Protection

The --bind-dn password (typically cn=Directory Manager) grants full read access to the source LDAP server, including sensitive attributes like userPassword hashes. This password is provided as a command-line argument to ipa migrate-ds, which may be visible to other users via ps command output during migration. Use process protection to prevent credential exposure: run migration from a restricted console session, consider using environment variables instead of command-line arguments (if supported), and ensure command history is disabled or cleared after migration (history -c). Rotate the Directory Manager password on the source LDAP server immediately after migration completes.

Migrated Users Lack Kerberos Credentials

After migration, users have only LDAP passwords stored in IPA, not Kerberos credentials. This creates an inconsistent authentication state where users cannot use kinit or Kerberos-based SSO until they complete the migration portal workflow. Users who never visit the migration portal remain in this incomplete state indefinitely. This may create support burden and confusion. Communicate migration process clearly to users, send reminder emails, and monitor which users have not completed migration using custom LDAP queries for users lacking krbPrincipalKey attribute. Consider setting password expiration to force migration portal usage.

Group Membership Timing Window

During migration, users are added to IPA in batches of 100, but group membership updates (adding to ipausers default group) lag behind. This creates a timing window (potentially minutes for large migrations) where users exist in IPA but are not members of the default user group. During this window, HBAC rules, sudo rules, or other policies relying on ipausers group membership may not apply to newly migrated users, potentially denying legitimate access or failing to apply security policies. Plan migration during maintenance windows when authorization inconsistencies are acceptable, or use --use-default-group=FALSE and add users to groups in post-migration batches.

Duplicate uidNumber/gidNumber Conflicts

If the source LDAP server contains users or groups with uidNumber/gidNumber values that already exist in IPA (e.g., migrating from IPA v1 which has overlapping default group GIDs), migration may fail or create conflicts. Without --group-overwrite-gid, migration skips groups with conflicting GIDs, potentially leaving users with primary groups that don’t exist in the new IPA server. This can break file permissions, user logins, and group-based access controls. Use --group-overwrite-gid when migrating from IPA v1 or any source with known GID overlaps. Audit uidNumber/gidNumber ranges in source LDAP to identify potential conflicts before migration.

Schema Compatibility Plugin Performance Impact

If IPA’s schema compatibility plugin is enabled during migration (--with-compat), the plugin reformats each migrated entry for RFC2307 compatibility in real-time, significantly increasing CPU load and migration duration. For large migrations (>1000 users), this can cause IPA server resource exhaustion, slow migration to unusable speeds, or trigger timeout failures. Disable schema compat plugin before migration (ipa-compat-manage disable), perform migration, then re-enable (ipa-compat-manage enable). If migration must occur with compat enabled (due to client dependencies), plan for extended migration duration and increased server load.

Excluded Users Still in Source LDAP

Using --exclude-users prevents specific users from migrating, but does not disable or delete those users from the source LDAP server. If the source LDAP remains operational during transition, excluded users can continue authenticating to old systems. This creates split-brain scenarios where some users authenticate to IPA, others to legacy LDAP. Document which users were excluded and why, establish cutover timeline for decommissioning source LDAP, and ensure excluded users are either migrated later (manual creation in IPA) or documented as intentionally not migrated (e.g., service accounts migrated via different mechanism).

Custom Attributes Lost During Migration

Attributes not recognized by IPA’s schema are silently dropped during migration unless explicitly ignored with --user-ignore-attribute or --group-ignore-attribute. Users may have custom attributes (employee ID, cost center, custom fields) that are lost without warning. If these attributes are referenced by downstream systems or provisioning workflows, data loss creates broken integrations. Before migration, audit source LDAP schema for custom attributes, document which attributes will be lost, and establish plan for preserving critical custom data (extend IPA schema, store in custom LDAP attributes, or export to external system).

Migration Does Not Transfer Access Controls

Source LDAP server may have ACIs (Access Control Instructions) defining who can read/modify which attributes or entries. FreeIPA migration does not transfer these ACIs—IPA uses its own RBAC system (roles, privileges, permissions). After migration, all user data inherits default IPA ACLs, which may be more permissive or restrictive than source LDAP. Review source LDAP ACIs before migration, document any restrictive access controls (e.g., “only HR can read employee numbers”), and implement equivalent controls in IPA using custom permissions and roles. Default IPA permissions may expose previously restricted data.

Insufficient Logging of Migration Failures

Failed migrations (users/groups that could not be migrated) are logged to Apache error log (/var/log/httpd/error_log), but this log may rotate or be overwritten before administrators review it. In continuous mode (--continue), migration proceeds despite errors, and final output only shows summary counts without details of which specific users failed. Failed users remain in source LDAP without IPA accounts, potentially being forgotten. After migration, immediately archive error logs to persistent storage, parse error log to extract list of failed users, and establish process to manually investigate and migrate failed accounts.

Migrated Passwords Use Weak Hashing

Source LDAP server may use weak password hashing algorithms (DES, MD5, salted SHA1) that are preserved during migration to IPA. While IPA stores these hashes, they remain vulnerable to offline cracking attacks if IPA’s LDAP is compromised. Migration portal workflow generates Kerberos credentials but does not replace the old LDAP password hash. Force users to change passwords after migration using password expiration policies: ipa pwpolicy-mod --maxlife=1 (1 day) to force immediate password change, which generates new strong Kerberos key and LDAP password hash. This eliminates weak source LDAP hashes.

Troubleshooting

Migration Fails with “Migration mode is disabled”

Symptoms: Running ipa migrate-ds returns error “Migration mode is disabled”.

Diagnosis:

# Check migration mode status
ipa config-show | grep "Migration mode"
# Shows: Migration mode: FALSE

Resolution: Migration must be explicitly enabled before using migrate-ds. Enable migration: ipa config-mod --enable-migration=TRUE. Verify enabled: ipa config-show | grep "Migration mode". After migration completes, disable migration mode for security: ipa config-mod --enable-migration=FALSE.

Cannot Connect to Source LDAP Server

Symptoms: ipa migrate-ds fails immediately with “Can’t contact LDAP server” error.

Diagnosis:

# Test network connectivity to source LDAP
ping old-ds.example.com

# Test LDAP port
telnet old-ds.example.com 389
# Or for LDAPS:
openssl s_client -connect old-ds.example.com:636

# Test LDAP bind
ldapsearch -x -H ldap://old-ds.example.com:389 \
  -D "cn=Directory Manager" -W \
  -b "dc=example,dc=com" \
  "(objectClass=*)" dn

Resolution: Verify source LDAP server is running and accessible from IPA server. Check firewall rules between IPA and source LDAP. Verify correct hostname, port (389 for LDAP, 636 for LDAPS), and LDAP URI format (ldap:// or ldaps://). If using LDAPS, verify TLS certificate with --ca-cert-file. Ensure source LDAP server accepts connections from IPA server’s IP address.

Authentication Failure with Bind DN

Symptoms: Migration fails with “Invalid credentials” or “Bind failed” error.

Diagnosis:

# Test bind credentials
ldapwhoami -x -H ldap://old-ds.example.com:389 \
  -D "cn=Directory Manager" -W

# Check bind DN syntax
# Common formats:
# - cn=Directory Manager
# - cn=admin,dc=example,dc=com
# - uid=admin,ou=Administrators,dc=example,dc=com

Resolution: Verify bind DN and password are correct. The bind DN must have read access to userPassword attribute to migrate password hashes (typically requires Directory Manager or equivalent admin). Try authenticating with bind DN outside of migration to isolate issue. Check source LDAP logs for authentication failures. Ensure bind password doesn’t contain special characters that need escaping.

User/Group Container Not Found

Symptoms: Migration completes but finds 0 users or 0 groups. “No such object” error in logs.

Diagnosis:

# Verify container DNs exist in source LDAP
ldapsearch -x -H ldap://old-ds.example.com:389 \
  -D "cn=Directory Manager" -W \
  -b "ou=People,dc=example,dc=com" \
  -s base "(objectClass=*)" dn

# Common user container DNs:
# - ou=People,dc=example,dc=com
# - cn=users,cn=accounts,dc=example,dc=com (IPA v1)
# - ou=users,dc=example,dc=com

# Check actual structure
ldapsearch -x -H ldap://old-ds.example.com:389 \
  -D "cn=Directory Manager" -W \
  -b "dc=example,dc=com" \
  -s one "(objectClass=organizationalUnit)" dn

Resolution: Identify correct user and group containers in source LDAP. Use --user-container and --group-container to specify correct relative DNs (relative to base DN, not full DN). For IPA v1 migration, use --user-container="cn=users,cn=accounts" and --group-container="cn=groups,cn=accounts". Use --base-dn to specify correct base DN if auto-detection fails.

Migration Completes But Many Users Skipped

Symptoms: Migration summary shows “1500 users migrated, 500 skipped”. Many users missing in IPA.

Diagnosis:

# Check Apache error log for skip reasons
grep -i "skipped\|already exists" /var/log/httpd/error_log

# Common skip reasons:
# - User already exists in IPA (duplicate)
# - uidNumber conflict
# - Invalid attribute values
# - Missing required attributes

# Identify which users were skipped
# Compare source LDAP user list with IPA user list
ldapsearch -x -H ldap://old-ds.example.com:389 \
  -D "cn=Directory Manager" -W \
  -b "ou=People,dc=example,dc=com" \
  "(objectClass=person)" uid | grep "uid:" | sort > source-users.txt

ipa user-find --pkey-only --sizelimit=0 | grep "User login:" | awk '{print $3}' | sort > ipa-users.txt

comm -23 source-users.txt ipa-users.txt > skipped-users.txt

Resolution: Review error log to understand why users were skipped. If skipped due to “already exists”, users may have been pre-created in IPA—verify and reconcile manually. If skipped due to invalid attributes, use --user-ignore-attribute to skip problematic attributes. For uidNumber conflicts, adjust source LDAP uidNumbers or use custom scripts to migrate users with new uidNumbers.

TLS Certificate Verification Failure

Symptoms: Migration with LDAPS fails with “certificate verify failed” or “SSL certificate problem” error.

Diagnosis:

# Test TLS connection to source LDAP
openssl s_client -connect old-ds.example.com:636 -showcerts

# Check certificate validity
openssl s_client -connect old-ds.example.com:636 </dev/null 2>/dev/null | \
  openssl x509 -noout -dates

# Verify hostname matches certificate
openssl s_client -connect old-ds.example.com:636 </dev/null 2>/dev/null | \
  openssl x509 -noout -subject

Resolution: Download source LDAP server’s CA certificate and provide to migration with --ca-cert-file. Extract CA cert: openssl s_client -connect old-ds.example.com:636 -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM > /tmp/ca.pem. Use in migration: ipa migrate-ds ldaps://old-ds.example.com:636 --ca-cert-file=/tmp/ca.pem .... If using self-signed certificate, ensure CA cert is complete certificate chain.

RFC2307 vs RFC2307bis Schema Mismatch

Symptoms: Group memberships not preserved during migration. Users migrated but group member lists empty.

Diagnosis:

# Check source LDAP group schema
ldapsearch -x -H ldap://old-ds.example.com:389 \
  -D "cn=Directory Manager" -W \
  -b "ou=Groups,dc=example,dc=com" \
  "(cn=testgroup)" member memberUid

# RFC2307: Uses memberUid (username only)
# memberUid: alice
# memberUid: bob

# RFC2307bis: Uses member or uniqueMember (full DN)
# member: uid=alice,ou=People,dc=example,dc=com
# member: uid=bob,ou=People,dc=example,dc=com

Resolution: Specify correct schema with --schema=RFC2307 or --schema=RFC2307bis. Default is RFC2307bis. If source LDAP uses memberUid (username), use --schema=RFC2307. If source uses member (full DN), use --schema=RFC2307bis. Incorrect schema selection causes group memberships to fail during migration.

Migration Timeout on Large User Base

Symptoms: Migration fails after 10-15 minutes with timeout error. Only partial user migration completed.

Diagnosis:

# Check number of users to migrate
ldapsearch -x -H ldap://old-ds.example.com:389 \
  -D "cn=Directory Manager" -W \
  -b "ou=People,dc=example,dc=com" \
  "(objectClass=person)" dn | grep -c "^dn:"

# Check Apache timeout settings
grep Timeout /etc/httpd/conf/httpd.conf
# Default: Timeout 60

Resolution: For migrations >5000 users, increase Apache timeout: Edit /etc/httpd/conf/httpd.conf, set Timeout 600 (10 minutes) or higher. Restart Apache: systemctl restart httpd. Alternatively, disable schema compat plugin before migration (ipa-compat-manage disable) to reduce per-user processing time. For very large migrations (>10k users), consider migrating in batches using --exclude-users to exclude users already migrated in previous runs.

Custom Object Class Causes Migration Failure

Symptoms: Migration fails with “Unknown object class” or “Object class violation” errors for specific users.

Diagnosis:

# Identify custom object classes in source
ldapsearch -x -H ldap://old-ds.example.com:389 \
  -D "cn=Directory Manager" -W \
  -b "ou=People,dc=example,dc=com" \
  "(uid=faileduser)" objectClass

# Example output showing custom class:
# objectClass: inetOrgPerson
# objectClass: posixAccount
# objectClass: customEmployeeClass ← Not in IPA schema

Resolution: Use --user-ignore-objectclass to exclude unknown object classes: ipa migrate-ds ... --user-ignore-objectclass=customEmployeeClass. This removes the object class but preserves attributes IPA understands. If custom object class has required attributes IPA doesn’t support, also use --user-ignore-attribute to exclude those attributes. Migration will strip custom schema elements and migrate only IPA-compatible data.

Group GID Conflicts with Existing IPA Groups

Symptoms: Group migration skipped for critical groups like “admins” or “ipausers”. Error logs show “GID already exists”.

Diagnosis:

# Check if GIDs conflict
ipa group-show admins | grep GID
# GID: 500

ldapsearch -x -H ldap://old-ds.example.com:389 \
  -D "cn=Directory Manager" -W \
  -b "ou=Groups,dc=example,dc=com" \
  "(cn=admins)" gidNumber
# gidNumber: 600 (different, but maybe another conflict)

# List all IPA group GIDs
ipa group-find --all | grep -E "Group name:|GID:"

Resolution: When migrating from IPA v1 or LDAP with overlapping GIDs, use --group-overwrite-gid to force IPA to overwrite existing group GIDs with migrated values. This is necessary when source and destination have same group names but different GIDs. WARNING: This changes GIDs on destination, which may break file ownership. Alternative: Rename conflicting groups in source LDAP before migration.

Migration Portal Inaccessible After Migration

Symptoms: Users cannot access https://ipa.example.com/ipa/migration to complete password migration.

Diagnosis:

# Check if migration mode still enabled
ipa config-show | grep "Migration mode"
# Should show: Migration mode: TRUE (if portal should be accessible)

# Test portal HTTP accessibility
curl -I https://ipa.example.com/ipa/migration

# Check Apache error log
grep migration /var/log/httpd/error_log

Resolution: Migration portal only functions when migration mode is enabled. Verify ipa config-mod --enable-migration=TRUE. Ensure HTTPS is working (port 443 accessible). Check Apache virtual host configuration includes migration endpoint. If migration mode is enabled but portal returns 404, restart Apache: systemctl restart httpd. Verify IPA web UI is functioning: https://ipa.example.com/ipa/ui.

Users Cannot Authenticate After Migration

Symptoms: Users migrated successfully but cannot login via SSH or kinit. “Preauthentication failed” errors.

Diagnosis:

# Verify user exists in IPA
ipa user-show alice

# Check if user has Kerberos principal key (password)
ipa user-show alice --all | grep -i krbprincipalkey
# If empty, user has not completed migration portal workflow

# Test kinit
kinit alice
# Error: Preauthentication failed (user has LDAP password but no Kerberos creds)

Resolution: Migrated users must visit migration portal (https://ipa.example.com/ipa/migration) to convert LDAP password to Kerberos credentials. User enters username and original LDAP password, portal generates Kerberos keys. Until user completes this step, only LDAP authentication works (not Kerberos/SSH). Communicate migration portal requirement to all users. Alternatively, admins can force password reset: ipa user-mod alice --password, which generates Kerberos credentials immediately.

Migrated Users Have Wrong UID/GID

Symptoms: After migration, files owned by users show numeric UIDs instead of usernames. UID/GID mismatches cause permission issues.

Diagnosis:

# Check migrated user's UID
ipa user-show alice | grep UID
# UID: 10001

# Check file ownership expectations
ls -ln /home/alice
# Shows numeric UID instead of alice

# Compare source LDAP UID
ldapsearch -x -H ldap://old-ds.example.com:389 \
  -D "cn=Directory Manager" -W \
  -b "ou=People,dc=example,dc=com" \
  "(uid=alice)" uidNumber

Resolution: Migration preserves uidNumber from source LDAP. If file ownership is wrong, source LDAP may have had different uidNumbers than expected. Options: (1) Correct uidNumbers in source LDAP before migration and re-migrate, (2) Use chown -R alice:alice /home/alice to fix file ownership after migration, (3) Migrate UIDs as-is and accept file ownership changes (appropriate if old LDAP is being decommissioned and users are moving to new systems). UID/GID cannot be easily changed in IPA after user creation without data loss risk.

High CPU Load During Migration

Symptoms: IPA server experiences high CPU load, migration very slow (>1 hour for 1000 users).

Diagnosis:

# Monitor CPU usage
top
# Look for httpd, ns-slapd (LDAP), ipa_memcached processes

# Check if schema compat plugin enabled
ipa-compat-manage status
# Shows: Schema compat is enabled

# Monitor migration progress from Apache error log
tail -f /var/log/httpd/error_log | grep "users migrated"

Resolution: Schema compatibility plugin causes significant CPU overhead during migration. Disable before migration: ipa-compat-manage disable, then migrate, then re-enable: ipa-compat-manage enable. If migration must occur with compat enabled (due to active clients), plan for extended migration duration and ensure IPA server has adequate CPU resources. Consider migrating during low-usage period to reduce resource contention.

Commands

migrate-ds

Usage: ipa [global-options] migrate-ds LDAP-URI PASSWORD [options]

Migrate users and groups from DS to IPA.

Arguments

Argument	Required	Description
`LDAP-URI`	yes	LDAP URI of DS server to migrate from

PASSWORD yes bind password

Options

Option	Description
`--bind-dn BIND-DN`	Bind DN
`--user-container USER-CONTAINER`	DN of container for users in DS relative to base DN
`--group-container GROUP-CONTAINER`	DN of container for groups in DS relative to base DN
`--user-objectclass USER-OBJECTCLASS`	Objectclasses used to search for user entries in DS
`--group-objectclass GROUP-OBJECTCLASS`	Objectclasses used to search for group entries in DS
`--user-ignore-objectclass USER-IGNORE-OBJECTCLASS`	Objectclasses to be ignored for user entries in DS
`--user-ignore-attribute USER-IGNORE-ATTRIBUTE`	Attributes to be ignored for user entries in DS
`--group-ignore-objectclass GROUP-IGNORE-OBJECTCLASS`	Objectclasses to be ignored for group entries in DS
`--group-ignore-attribute GROUP-IGNORE-ATTRIBUTE`	Attributes to be ignored for group entries in DS
`--group-overwrite-gid`	When migrating a group already existing in IPA domain overwrite the group GID and report as success
`--schema SCHEMA`	The schema used on the LDAP server. Supported values are RFC2307 and RFC2307bis. The default is RFC2307bis
`--continue`	Continuous operation mode. Errors are reported but the process continues
`--base-dn BASE-DN`	Base DN on remote LDAP server
`--with-compat`	Allows migration despite the usage of compat plugin
`--ca-cert-file CA-CERT-FILE`	Load CA certificate of LDAP server from FILE
`--use-default-group USE-DEFAULT-GROUP`	Add migrated users without a group to a default group (default: true)
`--scope SCOPE`	LDAP search scope for users and groups: base, onelevel, or subtree. Defaults to onelevel
`--exclude-users EXCLUDE-USERS`	users to exclude from migration
`--exclude-groups EXCLUDE-GROUPS`	groups to exclude from migration

Use Cases

1. Migrating from 389 Directory Server to IPA

2. Migrating from IPA v1 to IPA v4

3. Migrating NIS Users to IPA

4. Selective Migration Excluding Service Accounts

5. Migrating with Custom Object Classes and Attributes

6. Migrating with TLS/SSL to Secure Password Transfer

7. Debugging Failed Migration

8. Post-Migration Password Reset via Migration Portal

9. Migrating Subtree with Organizational Units

10. Migrating Without Default Group Assignment

Security Considerations

Password Exposure During Migration

Migration Mode Enables Unauthenticated Attacks

Bind DN Credential Protection

Migrated Users Lack Kerberos Credentials

Group Membership Timing Window

Duplicate uidNumber/gidNumber Conflicts

Schema Compatibility Plugin Performance Impact

Excluded Users Still in Source LDAP

Custom Attributes Lost During Migration

Migration Does Not Transfer Access Controls

Insufficient Logging of Migration Failures

Migrated Passwords Use Weak Hashing

Troubleshooting

Migration Fails with “Migration mode is disabled”

Cannot Connect to Source LDAP Server

Authentication Failure with Bind DN

User/Group Container Not Found

Migration Completes But Many Users Skipped

TLS Certificate Verification Failure

RFC2307 vs RFC2307bis Schema Mismatch

Migration Timeout on Large User Base

Custom Object Class Causes Migration Failure

Group GID Conflicts with Existing IPA Groups

Migration Portal Inaccessible After Migration

Users Cannot Authenticate After Migration

Migrated Users Have Wrong UID/GID

High CPU Load During Migration

Commands

migrate-ds

Arguments

Options

Related Topics