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.

Warning
  • 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.

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

    1. Migrate from RHEL 7 servers to RHEL 8 servers. See Migrating to Identity Management on RHEL 8.
    2. 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:

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.com is the RHEL 9 system that will become the new CA renewal server.

  • rhel8.example.com is 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.com

    If your IdM deployment does not use an IdM CA, any IdM server running on RHEL 8 can be rhel8.example.com.

Note

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:

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

On rhel9.example.com:

  1. The latest version of Red Hat Enterprise Linux is installed on the system. For more information, see Performing a standard RHEL 9 installation.
  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
  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-*

Additional resources

1.2. Installing the RHEL 9 replica

  1. 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 ...]

  2. (Optional) If you want to use the same per-server forwarders for rhel9.example.com that rhel8.example.com is using, view the per-server forwarders for rhel8.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
--------------------------------------------------

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

      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.

  4. (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).

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

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

  3. (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

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

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

  5. 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 ...]

Additional resources

1.3. Assigning the CA renewal server role to the RHEL 9 IdM server

Note

Complete the steps in this section only if your IdM deployment uses an embedded certificate authority (CA).

On rhel9.example.com, configure rhel9.example.com as the new CA renewal server:

  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

    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

  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
    3. Save and close the /etc/pki/pki-tomcat/ca/CS.cfg configuration file.

    4. Restart IdM services: 

      [user@rhel8 ~]$ ipactl restart

1.4. Stopping CRL generation on a RHEL 8 IdM CA server

Note

Complete the steps in this section only if your IdM deployment uses an embedded certificate authority (CA).

This section describes how to stop generating the Certificate Revocation List (CRL) on the rhel8.example.com CA server using the ipa-crlgen-manage command.

Prerequisites

  • You must be logged in as root.

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

  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

  3. Optionally, 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

Note

Complete the steps in this section only if your IdM deployment uses an embedded certificate authority (CA).

Prerequisites

  • You must be logged in as root on the rhel9.example.com machine.

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

Verification steps

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

  1. Make sure that all data, including the latest changes, have been correctly migrated from rhel8.example.com to rhel9.example.com. For example:

    1. Add a new user on rhel8.example.com: 

      [root@rhel8 ~]# ipa user-add random_user
First name: random
Last name: user

    2. Check 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

  2. Stop all IdM services on rhel8.example.com to force domain discovery to the new rhel9.example.com server. 

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

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