Migrating to Identity Management on RHEL 10

1. Configuring a RHEL 10 IdM server and adding it as a replica to your current RHEL 9 IdM environment. For details, see Installing the RHEL 10 replica.
2. Making the RHEL 10 server the certificate authority (CA) renewal server. For details, see Assigning the CA renewal server role to the RHEL 10 IdM server.
3. Stopping the generation of the certificate revocation list (CRL) on the RHEL 9 server and redirecting CRL requests to RHEL 10. For details, see Stopping CRL generation on a RHEL 9 IdM CA server.
4. Starting the generation of the CRL on the RHEL 10 server. For details, see Starting CRL generation on the new RHEL 10 IdM CA server.
5. Stopping and decommissioning the original RHEL 9 CA renewal server. For details, see Stopping and decommissioning the RHEL 9 server.

Procedure

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

   [root@rhel9 ~]# ipa server-find --all
   ---------------------
   2 IPA servers matched
   ---------------------
     dn: cn=rhel9-1.example.com,cn=masters,cn=ipa,cn=etc,dc=example,dc=com
     Server name: rhel9-1.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=rhel9-2.example.com,cn=masters,cn=ipa,cn=etc,dc=example,dc=com
     Server name: rhel9-2.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
   ----------------------------

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

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

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

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

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@rhel9 ~]# ipa-healthcheck --source=ipahealthcheck.ds.replication --source=ipahealthcheck.ipa.topology

Procedure

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

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

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

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

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 rhel9.example.com:

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

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

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

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

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 10 replica using the reused hostname. See Installing the RHEL 10 replica.

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

   [root@rhel9 ~]# ipa-healthcheck

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

Procedure

1. List which server roles are present in your RHEL 9 environment:

   [root@rhel9 ~]# ipa server-role-find --status enabled --server rhel9.example.com
   ----------------------
   3 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
   [... output truncated ...]

2. Optional: If you want to use the same per-server forwarders for rhel10.example.com that rhel9.example.com is using, view the per-server forwarders for rhel9.example.com:

   [root@rhel9 ~]# ipa dnsserver-show rhel9.example.com
   -----------------------------
   1 DNS server matched
   -----------------------------
     Server name: rhel9.example.com
     SOA mname: rhel9.example.com.
     Forwarders: 192.0.2.20
     Forward policy: only
   --------------------------------------------------
   Number of entries returned 1
   --------------------------------------------------

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 rhel10.example.com to configure it as a replica of the RHEL 9 IdM server, including all the server roles present on rhel9.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 rhel10.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@rhel10 ~]# ipa-replica-install --setup-ca --ip-address 192.0.2.1 --setup-dns --forwarder 192.0.2.20 --ntp-server ntp.example.com

     You do not need to specify the RHEL 9 IdM server itself because if DNS is working correctly, rhel10.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, rhel10.example.com. The presence of the SRV record for the time server in IdM DNS ensures that future RHEL 10 replica and client installations are automatically configured to synchronize with the time server used by rhel10.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 rhel10.example.com:

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

2. Run ipa-healthcheck to identify any issues with the new replica:

   [root@rhel10 ~]# ipa-healthcheck

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

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

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

   [root@rhel10 ~]# ipa-csreplica-manage list --verbose rhel10.example.com
   Directory Manager password:
   
   rhel9.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

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 rhel10.example.com:

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

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

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

Procedure

1. On rhel10.example.com, configure rhel10.example.com as the new CA renewal server:

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

   The output confirms that the update was successful.

2. On rhel10.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@rhel10 ~]$ ipactl restart

3. On rhel9.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

   3. Save and close the /etc/pki/pki-tomcat/ca/CS.cfg configuration file.

   4. Restart IdM services:

      [user@rhel9 ~]$ ipactl restart

Procedure

1. Check if your server is generating the CRL:

   [root@server ~]# ipa-crlgen-manage status

   CRL generation: enabled
   Last CRL update: 2019-10-31 12:00:00
   Last CRL Number: 6
   The ipa-crlgen-manage command was successful

2. Stop generating the CRL on the server:

   [root@server ~]# 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

3. Check if the server stopped generating CRL:

   [root@server ~]# ipa-crlgen-manage status

   The server stopped generating the CRL. The next step is to enable CRL generation on the IdM replica.

Procedure

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

   [root@rhel10 ~]# 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

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

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

5. Test authentication and lookups from the client to confirm it can reach the updated servers.

Procedure

1. Make sure that all data, including the latest changes, have been correctly migrated from rhel9.example.com to rhel10.example.com. For example:

   1. Add a new user on rhel9.example.com:

      [root@rhel9 ~]# ipa user-add random_user
      First name: random
      Last name: user

   2. Check that the user has been replicated to rhel10.example.com:

      [root@rhel10 ~]# ipa user-find random_user
      --------------
      1 user matched
      --------------
        User login: random_user
        First name: random
        Last name: user

2. Ensure that a Distributed Numeric Assignment (DNA) ID range is allocated to rhel10.example.com. If you recorded DNA ranges earlier (see Recording DNA ID ranges before migration), you can reference those values when reassigning ranges. Use one of the following methods:

   • Activate the DNA plug-in on rhel10.example.com directly by creating another test user:

     [root@rhel10 ~]# ipa user-add another_random_user
     First name: another
     Last name: random_user

   • Assign a specific DNA ID range to rhel10.example.com:

     1. On rhel9.example.com, display the IdM ID range:

        [root@rhel9 ~]# ipa idrange-find
        ----------------
        3 ranges matched
        ----------------
          Range name: EXAMPLE.COM_id_range
          First Posix ID of the range: 196600000
          Number of IDs in the range: 200000
          First RID of the corresponding RID range: 1000
          First RID of the secondary RID range: 100000000
          Range type: local domain range

     2. On rhel9.example.com, display the allocated DNA ID ranges:

        [root@rhel9 ~]# ipa-replica-manage dnarange-show
        rhel9.example.com: 196600026-196799999
        rhel10.example.com: No range set

     3. Reduce the DNA ID range allocated to rhel9.example.com so that a section becomes available to rhel10.example.com:

        [root@rhel9 ~]# ipa-replica-manage dnarange-set rhel9.example.com 196600026-196699999

     4. Assign the remaining part of the IdM ID range to rhel10.example.com:

        [root@rhel9 ~]# ipa-replica-manage dnarange-set rhel10.example.com 196700000-196799999

3. Stop all IdM services on rhel9.example.com to force domain discovery to the new rhel10.example.com server.

   [root@rhel9 ~]# ipactl stop
   Stopping CA Service
   Stopping pki-ca:                                           [  OK  ]
   Stopping HTTP Service
   Stopping httpd:                                            [  OK  ]
   Stopping MEMCACHE Service
   Stopping ipa_memcached:                                    [  OK  ]
   Stopping DNS Service
   Stopping named:                                            [  OK  ]
   Stopping KPASSWD Service
   Stopping Kerberos 5 Admin Server:                          [  OK  ]
   Stopping KDC Service
   Stopping Kerberos 5 KDC:                                   [  OK  ]
   Stopping Directory Service
   Shutting down dirsrv:
       EXAMPLE-COM...                                         [  OK  ]
       PKI-IPA...                                             [  OK  ]

   After this, the ipa utility contacts the new server through a remote procedure call (RPC).

4. Remove the RHEL 9 server from the topology by executing the removal commands on the RHEL 10 server. For details, see Uninstalling an IdM server.

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.

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

   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

4. Configure the IdM server to allow migration:

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

   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

   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

6. Re-enable the compat plug-in:

   # ipa-compat-manage enable

7. Restart the IdM Directory Server:

   # systemctl restart dirsrv.target

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

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

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

    • 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

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

    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

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

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

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.