Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 4. Migrating from one IdM server to another

Use the ipa-migrate tool to migrate all Identity Management (IdM) data, including configurations, schema, and database content, from one IdM server to another. This tool is useful for moving a deployment from staging to production or for migrating data between production servers.

4.1. IdM to IdM migration
Copy link

You can use the ipa-migrate admin tool to migrate IdM data between two servers, such as when moving a deployment from staging to production. Run the tool on the new, local IdM server to transfer schema, configuration, and database content from the original, remote IdM server.

Using the tool, you can transfer most of the data from the remote server:

  • Schema: All LDAP object classes and attributes.
  • Configuration: Core Directory Server settings (dse.ldif), including performance tuning, security settings, plugins, and database settings.
  • Database: Most subtrees and entries, including users, groups, roles, hosts, services, sudo rules, HBAC rules, and DNS records (optional).

However, for security reasons, some items are excluded:

  • Kerberos master key
  • Self-signed CA certificates and KRA keys
  • The admin and Directory Manager passwords
  • Data stored in Custodia

You can perform the migration online, using an LDAP connection, or offline, using LDIF files from the remote server. You can also combine the online and offline methods by using a mixed approach. For large databases, a mixed approach is often the most efficient. For example, you can migrate the configuration and schema online and then use an LDIF file for the database migration, which is faster and more stable than transferring thousands of entries over the network.

Before committing to a migration, you can perform a dry run to preview the changes without writing any data to the new server. You can also record the LDAP operations to an LDIF file for detailed inspection or for replaying the migration at a later time.

The ipa-migrate tool offers the following migration modes:

  • Production mode

    This mode assumes the remote server is a fully functional, production environment. It migrates all data, including DNA ranges, IDs, and SIDs, as is.

  • Staging mode

    This mode is intended for migrating from a staging environment. It does not migrate DNA ranges and ID attributes like uidNumber and gidNumber, but regenerates them on the new server.

The migration process automatically converts the remote server’s realm, domain, and suffixes to match the new local server’s configuration. You can choose whether to migrate ID ranges, and you have the option to skip migrating DNS records, configuration, or schema. Using the tool, you can also include non-IdM content stored in the database tree by specifying the subtree in a command-line option.

After a successful migration, you must re-enroll IdM clients to the new deployment, and users must reset their passwords to generate new Kerberos keys.

You can use the ipa-migrate tool in staging mode to transfer an IdM environment from a staging server to a production server, regenerating identity numbers for the new environment.

This example uses a mixed migration approach, where the database is migrated offline using an LDIF file for improved performance and stability, while the configuration and schema are migrated online. The migration is performed in staging-mode to ensure that identity numbers (UIDs/GIDs) are regenerated for the new production environment.

Prerequisites

  • You are using RHEL 10.1 or later.

  • On the new production (local) server:

    • You have performed a standard installation of IdM.
    • The IdM domain and realm are set to their final production values.

  • On the staging (remote) server:

    • You have root access to export the user database.
    • You have the Directory Manager password.

Procedure

  1. On the remote staging server, for example remote.server.com, export the userRoot database to an LDIF file, such as userroot.ldif:

    1. Stop the DS instance: 

      # dsctl slapd-EXAMPLE-COM stop

    2. Export the database: 

      # dsctl slapd-EXAMPLE-COM db2ldif userroot /root/userroot.ldif

    3. Restart the DS instance: 

      # dsctl slapd-EXAMPLE-COM start
  2. Copy the userroot.ldif to the new local production server, for example to /root/userroot.ldif.

  3. On the local production server, execute a dry run of the migration to validate the process and preview changes without writing any data. Use stage-mode to ensure that DNA ranges and ID attributes are reset for the new production environment: 

    # ipa-migrate stage-mode remote.server.com --db-ldif=/root/userroot.ldif --dryrun
  4. Review the output to confirm that the tool identifies the correct entries for migration.

  5. Execute the migration command without the --dryrun option. You will be prompted for the Directory Manager password for the remote server: 

    # ipa-migrate stage-mode remote.server.com --db-ldif=/root/userroot.ldif
    Note

    The migration process includes running the ipa-server-upgrade task, which may take a significant amount of time depending on the size of your database.

Verification

  1. On the new production server, verify that the IdM services are running correctly: 

    # ipactl status
  2. Confirm that IdM data, such as users, groups, and sudo rules, has been successfully migrated using ipa user-find and ipa sudorule-find.
Note

The primary log file for the migration tool is located at /var/log/ipa-migrate.log. This file is appended to on each run, preserving the history of multiple migration attempts.

Next steps

  1. Re-enroll clients: All IdM clients that were connected to the old staging server must be re-enrolled into the new production IdM deployment. You can follow the steps in Re-enrolling na IdM client.
  2. Migrate user passwords: Users must log in to generate new Kerberos keys, as passwords are not migrated directly. Inform your users about the need to reset their passwords upon their first login to the new production environment. See Managing user passwords in IdM.
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top