Chapter 2. Patching JBoss EAP

The method you should choose to apply a patch to JBoss EAP depends on your installation method. If you installed JBoss EAP using the archive or installer methods, you must use the patch management .zip file. If you used RPMs to install JBoss EAP on Red Hat Enterprise Linux, you must use RPM patches.

Important

Before applying or rolling back a patch, back up your JBoss EAP server, including all deployments and configuration files.

If you have a locally installed JBoss EAP Maven repository, you must also patch the Maven repository to the same cumulative patch version as your JBoss EAP server.

2.1. Patching an archive or installer installation

You can download cumulative patches for an archive or installer installation of JBoss EAP from the Red Hat Customer Portal. If you have multiple JBoss EAP hosts in a managed domain environment, you can patch individual hosts from your JBoss EAP domain controller.

Important notes on archive or installer installation patching

Before patching an archive or installer, you must take note of the following:

  • If you apply a patch that updates a module, the new patched JARs used at runtime are stored in EAP_HOME/modules/system/layers/base/.overlays/PATCH_ID/MODULE. The original unpatched files remain in EAP_HOME/modules/system/layers/base/MODULE, and are not used at runtime.

  • To significantly decrease the size of cumulative patch releases for JBoss EAP 7, you must first confirm that there were no issues with the cumulative patch update, then run this CLI command /core-service=patching:ageout-history(). This removes all cumulative patch overlays except the latest and the original base release.

    For example, if you had JBoss EAP 7.0.0 and applied CP01 and then later applied CP02. If you run /core-service=patching:ageout-history(), you will not be able to rollback to CP01. Rolling back CP02 would mean rolling back to JBoss EAP 7.0.0, you would have to download CP01 and apply it again.

    Note
    • The patch only works for archive installations, not RPMs.
    • You do not need to apply intermediate cumulative patches. For example, If you have JBoss EAP 7.0.0 you can apply CP05 without applying CP01-CP04.
    • You can only roll back to a previous cumulative patch if you had installed it previously.

2.1.1. Patching JBoss EAP using the management CLI

You can apply patches to JBoss EAP using the management CLI.

Note

You cannot use these instructions to update any JBoss EAP servers that you installed using the RPM method. See the RPM instructions for applying a patch instead.

Procedure

  1. Log in to the Red Hat Customer Portal and download the patch file from JBoss EAP Software Downloads.

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

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

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

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

    The patch tool displays a warning message if there are any conflicts when it attempts to apply a patch. If there are conflicts, enter patch --help for the available arguments for resolving patching conflicts.

  3. Restart the JBoss EAP server for the patch to take effect: 

    shutdown --restart=true

Verification

  • You can verify that a patch has been applied successfully by opening the management CLI and running patch info.

    Expected output: 

    Version:             <PATCH_VERSION_NUMBER>.GA
Cumulative patch ID: jboss-eap-<PATCH VERSION NUMBER>.CP
One-off patches:     none

    This displays the version and cumulative patch ID for the newly applied patch.

2.1.2. Patching JBoss EAP using the management console

You can apply patches to JBoss EAP using the management console.

Note

You cannot use these instructions to update any JBoss EAP servers that you installed using the RPM method. See the RPM instructions for applying a patch instead.

Procedure

  1. Log in to the Red Hat Customer Portal and download the patch file from JBoss EAP Software Downloads.
  2. Open the management console and navigate to the Patching tab.

  3. Add the patch using the Add Patch wizard.

    • For a standalone server:

      1. Click the Add (+) button.
      2. Click Choose a file or drag it here, select the downloaded patch to apply, and click Next.
      3. Configure any of the additional options and click Finish.

    • For a managed domain:

      1. Select the host to patch and click the Add (+) button.
      2. Select whether to shut down the servers on the host, and click Next.
      3. Click Choose a file or drag it here, select the downloaded patch to apply, and click Next.
      4. Configure any of the additional options and click Finish.
    • If the patch was applied successfully, restart the server for the changes to take effect.
    • If the patch application fails, review the error message. If there was a conflict, you can use the Override All, Override Modules, and Override fields in the Add Patch wizard to bypass content verification for items that the patch changes. When you override conflicts, the patch contents override your modifications.

Verification

  • To verify that you have applied a patch successfully, open the console to apply a cumulative patch. If it was installed successfully, it should be listed in Patching tab on the management console. This is the same for both standalone and the managed domain servers.

2.1.3. Rolling back to a previously applied patch

You can roll back a previously applied JBoss EAP patch using either the management CLI or the 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.

Warning

When you roll back a patch, be sure to specify the correct value for the Reset Configuration option. You must set one of the following two values before you roll back a patch:

  • If set to TRUE, the patch rollback process rolls back the JBoss EAP server configuration files to their pre-patch state. All changes that were made to the JBoss EAP server configuration files after the patch was applied cannot be recovered.
  • If set to FALSE, the server configuration files cannot be rolled back. In this situation, the server might not start after the rollback, as the patch can alter configurations, such as namespaces, which you can fix manually.

2.1.4. Rolling back a patch using the management CLI

You can roll back a patch on JBoss EAP using the management CLI.

Procedure

  1. Use the patch history command from the management CLI 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 to specify the JBoss EAP 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 warns you if there are any conflicts when attempting to roll back the patch. If there are conflicts, enter patch --help for the available arguments and re-run the command with an argument specifying how you want to resolve the conflicts.

  3. Restart the JBoss EAP server for the patch roll back to take effect: 

    shutdown --restart=true

Verification

  1. You can verify that a patch has been rolled back successfully Opening the management CLI and running patch info.This displays the version and cumulative patch ID for the previously applied patch.

2.1.5. Rolling back a patch using the management console

You can roll back a patch on JBoss EAP using the management console.

Procedure

  1. Open the management console and navigate to the Patching tab.

  2. Roll back the patch using the Rollback wizard.

    • For a standalone server:

      1. Select the patch to roll back and click Rollback.
      2. Configure any of the additional options and click Finish.

    • For a managed domain:

      1. Select the host, select the patch to roll back, and click Rollback.
      2. Select whether to shut down the servers on the host and click Next.
      3. Configure any of the additional options and click Finish.
    • If the patch was rolled back successfully, restart the server for the changes to take effect.
    • If the patch rollback failed, review the error message. If there was a conflict, you can use the Override All, Override Modules, and Override fields in the wizard to bypass content verification for items affected by the patch.

Verification

  • To verify that you have rolled back a patch successfully, open the management console and navigate to the Patching tab. On the left, you can see the patch version that has been previously applied. This is the same for both standalone and the managed domain servers.

2.2. Patching an RPM installation

JBoss EAP supports RPM installation patching. Before patching an RPM installation, you must ensure that your system meets all the following setup prerequisites.

Prerequisites

  • The base operating system is up-to-date, and you get updates from the standard Red Hat Enterprise Linux repositories.

  • You are subscribed to the relevant JBoss EAP repository for the update.

    Warning

    When updating an RPM installation, JBoss EAP is updated cumulatively with all RPM-released fixes for the subscribed repository.

  • Back up all configuration files, deployments, and user data.
Important

In a managed domain, ensure that the JBoss EAP domain controller is updated first.

Procedure

To install a JBoss EAP patch using RPM from your subscribed repository, update your Red Hat Enterprise Linux system using the following command: 

# yum update

2.3. Patching a local JBoss EAP Maven repository

If you have installed the JBoss EAP Maven repository, You must apply the patch to your JBoss EAP Maven.

The JBoss EAP Maven repository is available online or as a downloadable compressed file. If you use the publicly hosted online Maven repository, updates are automatically applied, so you don’t need to update the repository. However, if you installed the Maven repository locally using the compressed file, you are responsible for applying updates to the repository.

Whenever a cumulative patch is released for JBoss EAP, a corresponding patch is provided for the JBoss EAP Maven repository. This patch is available in the form of an incremental compressed file that is decompressed into the existing local repository. It does not overwrite or remove any existing files, so there is no rollback requirement.

Use the following procedure to apply updates to your locally installed JBoss EAP Maven repository.

Prerequisites

  • You have subscribed to the Red Hat Customer Portal.
  • You have downloaded and locally installed JBoss EAP 7.4, Maven repository.

Procedure

  1. Open a browser and log in to the Red Hat Customer Portal.
  2. Select Downloads from the menu bar on the header.
  3. Find Red Hat JBoss Enterprise Application Platform in the list and click on it.
  4. Select the correct version of JBoss EAP from the Version drop-down menu, then click on Patches tab.
  5. Find Red Hat JBoss Enterprise Application Platform 7.4 Update CP_NUMBER Incremental Maven Repository in the list, where CP_NUMBER is the cumulative patch number you want to update to, and then click Download.
  6. Locate the path to your JBoss EAP Maven repository. This is referred to in the commands below as EAP_MAVEN_REPOSITORY_PATH.

  7. Decompress the downloaded Maven patch file directly into the directory of the JBoss EAP 7.4 Maven repository.

    1. For Red Hat Enterprise Linux, open a terminal and run the following command, replacing CP_NUMBER with cumulative patch number you want to update to and EAP_MAVEN_REPOSITORY_PATH with your Maven repository path. 

      $ unzip -o jboss-eap-7.4.CP_NUMBER-incremental-maven-repository.zip -d EAP_MAVEN_REPOSITORY_PATH
    2. For Microsoft Windows, use the Windows extraction utility to extract the compressed file into the root of the EAP_MAVEN_REPOSITORY_PATH directory.

Additional information