Chapter 2. Migrating your IdM environment from RHEL 9 servers to RHEL 10 servers

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.