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.
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 inEAP_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.
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
- Log in to the Red Hat Customer Portal and download the patch file from JBoss EAP Software Downloads.
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
NoteTo 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.
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.
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
- Log in to the Red Hat Customer Portal and download the patch file from JBoss EAP Software Downloads.
- Open the management console and navigate to the Patching tab.
Add the patch using the Add Patch wizard.
For a standalone server:
- Click the Add (+) button.
- Click Choose a file or drag it here, select the downloaded patch to apply, and click Next.
- Configure any of the additional options and click Finish.
For a managed domain:
- Select the host to patch and click the Add (+) button.
- Select whether to shut down the servers on the host, and click Next.
- Click Choose a file or drag it here, select the downloaded patch to apply, and click Next.
- 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.
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.
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
Use the
patch history
command from the management CLI to find the ID of the patch that you want to roll back.NoteIf you are using a managed domain, you must add the
--host=HOSTNAME
argument to the commands to specify the JBoss EAP host.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.Restart the JBoss EAP server for the patch roll back to take effect:
shutdown --restart=true
Verification
-
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
- Open the management console and navigate to the Patching tab.
Roll back the patch using the Rollback wizard.
For a standalone server:
- Select the patch to roll back and click Rollback.
- Configure any of the additional options and click Finish.
For a managed domain:
- Select the host, select the patch to roll back, and click Rollback.
- Select whether to shut down the servers on the host and click Next.
- 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.
WarningWhen 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.
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
- Open a browser and log in to the Red Hat Customer Portal.
- Select Downloads from the menu bar on the header.
-
Find
Red Hat JBoss Enterprise Application Platform
in the list and click on it. - Select the correct version of JBoss EAP from the Version drop-down menu, then click on Patches tab.
-
Find
Red Hat JBoss Enterprise Application Platform 7.4 Update CP_NUMBER Incremental Maven Repository
in the list, whereCP_NUMBER
is the cumulative patch number you want to update to, and then click Download. -
Locate the path to your JBoss EAP Maven repository. This is referred to in the commands below as
EAP_MAVEN_REPOSITORY_PATH
. Decompress the downloaded Maven patch file directly into the directory of the JBoss EAP 7.4 Maven repository.
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 andEAP_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
-
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
- For information about creating a Red Hat Customer Portal account see creating a Red Hat Customer Portal account.
- For information about downloading and locally installing the JBoss EAP 7.4 Maven repository, see preparing to set up Maven.