Migrating to Identity Management on RHEL 9

1. Upgrade the system to the latest RHEL 8 version.

   Important

   If you are migrating to RHEL 9.0, do not update to a newer version than RHEL 8.6. Migrating from RHEL 8.7 is only supported for RHEL 9.1.

2. Update the ipa-* packages to their latest version:

   [root@rhel8 ~]# dnf update ipa-*

   Copy to Clipboard Toggle word wrap
   Warning

   When upgrading multiple Identity Management (IdM) servers, wait at least 10 minutes between each upgrade.

   When two or more servers are upgraded simultaneously or with only short intervals between the upgrades, there is not enough time to replicate the post-upgrade data changes throughout the topology, which can result in conflicting replication events.

1. Install the latest version of Red Hat Enterprise Linux on the system. For more information, see Interactively installing RHEL from installation media.
2. Ensure the system is an IdM client enrolled into the domain for which rhel8.example.com IdM server is authoritative. For more information, see Installing an IdM client: Basic scenario.
3. Ensure the system meets the requirements for IdM server installation. See Preparing the system for IdM server installation.

4. Ensure you know the time server rhel8.example.com is synchronized with:

   [root@rhel8 ~]# ntpstat
   synchronised to NTP server (ntp.example.com) at stratum 3
      time correct to within 42 ms
      polling server every 1024 s

   Copy to Clipboard Toggle word wrap
5. Ensure the system is authorized for the installation of an IdM replica. See Authorizing the installation of a replica on an IdM client.

6. Update the ipa-* packages to their latest version:

   [root@rhel8 ~]# dnf update ipa-*

   Copy to Clipboard Toggle word wrap

Procedure

1. List the servers in the topology and the roles enabled on each server:

   [root@rhel7 ~]# ipa server-find --all
   ---------------------
   2 IPA servers matched
   ---------------------
     dn: cn=ipa1.example.com,cn=masters,cn=ipa,cn=etc,dc=example,dc=com
     Server name: ipa1.example.com
     Managed suffixes: domain, ca
     Min domain level: 1
     Max domain level: 1
     Enabled server roles: AD trust agent, AD trust controller, CA server, DNS server, IPA master, KRA server
   
     dn: cn=ipa2.example.com,cn=masters,cn=ipa,cn=etc,dc=example,dc=com
     Server name: ipa2.example.com
     Managed suffixes: domain, ca
     Min domain level: 1
     Max domain level: 1
     Enabled server roles: AD trust agent, AD trust controller, CA server, IPA master
   ----------------------------
   Number of entries returned 2
   ----------------------------

   Copy to Clipboard Toggle word wrap

2. Verify that the CA renewal master role is assigned to exactly one server:

   [root@rhel7 ~]# ipa config-show | grep "CA renewal master"
   IPA CA renewal master: ipa1.example.com

   Copy to Clipboard Toggle word wrap

3. Verify that the DNSSEC key master role is assigned to exactly one server:

   [root@rhel7 ~]# ipa dnsconfig-show | grep 'DNSSec key master'
   IPA DNSSec key master: ipa1.example.com

   Copy to Clipboard Toggle word wrap
4. Record which servers provide other critical roles (such as CA, DNS, KRA, AD trust agent, and AD trust controller). You will reference this list when assigning roles to new replicas or validating redundancy during migration.

5. If your IdM deployment is in a trust with an Active Directory (AD) forest, plan to ensure that during the migration:

   1. At least one trust controller remains online at all times.
   2. Whenever possible, each replica also runs the trust agent so that clients can resolve AD users regardless of which server they contact.
6. Review replication agreements and the site layout to confirm that each site keeps redundant connectivity throughout the migration: Replica topology examples.
7. Ensure that the number of replication agreements per server aligns with the long-term guideline of four or fewer links: Guidelines for connecting IdM replicas in a topology.

8. Run ipa-healthcheck to identify replication issues before you modify the topology:

   [root@rhel8 ~]# ipa-healthcheck --source=ipahealthcheck.ds.replication --source=ipahealthcheck.ipa.topology

   Copy to Clipboard Toggle word wrap

Procedure

1. On each server that will be decommissioned, display the DNA ID ranges currently allocated:

   [root@rhel7 ~]# ipa-replica-manage dnarange-show

   Copy to Clipboard Toggle word wrap

2. Display the next DNA range queued for allocation so you know what will be assigned after the current sub-range is consumed:

   [root@rhel7 ~]# ipa-replica-manage dnanextrange-show

   Copy to Clipboard Toggle word wrap
3. Record the collected ranges in your migration notes. You will reference these values when ensuring DNA range coverage on the new replica before decommissioning the old server. Losing a server that owns an unrecorded sub-range can block the creation of new users or groups.

Procedure

1. Run IdM Healthcheck on the server you plan to remove and resolve any issues so the topology is in a clean state before you begin: Using IdM Healthcheck to monitor your IdM environment.

2. Remove the server from the topology on a different replica. For example, to remove rhel8.example.com:

   [root@rhel9 ~]# ipa-replica-manage del rhel8.example.com --cleanup

   Copy to Clipboard Toggle word wrap

   Confirm the command completes successfully and that the removal is replicated to the remaining servers.

3. On the RHEL 8 host you are decommissioning, uninstall the IdM server to clean up services and certificates:

   [root@rhel8 ~]# ipa-server-install --uninstall

   Copy to Clipboard Toggle word wrap
4. Allow replication to converge across all remaining servers before you reinstall a replica with the same hostname. In high-latency environments, wait for at least one full replication cycle and confirm the host no longer appears in ipa server-find output.
5. After replication has fully converged and you have confirmed the old server no longer appears in the topology, proceed to install your new RHEL 9 replica using the reused hostname. See Installing the RHEL 9 replica.

6. After installation completes, run IdM Healthcheck on the new RHEL 9 replica to verify that no replication conflicts were introduced:

   [root@rhel9 ~]# ipa-healthcheck

   Copy to Clipboard Toggle word wrap

   Pay particular attention to replication-related checks to ensure the hostname reuse did not cause conflicts.

1. Review the replication agreements topology using the steps in either Viewing replication topology using the WebUI or Viewing topology suffixes using the CLI and Viewing topology segments using the CLI.

2. Install the IdM server software on rhel9.example.com to configure it as a replica of the RHEL 8 IdM server, including all the server roles present on rhel8.example.com. To install the roles from the example above, use these options with the ipa-replica-install command:

   • --setup-ca to set up the Certificate System component

   • --setup-dns and --forwarder to configure an integrated DNS server and set a per-server forwarder to take care of DNS queries that go outside the IdM domain

     Note

     Additionally, if your IdM deployment is in a trust relationship with Active Directory (AD), add the --setup-adtrust option to the ipa-replica-install command to configure AD trust capability on rhel9.example.com.

   • --ntp-server to specify an NTP server or --ntp-pool to specify a pool of NTP servers

     To set up an IdM server with the IP address of 192.0.2.1 that uses a per-server forwarder with the IP address of 192.0.2.20 and synchronizes with the ntp.example.com NTP server:

     [root@rhel9 ~]# ipa-replica-install --setup-ca --ip-address 192.0.2.1 --setup-dns --forwarder 192.0.2.20 --ntp-server ntp.example.com

     Copy to Clipboard Toggle word wrap

     You do not need to specify the RHEL 8 IdM server itself because if DNS is working correctly, rhel9.example.com will find it using DNS autodiscovery.

3. Optional: Add an _ntp._udp service (SRV) record for your external NTP time server to the DNS of the newly-installed IdM server, rhel9.example.com. The presence of the SRV record for the time server in IdM DNS ensures that future RHEL 9 replica and client installations are automatically configured to synchronize with the time server used by rhel9.example.com. This is because ipa-client-install looks for the _ntp._udp DNS entry unless --ntp-server or --ntp-pool options are provided on the install command-line interface (CLI).
4. Create any replication agreements needed to re-create the previous topology using the steps in Setting up replication between two servers using the Web UI or Setting up replication between two servers using the CLI.

Verification

1. Verify that the IdM services are running on rhel9.example.com:

   [root@rhel9 ~]# ipactl status
   Directory Service: RUNNING
   [... output truncated ...]
   ipa: INFO: The ipactl command was successful

   Copy to Clipboard Toggle word wrap

2. Run IdM Healthcheck on rhel9.example.com to validate services, replication, and certificate health:

   [root@rhel9 ~]# ipa-healthcheck

   Copy to Clipboard Toggle word wrap

   If Healthcheck reports warnings or errors, investigate and resolve them before decommissioning any RHEL 8 servers. For targeted replication tests, you can run:

   [root@rhel9 ~]# ipa-healthcheck --source=ipahealthcheck.ds.replication --source=ipahealthcheck.ipa.topology

   Copy to Clipboard Toggle word wrap

3. Verify that server roles for rhel9.example.com are the same as for rhel8.example.com:

   [root@rhel9 ~]# kinit admin
   [root@rhel9 ~]# ipa server-role-find --status enabled --server rhel9.example.com
   ----------------------
   2 server roles matched
   ----------------------
     Server name: rhel9.example.com
     Role name: CA server
     Role status: enabled
   
     Server name: rhel9.example.com
     Role name: DNS server
     Role status: enabled

   Copy to Clipboard Toggle word wrap

4. Optional: Display details about the replication agreement between rhel8.example.com and rhel9.example.com:

   [root@rhel9 ~]# ipa-csreplica-manage list --verbose rhel9.example.com
   Directory Manager password:
   
   rhel8.example.com
   last init status: None
   last init ended: 1970-01-01 00:00:00+00:00
   last update status: Error (0) Replica acquired successfully: Incremental update succeeded
   last update ended: 2019-02-13 13:55:13+00:00

   Copy to Clipboard Toggle word wrap

5. Optional: If your IdM deployment is in a trust relationship with AD, verify that it is working:

   1. Verify the Kerberos configuration

   2. Attempt to resolve an AD user on rhel9.example.com:

      [root@rhel9 ~]# id aduser@ad.domain

      Copy to Clipboard Toggle word wrap

6. Verify that rhel9.example.com is synchronized with the NTP server:

   [root@rhel8 ~]# chronyc tracking
   Reference ID    : CB00710F (ntp.example.com)
   Stratum         : 3
   Ref time (UTC)  : Wed Feb 16 09:49:17 2022
   [... output truncated ...]

   Copy to Clipboard Toggle word wrap

1. Configure rhel9.example.com to handle CA subsystem certificate renewal:

   [root@rhel9 ~]# ipa config-mod --ca-renewal-master-server rhel9.example.com
     ...
     IPA masters: rhel8.example.com, rhel9.example.com
     IPA CA servers: rhel8.example.com, rhel9.example.com
     IPA CA renewal master: rhel9.example.com

   Copy to Clipboard Toggle word wrap

   The output confirms that the update was successful.

2. On rhel9.example.com, enable the certificate updater task:

   1. Open the /etc/pki/pki-tomcat/ca/CS.cfg configuration file for editing.
   2. Remove the ca.certStatusUpdateInterval entry, or set it to the desired interval in seconds. The default value is 600.
   3. Save and close the /etc/pki/pki-tomcat/ca/CS.cfg configuration file.

   4. Restart IdM services:

      [user@rhel9 ~]$ ipactl restart

      Copy to Clipboard Toggle word wrap

3. On rhel8.example.com, disable the certificate updater task:

   1. Open the /etc/pki/pki-tomcat/ca/CS.cfg configuration file for editing.

   2. Change ca.certStatusUpdateInterval to 0, or add the following entry if it does not exist:

      ca.certStatusUpdateInterval=0

      Copy to Clipboard Toggle word wrap
   3. Save and close the /etc/pki/pki-tomcat/ca/CS.cfg configuration file.

   4. Restart IdM services:

      [user@rhel8 ~]$ ipactl restart

      Copy to Clipboard Toggle word wrap

Procedure

1. Optional: Verify that rhel8.example.com is generating the CRL:

   [root@rhel8 ~]# ipa-crlgen-manage status
   CRL generation: enabled
   Last CRL update: 2021-10-31 12:00:00
   Last CRL Number: 6
   The ipa-crlgen-manage command was successful

   Copy to Clipboard Toggle word wrap

2. Stop generating the CRL on the rhel8.example.com server:

   [root@rhel8 ~]# ipa-crlgen-manage disable
   Stopping pki-tomcatd
   Editing /var/lib/pki/pki-tomcat/conf/ca/CS.cfg
   Starting pki-tomcatd
   Editing /etc/httpd/conf.d/ipa-pki-proxy.conf
   Restarting httpd
   CRL generation disabled on the local host. Please make sure to configure CRL generation on another master with ipa-crlgen-manage enable.
   The ipa-crlgen-manage command was successful

   Copy to Clipboard Toggle word wrap

Procedure

1. To start generating the CRL on rhel9.example.com, use the ipa-crlgen-manage enable command:

   [root@rhel9 ~]# ipa-crlgen-manage enable
   Stopping pki-tomcatd
   Editing /var/lib/pki/pki-tomcat/conf/ca/CS.cfg
   Starting pki-tomcatd
   Editing /etc/httpd/conf.d/ipa-pki-proxy.conf
   Restarting httpd
   Forcing CRL update
   CRL generation enabled on the local host. Please make sure to have only a single CRL generation master.
   The ipa-crlgen-manage command was successful

   Copy to Clipboard Toggle word wrap

Procedure

1. Update the system resolvers on affected clients so they point to the current IdM DNS servers. Adjust /etc/resolv.conf or your network configuration tooling to remove references to retired servers.

2. If the client uses the fallback enrollment server defined in /etc/ipa/default.conf, replace the hostname in both of the following parameters with an active IdM server:

   xmlrpc_uri = https://ipa_new.example.com/ipa/xml
   server = ipa_new.example.com

   Copy to Clipboard Toggle word wrap

3. Review the ipa_server parameter in /etc/sssd/sssd.conf:

   • If it lists specific servers, update the list to include only active replicas or switch to SRV-only discovery by using srv.
   • If it references the retired hostname, replace it with the new server names.

4. Restart SSSD to apply the updates:

   [root@client ~]# systemctl restart sssd

   Copy to Clipboard Toggle word wrap
5. Test authentication and lookups from the client to confirm it can reach the updated servers.

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

      Copy to Clipboard Toggle word wrap

   2. Export the database:

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

      Copy to Clipboard Toggle word wrap

   3. Restart the DS instance:

      # dsctl slapd-EXAMPLE-COM start

      Copy to Clipboard Toggle word wrap
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

   Copy to Clipboard Toggle word wrap
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

   Copy to Clipboard Toggle word wrap
   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

   Copy to Clipboard Toggle word wrap
2. Confirm that IdM data, such as users, groups, and sudo rules, has been successfully migrated using ipa user-find and ipa sudorule-find.

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.

Procedure

1. If IdM is not yet installed: install the IdM server, including any custom LDAP directory schema, on a different machine from the one on which the existing LDAP directory is installed. For details, see Installing Identity Management.

   Note

   Custom user or group schemas have limited support in IdM. They can cause problems during the migration because of incompatible object definitions.

2. For performance reasons, disable the compat plug-in:

   # ipa-compat-manage disable

   Copy to Clipboard Toggle word wrap

   For more information about the schema compat feature and the benefits of disabling it for the migration, see The schema to use when migrating from LDAP to IdM and the schema compat feature.

3. Restart the IdM Directory Server instance:

   # systemctl restart dirsrv.target

   Copy to Clipboard Toggle word wrap

4. Configure the IdM server to allow migration:

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

   Copy to Clipboard Toggle word wrap

   By setting --enable-migration to TRUE, you do the following:

   • Allow pre-hashed passwords during an LDAP add operation.
   • Configure SSSD to try the password migration sequence if the initial Kerberos authentication fails. For more information, see the Workflow section in Using SSSD when migrating passwords from LDAP to IdM.

5. Run the IdM migration script, ipa migrate-ds, with the options that are relevant for your use case. For more information, see Customizing the migration from LDAP to IdM.

   # ipa migrate-ds --your-options ldap://ldap.example.com:389

   Copy to Clipboard Toggle word wrap
   Note

   If you did not disable the compat plug-in in one of the previous steps, add the --with-compat option to ipa migrate-ds:

   # ipa migrate-ds --your-options --with-compat ldap://ldap.example.com:389

   Copy to Clipboard Toggle word wrap

6. Re-enable the compat plug-in:

   # ipa-compat-manage enable

   Copy to Clipboard Toggle word wrap

7. Restart the IdM Directory Server:

   # systemctl restart dirsrv.target

   Copy to Clipboard Toggle word wrap

8. When all users have had their passwords migrated, disable the migration mode:

   # ipa config-mod --enable-migration=FALSE

   Copy to Clipboard Toggle word wrap
9. Optional: When all of the users have been migrated, reconfigure non-SSSD clients to use Kerberos authentication, that is pam_krb5, instead of LDAP authentication, that is pam_ldap. For more information, see Configuring a Kerberos Client in the RHEL 7 System-level Authentication Guide.

10. Have users generate their hashed Kerberos passwords. Choose one of the methods described in Planning password migration when migrating from LDAP to IdM.

    • If you decide on the SSSD method:

      • Move clients that have SSSD installed from the LDAP directory to the IdM directory, and enroll them as clients with IdM. This downloads the required keys and certificates.

        On Red Hat Enterprise Linux clients, this can be done using the ipa-client-install command. For example:

        # ipa-client-install --enable-dns-update

        Copy to Clipboard Toggle word wrap

    • If you decide on the IdM migration web page method:

      • Instruct users to log into IdM using the migration web page:

        https://ipaserver.example.com/ipa/migration

        Copy to Clipboard Toggle word wrap

11. To monitor the user migration process, query the existing LDAP directory to see which user accounts have a password but do not yet have a Kerberos principal key.

    $ ldapsearch -LL -x -D 'cn=Directory Manager' -w secret -b 'cn=users,cn=accounts,dc=example,dc=com' '(&(!(krbprincipalkey=))(userpassword=))' uid

    Copy to Clipboard Toggle word wrap
    Note

    Include the single quotes around the filter so that it is not interpreted by the shell.

12. When the migration of all clients and users is complete, decommission the LDAP directory.

Verification

1. Create a test user in IdM by using the ipa user-add command. Compare the output of migrated users to that of the test user. Ensure that the migrated users contain the minimal set of attributes and object classes present on the test user. For example:

   $ ipa user-show --all testing_user
   dn: uid=testing_user,cn=users,cn=accounts,dc=idm,dc=example,dc=com
   User login: testing_user
   First name: testing
   Last name: user
   Full name: testing user
   Display name: testing user
   Initials: tu
   Home directory: /home/testing_user
   GECOS: testing user
   Login shell: /bin/sh
   Principal name: testing_user@IDM.EXAMPLE.COM
   Principal alias: testing_user@IDM.EXAMPLE.COM
   Email address: testing_user@idm.example.com
   UID: 1689700012
   GID: 1689700012
   Account disabled: False
   Preserved user: False
   Password: False
   Member of groups: ipausers
   Kerberos keys available: False
   ipauniqueid: 843b1ac8-6e38-11ec-8dfe-5254005aad3e
   mepmanagedentry: cn=testing_user,cn=groups,cn=accounts,dc=idm,dc=example,dc=com
   objectclass: top, person, organizationalperson, inetorgperson, inetuser, posixaccount, krbprincipalaux, krbticketpolicyaux, ipaobject,
                ipasshuser, ipaSshGroupOfPubKeys, mepOriginEntry

   Copy to Clipboard Toggle word wrap
2. Compare the output of migrated users, as seen on IdM, to the source users, as seen on the original LDAP server. Ensure that imported attributes are not copied twice and that they have the correct values.

Procedure

1. Store the certificate of the CA that issued the remote LDAP server certificate in a file on the future IdM server. For example: /tmp/remote.crt.

2. Follow the steps described in Migrating an LDAP server to IdM. However, for an encrypted LDAP connection during the migration, use the ldaps protocol in the URL and pass the --ca-cert-file option to the ipa migrate-ds command. For example:

   # ipa migrate-ds --ca-cert-file=/tmp/remote.crt --your-other-options ldaps://ldap.example.com:636

   Copy to Clipboard Toggle word wrap

Verification

1. Create a test user in IdM by using the ipa user-add command. Compare the output of migrated users to that of the test user. Ensure that the migrated users contain the minimal set of attributes and object classes present on the test user. For example:

   $ ipa user-show --all testing_user
   dn: uid=testing_user,cn=users,cn=accounts,dc=idm,dc=example,dc=com
   User login: testing_user
   First name: testing
   Last name: user
   Full name: testing user
   Display name: testing user
   Initials: tu
   Home directory: /home/testing_user
   GECOS: testing user
   Login shell: /bin/sh
   Principal name: testing_user@IDM.EXAMPLE.COM
   Principal alias: testing_user@IDM.EXAMPLE.COM
   Email address: testing_user@idm.example.com
   UID: 1689700012
   GID: 1689700012
   Account disabled: False
   Preserved user: False
   Password: False
   Member of groups: ipausers
   Kerberos keys available: False
   ipauniqueid: 843b1ac8-6e38-11ec-8dfe-5254005aad3e
   mepmanagedentry: cn=testing_user,cn=groups,cn=accounts,dc=idm,dc=example,dc=com
   objectclass: top, person, organizationalperson, inetorgperson, inetuser, posixaccount, krbprincipalaux, krbticketpolicyaux, ipaobject,
                ipasshuser, ipaSshGroupOfPubKeys, mepOriginEntry

   Copy to Clipboard Toggle word wrap
2. Compare the output of migrated users, as seen on IdM, to the source users, as seen on the original LDAP server. Ensure that imported attributes are not copied twice and that they have the correct values.