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

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

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

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

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

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:

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

   [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:

   Copy to Clipboard Toggle word wrap

   [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 {AD} (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:

     Copy to Clipboard Toggle word wrap

     [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:

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

   [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

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

   Copy to Clipboard Toggle word wrap

   [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

4. 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:

      Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

   [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:

      Copy to Clipboard Toggle word wrap

      [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:

      Copy to Clipboard Toggle word wrap

      ca.certStatusUpdateInterval=0

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

   4. Restart IdM services:

      Copy to Clipboard Toggle word wrap

      [user@rhel9 ~]$ ipactl restart

Procedure

1. Check if your server is generating the CRL:

   Copy to Clipboard Toggle word wrap

   [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:

   Copy to Clipboard Toggle word wrap

   [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:

   Copy to Clipboard Toggle word wrap

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

Procedure

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

   Copy to Clipboard Toggle word wrap

   [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

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:

      Copy to Clipboard Toggle word wrap

      [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:

      Copy to Clipboard Toggle word wrap

      [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. Use one of the following methods:

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

     Copy to Clipboard Toggle word wrap

     [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:

        Copy to Clipboard Toggle word wrap

        [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:

        Copy to Clipboard Toggle word wrap

        [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:

        Copy to Clipboard Toggle word wrap

        [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:

        Copy to Clipboard Toggle word wrap

        [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.

   Copy to Clipboard Toggle word wrap

   [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 will contact 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.