Chapter 1. Migrating your IdM environment from RHEL 8 servers to RHEL 9 servers
To upgrade a RHEL 8 IdM environment to RHEL 9, you must first add new RHEL 9 IdM replicas to your RHEL 8 IdM environment, and then retire the RHEL 8 servers. The migration involves moving all Identity Management (IdM) data and configuration from a Red Hat Enterprise Linux (RHEL) 8 server to a RHEL 9 server.
- Performing an in-place upgrade of RHEL 8 IdM servers to RHEL 9 is not supported.
- For more information about adding a RHEL 9 IdM replica in FIPS mode to a RHEL 8 IdM deployment in FIPS mode, see the Identity Management section in Considerations in adopting RHEL 9.
After upgrading your IdM replica to RHEL 9.2, the IdM Kerberos Distribution Centre (KDC) might fail to issue ticket-granting tickets (TGTs) to users who do not have Security Identifiers (SIDs) assigned to their accounts. Consequently, the users cannot log in to their accounts.
To work around the problem, generate SIDs by running
# ipa config-mod --enable-sid --add-sidsas an IdM administrator on another IdM replica in the topology. Afterward, if users still cannot log in, examine the Directory Server error log. You might have to adjust ID ranges to include user POSIX identities.Migrating directly to RHEL 9 from RHEL 7 or earlier versions is not supported. To properly update your IdM data, you must perform incremental migrations.
For example, to migrate a RHEL 7 IdM environment to RHEL 9:
- Migrate from RHEL 7 servers to RHEL 8 servers. See Migrating to Identity Management on RHEL 8.
- Migrate from RHEL 8 servers to RHEL 9 servers, as described in this section.
This section describes how to migrate all Identity Management (IdM) data and configuration from a Red Hat Enterprise Linux (RHEL) 8 server to a RHEL 9 server.
The migration procedure includes:
- Configuring a RHEL 9 IdM server and adding it as a replica to your current RHEL 8 IdM environment. For details, see Installing the RHEL 9 Replica.
- Making the RHEL 9 server the certificate authority (CA) renewal server. For details, see Assigning the CA renewal server role to the RHEL 9 IdM server.
- Stopping the generation of the certificate revocation list (CRL) on the RHEL 8 server and redirecting CRL requests to the RHEL 9 replica. For details, see Stopping CRL generation on a RHEL 8 IdM CA server.
- Starting the generation of the CRL on the RHEL 9 server. For details, see Starting CRL generation on the new RHEL 9 IdM CA server.
- Stopping and decommissioning the original RHEL 8 CA renewal server. For details, see Stopping and decommissioning the RHEL 8 server.
In the following procedures:
-
rhel9.example.comis the RHEL 9 system that will become the new CA renewal server. rhel8.example.comis the original RHEL 8 CA renewal server. To identify which Red Hat Enterprise Linux 8 server is the CA renewal server, run the following command on any IdM server:[root@rhel8 ~]# ipa config-show | grep "CA renewal" IPA CA renewal master: rhel8.example.comIf your IdM deployment does not use an IdM CA, any IdM server running on RHEL 8 can be
rhel8.example.com.
Complete the steps in the following sections only if your IdM deployment uses an embedded certificate authority (CA):
1.1. Prerequisites for migrating IdM from RHEL 8 to 9
On rhel8.example.com:
Upgrade the system to the latest RHEL 8 version.
ImportantIf 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.
Update the ipa-* packages to their latest version:
[root@rhel8 ~]# dnf update ipa-*WarningWhen 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.
On rhel9.example.com:
- The latest version of Red Hat Enterprise Linux is installed on the system. For more information, see Performing a standard RHEL 9 installation.
-
Ensure the system is an IdM client enrolled into the domain for which
rhel8.example.comIdM server is authoritative. For more information, see Installing an IdM client: Basic scenario. - Ensure the system meets the requirements for IdM server installation. See Preparing the system for IdM server installation.
Ensure you know the time server
rhel8.example.comis 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
- Ensure the system is authorized for the installation of an IdM replica. See Authorizing the installation of a replica on an IdM client.
Update the ipa-* packages to their latest version:
[root@rhel8 ~]# dnf update ipa-*
Additional resources
To decide which server roles you want to install on the new IdM primary server,
rhel9.example.com, see the following links:- For details on the CA server role in IdM, see Planning your CA services.
- For details on the DNS server role in IdM, see Planning your DNS services and host names.
- For details on integration based on cross-forest trust between an IdM and Active Directory (AD), see Planning a cross-forest trust between IdM and AD.
- To be able to install specific server roles for IdM in RHEL 9, you need to download packages from specific IdM repositories: Installing packages required for an IdM server.
- To upgrade a system from RHEL 8 to RHEL 9, see Upgrading from RHEL 8 to RHEL 9.
1.2. Installing the RHEL 9 replica
List which server roles are present in your RHEL 8 environment:
[root@rhel8 ~]# ipa server-role-find --status enabled --server rhel8.example.com ---------------------- 3 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 [... output truncated ...](Optional) If you want to use the same per-server forwarders for
rhel9.example.comthatrhel8.example.comis using, view the per-server forwarders forrhel8.example.com:[root@rhel8 ~]# ipa dnsserver-show rhel8.example.com ----------------------------- 1 DNS server matched ----------------------------- Server name: rhel8.example.com SOA mname: rhel8.example.com. Forwarders: 192.0.2.20 Forward policy: only -------------------------------------------------- Number of entries returned 1 --------------------------------------------------
Install the IdM server software on
rhel9.example.comto configure it as a replica of the RHEL 8 IdM server, including all the server roles present onrhel8.example.com. To install the roles from the example above, use these options with theipa-replica-installcommand:-
--setup-cato set up the Certificate System component --setup-dnsand--forwarderto configure an integrated DNS server and set a per-server forwarder to take care of DNS queries that go outside the IdM domainNoteAdditionally, if your IdM deployment is in a trust relationship with Active Directory (AD), add the
--setup-adtrustoption to theipa-replica-installcommand to configure AD trust capability onrhel9.example.com.--ntp-serverto specify an NTP server or--ntp-poolto specify a pool of NTP serversTo 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.comNTP 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.comYou do not need to specify the RHEL 8 IdM server itself because if DNS is working correctly,
rhel9.example.comwill find it using DNS autodiscovery.
-
-
(Optional) Add an
_ntp._udpservice (SRV) record for your externalNTPtime 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 becauseipa-client-installlooks for the_ntp._udpDNS entry unless--ntp-serveror--ntp-pooloptions are provided on the install command-line interface (CLI).
Verification
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 successfulVerify that server roles for
rhel9.example.comare the same as forrhel8.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
(Optional) Display details about the replication agreement between
rhel8.example.comandrhel9.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(Optional) If your IdM deployment is in a trust relationship with AD, verify that it is working:
- Verify the Kerberos configuration
Attempt to resolve an AD user on
rhel9.example.com:[root@rhel9 ~]# id aduser@ad.domain
Verify that
rhel9.example.comis synchronized with theNTPserver:[root@rhel8 ~]# chronyc tracking Reference ID : CB00710F (ntp.example.com) Stratum : 3 Ref time (UTC) : Wed Feb 16 09:49:17 2022 [... output truncated ...]
Additional resources
1.3. Assigning the CA renewal server role to the RHEL 9 IdM server
If your IdM deployment uses an embedded certificate authority (CA), assign the CA renewal server role to the Red Hat Enterprise Linux (RHEL) 9 IdM server.
On rhel9.example.com, configure rhel9.example.com as the new CA renewal server:
Configure
rhel9.example.comto 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
The output confirms that the update was successful.
On
rhel9.example.com, enable the certificate updater task:-
Open the
/etc/pki/pki-tomcat/ca/CS.cfgconfiguration file for editing. -
Remove the
ca.certStatusUpdateIntervalentry, or set it to the desired interval in seconds. The default value is600. -
Save and close the
/etc/pki/pki-tomcat/ca/CS.cfgconfiguration file. Restart IdM services:
[user@rhel9 ~]$ ipactl restart
-
Open the
On
rhel8.example.com, disable the certificate updater task:-
Open the
/etc/pki/pki-tomcat/ca/CS.cfgconfiguration file for editing. Change
ca.certStatusUpdateIntervalto0, or add the following entry if it does not exist:ca.certStatusUpdateInterval=0
-
Save and close the
/etc/pki/pki-tomcat/ca/CS.cfgconfiguration file. Restart IdM services:
[user@rhel8 ~]$ ipactl restart
-
Open the
1.4. Stopping CRL generation on a RHEL 8 IdM CA server
If your IdM deployment uses an embedded certificate authority (CA), stop generating the Certificate Revocation List (CRL) on the IdM CRL publisher server.
Prerequisites
- You must be logged in as root.
Procedure
(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
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 successfulOptionally, check if the rhel8.example.com server stopped generating the CRL:
[root@rhel7 ~]# ipa-crlgen-manage status
The rhel8.example.com server stopped generating the CRL. The next step is to enable generating the CRL on rhel9.example.com.
1.5. Starting CRL generation on the new RHEL 9 IdM CA server
If your IdM deployment uses an embedded certificate authority (CA), start Certificate Revocation List (CRL) generation on the new Red Hat Enterprise Linux (RHEL) 9 IdM CA server.
Prerequisites
- You must be logged in as root on the rhel9.example.com machine.
Procedure
To start generating the CRL on rhel9.example.com, use the
ipa-crlgen-manage enablecommand:[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
Verification steps
To check if CRL generation is enabled, use the
ipa-crlgen-manage statuscommand:[root@rhel8 ~]# ipa-crlgen-manage status CRL generation: enabled Last CRL update: 2021-10-31 12:10:00 Last CRL Number: 7 The ipa-crlgen-manage command was successful
1.6. Stopping and decommissioning the RHEL 8 server
Make sure that all data, including the latest changes, have been correctly migrated from
rhel8.example.comtorhel9.example.com. For example:Add a new user on
rhel8.example.com:[root@rhel8 ~]# ipa user-add random_user First name: random Last name: userCheck that the user has been replicated to
rhel9.example.com:[root@rhel9 ~]# ipa user-find random_user -------------- 1 user matched -------------- User login: random_user First name: random Last name: user
Ensure that a Distributed Numeric Assignment (DNA) ID range is allocated to
rhel9.example.com. Use one of the following methods:Activate the DNA plug-in on
rhel9.example.comdirectly by creating another test user:[root@rhel9 ~]# ipa user-add another_random_user First name: another Last name: random_userAssign a specific DNA ID range to
rhel9.example.com:On
rhel8.example.com, display the IdM ID range:[root@rhel8 ~]# 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
On
rhel8.example.com, display the allocated DNA ID ranges:[root@rhel8 ~]# ipa-replica-manage dnarange-show rhel8.example.com: 196600026-196799999 rhel9.example.com: No range set
Reduce the DNA ID range allocated to
rhel8.example.comso that a section becomes available torhel9.example.com:[root@rhel8 ~]# ipa-replica-manage dnarange-set rhel8.example.com 196600026-196699999Assign the remaining part of the IdM ID range to
rhel9.example.com:[root@rhel8 ~]# ipa-replica-manage dnarange-set rhel9.example.com 196700000-196799999
Stop all IdM services on
rhel8.example.comto force domain discovery to the newrhel9.example.comserver.[root@rhel8 ~]# 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
ipautility will contact the new server through a remote procedure call (RPC).- Remove the RHEL 8 server from the topology by executing the removal commands on the RHEL 9 server. For details, see Uninstalling an IdM server.
