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

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.