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

1. Upgrade the system to the latest RHEL 7 version.
2. Ensure that the domain level for your domain is set to 1. For more information, see Displaying and Raising the Domain Level in the Linux Domain Identity, Authentication, and Policy Guide for RHEL 7.

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

   [root@rhel7 ~]# yum 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. Identify the time server rhel7.example.com is synchronized with:

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

   In RHEL 8, IdM does not provide its own time server: the installation of IdM on rhel8.example.com does not result in the installation of an NTP server on the host. Therefore, you need to use a separate NTP server, for example ntp.example.com. For more information, see Migrating to chrony and Time service requirements for IdM.

   While rhel7.example.com can be used in an NTP server role, you will decommission the server as part of the migration process. Therefore, rhel8.example.com needs to be synchronized directly with ntp.example.com instead. You can specify this during the client installation process.

3. Enroll the system as an IdM client into the domain for which rhel7.example.com IdM server is authoritative. For more information, see Installing an IdM client. When installing the client, specify the time server from the previous step:

   [root@rhel8]# ipa-client-install --mkhomedir --ntp-server ntp.example.com

   Copy to Clipboard Toggle word wrap

   If you are using a pool of NTP servers, use the --ntp-pool option.

   If you do not specify an NTP server manually, it will be automatically set from DNS records. This can lead to rhel8.example.com synchronizing with rhel7.example.com. This will cause issues when the RHEL 7 server is decommissioned.

   If the RHEL8 system is already properly configured as an NTP client, you can use the --no-ntp option when performing the IdM client installation.

   Important

   Do not use single-label domain names, for example .company. Starting with RHEL 8, IDM does not accept single-labeled domain names and the domain name must be composed of one or more subdomains and a top level domain, for example example.com or company.example.com.

   If the existing domain is single-labeled, it is not possible to perform the migration using these instructions. In these cases, use Migrating an LDAP Server to Identity Management.

4. Prepare the system for IdM server installation. See Preparing the system for IdM server installation.
5. Authorize the system 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@rhel7 ~]# yum 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.

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. Remove the server from the topology on a different replica. For example, to remove rhel7.example.com:

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

   Copy to Clipboard Toggle word wrap

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

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

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

   Copy to Clipboard Toggle word wrap
3. 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.
4. After replication has fully converged and you have confirmed the old server no longer appears in the topology, proceed to install your new RHEL 8 replica using the reused hostname. See Installing the RHEL 8 replica.

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

   [root@rhel8 ~]# ipa-healthcheck

   Copy to Clipboard Toggle word wrap

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

Verification

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

   [root@rhel8 ~]# 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 rhel8.example.com to validate services, replication, and certificate health:

   [root@rhel8 ~]# ipa-healthcheck

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

3. Verify that server roles for rhel8.example.com are the same as for rhel7.example.com except the NTP server role:

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

   Copy to Clipboard Toggle word wrap

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

   [root@rhel8 ~]# ipa-csreplica-manage list --verbose rhel8.example.com
   Directory Manager password:
   
   rhel7.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. link: Verify the Kerberos configuration

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

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

      Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

   The output confirms that the update was successful.

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

      Copy to Clipboard Toggle word wrap

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

      Copy to Clipboard Toggle word wrap

Procedure

1. Optional: Check if rhel7.example.com is generating the CRL:

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

   Copy to Clipboard Toggle word wrap

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

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

Verification

1. Check if the rhel7.example.com server stopped generating the CRL:

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

   Copy to Clipboard Toggle word wrap

Procedure

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

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

2. To check if CRL generation is enabled, use the ipa-crlgen-manage status command:

   [root@rhel8 ~]# ipa-crlgen-manage status
   CRL generation: enabled
   Last CRL update: 2019-10-31 12:10:00
   Last CRL Number: 7
   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.