keycloak-scim/upgrading/topics/rhsso/patching-zip-installation.adoc

[[zip-patching]]
= ZIP/installer installation patching

Patches for a ZIP installation of RH-SSO are available to download from the
link:https://access.redhat.com/[Red Hat Customer Portal].

For multiple RH-SSO hosts in a managed domain environment, individual hosts can be patched from your RH-SSO domain controller.

In addition to applying a patch, you can also roll back the application of a patch.

== Important notes on ZIP installation patching

* If you apply a patch that updates a module, the new patched JARs that are used at runtime are stored in `RHSSO_HOME/modules/system/layers/base/.overlays/_PATCH_ID_/_MODULE_`. The original unpatched files are left in `RHSSO_HOME/modules/system/layers/base/_MODULE_`, but these JARs are *not* used at runtime.
* In order to significantly decrease the size of cumulative patch releases for RH-SSO 7 you cannot perform a partial roll back of a cumulative patch. For a patch that has been applied, you will only be able to roll back the whole patch.
+
For example, if you apply CP03 to RH-SSO 7.0.0, you will not be able to roll back to CP01 or CP02. If you would like the ability to roll back to each cumulative patch release, each cumulative patch must be applied separately in the order they were released.

== Applying a patch

NOTE:  RH-SSO servers that have been installed using the RPM method cannot be updated using these instructions. See the xref:rpm-patching[RPM instructions for applying a patch] instead.

You can apply downloaded patches to a RH-SSO server using either the xref:zip_patching_management_cli[management CLI] or the xref:zip_patching_management_console[management console].

[[zip_patching_management_cli]]
.Applying a patch to RH-SSO using the management CLI

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

. From the link:{appserver_managementcli_link}[management CLI], apply the patch using the following command, including the appropriate path to the patch file:
+
[options="nowrap"]
----
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:

[options="nowrap"]
----
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.

. Restart the RH-SSO server for the patch to take effect:
+
[options="nowrap"]
----
shutdown --restart=true
----

[[zip_patching_management_console]]
.Applying a patch to RH-SSO using the Management Console

.Procedure

. Download the patch file from the Red Hat Customer Portal at https://access.redhat.com/downloads/.
. Open the link:{appserver_managementconsole_link}[management console] and navigate to the *Patch Management* view.
.. For a standalone server, click the *Patching* tab.
+
.The Patch Management Screen for a Standalone Server
image:images/patching-standalone-tab.png[The Patch Management Screen for a Standalone Server]
.. 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
image:images/patching-domain-tab.png[The Patch Management Screen for a Managed Domain]

. Click *Apply a New Patch*.
.. If you are patching a managed domain host, on the next screen select whether to shut down the servers on the host, and click *Next*.

. Click the *Browse* button, select the downloaded patch you want to apply, and then click *Next*.
+
.Apply Patch Screen
image:images/patching-select-patch.png[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.

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

== Rolling back a patch

You can roll back a previously applied RH-SSO patch using either the xref:zip_rollback_management_cli[management CLI] or the xref:zip_rollback_management_console[management console].

IMPORTANT: Rolling back a patch using the patch management system is not intended as a general uninstall functionality. It is only intended to be used immediately after the application of a patch that had undesirable effects.

.Prerequisites
* A patch that was previously applied.

[WARNING]
====
When following either procedure, use caution when specifying the value of the `Reset Configuration` option:

If set to `TRUE`, the patch rollback process will also roll back the RH-SSO server configuration files to their pre-patch state. Any changes that were made to the RH-SSO server configuration files after the patch was applied will be lost.

If set to `FALSE`, the server configuration files will not be rolled back. In this situation, it is possible that the server will not start after the rollback, as the patch may have altered configurations, such as namespaces, which may no longer be valid and will have to be fixed manually.
====

[[zip_rollback_management_cli]]
.Rolling Back a Patch Using the Management CLI

.Procedure

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

. Roll back the patch with the appropriate patch ID from the previous step.
+
[options="nowrap"]
----
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.

.  Restart the RH-SSO server for the patch roll back to take effect:
+
[options="nowrap"]
----
shutdown --restart=true
----

[[zip_rollback_management_console]]
.Rolling back a patch using the Management Console

.Procedure
. Open the management console and navigate to the *Patch Management* view.
.. For a standalone server, click the *Patching* tab.
.. 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*.

. Select the patch that you want to rollback from those listed in the table, then click *Rollback*.
+
.Recent Patch History Screen
image:images/patching-rollback-table.png[Recent Patch History Screen]
.. If you are rolling back a patch on a managed domain host, on the next screen select whether to shut down the servers on the host, and click *Next*.

. Choose your options for the rollback process, then click *Next*.
+
.Patch Rollback Options
image:images/patching-rollback-options.png[Patch Rollback Options]

. Confirm the options and the patch to be rolled back, then click *Next*.
.. If there are any conflicts in attempting to roll back 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.

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

== Clearing patch history

When patches are applied to a RH-SSO server, the content and history of the patches are preserved for use in rollback operations. If multiple cumulative patches are applied, the patch history may use a significant amount of disk space.

You can use the following management CLI command to remove all older patches that are not currently in use. When using this command, only the latest cumulative patch is preserved along with the GA release. This is only useful for freeing space if multiple cumulative patches have previously been applied.

[options="nowrap"]
----
/core-service=patching:ageout-history
----

IMPORTANT: If you clear the patch history, you will not be able to roll back a previously applied patch.