Patching and Upgrading Guide
For Use with Red Hat JBoss Enterprise Application Platform 7.1
Abstract
Chapter 1. Introduction
1.1. About Migrations and Upgrades
Major Upgrades
A major upgrade or migration is required when an application is moved from one major release to another, for example, from JBoss EAP 6.4 to JBoss EAP 7.0. If an application follows the Java EE specifications, does not access deprecated APIs, and does not contain proprietary code, it might be possible to run the application in JBoss EAP 7 without any application code changes. However, the server configuration has changed in JBoss EAP 7 and requires migration. This type of migration is addressed in the JBoss EAP Migration Guide.
Minor Updates
JBoss EAP periodically provides point releases, which are minor updates that include bug fixes, security fixes, and new features. Information about the changes made in a point release are documented in the JBoss EAP Migration Guide and in the 7.1.0 Release Notes.
You can use the JBoss Server Migration Tool to automatically upgrade from one point release to another, for example from JBoss EAP 7.0 to JBoss EAP 7.1. For information about how to configure and run the tool, see Using the JBoss Server Migration Tool.
If you prefer, you can perform a manual upgrade of the server configuration. Instructions on how to perform a manual upgrade are documented in this guide. For more information, see Upgrading JBoss EAP.
Cumulative Patches
JBoss EAP also periodically provides cumulative patches that contain bug and security fixes. Cumulative patches increment the release by the last digit, for example from 7.1.0 to 7.1.1. Patch installation is addressed in the Patching JBoss EAP chapter of this guide.
1.2. Subscribing to Security Announcements
Red Hat maintains a mailing list for security announcements. You can subscribe to this mailing list to be notified of security-related announcements that affect JBoss EAP.
Chapter 2. Patching JBoss EAP
The method of applying a patch to JBoss EAP depends on your installation method. If you installed JBoss EAP using the ZIP or installer methods, you must use the ZIP-based patch management system. 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, you should 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 a ZIP/Installer Installation
Cumulative patches for a ZIP or Installer installation of JBoss EAP are available to download from the Red Hat Customer Portal.
For multiple JBoss EAP hosts in a managed domain environment, individual hosts can be patched from your JBoss EAP domain controller.
In addition to applying a patch, you can also roll back the application of a patch.
2.1.1. Important Notes on ZIP/Installer Installation Patching
- If you apply a patch that updates a module, the new patched JARs that are used at runtime are stored in
EAP_HOME/modules/system/layers/base/.overlays/PATCH_ID/MODULE. The original unpatched files are left in
EAP_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 JBoss EAP 7, you now 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 JBoss EAP 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.
2.1.2. Applying a Patch
JBoss EAP servers that have been installed using the RPM method cannot be updated using these instructions. See the RPM instructions for applying a patch instead.
You can apply downloaded patches to a JBoss EAP server using either the management CLI or the management console.
Applying a Patch to JBoss EAP Using the Management CLI
- Log in to the Red Hat Customer Portal, and download the patch file from JBoss EAP Software Downloads.
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.zipNote
To patch another 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 will warn if there are any conflicts in attempting to apply the patch. If there are conflicts, enter
patch --helpfor the available arguments to re-run the command with an argument specifying how to resolve the conflicts.
Restart the JBoss EAP server for the patch to take effect:
shutdown --restart=true
Applying a Patch to JBoss EAP Using the Management Console
- 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 Patch Management view.
For a standalone server, click the Patching tab.
Figure 2.1. 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.
Figure 2.2. 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 shutdown the servers on the host, and click Next.
Click the Browse button, select the downloaded patch you want to apply, and then click Next.
Figure 2.3. 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 JBoss EAP now for the patch to take effect, and click Finish.
2.1.3. Rolling Back a 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.
Prerequisites
- A patch that was previously applied.
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 JBoss EAP server configuration files to their pre-patch state. Any changes that were made to the JBoss EAP 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.
Rolling Back a Patch Using the Management CLI
From the management CLI, use the
patch historycommand 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=HOSTNAMEargument to the commands in this procedure 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 will warn if there are any conflicts in attempting to roll back the patch. If there are conflicts, enter
patch --helpfor the available arguments to re-run the command with an argument specifying how to resolve the conflicts.
Restart the JBoss EAP server for the patch roll back to take effect:
shutdown --restart=true
Rolling Back a Patch Using the Management Console
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.
Figure 2.4. 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.
Choose your options for the rollback process, then click Next.
Figure 2.5. Patch Rollback Options
Confirm the options and the patch to be rolled back, then click Next.
- 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.
- After the patch has been successfully rolled back, select whether to restart the JBoss EAP server now for the changes to take effect, and click Finish.
2.1.4. Clearing Patch History
When patches are applied to a JBoss EAP 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.
/core-service=patching:ageout-history
If you clear the patch history, you will not be able to roll back a previously applied patch.
2.2. Patching an RPM Installation
Prerequisites
- Ensure that the base operating system is up to date, and is subscribed and enabled to get updates from the standard Red Hat Enterprise Linux repositories.
Ensure that 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.
If you are subscribed to the
currentrepository, this may mean that your installation will also be upgraded to the next available minor release. For more details, see the information on choosing a JBoss EAP repository in the Installation Guide.
- Back up all configuration files, deployments, and user data.
For a managed domain, the JBoss EAP domain controller should be updated first.
To install a JBoss EAP patch via RPM from your subscribed repository, update your Red Hat Enterprise Linux system using the following command:
# yum update
2.3. Optional: Patch a Local JBoss EAP Maven Repository
If you have installed the JBoss EAP Maven repository, it may also need to be patched.
The JBoss EAP Maven repository is available online or as a downloaded ZIP file. If you use the publicly hosted online Maven repository, updates are automatically applied, and no action is required to update it. However, if you installed the Maven repository locally using the ZIP 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 ZIP file that is unzipped 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
- Valid access and subscription to the Red Hat Customer Portal.
- The JBoss EAP 7.1 Maven repository, previously downloaded and installed locally.
Update a Locally Installed JBoss EAP Maven Repository
- Open a browser and log into the Red Hat Customer Portal.
- Select Downloads from the menu at the top of the page.
- Find
Red Hat JBoss Enterprise Application Platformin 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.1 Update CP_NUMBER Incremental Maven Repositoryin the list, where
CP_NUMBERis 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.
Unzip the downloaded Maven patch file directly into the directory of the JBoss EAP 7.1 Maven repository.
For Red Hat Enterprise Linux, open a terminal and run the following command, replacing the values for the cumulative patch number and your Maven repository path.
$ unzip -o jboss-eap-7.1.CP_NUMBER-incremental-maven-repository.zip -d EAP_MAVEN_REPOSITORY_PATH
- For Microsoft Windows, use the Windows extraction utility to extract the ZIP file into the root of the
EAP_MAVEN_REPOSITORY_PATHdirectory.
Chapter will still be applicable after the upgrade. thanJ-10-11 12:33:03 UTC