Chapter 3. Upgrading the Red Hat Single Sign-On server

Procedure

1. Download the new server archive.
2. Move the downloaded archive to the desired location.
3. Extract the archive. This step installs a clean instance of the latest Red Hat Single Sign-On release.

4. For standalone installations, copy the RHSSO_HOME/standalone/ directory from the previous installation over the directory in the new installation.

   For domain installations, copy the RHSSO_HOME/domain/ directory from the previous installation over the directory in the new installation.

   For domain installations, create the empty directory RHSSO_HOME/domain/deployments.

   NOTE: Files in the bin directory should not be overwritten by the files from previous versions. Changes should be made manually.

5. Copy any custom modules that have been added to the modules directory.
6. Continue with the section, Running the server upgrade script.

Procedure

1. Subscribe to the proper repository containing Red Hat Single Sign-On.

   For Red Hat Enterprise Linux 7:

   subscription-manager repos --enable=rh-sso-7.6-for-rhel-7-x86_64-rpms

   For Red Hat Enterprise Linux 8:

   subscription-manager repos --enable=rh-sso-7.6-for-rhel-8-x86_64-rpms

2. Disable the older product repository for Red Hat Single Sign-On:

   subscription-manager repos --disable=rh-sso-7.5-for-rhel-8-x86_64-rpms

3. Check the list of repositories:

   dnf repolist

   Updating Subscription Management repositories.
   repo id repo name
   rh-sso-7.6-for-rhel-8-x86_64-rpms Single Sign-On 7.6 for RHEL 8 x86_64 (RPMs)
   rhel-8-for-x86_64-appstream-rpms Red Hat Enterprise Linux 8 for x86_64 - AppStream (RPMs)
   rhel-8-for-x86_64-baseos-rpms Red Hat Enterprise Linux 8 for x86_64 - BaseOS (RPMs)

4. Back up any modified configuration files and custom modules.

5. Use dnf upgrade to upgrade to the new Red Hat Single Sign-On version.

   The RPM upgrade process does not replace any modified configuration files. Instead, this process creates .rpmnew files for the default configuration of the new Red Hat Single Sign-On version.

6. To activate any new features in the new release, such as new subsystems, manually merge each .rpmnew file into your existing configuration files.
7. Copy any custom modules that have been added to the modules directory.

8. Continue with the section, Running the server upgrade script.

   Note

   Red Hat Single Sign-On RPM server distribution is using

   RHSSO_HOME=/opt/rh/rh-sso7/root/usr/share/keycloak

   Use it when calling migration scripts below.

Procedure

1. If you are using a different configuration file than the default one, edit the migration script to specify the new file name.
2. Stop the server.

3. Run the upgrade script:

   bin/jboss-cli.sh --file=bin/migrate-standalone.cli

Procedure

1. If you are using a different configuration file than the default one, edit the migration script to specify the new file name.
2. Stop the server.

3. Run the upgrade script:

   bin/jboss-cli.sh --file=bin/migrate-standalone-ha.cli

Procedure

1. If you have changed the profile name, you must edit the upgrade script to change a variable near the beginning of the script.
2. Edit the domain script to include the location of the keycloak-server.json file.
3. Stop the server.

4. Run the upgrade script on the domain controller

   bin/jboss-cli.sh --file=bin/migrate-domain.cli

Procedure

1. If you have changed the profile name, you must edit the upgrade script to change a variable near the beginning of the script.
2. Edit the domain-clustered script to include the location of the keycloak-server.json file.
3. Stop the server.

4. Run the upgrade script on the domain controller only:

   bin/jboss-cli.sh --file=bin/migrate-domain-clustered.cli

Procedure

1. Download the patch file from the Red Hat Customer Portal at https://access.redhat.com/downloads/.

2. From the management CLI, apply the patch using the following command, including the appropriate path to the patch file:

   patch apply /path/to/downloaded-patch.zip

   Note

   To patch another RH-SSO host in a managed domain, you can specify the RH-SSO host name using the --host= argument. For example:

   patch apply /path/to/downloaded-patch.zip --host=my-host

   The patch tool will warn if there are any conflicts in attempting to apply the patch. If there are conflicts, enter patch --help for the available arguments to re-run the command with an argument specifying how to resolve the conflicts.

3. Restart the RH-SSO server for the patch to take effect:

   shutdown --restart=true

Procedure

1. Download the patch file from the Red Hat Customer Portal at https://access.redhat.com/downloads/.

2. Open the management console and navigate to the Patch Management view.

   1. For a standalone server, click the Patching tab.

      The Patch Management Screen for a Standalone Server

      

   2. For a server in a managed domain, click the Patching tab, then select the host that you want to patch from the table, and click View.

      The Patch Management Screen for a Managed Domain

      

3. Click Apply a New Patch.

   1. If you are patching a managed domain host, on the next screen select whether to shutdown the servers on the host, and click Next.

4. Click the Browse button, select the downloaded patch you want to apply, and then click Next.

   Apply Patch Screen

   .. If there are any conflicts in attempting to apply the patch, a warning will be displayed. Click View error details to see the detail of the conflicts. If there is a conflict, you can either cancel the operation, or select the Override all conflicts check box and click Next. Overriding conflicts will result in the content of the patch overriding any user modifications.

5. After the patch has been successfully applied, select whether to restart RH-SSO now for the patch to take effect, and click Finish.

Procedure

1. From the management CLI, use the patch history command to find the ID of the patch that you want to roll back.

   Note

   If you are using a managed domain, you must add the --host=HOSTNAME argument to the commands in this procedure to specify the RH-SSO host.

2. Roll back the patch with the appropriate patch ID from the previous step.

   patch rollback --patch-id=PATCH_ID --reset-configuration=TRUE

   The patch tool will warn if there are any conflicts in attempting to roll back the patch. If there are conflicts, enter patch --help for the available arguments to re-run the command with an argument specifying how to resolve the conflicts.

3. Restart the RH-SSO server for the patch roll back to take effect:

   shutdown --restart=true

Procedure

1. Open the management console and navigate to the Patch Management view.

   1. For a standalone server, click the Patching tab.
   2. For a server in a managed domain, click the Patching tab, then select the host that you want to patch from the table, and click View.

2. Select the patch that you want to rollback from those listed in the table, then click Rollback.

   Recent Patch History Screen

   .. If you are rolling back a patch on a managed domain host, on the next screen select whether to shutdown the servers on the host, and click Next.

3. Choose your options for the rollback process, then click Next.

   Patch Rollback Options

   

4. Confirm the options and the patch to be rolled back, then click Next.

   1. If there are any conflicts in attempting to rollback the patch and the Override all option was not selected, a warning will be displayed. Click View error details to see the detail of the conflicts. If there is a conflict, you can either cancel the operation, or click Choose Options and try the operation again with the Override all check box selected. Overriding conflicts will result in the rollback operation overriding any user modifications.
5. After the patch has been successfully rolled back, select whether to restart the RH-SSO server now for the changes to take effect, and click Finish.